perf: adapt ios runner uptime preflight

[thymikee]

Summary

Implement work slice 2 from docs/ios-runner-protocol-optimizations.md: adaptive iOS runner uptime preflight policy for hot tap interactions.

• Keeps startup and no-recent-success paths conservative by running readiness preflight.
• Skips uptime for hot tap/tapSeries commands when the runner has a recent successful response.
• Keeps non-tap mutating commands preflighted until measured.
• Marks post-skip transport failures so status recovery diagnostics show that readiness preflight was skipped.
• Preserves the merged fix: reduce iOS runner invalidation after status recovery #666 invalidation-decision path: status recovery can still skip invalidation for observed lifecycle states, and skipped-preflight context is included in recovery guidance.
• Uses ios_runner_readiness_preflight as the preflight-used diagnostic and emits ios_runner_readiness_preflight_skipped / ios_runner_readiness_preflight_recovered for skipped and recovered paths.

This PR is now rebased directly on current main; #661, #663, #665, and #666 are merged, so the diff contains only adaptive-uptime slice changes.

Validation

Focused unit coverage passed after the rebase:

• pnpm exec vitest run src/platforms/ios/__tests__/runner-session.test.ts src/platforms/ios/__tests__/runner-command-retry.test.ts src/platforms/ios/__tests__/runner-client.test.ts src/platforms/ios/__tests__/runner-provider.test.ts: 4 files, 83 tests.

Static validation passed:

• pnpm format
• pnpm check:quick

Earlier simulator validation on iPhone 17 Pro (C25DBB5B-9254-4293-A8D5-2785C78DE03A) with --session adaptive-uptime-main --state-dir /private/tmp/agent-device-adaptive-uptime-main:

• Opened Settings and ran the first coordinate press without a prior snapshot. Diagnostics showed ios_runner_readiness_preflight with reason:"startup", then successful tap send.
• Ran a hot selector press with press 'label="Silent Mode"'. Diagnostics showed ios_runner_readiness_preflight_skipped with reason:"recent_successful_response" and no session invalidation records.
• Closed the session with matching platform/device/session/state-dir flags.

Touched files: 4. Scope stayed within the iOS runner client/session module group and focused unit tests.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.1 MB	1.1 MB	+1.7 kB
JS gzip	362.2 kB	362.6 kB	+361 B
npm tarball	467.2 kB	467.5 kB	+362 B
npm unpacked	1.6 MB	1.6 MB	+1.7 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.0 ms	26.1 ms	-0.9 ms
CLI --help	41.9 ms	41.8 ms	-0.1 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/2415.js	+1.7 kB	+361 B

[thymikee]

Review

Nice evolution of the preflight logic. Turning shouldPreflightMutatingRunnerCommand (a bare boolean) into resolveRunnerReadinessPreflightDecision returning a tagged { action, reason, freshnessMs, … } object lets the diagnostics carry why a preflight ran or was skipped (startup / conservative_command / no_successful_response / successful_response_stale / recent_successful_response) instead of leaving callers to guess. The explicit ios_runner_readiness_preflight_used / _skipped / _recovered events make the policy observable.

Notes:

1. Skip-marking is correctly scoped. The .catch that wraps the error via markRunnerSkippedReadinessPreflightError only fires on the action === 'skip' path and only for the transport send (it's attached to sendRunnerCommandOnce, before parseRunnerResponse). The test does not mark runner response failures as skipped preflight transport failures confirms a runner-reported COMMAND_FAILED isn't mislabeled — that's the important distinction and it's covered. Good.

2. markRunnerSkippedReadinessPreflightError preserves code, message, details, and cause when re-wrapping, so downstream recovery/hint logic still sees the original error shape. 👍

3. Conflict with fix: reduce iOS runner invalidation after status recovery #666. This PR and fix: reduce iOS runner invalidation after status recovery #666 edit the same functions in runner-client.ts — handleCompletedRunnerStatus, runnerStatusFailureError, runnerStatusInFlightError, and all three *Hint helpers. perf: adapt ios runner uptime preflight #662 threads RunnerReadinessPreflightRecoveryDetails through them while keeping the throw-based flow; fix: reduce iOS runner invalidation after status recovery #666 rewrites them into a return-based discriminated union. They will not merge cleanly together. Recommend deciding a merge order and rebasing the second one — the readiness-context (lostResponseReadinessContext + the readiness* detail fields) will need re-applying onto fix: reduce iOS runner invalidation after status recovery #666's union structure if fix: reduce iOS runner invalidation after status recovery #666 lands first.

4. Minor: freshnessMs is always the RUNNER_TAP_PREFLIGHT_SKIP_FRESHNESS_MS constant today, so emitting it per-decision is informational-only — fine to keep for forward-compat if you expect this to become configurable, otherwise it's slightly redundant in the payload.

LGTM pending CI and the #666 coordination.

---

Generated by Claude Code

[thymikee]

Reviewed current head ecd4b9c26. No blocking code findings.

Coordination note: this PR overlaps with #666 in runner-client.ts/status-recovery helper code. If #666 merges first, please rebase this branch and make sure the skipped-readiness-preflight metadata still flows into the new invalidation-decision shape. I’d prefer merge order #662 first, then rebase #666, because #666’s decision union can then preserve the adaptive-uptime metadata explicitly.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-06-02 04:15 UTC