fix: retry iOS runner prepare launch

[thymikee]

Summary

Retry prepare ios-runner health-check failures by invalidating the stuck runner session and launching a fresh one once, without forcing an .xctestrun rebuild.

Keep the bad cached runner artifact recovery path separate and limited to the first prepare attempt: cached artifacts still get marked bad and rebuilt only when the initial restored artifact itself is suspect.

Handle review hardening: the retry loop is split below fallow complexity limits, cancellation is re-checked before relaunch, terminal retry invalidation is best-effort so it does not mask the original health error, and tests cover non-retryable startup failures plus attempt-two no-rebuild behavior.

Document the CI contract in command docs and CLI help: run prepare ios-runner after boot/install and before replay/test, use exact runner cache keys, and avoid broad restore-key fallbacks.

Validation

• pnpm exec vitest run src/platforms/ios/__tests__/runner-command-retry.test.ts
• pnpm exec vitest run src/__tests__/cli-help.test.ts
• pnpm exec vitest run src/platforms/ios/__tests__/runner-command-retry.test.ts src/__tests__/cli-help.test.ts
• pnpm check:fallow
• pnpm check:quick
• pnpm build
• pnpm pack --pack-destination /tmp
• Temporarily installed /tmp/agent-device-0.16.13.tgz in React Navigation and ran prepare ios-runner against iPhone 17 Pro successfully

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.1 MB	1.1 MB	+1.6 kB
JS gzip	370.3 kB	370.7 kB	+481 B
npm tarball	476.7 kB	477.2 kB	+576 B
npm unpacked	1.6 MB	1.6 MB	+1.6 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.8 ms	28.8 ms	+0.9 ms
CLI --help	43.3 ms	44.5 ms	+1.2 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/2415.js	+1.2 kB	+332 B
dist/src/args.js	+325 B	+113 B
dist/src/1352.js	+73 B	+36 B

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-06-05 16:05 UTC