Run state reference
One table, every run status. orcho status and orcho_run_status report one
of these values; this page says what each means and what you can do about it.
For why these states are trustworthy, read
Runs as recorded state.
Status table
Section titled “Status table”| Status | Class | Meaning | Allowed next actions |
|---|---|---|---|
unknown | diagnostic | No projected lifecycle yet. Not a runnable target by itself. | Diagnose: orcho status, orcho_run_diagnose. |
running | live | Pipeline is active or ready to continue from checkpoint. | Observe: orcho status, orcho_run_status; nothing to decide. |
awaiting_phase_handoff | operator pause | A phase handoff is active and needs a decision before resume. | Decide, then resume: orcho run --resume <run-id> (interactive menu), or orcho_phase_handoff_decide then orcho_run_resume. Decisions: continue, continue_with_waiver, retry_feedback, halt. |
awaiting_gate_decision | operator pause | A gate decision is active and blocks resume. | Record the gate decision, then resume: orcho run --resume <run-id>, or orcho_delivery_gate then orcho_delivery_decide when the pending gate is delivery/correction. |
awaiting_human_review | operator pause | Human review is active and blocks resume. | Record the review decision, then resume: orcho run --resume <run-id>, or the same MCP decide-then-resume pair. |
done | settled terminal | Run completed successfully. Never resumed as the same run. | Read results: orcho evidence, orcho diff; follow-up: orcho run --resume <run-id> --task ... or --from-run-plan <run-id>. |
halted | settled terminal | Operator or policy halted the run (including no-diff halts). Not resumed as the same run unless repaired by explicit policy. | Inspect: orcho evidence; correction follow-up: orcho run --resume <run-id> --task ...; repair only via orcho repair-state. |
failed | terminal / diagnostic | Run failed. An active handoff may be preserved for diagnosis. | No blind resume. Inspect first: orcho status -v, orcho evidence, orcho_run_diagnose; decide the preserved handoff if one exists; then correction follow-up. |
cancelled | terminal | Run was cancelled or aborted by contract (a cross-run terminal). | Not resumed as the same run. Follow-up only. |
interrupted | torn / diagnostic | Process ended before a clean terminal write. | Checkpoint restore: orcho run --resume <run-id>; if it still carries an undecided handoff, decide that first; orcho repair-state <run-id> for torn shapes. |
Statuses come from the engine’s RunStatus taxonomy; do not infer state from
terminal text when a typed surface exists.
Parked delivery decisions
Section titled “Parked delivery decisions”Two decision points appear after the run reaches a release state. They are delivery control surfaces, not run statuses — the run status around them is a terminal or an operator pause.
| Decision point | Trigger | Allowed actions |
|---|---|---|
| Correction gate | Final acceptance rejected the delivery. | fix (correction follow-up), approve (override, apply, commit), apply (override, leave uncommitted), skip (retain, do not deliver), halt (mark the run halted). |
| Dirty target pause | The project checkout changed while the run worked. | retry (re-check after cleanup), skip (keep the diff in run artifacts), halt (mark the run halted). |
Interactive runs present these as menus; MCP clients use orcho_delivery_gate
to read the parked state and orcho_delivery_decide to act. Details in
Delivery control.
How states change
Section titled “How states change”events.jsonl events.jsonl, and its
class decides what resume may do.
Green terminals are settled — the active handoff is
cleared. Red failed keeps the handoff: an
undecided decision is never erased. The amber pause hands
the wheel to the operator, whose decision is the only way back to
running. A process that dies mid-flight leaves any live
status torn as interrupted — repaired
offline or decided by the operator, never silently resumed.
One rule is load-bearing: settled terminals (done, halted, cancelled)
must not carry an active handoff, so reaching them clears it. failed and
interrupted intentionally preserve the active handoff — the operator may
still need to resolve that decision, so nothing is allowed to erase it.
Cross-project runs differ on one point: a cross terminal never preserves a
handoff, even for failed. Any handoff left after a cross terminal is stale
and safely repairable.
Deep reference
Section titled “Deep reference”The canonical engineering doc lives with the code:
- docs/architecture/run_state_machine.md — full transition matrices, state writers, and torn-shape repair policy