1
Launch
The CLI or workflow tool resolves a named definition, validates inputs, creates a run identity, and admits a detached/background runner. Goal’s runner creates its ledger and artifact directory before the first orchestrator turn.
State machine / background runs
From goal to bounded proof.
A background workflow is not a detached prompt. It is a durable run with a graph, stage sessions, checkpoints, controls, artifacts, and a reducer-defined terminal decision.
admitted→running→paused / awaiting input→resumed→completed / failed / blocked / killed
Exact lifecycle
2
Track
The workflow executor materializes stage/task/parallel/nested nodes and records stage start/end, tool events, session IDs, ownership, and graph topology. The status store and graph surfaces read these snapshots.
3
Checkpoint
Durable stage primitives and DBOS envelopes persist replay keys, topology, outputs, prompts, and timing. Artifacts keep large context outside prompts; goal receipts and review JSON paths become the next stage’s handoff.
4
Steer or ask
A stage can await human input through the UI broker. A parent can connect, attach, send, or steer; queue modes preserve the distinction between steering and follow-up and stage admission prevents late messages from crossing a closed boundary.
5
Pause / interrupt / quit
Interrupt aborts active work cooperatively; pause holds queued messages and records a run/stage pause. Graceful quit waits for pause acknowledgement and keeps the run resumable when durable state accepts the transition. `/workflow interrupt` is the immediate control; `/workflow quit` is the resumable stop.
6
Resume
Resume resolves a run ID, restores the durable graph and retained sessions, replays completed stages, and dispatches a continuation with a fresh process-local identity while preserving the original durable run identity and elapsed timing.
7
Bounded completion
Goal loops only through its configured maximum turns, records receipts and review artifacts, and lets the reducer decide complete, continue, or human-needed. Reviewer quorum and stop signals—not model narration—determine convergence; terminal state and final report are persisted.
Cross-state invariants
What must remain true
Run and stage IDs remain the join keys across in-memory status, durable checkpoints, session metadata, artifacts, and bridge receipts. A terminal root is not reopened by ordinary stage sends; a paused run is not counted as running; late messages are admitted only while their stage boundary is open; and a failed durable transition is never reported as a successful resumable quit.
Illegal input
Fail loudly
Unknown run IDs, ambiguous prefixes, missing stages, unavailable sessions, unsupported headless UI prompts, and terminal roots return explicit structured errors rather than silently creating new work.
Durability caveat. If no DBOS backend can be provisioned, Atomic can run with a process-local in-memory backend and emits a non-durable warning; a process exit then cannot restore the run. This distinction is part of the status contract, not a hosting assumption.
Usage & cost across a run and its stages
A proposed ledger would append one ordered model_attempt event per accepted stage attempt, preserve raw provider/model IDs, and roll numeric reported values from stage to run without counting retries twice. The current stage controller records attempt identity and outcome but not usage, so this page does not claim that workflow totals exist today.
packages/workflows/src/shared/authoring-contract-stage.ts#L82-L97 packages/workflows/src/durable/dbos-envelope.ts#L447-L482 packages/workflows/src/runs/foreground/stage-runner-controller.ts#L445-L455 packages/workflows/src/runs/foreground/stage-runner-controller.ts#L1236-L1265 packages/coding-agent/src/core/agent-session-export.ts#L14-L101 packages/coding-agent/src/core/agent-session-types.ts#L192-L209 packages/coding-agent/src/core/usage-totals.ts#L4-L59 packages/workflows/src/durable/dbos-envelope.ts#L44-L70