Apple platform + runner: simplification and correctness audit (tracking)

[thymikee]

Purpose

A tracking issue for a simplification and correctness audit of the Apple side: packages/platform-apple (about 32k lines of production TS) and apple/runner (about 17.5k lines of Swift plus ObjC bridges), at 01328de411.

Method:

1. Four read-only audits applied community Swift skills: AvdLee and twostraws Swift Concurrency and Swift Testing, the Swift API Design Guidelines, and jazzychad's ios-code-audit.
2. A second model cross-reviewed every finding against the code.
3. The top claims were spot-checked by hand.

Findings refuted in review are not filed here.

Verdict: the core machinery earns its complexity: runner lifecycle, lease detach/adopt, recycle ledger, readiness preflight, command journal, three-tier snapshot plan, and the private-AX ladder pinned by conformance fixtures. The waste sits at the edges. Removing it cuts about 1–1.5k production lines, and moving the inline tests (#2792) takes about 3.9k lines out of production Swift files.

Each child issue is one PR (or a small series of pure-move PRs) inside one module group.

Bugs (ready-for-agent)

• fix(ios-runner): snapshot capture plan reads and writes main-owned target state off the main thread #2781 Snapshot plan data race on main-owned target state
• fix(ios-runner): runMainThreadWork reports MAIN_THREAD_TIMEOUT for work that finished at the timeout boundary #2782 MAIN_THREAD_TIMEOUT reported for finished work
• fix(ios-runner): non-interactive query sweep outlives its 1s tier slice and causes RUNNER_BUSY #2783 Query sweep outlives its 1 s slice → RUNNER_BUSY
• fix(ios): pass the scoped simulator set to the AX bridge and fold simctl spawn calls #2784 simctl spawn missing --set (AX bridge, fold)
• fix(ios): physical-device install lost devicectl hints; delete the dead install/uninstall/push paths #2785 Physical install lost devicectl hints; dead install/uninstall/push
• fix(ios-runner): one synthesize-then-XCTest-fallback helper; align sequence tap with standalone tap #2788 Sequence tap and standalone tap fall back differently; one fallback helper
• fix(ios): visionOS taps request synthesis the runner cannot perform #2789 visionOS taps request impossible synthesis
• fix(ios): runtime clang builds must not use -Werror; cache the fold helper build #2796 Runtime clang -Werror; fold recompiles every call

Cuts (ready-for-agent)

• refactor(ios-runner): Swift retry decisions keyed on message text → typed codes #2786 Swift retry on message text → typed codes
• refactor(ios-runner): TS runner retry rules keyed on self-produced message text → typed reasons #2787 TS retry on self-produced message text → typed reasons
• chore(ios-runner): delete the unreachable synthesized .continuous drag profile #2790 Dead .continuous drag profile
• chore(ios-runner): remove env knobs nobody sets, the dead back wire command, and unreachable paths #2791 Dead env knobs, back command, unreachable paths
• refactor(ios-runner): move ~3.9k lines of inline unit tests out of production Swift files; split CommandExecution under 1,000 lines #2792 Move inline Swift unit tests out; split CommandExecution under 1,000 lines
• refactor(platform-apple): collapse the runner client forwarding chain and merge the TS command manifest/traits #2793 Runner client forwarding chain; one TS trait table
• refactor(platform-apple): one simctl --set builder and one simulator state parser #2794 One simctl --set builder and state parser (after fix(ios): pass the scoped simulator set to the AX bridge and fold simctl spawn calls #2784)
• refactor(platform-apple): dedupe xctrace logic between perf.ts and perf-xctrace.ts; split perf.ts under 1,000 lines #2795 xctrace dedupe; split perf.ts
• docs(ios-runner): RUNNER_PROTOCOL.md points at the wrong file and omits recovery and busy codes #2797 RUNNER_PROTOCOL.md drift

Decided 2026-09-23 (codex cross-check + code verification), now ready-for-agent

• refactor(cli): drop the inert --device-hub option #2798 Drop the inert --device-hub (plain removal, not treated as breaking)
• fix(macos): reject --fullscreen for macOS desktop/menubar helper surfaces #2799 Reject --fullscreen for macOS desktop/menubar helper surfaces; keep it for app sessions
• refactor(ios-runner): restrict the tap-witness synthesized type route to newline #2800 Restrict the tap-witness type route to '\n'
• fix(ios-runner): bound recorder frame capture through runMainThreadWork #2801 Bound recorder frame capture through runMainThreadWork; screenshots are already bounded
• refactor(ios-runner): delete Swift-side snapshot warning text; keep the tree pin #2802 Delete the Swift warning text (TS already renders every fact); keep the tree pin

Already tracked elsewhere

#2662 covers runner-session cleanup: the response decoder, a state enum, and the curl-through-simctl transport.

Measure before acting (not filed)

• The outer 3× read-only retry in runner/runner-client.ts:42-56. It predates the recycle ledger (Runner resilience under agent-abuse command patterns #1105).
• The runner's private-AX tier, about 1.4k lines. It could go only if the host bridge learns to read custom actions, and removing it weakens recovery while the bridge circuit is open.

Suggested order

1. fix(ios-runner): snapshot capture plan reads and writes main-owned target state off the main thread #2781–fix(ios-runner): non-interactive query sweep outlives its 1s tier slice and causes RUNNER_BUSY #2783 together (runner main-thread correctness).
2. fix(ios): pass the scoped simulator set to the AX bridge and fold simctl spawn calls #2784, fix(ios): physical-device install lost devicectl hints; delete the dead install/uninstall/push paths #2785 and fix(ios): runtime clang builds must not use -Werror; cache the fold helper build #2796.
3. The dead-code cuts chore(ios-runner): delete the unreachable synthesized .continuous drag profile #2790 and chore(ios-runner): remove env knobs nobody sets, the dead back wire command, and unreachable paths #2791.
4. refactor(ios-runner): move ~3.9k lines of inline unit tests out of production Swift files; split CommandExecution under 1,000 lines #2792, then the rest.