Skip to content

Commit a770533

Browse files
committed
Merge origin/main into docs/adr-0023-slim
2 parents dc9d5fb + b24ecf2 commit a770533

79 files changed

Lines changed: 3597 additions & 3292 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎contracts/fixtures/dispatch-disclosure.json‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -588,5 +588,59 @@
588588
"producer": "web-agent-browser",
589589
"trigger": "a coordinate fill whose click returned and whose in-page selection found no editable field the click reached: the fill is refused before any text is sent, and the failure reports unknown with details.dispatchedSteps 4",
590590
"dispatched": "unknown"
591+
},
592+
{
593+
"id": "daemon-client.socket-closed-after-send",
594+
"producer": "daemon-client",
595+
"trigger": "the daemon closed the socket after reading a press request and before replying; the request was sent, so the client discloses the press's declared mutates-app effect",
596+
"dispatched": "unknown"
597+
},
598+
{
599+
"id": "daemon-client.http-reset-after-send",
600+
"producer": "daemon-client",
601+
"trigger": "the daemon reset the HTTP connection after reading a press request and before replying",
602+
"dispatched": "unknown"
603+
},
604+
{
605+
"id": "daemon-client.invalid-response-after-send",
606+
"producer": "daemon-client",
607+
"trigger": "the daemon answered a press request over the socket with a line that is not a JSON-RPC response",
608+
"dispatched": "unknown"
609+
},
610+
{
611+
"id": "daemon-client.timeout-after-send",
612+
"producer": "daemon-client",
613+
"trigger": "the client's request window expired after it sent a press request to a remote daemon that never answered",
614+
"dispatched": "unknown"
615+
},
616+
{
617+
"id": "daemon-client.read-failure-after-send",
618+
"producer": "daemon-client",
619+
"trigger": "the daemon closed the socket after reading a snapshot request; snapshot declares observes-app, so nothing app-visible ran",
620+
"dispatched": "no"
621+
},
622+
{
623+
"id": "daemon-client.refused-before-send",
624+
"producer": "daemon-client",
625+
"trigger": "the socket connection was refused before a press request could be written",
626+
"dispatched": "no"
627+
},
628+
{
629+
"id": "daemon-client.delegated-composite-after-send",
630+
"producer": "daemon-client",
631+
"trigger": "the daemon closed the socket after reading a batch request; batch declares a delegated ref-frame effect, so its nested requests may have acted",
632+
"dispatched": "unknown"
633+
},
634+
{
635+
"id": "daemon-client.artifact-fetch-after-answer",
636+
"producer": "daemon-client",
637+
"trigger": "a remote daemon answered a press request with an artifact, then the artifact download failed; the daemon ran the request",
638+
"dispatched": "unknown"
639+
},
640+
{
641+
"id": "daemon-client.http-refused-before-send",
642+
"producer": "daemon-client",
643+
"trigger": "the HTTP connection was refused before a press request could be sent; the request never left the client",
644+
"dispatched": "no"
591645
}
592646
]

‎docs/adr/0010-error-system.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
- If the per-code default hint would mislead, supply a hint. If the default suffices, omit the hint.
1717
- When you wrap an error, preserve an existing hint and the cause chain.
1818
- Every consumer surface must carry at least code, message, and hint. Rehydration helpers copy all fields.
19+
- A failed CLI command prints one summary line (code, message, dispatch fact, Next step) first and, when anything follows it, last. The diagnostic id is not printed.
1920
- The router's thrown-error finalizer attempts a diagnostics flush. `diagnosticId` requires an active request diagnostics scope, and `logPath` appears only when that flush produces a file. Returned or pre-scope failures may omit both fields. Messages must not embed raw stderr dumps or secrets.
2021

2122
## Context
@@ -92,6 +93,30 @@ Nothing documented the conventions, so each new site decided them again.
9293
Messages must not embed raw stderr dumps or secrets.
9394
Structured context belongs in `details`, which is redacted at normalize/write time.
9495

96+
7. **CLI human failure output.** stderr opens with one summary line and, when anything follows it,
97+
closes with the same line: `Error (CODE): <message>. <dispatch fact> Next: <step>`.
98+
The dispatch fact is `Not dispatched.` or `May have reached the device.` from `details.dispatched`;
99+
an unclassified failure states none. `Next` is the hint; an ambiguous match with two or three
100+
candidates lists them instead, and an `INVALID_ARGS` failure for a known command appends its synopsis. When
101+
`details.dispatched` is `unknown`, `Next` starts with an observe-first step. The formatter adds
102+
it from the final disclosure when it prints the line, because batch aggregation, the request
103+
ledger and replay projection can raise the disclosure after the hint was resolved; the hint
104+
itself depends on the code only.
105+
The body between the copies holds the cause, warnings, candidates, the `Log:` path, and the
106+
`--debug` details and log tail. The diagnostic id is not printed; it stays in `--json`.
107+
Reason: agents merge stderr into stdout and keep `head -1` or, most often, `tail -1`; a footer-last
108+
layout hides the code under `tail -1`. Measurements: `docs/evidence/cli-failure-summary-eval-2026-11-07.md`.
109+
Consequence: a default hint is printed as an instruction, so `defaultHintForCode` never asks for a
110+
`--debug` rerun when a log already exists, and any retry a hint implies follows the observe-first
111+
step whenever the request may have dispatched.
112+
Rejected: footer last (npm style), which loses the error under `tail`; error last only, which breaks
113+
`head -1` readers; hiding the log path behind `--debug`, which forces a rerun to find evidence the
114+
failure already wrote.
115+
Open gap: live output starts before the outcome is known: command progress lines (for example
116+
from `doctor`) and the `--debug` daemon log stream. When a command streams either, only the last
117+
line is guaranteed to be the summary. Buffering live output was rejected because it hides
118+
progress from a reader who waits on a slow command, which is what the stream exists for.
119+
95120
## Consequences
96121

97122
- Agents can branch on `code`, retry on `retriable`, and follow `hint` without prose parsing.

‎docs/adr/0011-interaction-guarantee-contract.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,6 +205,13 @@ Before the ledger holds a sent mutation, the registry's `recordingEffect` decide
205205
- For `'observes-app'`, the router sets `no` over any producer value.
206206
- A command with no declared effect passes through.
207207

208+
`resolveCommandDispatchDisclosure` in the command registry owns this verdict.
209+
The client starts from this verdict for its own transport failures, because the router never sees them.
210+
A failure after the request left the client gets the verdict: a timeout, a connection lost after the send, or a reply it cannot read or parse.
211+
The client has no ledger, so it adds one rule: a sent delegating composite (`batch`, `replay`, `test`, declared `refFrameEffect: 'delegated'`) is `unknown`.
212+
The router needs no such rule: each nested request discloses itself, and a sent nested mutation makes the ledger nonzero.
213+
A failure before the send is `no`.
214+
208215
For a read, `no` means that a resend repeats no app-visible action.
209216
The registry declares `record`, `trace`, and `perf` as `'observes-app'`, although their recorder and profiler controls reach the device.
210217
There are two reasons:

0 commit comments

Comments
 (0)