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.