Gantry · When a run stops

Stage outcomes

7 values from src/domain/mod.rs

How one stage of the pipeline ended. Mechanical stages (the gate, a merge) and agent stages share this set, so a card reads the same whichever ran it. The pattern language has a second, unrelated `StepOutcome` — what an `if` step tests a named step's result against — which is vocabulary for writing a pattern rather than for reading a stopped run, and is not this set.

value	as the code writes it	what it means
ok	ok	The stage finished cleanly: the agent completed its work, or the gate passed. The run carries on to the next stage.
amber	amber	Healthy, but not finished. It is reserved for goal verification, and no current build path emits it, so no stage carries it.
rejected	rejected	The agent exited cleanly and the declared verdict output it wrote rejected the work — a reviewer that wrote `retry` or `blocked`, a troubleshoot pass that wrote `handover`. The pattern's routing takes it from there, so the run carries on; the record carries the verdict word beside this token.
failed	failed	The gate came back red, or the agent did not finish its work — a reported failure, a launch error, an exhausted retry, an operator abort. The pattern's recovery steps take it from here, and the run stops only once they are exhausted.
errored	errored	A stage the engine found started with no finish, closed out on a resume after its owner died mid-task. That cleanup is the only path that writes this outcome today; an agent that failed to launch or to authenticate ends its stage as `failed`.
oversized	oversized	The agent ran out of room or time before it could finish. No build path writes it as a stage outcome today; it is kept for old journals, and a ceiling reached now is recorded as the ledger status `OVERSIZED`.
note	note	Nothing failed. The stage recorded something worth reading — a harness override, a run-record ignore notice, interrupted work discarded, leftover processes cleaned up — and the run went on.

Run dispositions

3 values from src/engine/run/projection.rs

The terminal verdict of a pattern run. The engine derives it and no step an author writes names one: a recorded stop reads as `failure`, an operator pause as `resumable-stop`, and a run that reached `RunComplete` as `success`. The stop itself is recorded separately, with a typed stop class and reason.

value	as the code writes it	what it means
success	success	The pattern run declared itself finished: the work it was given is done. For a nested run this is the verdict its parent branches on, not necessarily the end of everything.
failure	failure	The pattern run declared a failed ending, and nothing further in it will run. The stop message beside it says what failed.
resumable_stop	resumable-stop	The pattern run ended unfinished but sound — a declared partial stop such as a cycle ceiling, not a failure. Whether there is more to do, and whether re-running picks it up, is what the stop message says.

Stop classes

6 values from src/engine/pattern_language.rs

The engine-assigned classes for final stop records and `on_stop` hook selection. `any` is only a hook-table catch-all key; `record` and `merge` hooks never dispatch.

value	as the code writes it	what it means
step	step	A producing step ended as `failed` and no pattern route handled that outcome.
absence	absence	A required branch or runtime binding was absent and no pattern route handled that absence.
plan	plan	Plan handling could not produce executable work, including a planning result that produced no work.
gate	gate	A gate stop escaped ordinary gate routing, including a baseline or admission gate that failed before authored recovery could run.
record	record	The run record cannot safely support execution or resume under the active interpreter contract. It is assigned as a stop class, but record hooks never dispatch and a record stop never falls through to `any`.
merge	merge	Merge or merge-repair work could not be completed. Like `record` it is typed for reporting only: merge hooks never dispatch and a merge stop never falls through to `any`.

Stop identity routes

3 values from src/domain/mod.rs

The `stop_identity.route` values on stopped run events. The route selects which optional payload fields can be present: `class` on engine stops, and `merge_kind` beside it on a merge-class one; `operator_kind` on operator stops; none on pattern stops.

value	as the code writes it	what it means
pattern	pattern	An authored `stop` step ended the run. The stop identity carries no class, operator kind or merge sub-kind.
operator	operator	The operator paused or aborted the run. The stop identity carries an operator kind.
engine	engine	The engine stopped execution because a condition escaped authored routing. The stop identity carries a class, and merge-class stops may carry a merge sub-kind.

Stop identity classes

6 values from src/domain/mod.rs

The `stop_identity.class` values on engine stopped run events, one per engine stop class. `record` and `merge` are reporting vocabulary only: `handler_for` returns no handler for either, so neither reaches an `on_stop` hook.

value	as the code writes it	what it means
step	step	A producing step ended as `failed` and no pattern route handled that outcome.
absence	absence	A required branch or runtime binding was absent and no pattern route handled that absence.
plan	plan	Plan handling could not produce executable work, including a planning result that produced no work.
gate	gate	A gate stop escaped ordinary gate routing, including a baseline or admission gate that failed before authored recovery could run.
record	record	The run record cannot safely support execution or resume under the active interpreter contract.
merge	merge	Merge or merge-repair work could not be completed.

Stop identity operator kinds

2 values from src/domain/mod.rs

The `stop_identity.operator_kind` values on operator stopped run events.

value	as the code writes it	what it means
pause	pause	The operator requested a pause at the next engine boundary.
abort	abort	The operator requested an abort.

Stop identity merge sub-kinds

7 values from src/engine/run/finish.rs

The `stop_identity.merge_kind` values on merge-class stopped run events. The field is present only when `stop_identity.class` is `merge`.

value	as the code writes it	what it means
attempt_ceiling	attempt-ceiling	The merge repair pattern exhausted the per-state attempt ceiling.
checkout_drift	checkout-drift	The main checkout is no longer on the run's home branch, so the merge would land where the run does not belong.
finalization	finalization	The work around the merge stopped the run: the final sanity test run, the post-merge gate, committing the ledger's trailing rows, or a partial merge with nothing to ship. It is also what a merge stop carries when it names no other sub-kind.
gate_red_handover	gate-red-handover	The selected merge pattern stopped after its gate-red repair route produced a handover.
git_plumbing	git-plumbing	A git command the merge depends on failed: the check that the checkout is still on the home branch, or the verified merge itself not landing cleanly.
home_checkout_blocked	home-checkout-blocked	Git refused to start the final merge, usually because the home checkout has uncommitted or staged changes. No merge was started and nothing in the home checkout changed.
merge_repair_stopped	merge-repair-stopped	The selected merge pattern stopped before producing an integration that both merges cleanly and passes the gate.

Ledger statuses

4 values from src/engine/ledger.rs

The `status` column of a run's `PROGRESS.md` ledger, and the durable record of what a task came to. Resume re-derives which tasks are already built from this column, so `DONE` is the one status it skips and every other status is work it will pick up again.

value	as the code writes it	what it means
done	DONE	The task is built and recorded. A resume of this run skips it and moves on to the next one.
amber	AMBER	Healthy but not finished, reserved for goal verification: the task made sound progress without declaring itself done. No build path writes it today.
failed	FAILED	The task did not finish. It is also the conservative record for every ending that is not one of the other three — a stop or an abort reads as `FAILED` too — so a resume treats it as work still to do.
oversized	OVERSIZED	The task hit a harness output or context ceiling before producing acceptable work. A resume takes it again as it stands, so it meets the same ceiling unless the task is split first.

Prompt kinds

4 values from src/domain/mod.rs

What kind of answer a run is waiting for when it asks a question. A front-end renders the input from the kind; a headless run answers what its flags cover and stops with a message rather than guessing at the rest.

value	as the code writes it	what it means
confirm	confirm	A yes/no confirmation, defaulting to no. A headless run answers it yes only when `--yes` was passed, and otherwise answers no without waiting.
text	text	A free-text answer. Nothing configures a default for a headless run, so a headless run says so and stops rather than inventing one.
investigation	investigation	The run is blocked and is asking what to do about it. Its answers are the blocker choices below, one launcher token per registered harness ahead of the four fixed ones. A headless run answers `stop-run`.
choice	choice	A pick from a fixed set of options. A headless run has no way to choose, so it says so and stops; only an interactive run can answer it.

Blocker choices

5 values from src/domain/mod.rs

The answers to a blocked run's investigation prompt, as the tokens they are written as. `proceed` and `stop-run` resolve the prompt; the three launchers open something to look at and leave it waiting. `let-gantry-try` is accepted as a second spelling of `proceed` and is never offered. The harness launcher's token is `investigate-with-harness:` followed by a harness id, one per registered harness.

value	as the code writes it	what it means
investigate_with_harness	investigate-with-harness:<harness-id>	Opens that agent harness interactively in the run's worktree, for a look at the blocker. It does not resolve the prompt: the run is still waiting afterwards.
investigate_with_gantry	investigate-with-gantry	Opens the Gantry Assistant on the blocker, in the run's worktree. It does not resolve the prompt: the run is still waiting afterwards.
open_shell	open-shell	Opens a plain shell in the run's worktree. Like the other two launchers it leaves the prompt waiting.
proceed	proceed	Resolves the prompt by re-entering the run's gate-verified execution path. The run re-checks the worktree through its normal recovery path rather than trusting the answer.
stop_run	stop-run	Resolves the prompt as a stop. The worktree stays on disk with everything the run built, and `gantry resume <name>` picks it up later.

Run states

4 values from src/engine/registry.rs

Where a run sits in its lifecycle, as `gantry list` and `gantry status` print it. The state is read from the run's canonical records and its run lock: whether completion was recorded, and whether a live engine holds the lock.

value	as the code writes it	what it means
active	active	Nothing has recorded the run's completion and a live engine holds its run lock, so the run is being worked on right now.
finished	finished	The run recorded its completion: the full merge into the home branch landed and the worktree was removed. Nothing is left to resume.
partial	partial	The run's records are on disk, nothing has recorded its completion, and no live engine holds its lock — whether it was stopped, its engine died, or it merged back with only some tasks done. While its worktree is still present, the run can be resumed.
empty	empty	No durable records on disk and no live owner: the run left nothing behind to read or resume.

Process exit codes

4 values from src/engine/reference_vocabulary.rs

What the `gantry` process exits with, for a script that runs it. These four are the whole set Gantry chooses for itself. The one exception is `gantry enter`, which hands back whatever the shell it ran in the run's worktree exited with.

value	as the code writes it	what it means
success	0	The command did what was asked: a headless build run reached its end without stopping, or a management command succeeded.
failed	1	The command ran and is reporting failure — a headless run that stopped before finishing, a name that matched no run, a declined confirmation, or `gantry doctor` finding a hard requirement missing.
error	2	Gantry gave up before or during the work and said why on stderr: an argument it could not read, a plan it could not open, a preflight it could not pass. Nothing about the run's own progress is implied.
panicked	101	Gantry panicked. 101 is rustc's conventional status for a panic, which the TUI's panic hook exits with by hand so a panic inside a raw-mode terminal still reports it.