Error and Exit Code Reference

Exit Codes

Code	Meaning	Retryable
0	success (including empty results)	n/a
1	user-input-error	no
2	safety-block (refused; a –force form may exist)	no
3	tool-environment-error (ordinary tool-environment failures use ok:false with errors; doctor readiness failures use ok:true, empty errors, and data.ready:false, so envelope consumers key off data.ready for doctor)	n/a
4	transient-failure (retry after a short delay)	yes
5	conflict (state changed underneath)	no
6	job-outcome-failure (an awaited job ended non-success) (pairs with ok:true and empty errors[]; the tool call succeeded and the exit code carries the job outcome for shell use; envelope consumers key off data.all_succeeded, not the exit code)	no

Code	Exit Code	Summary	Retryable
`CONFLICT`	5	The requested mutation conflicts with current job state.	no
`IDEMPOTENCY_CONFLICT`	5	An active idempotency key was reused with a different execution payload.	no
`INTERNAL`	3	The CLI or environment failed outside a user-input contract path.	n/a
`INVALID_INPUT`	1	A supplied value has the wrong type, range, enum, or grammar.	no
`LOCKED`	4	The queue database stayed busy beyond the configured lock timeout.	yes
`MISSING_REQUIRED`	1	A required verb, flag value, or positional argument is absent.	no
`NOT_FOUND`	1	The requested job or attempt does not exist.	no
`SAFETY_BLOCK`	2	A destructive or interrupting action was refused without explicit confirmation.	no
`TIMEOUT`	4	A wait-style operation exceeded its declared time budget.	yes
`UNKNOWN_COMMAND`	1	The requested verb is not implemented by this CLI.	no
`UNKNOWN_FLAG`	1	A flag is not accepted by the selected command surface.	no

Code	Summary
`IDEMPOTENCY_METADATA_DIFFERS`	An active idempotent add matched execution payload but ignored metadata differences.
`KILL_ASYNC`	A running cancel has been recorded; process-group termination is asynchronous.
`NO_ATTEMPTS_YET`	A job exists but no attempt output can be read yet.
`TAG_FILTER_SCAN_CAPPED`	A list tag filter scanned a bounded prefix and may have omitted later matches.

Failure reasons are recorded on attempts to indicate why an attempt ended. The canonical order is preserved from the contract.

Reason	Recorded By
`process_exit`	worker execution
`timeout`	worker execution
`spawn_failed`	worker execution
`worker_crash`	reaping
`canceled`	cancel and force-retry
`unknown`	historical backfill (ambiguous pre-v6 failures)

These verbs have destructive or interrupting actions that require explicit confirmation.

These codes relate to idempotency key handling on the add verb.

Code	Type	Summary
`IDEMPOTENCY_CONFLICT`	errors	An active idempotency key was reused with a different execution payload.
`IDEMPOTENCY_METADATA_DIFFERS`	warnings	An active idempotent add matched execution payload but ignored metadata differences.