|
16 | 16 | - If the per-code default hint would mislead, supply a hint. If the default suffices, omit the hint. |
17 | 17 | - When you wrap an error, preserve an existing hint and the cause chain. |
18 | 18 | - 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. |
19 | 20 | - 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. |
20 | 21 |
|
21 | 22 | ## Context |
@@ -92,6 +93,30 @@ Nothing documented the conventions, so each new site decided them again. |
92 | 93 | Messages must not embed raw stderr dumps or secrets. |
93 | 94 | Structured context belongs in `details`, which is redacted at normalize/write time. |
94 | 95 |
|
| 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 | + |
95 | 120 | ## Consequences |
96 | 121 |
|
97 | 122 | - Agents can branch on `code`, retry on `retriable`, and follow `hint` without prose parsing. |
|
0 commit comments