Run Lifecycle

Run lifecycle vocabulary appears in durable run records and append-only run events. Storage, operator tools, and dashboards can branch on these values.

RunStatus

Enum	Value	Meaning
`RunStatus.CancellationRequested`	`cancellation_requested`	Cancellation was requested for a leased running run; the owner may stop cooperatively, and maintenance can finalize after lease expiry.
`RunStatus.Cancelled`	`cancelled`	Terminal cancellation outcome.
`RunStatus.Failed`	`failed`	Terminal failure outcome after retry budget is exhausted, retry is not allowed, or a cancellation-requested attempt fails.
`RunStatus.Queued`	`queued`	Waiting for worker acquisition or dispatch; runnable when `runAt ?? updatedAt` is due and queue capacity or an existing dispatch reservation allows it.
`RunStatus.Released`	`released`	Business waiting; runnable again when a time wait is due, a signal is sent, or a source run reaches terminal state.
`RunStatus.Retrying`	`retrying`	Failure-driven retry; runnable again when `runAt` is due.
`RunStatus.Running`	`running`	A worker owns an active lease; the attempt is about to start or is executing.
`RunStatus.Scheduled`	`scheduled`	Delivery has been requested for a future `runAt`.
`RunStatus.Succeeded`	`succeeded`	Terminal success outcome.

RunStatusClassification

Enum	Value	Meaning
`RunStatusClassification.Active`	`active`	The run can still move through lifecycle transitions.
`RunStatusClassification.Terminal`	`terminal`	The run does not reactivate; rerun and manual retry create linked child runs.

Use runStatusValues.isActive() and runStatusValues.isTerminal() instead of duplicating classification lists.

Status classification is broader than worker eligibility. cancellation_requested is active because it can still move to cancelled or failed, but it is not a runnable candidate. Terminal runs never accept more lifecycle events; rerun and manual retry create linked child runs instead.

Scan candidate status groups

Storage scans use narrower status groups than active/terminal classification. These groups are status-only gates; time and lease eligibility still come from getRunRunnableAvailableAt(), getRunDeliveryRecoveryAvailableAt(), and getRunCancellationFinalizationAvailableAt().

Group	Values	Meaning
`runStatusValues.runnableCandidates`	`queued`, `released`, `retrying`, `running`, `scheduled`	Statuses that `listRunnableRuns()` may return when the run is due or its lease has expired.
`runStatusValues.deliveryRecoveryCandidates`	`released`, `retrying`, `running`, `scheduled`	Statuses that `listRunsNeedingDelivery()` may return when maintenance needs to append a fresh delivery request.
`runStatusValues.cancellationFinalizationCandidates`	`cancellation_requested`	Statuses that `listRunsNeedingCancellationFinalization()` may return after the current lease expires.

queued is excluded from delivery recovery candidates because it already has durable delivery intent and outbox state.

Use the matching predicates, such as runStatusValues.isDeliveryRecoveryCandidate(), instead of duplicating status switches in adapters.

Attempt-timeout finalization is narrower than a status group: it applies only to running runs whose current lease has recorded run.started and whose fixed attemptDeadlineAt has passed. Use getRunAttemptTimeoutFinalizationAvailableAt() for that predicate instead of treating all expired leases as timeouts.

Dispatch Reservation Predicate

Bounded queues reserve capacity before publishing a delivery wakeup. Use this helper anywhere storage code needs to reason about that reservation window.

Helper	Condition	Meaning
`isRunDispatchReservation({ run, at, condition: RunDispatchReservationCondition.Active })`	`active`	The queued run still owns a dispatch slot at `at`.
`isRunDispatchReservation({ run, at, condition: RunDispatchReservationCondition.Expired })`	`expired`	The queued run had a dispatch slot, but it expired at or before `at`.

RunCounters

RunRecord.counters is materialized from replayed events. It is durable run state, not a derived dashboard-only summary.

Field	Incremented by	Meaning
`attempts`	`run.started`	Count of started execution attempts.
`failures`	`run.failed`, `run.retry_scheduled`	Failure pressure recorded for terminal failures and retry-scheduled failures.
`releases`	`run.released`	Business waits that did not count as failure pressure.
`retries`	`run.retry_scheduled`	Failed attempts that scheduled another try.

run.succeeded and run.cancelled do not increment counters by themselves. They close an existing attempt or, for waiting-run cancellation, finish a run that may have no attempts.

RunAttemptStatus

RunAttemptStatus appears in runlane.runs.attempts(runId) summaries. It is derived from replayed run events; it is not stored as a separate durable run field.

Enum	Value	Meaning
`RunAttemptStatus.Cancelled`	`cancelled`	The attempt ended after cooperative cancellation.
`RunAttemptStatus.Failed`	`failed`	The attempt failed without scheduling another try.
`RunAttemptStatus.Released`	`released`	The attempt released the run to resume later.
`RunAttemptStatus.Retrying`	`retrying`	The attempt failed and scheduled another try.
`RunAttemptStatus.Running`	`running`	The attempt has started and has no terminal attempt event yet.
`RunAttemptStatus.Succeeded`	`succeeded`	The attempt completed successfully.

Only run.started creates an attempt summary. A later run.cancelled marks the latest still-running attempt as cancelled; cancelling queued, released, retrying, or scheduled work without a started attempt does not create an attempt row.

RunEventType

Enum	Value	Meaning
`RunEventType.CancellationRequested`	`run.cancellation_requested`	Operator or system requested cooperative cancellation of a leased running run.
`RunEventType.Cancelled`	`run.cancelled`	Waiting work, a cancellation-requested run, or the latest running attempt completed with terminal cancellation.
`RunEventType.Created`	`run.created`	First durable event for a run.
`RunEventType.DeliveryRequested`	`run.delivery_requested`	Runtime recorded durable wakeup intent; transport-delivery lanes may also request a matching outbox row.
`RunEventType.Failed`	`run.failed`	Current started attempt ended in terminal failure.
`RunEventType.LeaseClaimed`	`run.lease_claimed`	Worker or inline execution claimed ownership for execution.
`RunEventType.LeaseHeartbeat`	`run.lease_heartbeat`	Worker extended the current lease with the same worker id and token.
`RunEventType.Released`	`run.released`	Attempt chose business waiting without counting a failure. It may carry a time, signal, or run-completion wait condition.
`RunEventType.RetryScheduled`	`run.retry_scheduled`	Current started attempt failed and scheduled another try.
`RunEventType.Started`	`run.started`	Execution attempt started.
`RunEventType.Succeeded`	`run.succeeded`	Attempt completed successfully, optionally with JSON output.

RunSourceType

Enum	Value	Meaning
`RunSourceType.ManualRetry`	`manual_retry`	Operator-created child retry linked to a failed source run.
`RunSourceType.Rerun`	`rerun`	Operator-created child rerun linked to a terminal source run.
`RunSourceType.Schedule`	`schedule`	Schedule materialization created the run.
`RunSourceType.Trigger`	`trigger`	Application trigger created the run.

Task-context child triggers also use RunSourceType.Trigger with sourceRunId set to the parent run. Top-level public triggers usually have no source.

RunWaitConditionType

Enum	Value	Meaning
`RunWaitConditionType.RunCompletion`	`run_completion`	Released run resumes when the referenced source run reaches terminal state, immediately if that source is already terminal, or when its optional timeout becomes due.
`RunWaitConditionType.Signal`	`signal`	Released run resumes when application code sends the matching signal key, or when its optional timeout becomes due.
`RunWaitConditionType.Time`	`time`	Released run resumes when `resumeAt` becomes due through maintenance delivery.

TriggerOutcomeType

TriggerOutcomeType appears in TriggerRunResult from runlane.trigger(). It describes the result of the trigger call, not the run lifecycle status.

Enum	Value	Meaning
`TriggerOutcomeType.Created`	`created`	The trigger call persisted a new run.
`TriggerOutcomeType.ReturnedExisting`	`returned_existing`	Idempotency returned the active or retained run already owning the selected key.

ActorType

Enum	Value	Meaning
`ActorType.Operator`	`operator`	Human or operator action.
`ActorType.Schedule`	`schedule`	Schedule materializer action.
`ActorType.System`	`system`	Framework/system action.
`ActorType.Worker`	`worker`	Worker execution action.

contractDefaults.actor.system and contractDefaults.actor.operator provide the canonical actor records for framework and operator actions that do not carry a more specific actor id.

Output And Failure Fields

RunRecord.output is the current visible successful output. It is present only when run.succeeded carried JSON output; undefined handler returns are void success and leave the field absent. null is explicit JSON output and remains visible as output: null.

RunRecord.failure is the current visible failure summary for failed and retrying runs. Succeeded runs may have output; failed and retrying runs may have failure; released and cancelled runs have neither current success output nor current failure. Use runlane.runs.attempts(runId) or raw events when you need previous attempt outcomes.

RunRecord.wait is the current visible business-wait condition for released runs. RunSummary.wait carries the same compact condition for list rows. RunRecord.attemptDeadlineAt is visible while a running attempt has a fixed max-attempt deadline and clears when that attempt leaves running.

On this page