Statuses, outcomes, and exit codes
Run states, step outcomes, typed reason codes, and CLI exit codes, generated from the enumerations in the factory binary.
Statuses, outcomes, and exit codes
Run states, step outcomes, typed reason codes, and CLI exit codes, generated from the enumerations in the factory binary.
Run states
| State | Description | User transitions |
|---|---|---|
queued | Waiting to start. | stop_run |
running | Pipeline steps are in progress. | stop_run |
waiting_for_human | Stopped at a gate for a person to approve or reject. | approve, reject, stop_run |
finalizing | Running finally steps after the pipeline decided an outcome. | stop_run |
succeeded | The run finished successfully. | — |
failed | The run finished with a failure. | requeue, restart |
rejected | A step rejected the work. | — |
stopped | Stopped by a person or the watchdog. | requeue, dismiss, restart |
needs_attention | Finished in a state that needs a person. | dismiss, requeue, resume_failed, restart |
Step outcomes
| Outcome | Description |
|---|---|
ok | The step finished successfully. |
fail | The step failed. |
retry | The step asked to be tried again. |
reject | The step rejected the work. |
skipped | The step did not run. |
killed | The factory stopped the step. |
Reason codes
| Code | Description |
|---|---|
ok | The step finished successfully. |
unclear_spec | The spec is too unclear to implement. |
unclear_plan | The Work order plan has problems that block it. |
tests_failed | Tests still fail after the change. |
no_red_test | The step could not produce a failing test first. |
review_findings | Review reported findings that block the step. |
verification_failed | Verification commands did not pass. |
no_changes | The step made no changes. |
nothing_to_learn | The retro step found nothing to propose. |
not_confirmed | A person did not confirm the work. |
timeout | The step ran past its time limit. |
protocol_error | The step broke the step protocol. |
protocol_version | The step does not speak a protocol version this factory accepts. |
crashed | The step process crashed or could not start. |
retries_exhausted | Retries ran out. |
rate_limited | An upstream model or API rate-limited the step. |
usage_limit | A provider usage limit is reached; the run is suspended until the window has room. |
model_error | The model returned an error. |
dependency_missing | A required command or tool is missing. |
permission_denied | The process was not allowed to run. |
worktree_modified | The worktree was modified outside the step. |
repo_modified | The repo was modified outside the step. |
budget_exhausted | The run spent its dollar budget. |
bad_condition | A when-condition could not be evaluated. |
not_implemented | This built-in step is not implemented yet. |
worktree_dirty | The worktree had uncommitted changes. |
nothing_to_deliver | The branch has no changes against its base. |
git_error | A git command failed. |
deliver_restore_failed | Delivery failed and the branch could not be restored. |
bad_request | The step request was invalid. |
command_env_failed | The repo's command environment failed. |
check_error | A milestone check could not run. |
secret_missing | A declared secret has no stored value. |
secret_unavailable | The secret store backend is not available. |
secret_not_declared | The handshake listed a secret the step env does not declare. |
provider_not_allowed | The step's provider is no longer allowed on this machine. |
output_invalid | The step did not return JSON that matches its output schema. |
effects_invalid | The step returned effects that failed validation, so none were applied. |
effects_failed | An effect applier failed; remaining effects were skipped. |
effects_awaiting_approval | Outside effects are waiting for kusaw effects apply or reject. |
plan_invalid | The planner returned a plan the factory refused. |
ownership_violation | A subtask changed files it does not own. |
gather_conflict | Gathering a subtask conflicted with work already on the parent. |
no_candidate_passed | None of the candidates passed verify, so nothing was delivered. |
wrong_workflow | The step says this task belongs in another workflow. |
connector_error | A connector call failed, or required connector context could not be loaded. |
connector_needs_input | A connector tool asked for input the factory does not collect. |
connector_tool_changed | A connector tool changed since it was last checked. |
tracker_item_closed | The tracker item was closed while this run was going. |
signing_failed | Signing a delivered commit failed. |
signing_locked | The signing key was locked, so the run could not start or parked at the signing gate. |
git_control_modified | A step changed git control files; they were put back. |
git_control_restore_failed | A step changed git control files and the factory could not put them back. |
ports_exhausted | No free port block remained for this worktree set. |
service_failed | A declared service exited early or was not ready in time. |
CLI exit codes
| Code | Name | Description |
|---|---|---|
| 0 | ok | Success. |
| 1 | error | Runtime error. |
| 2 | usage | Usage or validation error. |
| 3 | rejected | Control request rejected; the error string is printed verbatim. |
| 4 | not picked up | Control request not picked up within the wait time while serve runs. |