feat(ios): route Simulator snapshots through AX bridge

[thymikee]

Summary

Closes #2197. Eligible local iOS Simulator snapshots use the packaged AX bridge and existing TypeScript presenter, with typed, generation-scoped XCTest fallback. Unknown generations remain incomparable; regular depth is presentation-only and raw depth bounds acquisition.

Target discovery is reused only while OS process-start identity matches. Native acquisition verifies the foreground owner before and after capture, preventing app-only trees beneath system dialogs. XCTest retains modal resolution; fallback disables the bridge until that app generation changes. Provider, physical-device, interaction, and prewarm routes are preserved.

Scope: 34 files, 1,353 gross lines; maintainer-approved exception for required correctness and regression coverage.

Validation

Head: ae26f7afc064c75c65c71e677d32d77cdf2f9709; matched base: 7a2d48d160aaacb582c6f4cde98b6af7531bf7af.

• Published acceptance evidence is held separately on evidence/ios-snapshot, tagged evidence/ios-snapshot/ae26f7afc0: raw responses, traces, provenance, checksums, and verification script.
• Six screens × 20 warm samples per revision: 240 captures, zero failures or anchor mismatches. CLI median/p95 improved on all six; sequential runs under uncontrolled host load do not establish a general speed guarantee.
• Live foreground fallback, dismissal/relaunch circuit proof, and real native capture tests retained. Five native scenarios pass; deleting PRE produces three failures, deleting POST one.
• Final-head pnpm check:affected --run passed (746 files / 5,691 tests); all runnable CI checks green. Accepted Size growth: +35,845 unpacked bytes.

Acceptance evidence is complete. Runner-demand/open latency and proxy acceptance remain #2198 scope.

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	4.44 MB	4.48 MB	+35.8 kB
Package (unpacked)	4.44 MB	4.48 MB	+35.8 kB
Package (download)	1.32 MB	1.33 MB	+10.4 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	28.8 ms	28.0 ms	-0.8 ms
CLI --help	80.2 ms	80.3 ms	+0.1 ms

[thymikee]

Review at exact head 1600d40d077b02a547349396b0677d15902bb7ab: blocked on two comparison-lineage bugs plus the exact-head iOS failure.

1. snapshot-route.ts stamps XCTest fallback with the pre-acquisition target lineage. When bridge acquisition reports a stale/relaunched target, XCTest may capture the new app while the result is labeled with the old generation. Re-resolve before fallback or make that fallback explicitly incomparable, and add a stale-generation -> fallback regression.
2. Target-resolution failure creates a comparison identity with only stable targetId; two results with omitted generations compare equal. They can straddle an app relaunch and still be treated as one baseline. Unknown-generation fallback must fail closed across comparisons, with a closest-negative regression.
3. Exact-head iOS Smoke is red: the regular depth-1 fixture now routes through the bridge and no longer provides the asserted snapshotQuality.backend === "tree". Reconcile the shipped output/evidence contract and rerun the iOS lane green.

The route otherwise reuses the Apple runtime/facade and shutdown seams cleanly, and the merged source lifecycle already provides authoritative OS process-start-time checks around acquisition.

[thymikee]

Addressed all three actionable review items in fd3c6ac:

1. Stale acquisition: stale-target failures now resolve the current target again before XCTest fallback, and the regression proves the fallback identity carries the relaunched generation.
2. Unknown generation: resolution failures carry a typed per-capture unknown-generation residue. The closest-negative regression proves two otherwise identical unresolved fallbacks do not compare equal.
3. iOS smoke: the depth-frontier scenario now asserts the bridge public evidence shape (no XCTest tree quality annotation plus the acquisition evidence warning) for regular and raw captures.

Also normalized fallback lineage to the declared targetId/generation fields only.

Planted-red failures were observed for items 1 and 2 before the fix. Exact-head pnpm check:affected --run is green: 731 test files, 5,589 tests. The updated iOS native lane is running on this head.

[thymikee]

Re-review at exact head fd3c6ac226e6fe2fff5eb3aaf2ded51662aacf63 remains blocked. P1: exact-head iOS Simulator Smoke failed in the live fixture: snapshot --depth 1 published only the Application root and omitted visible-depth-projected-child. This was a successful bridge publication (not typed fallback), so it violates #2197's established regular-depth result and disproves readiness. Fix the acquisition/presentation route so bridge success preserves the visible-depth contract, then rerun the live lane. P2: the Size report shows +35.2 kB npm unpacked (+11.2 kB gzip), above the 3 kB review trigger, but the PR body does not itemize the growth or record why a materially smaller design was rejected. The architecture otherwise reuses the intended source facade, runtime binding, shared presentation engine, and interaction facade; all non-iOS checks pass.

[thymikee]

Follow-up from the exact-head iOS rerun: after the requested evidence assertion was corrected, the lane exposed a real bridge-depth bug rather than a test-only mismatch.

Regular --depth 1 was being sent to the native bridge as maxDepth: 1, so the TypeScript presenter never received the deeper structural nodes needed to project the visible child to presented depth 1. Fixed in 1519222: only rawTraversalDepth bounds native acquisition; regularPresentedDepth remains presentation-only.

A planted-red adapter test observed 1 instead of the bounded maximum 10, while raw depth 1 remained 1. Focused tests pass, and the rebased exact-head affected gate is green with 734 files / 5,624 tests.

[thymikee]

Exact-head iOS rerun is green at 1519222. It passed clean-install bridge preparation, targeted XCTest regressions, public CLI preflight, Settings replay, the fixture-backed E2E scenario with the corrected depth frontier, and gesture replay. All PR checks are now green.

[thymikee]

The exact-head depth fix is correct: regular --depth is presentation-only again, while only rawTraversalDepth bounds native acquisition. The regression test covers the old failure, exact-head iOS Smoke includes the real projected-child assertion plus raw-depth counterexample, and all checks are green.

One readiness item remains: CI reports +35.2 kB npm unpacked (+11.2 kB gzip). Because this exceeds the repository threshold, please itemize the justified package growth and record which materially smaller designs were considered and why they were rejected. Until that rationale is recorded, I’m holding ready-for-human.

[thymikee]

Addressed the remaining size-review item. The CI size report at 1519222 measures +35.2 kB npm unpacked and +11.2 kB JS gzip:

• +27.2 kB: the existing adapter and its cache, lifecycle, transport, and tree-decoding dependencies become reachable from the shipped CLI. This is reused implementation, not another bridge. The facade still dynamically imports it only on the first eligible capture.
• +4.8 kB: Apple runtime chunk growth, including routing, target resolution, bounded fallback, and generation-scoped circuit state.
• +2.0 kB: the shared snapshot-planning chunk becomes separately emitted/reachable. Presentation still has one TypeScript owner.
• Remaining roughly +1.2 kB net: declaration growth, other changed/shared chunks, and packaging output. This includes the -706 B runner-presentation reduction; rounded chunk deltas are not a source-line attribution.
• Native runner, presentation, and simulator bridge source payloads are unchanged (0 B each).

Smaller alternatives considered: retaining XCTest-only routing would omit #2197; deleting XCTest would break required fallback and excluded targets; replacing the source facade with direct helper calls would duplicate or drop its existing deadline, process-generation, cache, and teardown safeguards. Moving the adapter into an optional package would move the installation cost rather than remove it, introduce a separate install/version boundary, and change the packaged-default contract. None is a justified reduction for this slice.

The repository-required independent read-only size/design review found no actionable simplification: one runtime-owned lazy source is reused and closed, with the existing presenter and fallback retained. No production-code changes were needed for this comment.

Rebased onto 0da105e; git range-diff confirms all three patches are unchanged. The new head is 37e3ef5. Prior green CI/device evidence is stamped to the old head; fresh validation is reported in the PR description.

[thymikee]

Reviewed 37e3ef5: no remaining actionable findings. Stale/unknown lineage and regular-depth regressions are resolved; existing lazy bridge, shared presenter and typed fallback retained. The +35.2 kB growth is itemized and smaller designs addressed. Prior live depth/raw-depth evidence covers the unchanged rebased patches. Code-review clean; fresh iOS CI was pending at review, so not an unconditional merge-ready claim.

[thymikee]

Delta review at e84bdc1, independently reviewed: no concrete source-level findings. Device/app-scoped target reuse requires matching process start identity; the bridge checks the pinned identity before capture and current identity after it, and stale acquisition explicitly refreshes discovery before fallback. Tests cover PID reuse, unavailable identity, replacement and refresh. Existing source/presenter/lifecycle owners are reused. Readiness remains held for the promised exact-base versus head six-screen benchmark and public-response evidence, still marked in progress; prior green evidence does not cover this new warm-path delta. Exact-head iOS is also pending. Removed the label that this sentinel applied to the previous head; restore only after the required evidence is complete and no failing checks/conflicts remain.

[thymikee]

Sentinel evidence update at unchanged e84bdc1: exact-head iOS Smoke is now failing in smoke:automation-input, waiting for Agent Device Tester. Typed reason wait_capture_stalled, readableCaptures=0, 10,000 ms budget / 10,233 ms elapsed (run 33985544618). This does not yet isolate a source defect, but requires investigation or successful exact-head validation. The promised matched six-screen benchmark/public-response evidence is also still marked in progress. Previous code review stands; readiness remains held.

[thymikee]

Acceptance update at 7cf6e7fd3841f0e63ae56d5a9cc1459920193b41:

• Scope exception approved: the maintainer approved keeping the required correctness fixes and regression coverage together at 1,267 gross changed lines. This is a scoped exception to the 1,000-line PR budget, not a readiness waiver.
• Stalled iOS capture investigated: run 33985544618, at e84bdc15d4, shows the fixture home screen correctly visible. Request 712353abbe3417aa spent 4,650 ms connecting for runner findText, then target discovery hit its 3,000 ms xcrun timeout. Typed target-resolution fallback started with about 1.8 seconds left and was cancelled at the original request deadline. No bridge acquisition occurred. This identifies where the budget was spent; it does not establish the underlying cause of the slow connections or dismiss the failure as flaky. Fresh exact-head iOS validation remains required.
• Foreground correctness: the worker observed a normal bridge capture, then opened a microphone permission dialog in the same app process. foreground-owner-unverified triggered XCTest fallback, which returned the dialog and buttons rather than the covered app tree. The native guard and automatic iOS regression are committed. Local affected gates passed: 743 files / 5,671 tests.
• Benchmark evidence remains pending: the matched six-screen base/head corpus is not complete. A rebase is underway because upstream perf: bundle runtime dependencies and report full install size #2310 changed packaging and the size-report schema; the size job mixed reporter versions and failed before comparison. Final measurements will use the updated exact base/head, with earlier evidence retaining its original SHA attribution.

Still required before merge-readiness: publish the complete matched benchmark/public-response artifacts and obtain green final-head CI, including iOS. No new performance claim yet.

[thymikee]

Sentinel review at 7cf6e7f: Two confirmed readiness gaps: (1) the new native-runtime.test.ts beforeAll hits the 10s hook timeout in iOS run33987768263, so its native regression never executes; use an explicit bounded compile/hook budget or smaller compilation scope and establish green CI. (2) foreground-owner.m calls only isPrimaryForegroundProcess, not snapshotForProcess: removing either new pre/post ownership guard leaves this test green. Add regression proof that deleting either guard fails and covered/changing ownership yields typed failure without publishing the app tree. The foreground-owner implementation otherwise matches the intended fallback policy. Matched benchmark/public-response artifacts remain pending, and Size has the cross-version reporter-schema failure. No readiness label.

[thymikee]

Follow-up to the two findings in this review:

1. Compiler/setup timeout: the current branch uses a 45-second compiler subprocess deadline and a separate 60-second beforeAll budget. Each test executable also has a 5-second deadline. This bounds the expensive setup without increasing the runtime test timeout indiscriminately. Green final-head iOS CI is still required; the earlier 10-second hook failure is not being treated as a passed regression.

2. Guard-deletion proof: I replaced the predicate-only test with five cases calling the actual snapshotForProcess entry point. The fixture compiles the production runtime with fake native dependencies and loader symbols; it does not copy the guards or add production test hooks. It exercises initialization, capture, both ownership checks, and tree materialization.

Observed with pnpm exec vitest run packages/platform-apple/src/snapshot-source/native-runtime.test.ts:

Production mutation	Result
Delete only the pre-acquisition guard	3 failures: covered, missing, malformed ownership
Restore pre-guard; delete only the post-acquisition guard	1 failure: changed ownership publishes the app tree
Restore both guards	All 5 pass

Refusal cases assert no published tree, the exact typed ownership failure, request ID, and expected native acquisition count. The stable case requires a successfully materialized app tree, preventing an always-refuse implementation from passing.

The test-only change was independently handed to the implementation worker and is integrated locally, awaiting the serialized final gate and PR push. Production runtime code is unchanged by this test fix. This records completed regression proof, not final CI acceptance. The worker continues to own final-head iOS validation and the matched six-screen benchmark/public-response artifacts; those remain open until their evidence is published.

[thymikee]

The remaining acceptance evidence is now published; no benchmark waiver is needed.

Immutable evidence corpus, tag evidence/ios-snapshot/ae26f7afc0, compares head ae26f7afc064c75c65c71e677d32d77cdf2f9709 against base 7a2d48d160aaacb582c6f4cde98b6af7531bf7af. It includes the full public responses, request traces, samples, fixture provenance, checksums, and a corpus verifier. I independently ran the verifier and checksum validation after the worker handed over the completed runs.

Screen	Base CLI median / p95 (ms)	Head CLI median / p95 (ms)
quiet	122.9 / 143.4	99.4 / 124.1
list	291.9 / 308.6	206.3 / 225.7
nested-scroll	164.5 / 197.1	109.2 / 166.0
alert	220.3 / 318.2	137.4 / 163.5
system-surface	188.0 / 279.5	133.7 / 154.3
xctest-stress	221.7 / 293.4	137.1 / 152.3

20 warm samples per screen per revision, 240 total; zero failed samples, unreadable trees, anchor mismatches, or admission stops. Head initial traces confirm bridge acquisition followed by TypeScript presentation; measured responses have no fallback warning. These are sequential same-device runs with uncontrolled host load, not a general performance guarantee or cold-start claim.

The evidence also preserves live system-dialog fallback and generation-circuit recovery, plus the real native guard-deletion proof requested in review: five cases pass, PRE deletion fails three, POST deletion fails one. Final-head iOS CI executed the five cases successfully. All runnable checks remain green and GitHub reports CLEAN. The earlier stalled capture was documented as connection/discovery exhausting the request budget before bridge acquisition; it is not being presented as a proven bridge failure or a fully root-caused infrastructure incident.

The PR body now reflects completed acceptance, with evidence off the source branch. The worker confirmed benchmark daemons stopped and the dedicated simulator removed. No additional code changes or duplicate device runs were needed. #2198 still owns runner-demand/open latency and proxy acceptance. Ready for maintainer merge; not merged by me.

[thymikee]

Sentinel at ae26f7a: clean coordinator + independent Terra/high review; merge-ready. The immutable a0e6418/pr-2279 corpus now closes the matched benchmark gap: exact base/head, 240 captures, no failures/anchor mismatches, bridge-to-TypeScript traces; independent checksum/corpus verification passed. The native regression exercises the real capture entry point with PRE/POST deletion proof, and exact-head iOS executes all five cases. All runnable CI checks are green and no conflicts. Size growth (+35,845 unpacked bytes) and scoped growth rationale are recorded; existing presenter/modal resolution are reused. Sequential uncontrolled-host measurements are not a general speed guarantee. Next action: maintainer merge; no merge performed.

[github-actions]

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