fix: reduce iOS runner invalidation after status recovery

[thymikee]

Summary

Reduce iOS runner session invalidation after status recovery proves a post-send command reached an observable lifecycle state.

This slice originally built on #661, which is now merged into main as 57cd3f3a07c9e174e87aea0c441613157506902a. The branch has been rebased onto current origin/main, so this PR diff contains only the invalidation-reduction changes.

Acceptance coverage:

• Completed/failed lifecycle status skips invalidation when the status probe proves the runner is reachable.
• Accepted/started/completed/failed mutating states return guidance instead of replaying the command.
• Unknown and notAccepted lifecycle states retain invalidation and now surface lifecycle-aware errors.
• Diagnostics emit ios_runner_command_invalidation_decision with skip/retain reason and lifecycle state.

Touched files: 2 (src/platforms/ios/runner-client.ts, src/platforms/ios/__tests__/runner-command-retry.test.ts).

Validation

After rebasing onto current origin/main:
pnpm exec vitest run src/platforms/ios/__tests__/runner-client.test.ts src/platforms/ios/__tests__/runner-session.test.ts src/platforms/ios/__tests__/runner-command-retry.test.ts src/platforms/ios/__tests__/runner-provider.test.ts passed: 4 files, 75 tests.
pnpm check:quick passed.
pnpm format passed.
pnpm build passed.
pnpm clean:daemon passed.

Earlier simulator validation for this slice used isolated state dir /private/tmp/agent-device-invalidation-reduction.Ecer7r, session codex-invalidation-reduction, platform ios, UDID D74E0B66-57EB-4EC1-92DC-DA0A30581FE7. open settings and snapshot -i succeeded; runner xcodebuild PID was 64659. A follow-up same-session press @e24 succeeded and ps still showed PID 64659, so the next command used the existing runner rather than relaunching xcodebuild. The session was closed with matching flags; stale validation runner PID 64659 and isolated daemon PID 59686 were cleaned up after close reported no sessions.

Lost-response-after-completion behavior is simulated in the focused unit tests through the runner command seam because there is no production CLI hook for dropping a completed runner response.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.1 MB	1.1 MB	+2.2 kB
JS gzip	361.7 kB	362.2 kB	+588 B
npm tarball	466.6 kB	465.6 kB	-1.0 kB
npm unpacked	1.5 MB	1.5 MB	-5.3 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	22.4 ms	21.3 ms	-1.1 ms
CLI --help	35.2 ms	33.5 ms	-1.7 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/2415.js	+2.2 kB	+588 B

[thymikee]

Review

Solid refactor. The main win is handleRunnerTransportErrorAfterCommandSend, which collapses the three near-identical if (recovered) return recovered; await invalidateRunnerSession(...); throw … blocks into one place, and the RunnerTransportRecovery discriminated union (recovered / skipInvalidation / retainInvalidation) makes the decision explicit instead of overloading undefined + throw. The ios_runner_command_invalidation_decision diagnostic with skip/retain reason + lifecycle state is a nice observability addition (and the warn-on-retain / debug-on-skip split reads right).

A few notes:

1. Behavioral parity on the thrown error. Previously the non-retryable/exhausted paths threw the raw err/retryErr; the retain path now throws recovery?.error ?? transportError, i.e. the AppError-coerced appErr/retryAppErr. When the original was already an AppError this is identical; otherwise it's now wrapped, which is arguably an improvement — just calling it out so it's intentional.

2. status_probe_failed path. Returning { type: 'retainInvalidation', reason: 'status_probe_failed' } instead of bare undefined preserves the old "probe failed → invalidate + throw transportError" behavior while now emitting an explicit reason. Good. Worth a focused test asserting the retained diagnostic with reason: 'status_probe_failed' since that branch isn't covered in the new assertions.

3. Conflict with perf: adapt ios runner uptime preflight #662. This PR and perf: adapt ios runner uptime preflight #662 both rewrite the same region of runner-client.ts (handleRunnerCommandStatusRecovery, handleCompletedRunnerStatus, and all three *Hint functions). fix: reduce iOS runner invalidation after status recovery #666 converts them from throw-based to return-based recovery; perf: adapt ios runner uptime preflight #662 keeps them throw-based and threads readiness-preflight context through the hints. These won't merge cleanly together — whichever lands second will need a non-trivial rebase to re-apply the readiness-context changes onto the new union structure. Worth sequencing deliberately.

Otherwise LGTM pending CI.

---

Generated by Claude Code

[thymikee]

Reviewed current head 6d0e46c77. No blocking code findings.

Coordination note: this PR overlaps with #662 in runner-client.ts/status-recovery helper code. If #662 merges first, please rebase this branch and preserve the adaptive-uptime fields (runnerReadinessPreflightSkipped, skip reason, age/freshness) inside the new invalidation-decision diagnostics and user-facing hints. I’d prefer #662 -> #666 merge order so this PR’s explicit decision union can absorb the readiness metadata cleanly.

[github-actions]

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