fix: stabilize iOS runner navigation taps

[thymikee]

Summary

Stabilizes iOS runner sessions around navigation, stale runners, and broken XCTest accessibility trees.

The PR now does five concrete things: resolved iOS/macOS element activation uses coordinate-first taps, ready runner sessions are checked with a bounded uptime preflight instead of a legacy recent-success cache, AX-fatal iOS runner responses immediately invalidate the runner session so the next command starts from a fresh runner, AX-unavailable snapshot guidance clearly routes agents through plain screenshot plus coordinate recovery before retrying AX on the next screen, and the provider-backed iOS lifecycle scenario now covers synthesized coordinate taps from press @ref.

For broken-AX apps such as Bluesky, sparse snapshot fallbacks are no longer cached as healthy runner state. Mutating commands that record XCTest failures now return XCTEST_RECORDED_FAILURE instead of reporting success, and iOS coordinate-only taps use the lower-level synthesized event path so screenshot plus x/y recovery works even when app AX queries are poisoned. Review follow-up also makes collapsed-tab fallback use the AX-aware query invalidation path and reports synthesized tap fallback diagnostics when the runner falls back to XCTest coordinates.

Adds ADR 0005 plus internal docs and AGENTS.md guidance for resolved element activation, runner lifecycle behavior, AX-unavailable target invalidation, concise recoverable error messages, and checking daemon logs for unexpectedly slow interactions. Current PR scope is 31 files, focused on iOS runner lifecycle/transport, Swift runner interaction/snapshot handling, targeted tests, command guidance, and internal docs.

Validation

CI failure follow-up passed locally: pnpm test:integration:provider -- test/integration/provider-scenarios/ios-lifecycle.test.ts first reproduced the failed provider scenario, then passed 19 files / 37 tests after updating the transcript. The same fix also unblocks coverage: sandbox-free pnpm test:coverage passed 249 files / 2148 tests with 83.66% statements and 85.72% lines, above the configured thresholds. A sandboxed coverage attempt failed on local permissions (listen EPERM) before this, so the comparable result is the sandbox-free run.

Focused regression coverage passed: pnpm exec vitest run src/platforms/ios/__tests__/runner-session.test.ts src/platforms/ios/__tests__/runner-client.test.ts passed 77 tests, pnpm exec vitest run src/platforms/ios/__tests__/index.test.ts --testNamePattern "iosRunnerOverrides" passed 9 relevant tests with 70 skipped, and pnpm exec vitest run src/utils/__tests__/output.test.ts src/utils/__tests__/args.test.ts passed 147 tests. Swift review-follow-up coverage was added in the runner source for synthesized tap fallback diagnostics, XCTEST_RECORDED_FAILURE response wrapping, and sparse runnerFatal AX snapshot payloads.

Build and static checks passed: pnpm build, pnpm check:quick, pnpm build:xcuitest, pnpm format, pnpm check:fallow --base origin/main, and git diff --check. pnpm format reformatted unrelated existing files; that formatter churn was removed from the final diff. pnpm test:skillgym:case ios-ax-unavailable-screenshot-coordinate-recovery was added but could not run in this sandbox because SkillGym requires external Codex/Claude runners and network access.

Dogfooded on React Navigation org.reactnavigation.playground: repeated snapshots stayed fast after the earlier runner lifecycle fix, and the original long outlier was confirmed as stale runner recovery rather than snapshot traversal.

Dogfooded twice on Bluesky xyz.blueskyweb.app from /Users/thymikee/Developer/bluesky with Metro on 8081. The final run reproduced the known Home-screen AX failure (kAXErrorIllegalArgument), returned a sparse 1-node snapshot in 4.67s, and daemon.log showed AGENT_DEVICE_RUNNER_TARGET_CACHE_INVALIDATE reason=ax_snapshot_unavailable, ios_runner_session_invalidated, and ** BUILD INTERRUPTED **. A follow-up coordinate tap to Search used a fresh runner and returned in 4.49s, screenshot /private/tmp/agent-device-bluesky-final/after-search.png showed Explore/Search, and the next snapshot was healthy at 177 total nodes / 43 visible in 0.81s. The manual session, Metro process tree, stale xcodebuild runner, and daemon metadata were cleaned up.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-06-07 09:17 UTC

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.1 MB	1.1 MB	+173 B
JS gzip	371.1 kB	371.4 kB	+264 B
npm tarball	479.4 kB	482.0 kB	+2.6 kB
npm unpacked	1.6 MB	1.6 MB	+12.9 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.1 ms	26.9 ms	-0.2 ms
CLI --help	42.5 ms	42.3 ms	-0.2 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/args.js	+543 B	+179 B
dist/src/cli.js	+202 B	+88 B
dist/src/2415.js	-629 B	-42 B

[thymikee]

Updated the PR with an explicit uptime fast path in the Swift runner. The readiness probe is now answered directly by the HTTP listener before command journaling, the serial command queue, app activation, and main-thread XCTest dispatch. It still uses the existing command protocol, so we avoid adding a second health endpoint while removing the XCTest/app costs from the preflight.\n\nDogfood on React Navigation Example after rebuilding the local runner cache:\n- startup read-only snapshot skipped preflight as expected\n- ready-session preflights measured 2 ms, 3 ms, 4 ms, and 3 ms\n- successful Navigate to Details tap: preflight 4 ms, wall 0.71 s\n- post-tap snapshot: preflight 3 ms, snapshot_capture 120 ms, wall 0.19 s\n- daemon log had no TEST EXECUTE FAILED, runner restart, or snapshot matching failure lines for this session\n\nAlso added a runner journal regression test asserting uptime is not accepted into the command journal, and documented the probe contract in ADR 0005.

[thymikee]

Cleanup pass done and pushed. The only additional code change is in runner-session: read-only and mutating commands now share one post-preflight send helper, and readiness decision derives read-only/probe status internally instead of being passed an options object. I also scanned for stale freshness-cache branches and skipped-preflight recovery metadata and found none remaining.

Validation after cleanup: focused iOS runner Vitest suite passed, pnpm check:quick passed, git diff --check passed, and pnpm build:xcuitest passed.