Skip to content

Commit b30373d

Browse files
thymikeeclaude
andcommitted
fix(daemon-client): disclose dispatch on a client-side request timeout
When the CLI's daemon request window expired, the client threw "Daemon request timed out" with no details.dispatched and a hint that began "Retry with --debug". A timed-out tap that may have landed then printed a line whose Next step was a blind rerun. The timeout now discloses dispatch from the command's declared effect: "no" for a read (observes-app), "unknown" for everything else, so a tap prints "May have reached the device" with the snapshot-first step. The timeout, daemon-startup, launch and perf hints no longer ask for a --debug rerun; they point at the request log, daemon.log or --json. Also qualify the evidence page headline and fix its C/B sentence, and rename the stderr writer to writeHumanError so it no longer shares a name with the CLI's printHumanError. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 593a75e commit b30373d

14 files changed

Lines changed: 72 additions & 38 deletions

‎docs/evidence/cli-failure-summary-eval-2026-11-07.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# CLI failure summary line evaluation, 2026-11-07
22

3-
Small models recovered correctly from every failure when stderr opened and closed with one summary line that carried the error code, the dispatch fact and a runnable Next step. With the layout before the change, 58% recovered. Without the closing copy of the summary, recovery under `tail -1` fell to 11%. ADR 0010 decision 7 records the resulting rule.
3+
In one run per cell over synthetic, author-written and author-graded renders, layout D (one summary line first and last, with the dispatch fact and a runnable Next step) recovered in 192 of 192 answers; the layout before the change recovered in 58%. Without the closing copy of the summary, recovery under `tail -1` fell to 11%. ADR 0010 decision 7 records the resulting rule.
44

5-
These are synthetic renders of real failure scenarios, not live CLI runs. The author wrote the Next text and the answer key, so the 100% result partly measures whether a model follows a correct Next step. The wrong-Next condition below measures that directly.
5+
Treat these numbers as directional. The renders are synthetic, not live CLI runs. The author wrote the Next text, the answer key and the grader, so the D result partly measures whether a model follows a correct Next step; the wrong-Next condition below measures that directly. Each cell ran once, so differences of a few points are within run noise.
66

77
## How agents trim output
88

@@ -19,7 +19,7 @@ Twelve failure scenarios used codes, messages and hints taken from the codebase:
1919
| C: summary first and last, hints unchanged | 69% | 6% | 13% | 98% | 95% |
2020
| D: C with a runnable Next step | 100% | 0% | 0% | 97% | 96% |
2121

22-
Under `tail -1`, the error code was visible in 0% of A and B answers and in 100% of C and D answers. C recovered little better than B because the old generic hint ("Retry with --debug") became an instruction once it was labelled Next; under C, all three models that saw only the summary line reran a selector miss with `--debug`.
22+
Under `tail -1`, the error code was visible in 0% of A and B answers and in 100% of C and D answers. C recovered slightly less than B (69% against 71%, within run noise). A hypothesis that fits the answers: the old generic hint ("Retry with --debug") became an instruction once it was labelled Next. For the selector miss cut to one line under C, three of the four models reran the command with `--debug`.
2323

2424
## Isolating the repeat and blind obedience
2525

‎packages/daemon-client/src/__tests__/daemon-client-timeout-route.test.ts‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,7 @@ async function startStandIn(
201201
return { server, port, connections: () => connections };
202202
}
203203

204-
async function expectRouteError(run: Promise<unknown>, hintPattern: RegExp): Promise<void> {
204+
async function expectRouteError(run: Promise<unknown>, hintPattern: RegExp): Promise<AppError> {
205205
let thrown: unknown;
206206
try {
207207
await run;
@@ -225,6 +225,7 @@ async function expectRouteError(run: Promise<unknown>, hintPattern: RegExp): Pro
225225
[],
226226
'a timeout must not also diagnose a transport failure',
227227
);
228+
return thrown;
228229
}
229230

230231
beforeEach(() => {
@@ -249,6 +250,11 @@ type RouteRow = Readonly<{
249250
connections: 1 | 2;
250251
/** Whether this row's verdict is the reset branch, which clears the daemon's metadata. */
251252
resets: boolean;
253+
/**
254+
* The request was already sent, so a command declared to mutate the app may have run on the
255+
* device; only a declared read proves it did not. The CLI prints this as the dispatch fact.
256+
*/
257+
dispatched: 'no' | 'unknown';
252258
}>;
253259

254260
// The `ios` declarations are deliberate: eligibility never keyed off the declared platform, and
@@ -263,6 +269,7 @@ const ROUTE_ROWS: readonly RouteRow[] = [
263269
afterFirst: 'answer',
264270
hintPattern: /The timed-out open request was canceled; the daemon was kept alive/,
265271
connections: 2,
272+
dispatched: 'unknown',
266273
resets: false,
267274
},
268275
{
@@ -273,6 +280,7 @@ const ROUTE_ROWS: readonly RouteRow[] = [
273280
afterFirst: 'answer',
274281
hintPattern: /the daemon was kept alive so the session can still be closed or inspected/,
275282
connections: 2,
283+
dispatched: 'unknown',
276284
resets: false,
277285
},
278286
{
@@ -283,6 +291,7 @@ const ROUTE_ROWS: readonly RouteRow[] = [
283291
afterFirst: 'refuse',
284292
hintPattern: /The daemon did not answer the liveness probe and was reset after the timeout/,
285293
connections: 2,
294+
dispatched: 'unknown',
286295
resets: true,
287296
},
288297
{
@@ -296,6 +305,7 @@ const ROUTE_ROWS: readonly RouteRow[] = [
296305
hintPattern:
297306
/The timed-out snapshot request was canceled; the daemon was kept alive.*prepare ios-runner/s,
298307
connections: 1,
308+
dispatched: 'no',
299309
resets: false,
300310
},
301311
{
@@ -312,6 +322,7 @@ const ROUTE_ROWS: readonly RouteRow[] = [
312322
hintPattern:
313323
/^The daemon may still be exporting the recording\. Run agent-device record stop --session default again/,
314324
connections: 1,
325+
dispatched: 'no',
315326
resets: false,
316327
},
317328
{
@@ -321,8 +332,9 @@ const ROUTE_ROWS: readonly RouteRow[] = [
321332
command: RESET_POLICY_COMMAND,
322333
platform: 'android',
323334
afterFirst: 'answer',
324-
hintPattern: /verify the remote daemon URL, auth token, and remote host logs/,
335+
hintPattern: /Verify the remote daemon URL, auth token, and remote host logs/,
325336
connections: 1,
337+
dispatched: 'unknown',
326338
resets: false,
327339
},
328340
];
@@ -356,7 +368,7 @@ for (const row of ROUTE_ROWS) {
356368
: undefined;
357369
try {
358370
const info = registered ?? standInInfo(row, daemon.port);
359-
await expectRouteError(
371+
const error = await expectRouteError(
360372
sendRequest(
361373
info,
362374
buildRequest(row.command, row.platform, row.positionals),
@@ -367,6 +379,10 @@ for (const row of ROUTE_ROWS) {
367379
),
368380
row.hintPattern,
369381
);
382+
assert.equal(error.details?.dispatched, row.dispatched);
383+
// The hint is printed as the Next step; a failure that already wrote its log never asks for
384+
// a --debug rerun.
385+
assert.equal(/--debug/.test(String(error.details?.hint)), false);
370386
assert.equal(daemon.connections(), row.connections, 'probe-vs-skip is a route decision');
371387
assert.equal(
372388
fs.existsSync(statePaths.infoPath),

‎packages/daemon-client/src/__tests__/daemon-client-timeout.test.ts‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ test('request timeout hint names an Apple runner only on a declared Apple platfo
1717
command: 'press',
1818
applePlatformDeclared: true,
1919
}),
20-
'Retry with --debug and check daemon diagnostics logs. The timed-out press request was canceled; the daemon was kept alive so the session can still be closed or inspected.',
20+
'The timed-out press request was canceled; the daemon was kept alive so the session can still be closed or inspected. Read the request log for the timed-out step.',
2121
);
2222
assert.equal(
2323
resolveRequestTimeoutHint({
@@ -26,7 +26,7 @@ test('request timeout hint names an Apple runner only on a declared Apple platfo
2626
command: 'snapshot',
2727
applePlatformDeclared: true,
2828
}),
29-
'Retry with --debug and check daemon diagnostics logs. The timed-out snapshot request was canceled; the daemon was kept alive so the session can still be closed or inspected. If this was the first Apple-platform snapshot on the device, run agent-device prepare ios-runner with the same --platform before snapshot/test so runner startup is handled explicitly.',
29+
'The timed-out snapshot request was canceled; the daemon was kept alive so the session can still be closed or inspected. Read the request log for the timed-out step. If this was the first Apple-platform snapshot on the device, run agent-device prepare ios-runner with the same --platform before snapshot/test so runner startup is handled explicitly.',
3030
);
3131

3232
// An undeclared or declared non-Apple platform names no Apple runner in any branch, and the
@@ -38,7 +38,7 @@ test('request timeout hint names an Apple runner only on a declared Apple platfo
3838
command: 'snapshot',
3939
applePlatformDeclared: false,
4040
}),
41-
'Retry with --debug and check daemon diagnostics logs. The timed-out snapshot request was canceled; the daemon was kept alive so the session can still be closed or inspected.',
41+
'The timed-out snapshot request was canceled; the daemon was kept alive so the session can still be closed or inspected. Read the request log for the timed-out step.',
4242
);
4343

4444
// A reset is now reported as what it was decided from: an unanswered liveness probe. The reset
@@ -52,7 +52,7 @@ test('request timeout hint names an Apple runner only on a declared Apple platfo
5252
command: 'open',
5353
applePlatformDeclared,
5454
}),
55-
'Retry with --debug and check daemon diagnostics logs. The daemon did not answer the liveness probe and was reset after the timeout.',
55+
'The daemon did not answer the liveness probe and was reset after the timeout. Read the request log for the timed-out step.',
5656
);
5757
}
5858

@@ -64,7 +64,7 @@ test('request timeout hint names an Apple runner only on a declared Apple platfo
6464
command: 'press',
6565
applePlatformDeclared: false,
6666
}),
67-
'Retry with --debug and verify the remote daemon URL, auth token, and remote host logs.',
67+
'Verify the remote daemon URL, auth token, and remote host logs.',
6868
);
6969
});
7070

@@ -115,7 +115,7 @@ test('a timed-out record stop on a surviving daemon names the retry that returns
115115
action: 'stop',
116116
session: 'recording',
117117
}),
118-
'Retry with --debug and check daemon diagnostics logs. The daemon did not answer the liveness probe and was reset after the timeout.',
118+
'The daemon did not answer the liveness probe and was reset after the timeout. Read the request log for the timed-out step.',
119119
);
120120
// `record start` runs no export, so it keeps the generic remote wording.
121121
assert.equal(
@@ -127,6 +127,6 @@ test('a timed-out record stop on a surviving daemon names the retry that returns
127127
action: 'start',
128128
session: 'recording',
129129
}),
130-
'Retry with --debug and verify the remote daemon URL, auth token, and remote host logs.',
130+
'Verify the remote daemon URL, auth token, and remote host logs.',
131131
);
132132
});

‎packages/daemon-client/src/daemon-client-timeout.ts‎

Lines changed: 25 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
1-
import { AppError } from '@agent-device/kernel/errors';
1+
import { AppError, type DispatchDisclosure } from '@agent-device/kernel/errors';
2+
import type { DispatchedCommand } from '@agent-device/contracts/command';
23
import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
34
import type { DaemonRetirementResult } from '@agent-device/daemon-contracts/daemon-registration-owner';
45
import { PUBLIC_COMMANDS } from '@agent-device/command-registry/catalog';
5-
import { resolveCommandTimeoutPolicy } from '@agent-device/command-registry/registry';
6+
import {
7+
resolveCommandRecordingEffect,
8+
resolveCommandTimeoutPolicy,
9+
} from '@agent-device/command-registry/registry';
610
import type { DaemonPaths } from '@agent-device/daemon-contracts/daemon-resolution';
711
import type { PlatformSelector } from '@agent-device/kernel/device';
812
import { observedDaemonIdentityOf, type DaemonInfo } from './daemon-client-metadata.ts';
@@ -35,6 +39,8 @@ export async function handleRequestTimeout(
3539
/** Named together so the recovery hint cannot be assembled from a swapped session and action. */
3640
session?: string;
3741
action?: string;
42+
/** The timed-out request, read for its declared recording effect. */
43+
request: DispatchedCommand;
3844
}>,
3945
): Promise<AppError> {
4046
const {
@@ -48,7 +54,9 @@ export async function handleRequestTimeout(
4854
platform,
4955
session,
5056
action,
57+
request,
5158
} = params;
59+
const dispatched = timedOutRequestDispatch(request);
5260
// The command's declared policy (`timeoutPolicy.onTimeout`, ADR 0008) decides whether a local
5361
// timed-out request is RESET-ELIGIBLE; the liveness probe decides whether the eligibility runs.
5462
// A remote client cannot reach the host's process table or the daemon's state dir, so a remote
@@ -96,10 +104,11 @@ export async function handleRequestTimeout(
96104
timeoutMs,
97105
requestId,
98106
reason: 'daemon_transport_timeout',
107+
dispatched,
99108
...(retirement ? { retirement, stateDir: statePaths.baseDir } : {}),
100109
hint:
101110
retirement?.status === 'retained'
102-
? `The daemon could not be safely retired. State was retained at ${statePaths.baseDir}. ${retirement.error?.hint ?? 'Retry with --debug and inspect daemon diagnostics before retrying.'}`
111+
? `The daemon could not be safely retired. State was retained at ${statePaths.baseDir}. ${retirement.error?.hint ?? 'Read the request log and daemon.log in that directory before you retry.'}`
103112
: resolveRequestTimeoutHint({
104113
remote,
105114
resetDaemon: resetDaemon,
@@ -112,6 +121,14 @@ export async function handleRequestTimeout(
112121
});
113122
}
114123

124+
/**
125+
* The request already left this process, so the daemon may have run it. Only a command the
126+
* registry declares a read (`observes-app`) cannot have changed the app.
127+
*/
128+
function timedOutRequestDispatch(request: DispatchedCommand): DispatchDisclosure {
129+
return resolveCommandRecordingEffect(request) === 'observes-app' ? 'no' : 'unknown';
130+
}
131+
115132
async function forceRetireDaemon(
116133
info: DaemonInfo,
117134
statePaths: DaemonPaths,
@@ -182,15 +199,15 @@ export function resolveRequestTimeoutHint(params: {
182199
} again to wait for that export and receive the completed recording.`;
183200
}
184201
if (remote) {
185-
return 'Retry with --debug and verify the remote daemon URL, auth token, and remote host logs.';
202+
return 'Verify the remote daemon URL, auth token, and remote host logs.';
186203
}
187204
if (resetDaemon) {
188205
// The reset SIGKILLs the daemon pid only; child processes it owned (Apple runners included)
189206
// are not proven stopped from here, so the hint claims nothing about them.
190-
return 'Retry with --debug and check daemon diagnostics logs. The daemon did not answer the liveness probe and was reset after the timeout.';
207+
return 'The daemon did not answer the liveness probe and was reset after the timeout. Read the request log for the timed-out step.';
191208
}
192209
if (stopCommand) {
193-
return `Retry with --debug and check daemon diagnostics logs. The daemon did not answer the liveness probe, and this request does not retire a daemon it did not start. Stop it with ${stopCommand}, then retry. SDK clients call ensureDaemon() to start a fresh one.`;
210+
return `The daemon did not answer the liveness probe, and this request does not retire a daemon it did not start. Stop it with ${stopCommand}, then retry. SDK clients call ensureDaemon() to start a fresh one.`;
194211
}
195212
const iosPrepareHint =
196213
applePlatformDeclared && command === PUBLIC_COMMANDS.snapshot
@@ -199,9 +216,9 @@ export function resolveRequestTimeoutHint(params: {
199216
// The daemon canceled the request when this client's connection was destroyed, and stayed
200217
// reachable (the probe answered, or the command's policy forbids the reset), so the session
201218
// survives and can still be closed or inspected.
202-
return `Retry with --debug and check daemon diagnostics logs. The timed-out ${
219+
return `The timed-out ${
203220
command ?? 'request'
204-
} request was canceled; the daemon was kept alive so the session can still be closed or inspected.${iosPrepareHint}`;
221+
} request was canceled; the daemon was kept alive so the session can still be closed or inspected. Read the request log for the timed-out step.${iosPrepareHint}`;
205222
}
206223

207224
function daemonWasForceKilled(retirement: DaemonRetirementResult | undefined): boolean {

‎packages/daemon-client/src/daemon-client-transport.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -715,6 +715,7 @@ function timeoutRequestContext(
715715
platform: req.flags?.platform,
716716
session: req.session,
717717
action: req.positionals?.[0],
718+
request: { command: req.command, positionals: req.positionals, flags: req.flags },
718719
};
719720
}
720721

‎packages/daemon-client/src/daemon-lifecycle-errors.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -215,7 +215,7 @@ export function resolveDaemonStartupHint(
215215
const artifacts = [state.hasInfo ? paths.infoPath : null, state.hasLock ? paths.lockPath : null]
216216
.filter(Boolean)
217217
.join(' and ');
218-
return `Daemon startup did not establish a reachable owner. ${artifacts ? `State was retained at ${artifacts}. ` : ''}Retry with --debug and inspect daemon diagnostics. Before upgrading, stop all older clients and daemons with their original CLI and prevent them from returning to this state directory. Unverified lock state requires confirming every user stopped before manual recovery; deleting metadata alone is not a safe reset.`;
218+
return `Daemon startup did not establish a reachable owner. ${artifacts ? `State was retained at ${artifacts}. ` : ''}Read daemon.log in the state directory. Before upgrading, stop all older clients and daemons with their original CLI and prevent them from returning to this state directory. Unverified lock state requires confirming every user stopped before manual recovery; deleting metadata alone is not a safe reset.`;
219219
}
220220

221221
export function daemonRegistrationUnprovenError(

‎packages/platform-android/src/perf.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -240,7 +240,7 @@ function resolveAndroidHeapDumpHint(stdout: string, stderr: string): string {
240240
if (text.includes('permission') || text.includes('denied')) {
241241
return 'The device denied heap dump access. Use a debug/profileable build or a device image that permits app heap dumping.';
242242
}
243-
return 'Reopen the app to refresh the process, then retry perf memory snapshot. If it still fails, run with --debug and inspect adb am dumpheap output.';
243+
return 'Reopen the app to refresh the process, then retry perf memory snapshot. If it still fails, rerun it with --json and read the adb am dumpheap output in error.details.stderr.';
244244
}
245245

246246
function parseAndroidMemInfoTopConsumers(stdout: string): AndroidMemoryConsumer[] | undefined {

‎packages/platform-apple/src/core/launch-diagnostics.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,6 @@ export function launchFailureHint(reason: LaunchFailureReason): string {
9292
case 'PERSISTENT_LAUNCH_FAIL':
9393
return 'The simulator repeatedly refused to launch the app. Inspect crash logs in Console.app or ~/Library/Logs/DiagnosticReports/ and consider reinstalling the app.';
9494
default:
95-
return 'The simulator failed to launch the app. Retry with --debug and inspect diagnostics log for details.';
95+
return 'The simulator failed to launch the app. Read the diagnostics log for the launch output.';
9696
}
9797
}

‎packages/platform-apple/src/core/perf.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -172,7 +172,7 @@ export async function captureAppleMemorySnapshot(
172172
appBundleId,
173173
pid: processInfo.pid,
174174
path: outPath,
175-
hint: 'Retry with a writable --out path. If the file is still empty, run with --debug and inspect leaks output.',
175+
hint: 'Retry with a writable --out path. If the file is still empty, rerun it with --json and read the leaks output in error.details.stderr.',
176176
});
177177
}
178178

@@ -252,7 +252,7 @@ function annotateAppleMemorySnapshotToolError(
252252
pid: processInfo.pid,
253253
processName: path.basename(readProcessCommandToken(processInfo.command)),
254254
path: outPath,
255-
hint: 'Retry perf memory snapshot. If it still fails, run with --debug and inspect leaks output.',
255+
hint: 'Retry perf memory snapshot. If it still fails, rerun it with --json and read the leaks output in error.details.stderr.',
256256
},
257257
error,
258258
);

‎scripts/__tests__/help-conformance-error-recovery-coverage.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ const WAIVED_GENERIC_HINT_CODES: Record<string, string> = {
3333
'Catch-all wrap of an underlying failure: the specific "what failed" lives in the message, so the generic diagnostics guidance IS its recovery step.',
3434
};
3535

36-
// Human error rendering (src/commands/output/human-error.ts printHumanError) opens with
36+
// Human error rendering (src/commands/output/human-error.ts writeHumanError) opens with
3737
// `Error (CODE): message`, so any rendered error text names its own code.
3838
const RENDERED_ERROR_CODE = /(?:^|\n)Error \(([A-Z_]+)\):/g;
3939

0 commit comments

Comments
 (0)