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 three 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, and AX-fatal iOS runner responses immediately invalidate the runner session so the next command starts from a fresh runner.

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.

Adds ADR 0005 plus internal docs for resolved element activation, runner lifecycle behavior, and AX-unavailable target invalidation. Current PR scope is 24 files, focused on iOS runner lifecycle/transport, Swift runner interaction/snapshot handling, targeted tests, and internal docs.

Validation

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, and pnpm exec vitest run src/platforms/ios/__tests__/index.test.ts --testNamePattern "iosRunnerOverrides" passed 9 relevant tests with 70 skipped.

Build and static checks passed: pnpm build, pnpm check:quick, pnpm build:xcuitest, and git diff --check. pnpm format was run; unrelated formatter churn was removed from the final diff. pnpm check:unit was attempted and failed in unrelated local environment cases, including listen EPERM server tests, Android .aab bundletool tests, Android helper-session expectations, and Swift recording-script checks.

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
🚀 View preview at https://callstack.github.io/agent-device/pr-preview/pr-702/
Built to branch gh-pages at 2026-06-07 07:07 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.1 MB	1.1 MB	-572 B
JS gzip	371.1 kB	371.1 kB	-3 B
npm tarball	479.4 kB	480.9 kB	+1.5 kB
npm unpacked	1.6 MB	1.6 MB	+9.0 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	28.0 ms	27.9 ms	-0.1 ms
CLI --help	43.7 ms	43.6 ms	-0.1 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
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.