You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit b30373d
Browse filesBrowse the repository at this point in the historyBrowse files
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]>
Copy file name to clipboardExpand all lines: docs/evidence/cli-failure-summary-eval-2026-11-07.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,8 @@
1
1
# CLI failure summary line evaluation, 2026-11-07
2
2
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.
4
4
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.
6
6
7
7
## How agents trim output
8
8
@@ -19,7 +19,7 @@ Twelve failure scenarios used codes, messages and hints taken from the codebase:
19
19
| C: summary first and last, hints unchanged | 69% | 6% | 13% | 98% | 95% |
20
20
| D: C with a runnable Next step | 100% | 0% | 0% | 97% | 96% |
21
21
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`.
Copy file name to clipboardExpand all lines: packages/daemon-client/src/__tests__/daemon-client-timeout.test.ts
+7-7Lines changed: 7 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -17,7 +17,7 @@ test('request timeout hint names an Apple runner only on a declared Apple platfo
17
17
command: 'press',
18
18
applePlatformDeclared: true,
19
19
}),
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.',
21
21
);
22
22
assert.equal(
23
23
resolveRequestTimeoutHint({
@@ -26,7 +26,7 @@ test('request timeout hint names an Apple runner only on a declared Apple platfo
26
26
command: 'snapshot',
27
27
applePlatformDeclared: true,
28
28
}),
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.',
30
30
);
31
31
32
32
// 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
38
38
command: 'snapshot',
39
39
applePlatformDeclared: false,
40
40
}),
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.',
42
42
);
43
43
44
44
// 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
52
52
command: 'open',
53
53
applePlatformDeclared,
54
54
}),
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.',
56
56
);
57
57
}
58
58
@@ -64,7 +64,7 @@ test('request timeout hint names an Apple runner only on a declared Apple platfo
64
64
command: 'press',
65
65
applePlatformDeclared: false,
66
66
}),
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.',
68
68
);
69
69
});
70
70
@@ -115,7 +115,7 @@ test('a timed-out record stop on a surviving daemon names the retry that returns
115
115
action: 'stop',
116
116
session: 'recording',
117
117
}),
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.',
119
119
);
120
120
// `record start` runs no export, so it keeps the generic remote wording.
121
121
assert.equal(
@@ -127,6 +127,6 @@ test('a timed-out record stop on a surviving daemon names the retry that returns
127
127
action: 'start',
128
128
session: 'recording',
129
129
}),
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.',
? `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.'}`
103
112
: resolveRequestTimeoutHint({
104
113
remote,
105
114
resetDaemon: resetDaemon,
@@ -112,6 +121,14 @@ export async function handleRequestTimeout(
112
121
});
113
122
}
114
123
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.
@@ -182,15 +199,15 @@ export function resolveRequestTimeoutHint(params: {
182
199
} again to wait for that export and receive the completed recording.`;
183
200
}
184
201
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.';
186
203
}
187
204
if(resetDaemon){
188
205
// The reset SIGKILLs the daemon pid only; child processes it owned (Apple runners included)
189
206
// 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.';
191
208
}
192
209
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.`;
@@ -199,9 +216,9 @@ export function resolveRequestTimeoutHint(params: {
199
216
// The daemon canceled the request when this client's connection was destroyed, and stayed
200
217
// reachable (the probe answered, or the command's policy forbids the reset), so the session
201
218
// 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 ${
203
220
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}`;
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.`;
return'The device denied heap dump access. Use a debug/profileable build or a device image that permits app heap dumping.';
242
242
}
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.';
Copy file name to clipboardExpand all lines: packages/platform-apple/src/core/launch-diagnostics.ts
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -92,6 +92,6 @@ export function launchFailureHint(reason: LaunchFailureReason): string {
92
92
case'PERSISTENT_LAUNCH_FAIL':
93
93
return'The simulator repeatedly refused to launch the app. Inspect crash logs in Console.app or ~/Library/Logs/DiagnosticReports/ and consider reinstalling the app.';
94
94
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.';
0 commit comments