- Status: accepted
- Date: 2026-07-03
Amended by ADR 0019. Existing normalization and cause-preservation rules remain accepted. If an operation and binding/resource cleanup both fail, the operation remains primary. In that case, the cleanup failure is structured secondary diagnostic evidence. If only cleanup fails, the cleanup failure surfaces normally.
- Every thrown error that a user or agent can reach is an
AppError. Reserve bareErrorfor provably unreachable invariants. - For input validation, throw
AppError('INVALID_ARGS', ...). To coerce an unknown caught error, useasAppError(err, fallbackCode). - Use the most specific
KnownAppErrorCode. Put machine-dispatchable sub-classification indetails.reason. - If the per-code default hint would mislead, supply a hint. If the default suffices, omit the hint.
- When you wrap an error, preserve an existing hint and the cause chain.
- Every consumer surface must carry at least code, message, and hint. Rehydration helpers copy all fields.
- Failed requests always flush diagnostics. Messages must not embed raw stderr dumps or secrets.
The error system is centralized in packages/kernel/src/errors.ts (AppError, normalizeError, defaultHintForCode, retriableForErrorCode).
However, approximately 1,200 construction sites exist across the CLI, daemon, and platform layers.
A July 2026 audit combined a code sweep with iOS/Android dogfooding.
It found the kernel sound, but call-site quality had drifted:
- Internal validation threw bare
Error, which surfaced asUNKNOWNwith a misleading hint. - Some codes were semantically wrong, such as
COMMAND_FAILEDfor busy devices andINVALID_ARGSfor expired server-side resources. - The most common agent failures, selector/ref misses, had no hints.
- Some consumers dropped fields; for example, MCP tool errors carried only
message.
Nothing documented the conventions, so each new site decided them again.
- Every thrown error a user or agent can reach is an
AppError. Barethrow new Error(...)is reserved for provably unreachable invariants. Input validation, including daemon-side decoding of command input, throwsAppError('INVALID_ARGS', ...). To coerce an unknown caught error, useasAppError(err, fallbackCode), which preserves the cause chain. Do not hand-rollerr instanceof AppError ? err : new AppError(...). - Code selection. Use the most specific
KnownAppErrorCode.COMMAND_FAILEDis for genuine runtime failures of a well-formed request. Never useCOMMAND_FAILEDas a catch-all for these cases:- Capability gaps. Use
UNSUPPORTED_OPERATION. - Contention. Use
DEVICE_IN_USE. - Ambiguity. Use
AMBIGUOUS_MATCH.DEVICE_IN_USEis the only code that is retriable by default. The cross-worktree device-claim path overrides that default toretriable: false. Add new codes to the union deliberately. Machine-dispatchable sub-classification goes indetails.reason; the lease registry is the model.
- Capability gaps. Use
- Hints answer "what should the agent run next".
If the per-code default from
defaultHintForCodewould mislead, a hint is required. If the default suffices, omit the hint. Boilerplate hints added in bulk are worse than the default. Shared failure modes get shared hint constants next to the code that detects them, not copy-pasted strings:selectorFailureHintandSTALE_REF_HINTinpackages/selectors/src/internal/resolve.ts.resolveIosDevicectlHint.bootFailureHint. A re-wrap preserves an existing hint instead of overwriting it.
- Wrapping external tool failures. Prefer
exec.tserrors as they are. A hand-rolled wrap of anallowFailureresult must carry{ stdout, stderr, exitCode, processExitError: true }. Thus,normalizeErrorcan surface the first meaningful stderr line instead of "tool exited with code N". - The wire error contract contains:
code.message.hint.details(redacted).diagnosticId.logPath.- Optional typed signals
retriable/supportedOn. The typed signals are absent unless they are confidently known. Every consumer surface must carry at least code, message, and hint: - CLI human output.
- CLI
--json. - SDK.
- MCP.
- Events timeline.
Rehydration helpers (
throwDaemonError,toDaemonHttpRpcError) copy all fields.NormalizedErrorhoists the typed signals, so--jsonconsumers see them.
- Observability. Failed requests always flush diagnostics.
A
diagnosticIdand an ndjsonlogPathaccompany every error. Daemon-side diagnostics are under the session state dir. Client-side diagnostics are under~/.agent-device/logs. Messages must not embed raw stderr dumps or secrets. Structured context belongs indetails, which is redacted at normalize/write time.
- Agents can branch on
code, retry onretriable, and followhintwithout prose parsing. Wording can improve without breaking consumers, except for strings that help-text guarantees pin. If you change one of those strings, update its tests in the same change. - The known-code union stays small and meaningful.
The widened
(string & {})type still lets runner/daemon codes pass through, so SDK consumers keep adefaultbranch. - New call sites have a documented bar:
- The correct code.
- A contextual message that names the target.
- A hint only when the default misleads.
- A preserved cause.