feat(#186): Phase 6 — foreign-flow arbitration + canonical Maestro surface

[Lykhoyda]

Summary

#202 Phase 6 — the final phase of the re-think spec (docs/superpowers/specs/2026-06-10-device-control-phase4-6-rethink-design.md §3). Closes #186.

A detected foreign Maestro/XCUITest session (standalone maestro-mcp, raw CLI) is now an arbiter input: while it drives the target simulator (UDID-scoped ps axww scan, 5 s TTL, fail-open), local L2 device_* and L3 flow tools refuse fast with BUSY_FOREIGN_FLOW — pointing at the safe L1 reads — instead of colliding into the ~44 s runner-leak cascade #186 reported. L1 introspection stays free by contract; device_screenshot serves pixels via its simctl fallback; a 10 s teardown grace after the plugin's own flows prevents self-false-positives while WDA dies (plan-review BLOCKER). The plugin's maestro_run is declared the canonical Maestro surface.

Live gate (b) — foreign refusal end-to-end (booted iPhone 17 Pro)

planted fake foreign runner pid 46178 (argv contains maestro token + CE9D3DB9-…)
PASS: device_press refused BUSY_FOREIGN_FLOW in 53ms (vs the ~44s cascade in #186)
PASS: maestro_run (L3) refused BUSY_FOREIGN_FLOW
PASS: cdp_navigation_state (L1) unaffected
PASS: device_screenshot served via simctl fallback
PASS: refusal cleared within one TTL window after the foreign session ended
GATE PASS: foreign-flow arbitration end-to-end

~830× faster failure (53 ms vs ~44 s), and it's an explained refusal instead of a cascade.

Live gate (a) — escape hatches verified closed (#201 closed)

PASS #201: clearState flow ran via maestro_run (auto --app-file)
PASS #188: runFlow conditional ran through the plugin validator
GATE PASS: both escape hatches closed — plugin surface is sufficient

The gate caught one more real bug in the shipped #201 fix: the resolver passed the installed container path as --app-file, but clearState deletes that container before maestro-runner reinstalls from it ("No such file or directory", app left uninstalled). Fixed: the container resolution is snapshotted outside the device container (APFS clonefile cp -Rc) first (8119ba1).

Plan-review hardening (Gemini + Claude research, pre-code)

• BLOCKER: teardown grace — our own dying maestro driver matches the detector for seconds after lease release; cache-busting can't fix it (a fresh scan still sees the dying PID); DeviceSessionArbiter.lastFlowReleasedAt gates the scan.
• ps axww — command-column truncation could silently drop a mid-path UDID (production false negatives).
• Honest knob: RN_IOS_FOREIGN_GUARD=0 (authoritative; gates a refusal now, not a log line); RN_IOS_FOREIGN_WARN=0 stays as a deprecated alias with the same full effect.
• udid-gated in-flight scan dedup.

Tests

1985/1985 (test:all): 8 gate + 12 arbiter-foreign unit tests (incl. teardown grace, L1-never-scans, own-flow skip, envelope extras), 2 snapshot-resolver tests + 2 updated contract tests, wiring pins. Composite one-call-one-lease verified (internal handler calls never re-enter the gate).

This is the last open front of #202 — the issue closes when this merges.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.