Skip to content

Commit 3f5ffa8

Browse files
strzhaoclaude
andcommitted
fix(daemon): judge the remote burst on flags.count and observe the inter-frame abort
The daemon arms the burst from flags.count, so the remote policy judges that key and the policy tests drive flags and positionals as the remote client sends them. The cancel test aborts from a timer during the interval wait and asserts the abort reason with exactly one capture. The screenshot help names the remote refusal, the evidence names the SHA and frames the observed per-frame interval against the budget, the cleanup test reads the captured frame directly, and the evidence carries the md5 hashes and the json envelope. Co-Authored-By: Claude Code <[email protected]>
1 parent 77cc16f commit 3f5ffa8

3 files changed

Lines changed: 75 additions & 14 deletions

File tree

‎docs/evidence/ios-burst-capture-2026-11-13.md‎

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,12 @@
11
# Screenshot burst on an iOS simulator, 2026-11-13
22

3-
Live evidence for #4291: the burst path (`--count`/`--interval-ms`) captured
4-
five frames of an animation on real simulator dispatch. The screen was a page
3+
Live evidence for #4291 at head `7f3741906` (the format-only commit after the
4+
burst fixes; the behavior this documents is unchanged since): the burst path
5+
(`--count`/`--interval-ms`) captured five frames of an animation on real
6+
simulator dispatch. The observed per-frame interval here runs about 520-710 ms
7+
— above the plan's 500 ms per-frame budget, because each frame also pays the
8+
capture round trip the budget's doc comment excludes; the budget bounds the
9+
admission wait per frame, not the full round trip. The screen was a page
510
served to Safari on the booted iPhone 17 Pro simulator
611
(`C1C05FFF-29AD-40D8-94E5-D9CBB25EC6BB`, iOS 26.5) whose content updates every
712
50 ms (a millisecond clock and a progress bar), so consecutive frames cannot
@@ -35,4 +40,25 @@ hash the same.
3540
```
3641

3742
Five distinct md5 hashes — every frame captured a different render of the
38-
animation, and all five landed on disk beside the `--out` path.
43+
animation, and all five landed on disk beside the `--out` path:
44+
45+
```
46+
4a943cceb3b7468c40bc438b110980d4 page-0001.png
47+
7b9451fa6875aa2a1147ddeec78aee46 page-0002.png
48+
bda33d6c1e3ec2eb9b49c77dd690d265 page-0003.png
49+
df7a320a07e242ff281abea1d0358ec1 page-0004.png
50+
eb77c0c4882b8d2093c70a23b65e2cda page-0005.png
51+
```
52+
53+
The command's `--json` envelope (abridged to the identifying fields):
54+
55+
```json
56+
{
57+
"success": true,
58+
"data": {
59+
"path": "/tmp/ad-burst/frames/page-0001.png",
60+
"frames": [ "... five frames as shown above ..." ],
61+
"message": "Saved 5 screenshots starting at /tmp/ad-burst/frames/page-0001.png"
62+
}
63+
}
64+
```

‎packages/command-surface/src/capture/screenshot.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@ export const screenshotCommandFacet = defineCommandFacet({
106106
text: {
107107
summary: 'Capture a screenshot',
108108
cliDetail:
109-
"Web defaults to the viewport; use --fullscreen, --full, or -f for the entire page. iOS simulators default to 1x logical-point output; use --pixel-density to request a different screenshot density. Use --screen-mask black to fill the iOS simulator screen outline, including rounded corners, with black for this capture. It requires simctl: physical devices, tvOS and visionOS simulators, other platforms, provider captures and XCTest runner captures are refused. A masked capture fails if simctl fails instead of falling back to an unmasked runner capture. macOS app sessions default to the app window; use --fullscreen for full desktop, --scale to downscale, --crop-on <selector> to crop the capture to the frame the selector resolves on the same screen (currently iOS simulators, Android emulators, and CoreDevice physical iPhones), --overlay-refs to annotate current refs, --normalize-status-bar for deterministic iOS simulator or Android chrome. Physical iPhone crop verification covers portrait CoreDevice/devicectl captures only. XCTest, runner fallback, and physical iPad crops are refused; landscape iPhone crop is unverified. Android captures immediately by default; --normalize-status-bar also waits for transient UI to fade, and --no-stabilize keeps capture immediate. Use --count with --interval-ms to capture an animation burst in one request. The daemon captures frames sequentially and writes each frame as a numbered file beside the --out path, for example page-0001.png, and the result reports every frame path and capture time. A burst refuses --crop-on and --overlay-refs, because a crop binds one snapshot and overlay refs annotate one frame. Keep --count times --interval-ms plus 500 ms per frame within 60 seconds, because the frames must finish inside the request timeout. When --count is present without --interval-ms, the daemon waits 100ms between frames. A burst starts only when this invocation names --count; a count set for press and swipe in a config file never arms one. With the native macOS backend, the front window is the app's frontmost visible, nonempty normal-level (layer-0) window on the current Space: floating palettes and app-modal alerts at window level 8 are skipped, as is the small indicator window macOS adds in front of a window that a screen-sharing stream captures, and a sheet is captured as its own window. On macOS, any --surface other than app (desktop, menubar, frontmost-app) always captures the main display and refuses an explicit --fullscreen. On single-display iOS simulators and Android devices, the result reports displayRotation, the rotation the display rendered the capture in, when the device returns a reading in time; otherwise the field is absent. On iOS simulators a screenshot waits for that simulator's status bar to be free, and a request its caller cancelled while it waits reports the cancellation instead of capturing.",
109+
"Web defaults to the viewport; use --fullscreen, --full, or -f for the entire page. iOS simulators default to 1x logical-point output; use --pixel-density to request a different screenshot density. Use --screen-mask black to fill the iOS simulator screen outline, including rounded corners, with black for this capture. It requires simctl: physical devices, tvOS and visionOS simulators, other platforms, provider captures and XCTest runner captures are refused. A masked capture fails if simctl fails instead of falling back to an unmasked runner capture. macOS app sessions default to the app window; use --fullscreen for full desktop, --scale to downscale, --crop-on <selector> to crop the capture to the frame the selector resolves on the same screen (currently iOS simulators, Android emulators, and CoreDevice physical iPhones), --overlay-refs to annotate current refs, --normalize-status-bar for deterministic iOS simulator or Android chrome. Physical iPhone crop verification covers portrait CoreDevice/devicectl captures only. XCTest, runner fallback, and physical iPad crops are refused; landscape iPhone crop is unverified. Android captures immediately by default; --normalize-status-bar also waits for transient UI to fade, and --no-stabilize keeps capture immediate. Use --count with --interval-ms to capture an animation burst in one request. The daemon captures frames sequentially and writes each frame as a numbered file beside the --out path, for example page-0001.png, and the result reports every frame path and capture time. A burst refuses --crop-on and --overlay-refs, because a crop binds one snapshot and overlay refs annotate one frame. Keep --count times --interval-ms plus 500 ms per frame within 60 seconds, because the frames must finish inside the request timeout. When --count is present without --interval-ms, the daemon waits 100ms between frames. A burst starts only when this invocation names --count; a count set for press and swipe in a config file never arms one, and a remote daemon refuses --count with REMOTE_SCREENSHOT_BURST_DENIED, so run a burst against a local daemon. With the native macOS backend, the front window is the app's frontmost visible, nonempty normal-level (layer-0) window on the current Space: floating palettes and app-modal alerts at window level 8 are skipped, as is the small indicator window macOS adds in front of a window that a screen-sharing stream captures, and a sheet is captured as its own window. On macOS, any --surface other than app (desktop, menubar, frontmost-app) always captures the main display and refuses an explicit --fullscreen. On single-display iOS simulators and Android devices, the result reports displayRotation, the rotation the display rendered the capture in, when the device returns a reading in time; otherwise the field is absent. On iOS simulators a screenshot waits for that simulator's status bar to be free, and a request its caller cancelled while it waits reports the cancellation instead of capturing.",
110110
},
111111
metadata: screenshotCommandMetadata,
112112
run: (client, input) => client.capture.screenshot(input),

‎packages/daemon/src/execution/screenshot-runtime-burst.test.ts‎

Lines changed: 45 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import { daemonPlatformServicesFixture } from '../__tests__/support/platform-ser
22
import fs from 'node:fs';
33

44
import path from 'node:path';
5-
import { expect, test } from 'vitest';
5+
import { expect, test, vi } from 'vitest';
66
import type { CreateDaemonCommandSurface } from '@agent-device/contracts/daemon-command-surface';
77
import { ANDROID_EMULATOR, mkdtempForTestSync } from '@agent-device/test-kit';
88
import { makeSession } from '../__tests__/support/session-factories.ts';
@@ -146,15 +146,9 @@ test('a burst that fails past frame 1 leaves no implicit temp root behind', asyn
146146

147147
// The implicit root that held frame 1 is gone. Another concurrent run could
148148
// own its own root, so this checks the one this burst created — the dirname
149-
// the failure reported, not a global sweep.
150-
let frameOneDir: string | undefined;
151-
try {
152-
frameOneDir = path.dirname(fixture.captureScreenshot.mock.calls[0]![0]!.outPath);
153-
} catch {
154-
frameOneDir = undefined;
155-
}
156-
expect(frameOneDir).toBeDefined();
157-
expect(fs.existsSync(frameOneDir!)).toBe(false);
149+
// of the frame the burst captured, not a global sweep.
150+
const frameOneDir = path.dirname(fixture.captureScreenshot.mock.calls[0]![0]!.outPath);
151+
expect(fs.existsSync(frameOneDir)).toBe(false);
158152
});
159153

160154
test('burst admission refuses crop, overlay, and misbounded flags before any device work', async () => {
@@ -224,6 +218,47 @@ test('a cancelled request stops the burst before the next frame', async () => {
224218
expect(fixture.captureScreenshot.mock.calls.length).toBe(1);
225219
});
226220

221+
test('an abort during the inter-frame wait stops the burst with the abort reason and one capture', async () => {
222+
const fixture = screenshotRuntimeFixture();
223+
const session = makeSession('default', { device: ANDROID_EMULATOR });
224+
const outDir = mkdtempForTestSync('agent-device-burst');
225+
const req = screenshotRequest({
226+
positionals: [path.join(outDir, 'page.png')],
227+
flags: { count: 3, intervalMs: 1000 },
228+
});
229+
230+
const resolved = await resolveScreenshotGenericExecution({
231+
hostCwd: process.cwd(),
232+
createCommandSurface: testCreateCommandSurface,
233+
platformServices: daemonPlatformServicesFixture(),
234+
req,
235+
session,
236+
inspectFacts: fixture.inspectFacts,
237+
bindDevice: fixture.bindDevice,
238+
});
239+
if (!resolved.ok) throw new Error('screenshot admission must succeed');
240+
241+
const controller = new AbortController();
242+
const execution = resolved.execute(
243+
executionParams(session, req, {
244+
count: req.flags?.count,
245+
intervalMs: req.flags?.intervalMs,
246+
signal: controller.signal,
247+
}),
248+
);
249+
// Wait for frame 1 to complete; the abort then lands while the plan waits
250+
// out intervalMs, so the wait must surface the abort instead of dispatching
251+
// frame 2.
252+
await vi.waitFor(() => expect(fixture.captureScreenshot).toHaveBeenCalledTimes(1));
253+
const abortTimer = setTimeout(
254+
() => controller.abort(new Error('canceled during the interval')),
255+
20,
256+
);
257+
await expect(execution).rejects.toThrow('canceled during the interval');
258+
clearTimeout(abortTimer);
259+
expect(fixture.captureScreenshot.mock.calls.length).toBe(1);
260+
});
261+
227262
/** A command surface whose every capture reports the given warnings, so a burst frames them. */
228263
function burstWarningSurface(warnings: string[]): CreateDaemonCommandSurface {
229264
return async (config) => {

0 commit comments

Comments
 (0)