feat(open): let a polling caller skip the first-screen wait

Merged
TH
2h ago
+61-13

Summary

Since #4513, the first capture after open on a local iOS simulator waits up to 10 s for a labeled first screen. An app whose first screen labels nothing, such as a game canvas, always waits the full 10 s. open now accepts the existing postGestureStabilization opt-out, so a caller that polls the screen itself can skip the wait:

agent-device open com.example.game --foreground --no-post-gesture-stabilization
AGENT_DEVICE_POST_GESTURE_STABILIZATION=0 agent-device open com.example.game   # operator-wide
await client.apps.open({ app: 'com.example.game', postGestureStabilization: false });

With the opt-out set, open marks no wait. On every platform, it still drops the record the replaced screen left pending, such as a scroll's stabilization record. The field stays operator-only: MCP and AI SDK schemas do not offer it, so the always-loaded schema budget doesn't change, and ./agent-device.json still rejects the key.

Rebased on #4601. The open docs paragraph also takes two wording fixes from #4601's review: "An unlabeled splash image", and the game-canvas example moved to the no-labeled-element clause.

10 files: the open surface and client type, the daemon mark, flag and client docs, the guarantee cell, the user docs, and one test.

Validation

At 1c9adf2, with the review fixes rechecked at b0126a4 (typecheck, lint, 1,992 affected tests):

  • pnpm typecheck and pnpm lint pass.
  • Vitest passes for command-surface, command-registry, contracts, client, daemon sessions, src/commands, src/mcp and the deferred-outcome tests: 3,662 tests.
  • Probe: prepareDaemonCommandRequest('open', { postGestureStabilization: false }) carries the field to the daemon.
  • Live, iPhone 17 Pro simulator on iOS 27.0, Settings: open --relaunch --foreground with and without the flag, 3 runs each. All succeed with the full tree and no postGestureOutcome. Settings labels its first screen at once, so timing doesn't separate the two modes; the daemon test covers the skip.
  • Live on React Native at cb1bbfd: same simulator, Agent Device Tester Debug dev build, Metro serving. open --relaunch --foreground --metro-port 8081, interleaved, 4 runs per mode. All 12 runs returned the 52-node home screen with no postGestureOutcome. Median time: 7.3 s by default, 6.5 s with --no-post-gesture-stabilization, 6.3 s with AGENT_DEVICE_POST_GESTURE_STABILIZATION=0. The relaunch itself takes about 6 s, so the home screen is already drawn when open reads it, and the opt-out saves the confirming second read. The env run shows the operator config reaches open.
  • After the rebase, at 65294d3: build, typecheck and lint pass, and 2,611 affected tests pass.
  • CI owns the remaining gates.

🤖 Generated with Claude Code