Error and exit codes

Hostwright uses stable error codes for CLI and manifest diagnostics, and a small set of process exit categories. JSON mode reports classified failures with an envelope on stderr:

{"code":"HW-CLI-001","exitCode":64,"kind":"error","message":"..."}

Error codes

Code	Meaning	Status
HW-CLI-001	Invalid CLI usage.	Implemented
HW-CLI-002	Refused to overwrite an existing file.	Implemented for init, diagnostics bundles, benchmark reports
HW-CLI-003	Confirmation token or plan hash mismatch.	Implemented for apply plan mismatch and cleanup token mismatch
HW-CLI-004	Partial operation failure.	Implemented for cleanup partial failure
HW-CLI-005	Local file I/O failed.	Implemented for init writes, stack-file import reads, diagnostics paths
HW-COMPAT-001	Unsupported CPU architecture.	Implemented in compatibility/doctor model
HW-COMPAT-002	Unsupported macOS version.	Implemented in compatibility/doctor model
HW-RUNTIME-001	Runtime adapter unavailable.	Modelled
HW-RUNTIME-002	Runtime mutation not implemented.	Modelled
HW-MANIFEST-001	Manifest parsing failed.	Implemented
HW-MANIFEST-002	Manifest validation failed.	Implemented, incl. invalid version shape, unsafe env/volume values, failed import output
HW-MANIFEST-003	Unsupported manifest/YAML feature.	Implemented, incl. unsupported fields, older/newer versions, unsupported import fields
HW-MANIFEST-004	Manifest file I/O failed.	Implemented for validate, plan, status, apply, logs, cleanup
HW-STATE-001	State store unavailable.	Implemented for invalid paths, migration failure, incompatible/future schema, corrupt or locked database, backup/restore/repair/recover failures, read/write failures
HW-SECURITY-001	Unsafe exposure.	Modelled
HW-TEAM-001	Team profile malformed, unsupported, or violates required gates.	Implemented
HW-TEAM-002	Approval record malformed, rejected, unsupported, or incomplete.	Implemented for profile-aware apply and confirmed cleanup
HW-TEAM-003	Approval scope or profile/manifest/plan binding mismatch.	Implemented as confirmation mismatch before mutation
HW-BENCH-001	Benchmark options or report contract invalid.	Implemented before file or runtime access
HW-BENCH-002	Benchmark evidence blocked by missing capability or unmeasured dimension.	Implemented, exit 69, blocked report written
HW-BENCH-003	Benchmark command, version, identity, ownership, report, or cleanup evidence failed.	Implemented, exit 72, failed report written when possible
HW-DIST-001	Distribution arguments, source binding, artifact verification, command, ownership, installed lifecycle, or recovery failed.	Implemented by hostwright-dist; the exit code (64, 65, 69, 71, or 72) identifies the failure class
HW-DIST-002	Unsigned artifact assembly or temp-prefix lifecycle succeeded, but required distribution trust stages remain blocked.	Implemented, exit 69, blocked distribution-artifact evidence
HW-SECRET-001	Secret reference, value, or managed metadata is invalid.	Implemented before unsafe mutation
HW-SECRET-002	The selected secret backend is unavailable or cannot interact noninteractively.	Implemented, exit 69
HW-SECRET-003	The exact managed secret item does not exist.	Implemented, exit 66
HW-SECRET-004	A duplicate item, unmanaged item, replacement race, or active same-secret mutation conflicts.	Implemented, exit 72
HW-SECRET-005	Keychain denied the requested operation.	Implemented, exit 71
HW-SECRET-006	The secret operation was cancelled before a safe terminal result.	Implemented, exit 72
HW-SECRET-007	The Keychain effect or durable checkpoint is partial or ambiguous.	Implemented, exit 72, with recovery guidance
HW-REGISTRY-001	Registry endpoint, scope, challenge, token, credential configuration, or response is invalid.	Implemented, exit 65
HW-REGISTRY-002	No exact registry credential or required credential helper is available.	Implemented, exit 69
HW-REGISTRY-003	The registry or Keychain denied authentication.	Implemented, exit 71
HW-REGISTRY-004	Registry TLS transport, token service, or credential helper is unavailable.	Implemented, exit 69
HW-REGISTRY-005	A challenge or token denied, or attempted to expand, the requested registry scope.	Implemented, exit 71
HW-REGISTRY-006	Registry authentication or credential lookup was cancelled.	Implemented, exit 72
HW-REGISTRY-007	Registry credential mutation or its durable checkpoint has a partial or ambiguous effect.	Implemented, exit 72
HW-IMAGE-001	Image request, reference, path, platform, progress, or structured provider result is invalid.	Implemented before unsafe mutation
HW-IMAGE-002	The selected provider or image operation is unavailable.	Implemented, exit 69
HW-IMAGE-003	A target collision, ownership mismatch, digest drift, live reference, or active image intent conflicts.	Implemented, exit 72
HW-IMAGE-004	Image ownership, filesystem identity, or destructive-operation policy denied the operation.	Implemented, exit 71
HW-IMAGE-005	Image execution was cancelled and exact compensation was attempted.	Implemented, exit 72
HW-IMAGE-006	An image provider or durable checkpoint has a partial or ambiguous effect requiring recovery.	Implemented, exit 72

“Modelled” means the code exists in the error model but the triggering surface is narrower than the general description.

Exit codes

Exit code	Category	Used for
0	Success	Completed command.
64	Usage	Invalid arguments, unsupported flags, missing required confirmation/state arguments, refused overwrite, local non-manifest file I/O failure.
65	Validation	Missing/unreadable manifest, manifest/profile/approval validation failure, unsupported manifest/import feature, compatibility failure.
66	State unavailable	The selected state database failed resolution, validation, migration, schema compatibility, locking, corruption, read/write, or a backup, restore, repair, or recover operation.
69	Runtime / tool unavailable / evidence blocked	Runtime access failed, a distribution subprocess failed, or benchmark or distribution evidence remains blocked.
70	Confirmation mismatch	Plan hash, cleanup token, state restore or repair token, approval scope, or approval hash binding does not match.
71	Unsafe operation	Planner, apply, state-repair authority, extension policy, or distribution ownership checks blocked execution.
72	Partial failure	Mixed cleanup outcome, failed benchmark evidence, failed extension handshake, or an installed lifecycle that could not complete safely.

One special case: doctor --output json reports compatibility failures as a normal doctor document on stdout with hasFailures: true and exit code 65; not as an error envelope.