@@ -4,59 +4,59 @@ Use this for Apple runner changes or manual device runs. For foldables, also rea
44
55## Prepare
66
7- 1 . Build runtime changes with ` pnpm build ` .
7+ 1 . To build runtime changes, run ` pnpm build ` .
882 . For Android source verification, run ` pnpm build:android ` .
993 . For Swift runner changes, run ` pnpm build:xcuitest ` .
10- Graceful shutdown can hand off an active runner; a new daemon can adopt the old binary.
11- 4 . Run ` pnpm clean:daemon ` after the builds . The daemon does not reload code.
12- 5 . Use distinct devices for parallel worktrees. Inspect worktree-scoped state with ` pnpm daemon:state-dir ` .
10+ A graceful shutdown can hand off an active runner. A new daemon can adopt the old binary.
11+ 4 . After the builds, run ` pnpm clean:daemon ` . The daemon does not reload code.
12+ 5 . To examine the worktree-scoped state, run ` pnpm daemon:state-dir ` .
13136 . For ` Agent Device Tester ` , follow ` examples/test-app/README.md ` for the build, Metro, and expected app surface.
14- An installed ` com.callstack.agentdevicelab ` alone is insufficient .
15- 7 . For Android apps using Metro, run ` adb reverse tcp:<port> tcp:<port> ` before opening the app or URL.
14+ An installed ` com.callstack.agentdevicelab ` alone is not sufficient .
15+ 7 . For Android apps that use Metro, run ` adb reverse tcp:<port> tcp:<port> ` before you open the app or URL.
1616
1717## Prove the path
1818
19- Run the exact changed route. Record commands, device, source SHA, and observable results.
20- For Android, require ` snapshot -i --json ` to show ` androidSnapshot.backend: android-helper `
21- and ` helperVersion ` matching ` package.json ` . UIAutomator fallback proves only that fallback.
19+ Run the exact route that changed . Record the commands, device, source SHA, and observable results.
20+ For Android, ` snapshot -i --json ` must show ` androidSnapshot.backend: android-helper ` .
21+ Its ` helperVersion ` must match ` package.json ` . A UIAutomator fallback proves only that fallback.
2222
2323For Apple connection failures, start at ` packages/platform-apple/src/runner/runner-startup-transport.ts ` .
24- Retry policy belongs in ` runner-error-classification.ts ` ; command typing belongs in ` runner-contract.ts ` .
25- Keep transport below session/ client behavior. Keep xctestrun preparation outside request execution.
26- After signing, warm Node with ` node -e 0 ` before measuring Gatekeeper-sensitive startup.
24+ Retry policy belongs in ` runner-error-classification.ts ` . Command typing belongs in ` runner-contract.ts ` .
25+ Keep the transport below session and client behavior. Keep xctestrun preparation outside request execution.
26+ After signing, run ` node -e 0 ` before you measure Gatekeeper-sensitive startup.
2727
2828## Ownership and cleanup
2929
30- Use purpose-specific sessions . For extra isolation, use a separate ` --state-dir ` under ` /private/tmp ` .
31- Close every manually opened session, including failed attempts, with its original session, platform, UDID, and state directory.
30+ Use one session for each purpose . For more isolation, use a separate ` --state-dir ` under ` /private/tmp ` .
31+ Close each session that you opened manually, also failed attempts, with its original session, platform, UDID, and state directory.
3232
3333For ` DEVICE_IN_USE ` :
3434
35- - "already in use by session X": follow this daemon's ` close --session ` hint.
36- - "owned by session X in workspace Y": inspect ` device status ` ; follow ` device release --stale ` only for provably dead owners.
37- A live or uncertain owner blocks ` open ` unless the device rebooted after the claim.
38- With reboot evidence, ` open ` settles old resources, takes the claim, and reports release in ` warnings ` .
39- Do not hunt PIDs or steal the claim.
35+ - "already in use by session X": follow the ` close --session ` hint of this daemon .
36+ - "owned by session X in workspace Y": examine ` device status ` . Use ` device release --stale ` only for provably dead owners.
37+ A live or uncertain owner blocks ` open ` , unless the device rebooted after the claim.
38+ With reboot evidence, ` open ` settles old resources, takes the claim, and reports the release in ` warnings ` .
39+ Do not search for PIDs. Do not steal the claim.
4040
41- For stuck cleanup, run ` agent-device device status --stale ` .
42- Stop the owning daemon with ` agent-device daemon stop --state-dir <dir> ` ; add ` --clean ` for retained runners .
43- Release dead owners with ` agent-device device release --stale ` .
44- If blocked, report the session, state directory, and status output. Never hide incomplete cleanup.
45- The physical runner handoff checklist lives in ` docs/evidence/ios-physical-runner-handoff-2026-09-19.md ` .
41+ If cleanup is stuck , run ` agent-device device status --stale ` .
42+ To stop the owning daemon, run ` agent-device daemon stop --state-dir <dir> ` . For retained runners, add ` --clean ` .
43+ To release dead owners, run ` agent-device device release --stale ` .
44+ If you are blocked, report the session, state directory, and status output. Always report incomplete cleanup.
45+ The physical runner handoff checklist is in ` docs/evidence/ios-physical-runner-handoff-2026-09-19.md ` .
4646
4747## Platform policy
4848
49- Apple runner changes run ` pnpm check:xctest-selection ` and build the affected target.
50- Swift ` #if ` guards own XCTest classification. Do not maintain a second test-name list .
51- Use macOS host lanes for pure decisions and simulator lanes for iOS/ XCTest semantics.
49+ For Apple runner changes, run ` pnpm check:xctest-selection ` and build the affected target.
50+ Swift ` #if ` guards own the XCTest classification. Do not keep a second list of test names .
51+ Use macOS host lanes for pure decisions. Use simulator lanes for iOS and XCTest semantics.
5252If system policy rejects an unsigned host bundle, rebuild with ` CODE_SIGN_IDENTITY="Apple Development" `
53- or select an identity from ` security find-identity -v -p codesigning ` .
54- First runs need XCUITest automation permission.
53+ or an identity from ` security find-identity -v -p codesigning ` .
54+ The first run needs XCUITest automation permission.
5555
56- Keep Apple target changes synchronized across the kernel model, runtime-fact admission, dispatch,
56+ When you change Apple targets, synchronize the kernel model, runtime-fact admission, dispatch,
5757discovery, and xctestrun preparation. Simulator-set scoping must not hide the host macOS target.
5858HarmonyOS has no provisioned CI device or HDC. Mocked tests do not replace local hardware evidence.
59- Read live smoke harnesses before running them; their environment contracts live in their entry files under ` test/integration/ ` .
59+ Before you run a live smoke harness, read it. Its environment contract is in its entry file under ` test/integration/ ` .
6060
61- If a sandbox rejects localhost with ` listen EPERM ` , use host access when permitted.
62- Inspect the underlying error first . A generic startup or cleanup failure does not prove a sandbox cause.
61+ If a sandbox rejects localhost with ` listen EPERM ` , use host access, if permitted.
62+ First, examine the underlying error. A generic startup or cleanup failure does not prove a sandbox cause.
0 commit comments