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.

Status (2026-09-24)

19 of 22 closed. Remaining:

• fix(ios-runner): one synthesize-then-XCTest-fallback helper; align sequence tap with standalone tap #2788: PR fix(ios-runner): one synthesize-then-fallback helper; sequence taps use the standalone tap policy #2865 is open.
• fix(ios): runtime clang builds must not use -Werror; cache the fold helper build #2796: PR fix(ios): drop -Werror from runtime clang builds and cache the fold helper build #2858 is open. The maintainer is getting the iPhone Duo live evidence separately.
• docs(ios-runner): RUNNER_PROTOCOL.md points at the wrong file and omits recovery and busy codes #2797 (RUNNER_PROTOCOL.md drift): no PR yet. Write it after refactor(ios-runner): Swift retry decisions keyed on message text → typed codes #2786 and refactor(ios-runner): TS runner retry rules keyed on self-produced message text → typed reasons #2787, because both changed the retry and error vocabulary the doc must describe.

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): keep snapshot-plan target state on main and bound the query sweep by its slice #2836
• 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): return work that finished at the timeout boundary and bound recorder frame capture #2837
• 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-runner): keep snapshot-plan target state on main and bound the query sweep by its slice #2836
• 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): spawn the AX bridge and fold helper inside the scoped simulator set #2818
• 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): keep devicectl hints on physical install and delete the dead install paths #2857
• 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-runner): one synthesize-then-fallback helper; sequence taps use the standalone tap policy #2865 open
• fix(ios): visionOS taps request synthesis the runner cannot perform #2789 visionOS taps request impossible synthesis — fix(ios): request runner synthesis only on platforms that synthesize #2835
• fix(ios): runtime clang builds must not use -Werror; cache the fold helper build #2796 Runtime clang -Werror; fold recompiles every call — fix(ios): drop -Werror from runtime clang builds and cache the fold helper build #2858 open; iPhone Duo live evidence supplied separately by the maintainer

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): key runner retry decisions on typed failures, not message text #2831
• 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 — refactor(ios-runner): key TS runner retry rules on typed connect-failure reasons #2820
• chore(ios-runner): delete the unreachable synthesized .continuous drag profile #2790 Dead .continuous drag profile — chore(ios-runner): delete the unreachable synthesized continuous drag profile #2825
• chore(ios-runner): remove env knobs nobody sets, the dead back wire command, and unreachable paths #2791 Dead env knobs, back command, unreachable paths — chore(ios-runner): remove unset env knobs, the dead back wire command, and unreachable paths #2828
• 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(move): move the runner's inline unit tests into UnitTests/ #2854, refactor(move): split RunnerTests+CommandExecution.swift along command families #2855
• 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): collapse the runner client chain and merge the command trait table #2822
• 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(ios): one simctl --set builder and one simulator state parser #2824
• 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 — refactor(platform-apple): dedupe xctrace logic behind perf-xctrace and split perf.ts #2823
• docs(ios-runner): RUNNER_PROTOCOL.md points at the wrong file and omits recovery and busy codes #2797 RUNNER_PROTOCOL.md drift — no PR yet

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) — refactor(cli): drop the inert --device-hub option #2821
• fix(macos): reject --fullscreen for macOS desktop/menubar helper surfaces #2799 Reject --fullscreen for macOS desktop/menubar helper surfaces; keep it for app sessions — fix(macos): refuse --fullscreen on every helper-captured surface #2849 (widened to every helper-captured surface, including frontmost-app)
• refactor(ios-runner): restrict the tap-witness synthesized type route to newline #2800 Restrict the tap-witness type route to '\n' — refactor(ios-runner): restrict the tap-witness synthesized type route to the bare submit key #2845
• fix(ios-runner): bound recorder frame capture through runMainThreadWork #2801 Bound recorder frame capture through runMainThreadWork; screenshots are already bounded — fix(ios-runner): return work that finished at the timeout boundary and bound recorder frame capture #2837
• 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 — refactor(ios-runner): drop the runner's snapshot warning text; the verdict carries every disclosure #2834

Already tracked elsewhere

#2662 (still open) 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.