# blocker and conflict codes

The envelope's `error.code`, persisted `blockers[].code`, and structured Conflicts are different surfaces. A readiness reason can appear inside a `service_failed` detail; it is not necessarily a separate Blocker code. Remedies below describe the action; use current `next_actions` for exact IDs and revisions.

## request and admission codes

| code | condition | remedy |
| --- | --- | --- |
| `invalid_config` | schema, YAML, reference or source-input validation fails | fix the reported path / file / line; explain the effective value |
| `invalid_request` | arguments, checkout, unknown named action or control target invalid | correct the request from CLI help |
| `session_exists` | Workspace has a non-ended Session | inspect it; end deliberately before a new Session |
| `no_session` | request needs a registered Session / Project | start or adopt in the intended checkout |
| `no_free_port` | allocation range cannot satisfy start | free ports or restart daemon with a suitable range |
| `idempotency_key_reused` | key reused for incompatible intent | inspect original request; retain its key for retries |
| `operation_in_progress` | mutation or retained impact prevents admission | inspect the referenced Operation; settle it before incompatible work |
| `invalid_state` | lifecycle, resource ownership or other precondition invalid | inspect status and the specific error detail |
| `config_changed` | effective config or declared source inputs differ from pinned evidence | review changes; end and start a new Session |
| `permission_required` | a launch lacks a declared permission | use the current upgrade Remedy if compatible, or choose reviewed private allocation in a new Session |
| `claim_conflict` | incompatible holder or Claim request | inspect holders; choose a private or explicit allocation-time fork policy |
| `claim_changed` | Claim/Binding revision no longer matches the request | read fresh status and use a current revision |
| `prune_changed` | deletion preview is stale | review a fresh prune preview |

A permission Conflict additionally reports its `cause`, optional `rule`, Resource, matched paths, missing permissions, Allocation/Binding generations and Remedies. A Conflict can coexist with a running Session.

## persisted blockers

| code | meaning | remedy |
| --- | --- | --- |
| `service_failed` | startup failed; detail includes readiness / exit cause and log | inspect log, fix the Service, end and start |
| `service_exited` | previously ready Run exited | inspect exit/log; decide whether to restart the Session |
| `run_unknown` | exact execution is not known | inspect runner and Run; never repeat on a guess |
| `stop_unknown` | lifecycle cannot prove process-group stop | restore evidence or inspect before explicit abandon |
| `runner_lost` | runner unreachable | inspect processes; recover using the same Installation |
| `runner_incompatible` | runner cannot be trusted as the expected execution | inspect version / incarnation; do not signal unproven processes |
| `command_failed` | named command failed, was refused before start, or exceeded execution timeout | inspect Run/log and stop evidence; use explicit linked retry when eligible |
| `command_unknown` | arbitrary command execution or group completion uncertain | inspect/cancel the exact Run; retain its resource impact |
| `command_stop_unknown` | explicit cancel cannot confirm exact group stop | preserve holds and inspect the existing execution |
| `prune_failed` | an exact release failed or became uncertain | inspect the original prune; retry only its remaining releases |
| `resource_failed` | provisioning/validation failed or became uncertain | inspect the exact Allocation; reconcile only proven-quiescent retained work after end |
| `workspace_failed` | checkout creation failed | inspect the requested path and git worktree registry |
| `workspace_unknown` | interrupted checkout creation cannot be established | inspect existing checkout before correction or retry |

Launch refusals can also persist admission codes such as `permission_required` as Blockers.

## readiness detail reasons

| reason | remedy |
| --- | --- |
| `port_taken` | stop only the process you independently own or fix a server ignoring its assigned port; do not kill the foreign listener by guess |
| `ipv6_only` | bind the server to `127.0.0.1` |
| `ambiguous_listener` | resolve unverified listener ownership; a passing probe is insufficient |
| `timeout` | inspect startup/logs and probe path; adjust Service timeout only after diagnosing |
| `spawn_failed` | fix executable, work directory, secret reference or environment |
| `exited` | inspect the exit code and log |

## runtime failures

Infrastructure errors also use literal diagnostic codes: `bad_request`, `bad_response`, `client_error`, `config_create_failed`, `config_unreadable`, `config_write_failed`, `daemon_unavailable`, `daemon_unreachable`, `exclude_failed`, `executor_halted`, `git_inspect`, `git_reference`, `git_unavailable`, `home_error`, `log_unreadable`, `package_unreadable`, `state_error`, `workspace_conflict`, `workspace_path`. These describe I/O or internal failure surfaces rather than a stable lifecycle transition. Read `error.message` and any `path`, preserve unknown ownership, and follow current Remedies. Do not edit `state.db` to bypass a Blocker.