fix: iOS bug batch — screenshot path honored (#422), run-action fallback resilience (#423), cold build persists .xctestrun (#424) (#427)

* fix(rn-fast-runner): cold start persists a reusable .xctestrun (#424)

xcodebuild's bare 'test' action never writes a .xctestrun to Build/Products,
so a self-built runner stayed permanently 'not prebuilt' — every runner death
paid another multi-minute cold build. The cold path is now two-phase:
build-for-testing (awaited to exit, 360s budget, persists the artifact with
the same shape as the documented manual prebuild) followed by the standard
test-without-building launch (30s ready window). resolveRunnerXcodebuildArgs
is replaced by resolveRunnerStartPlan, which encodes the ordered invocations;
the gh-424 unit test supersedes rn-fast-runner-build-args.test.js whose cold
assertion pinned the buggy bare-test behavior. The #418 rebuild tier funnels
through the same path and is fixed by the same change.

Closes #424

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(device_screenshot): iOS pixels route to simctl — caller path honored (#422)

The rn-fast-runner screenshot verb writes into its own sandbox tmp/ and
returns a relative path; the caller's path is structurally droppable at three
layers (argv translation, RunIOSArgs wire shape, Swift handler), so with a
device session open the observe UI got a dimensionless unservable asset and
sips resize read the wrong file (reason: no-dimensions). iOS now routes to
the already-path-honoring raw simctl capture even when the platform is
inferred — simctl was already the flow-active and runner-down backend, this
makes it the sole iOS pixel path per the D1249 'pixels → simctl' doctrine.
Android keeps its runner path (outPath honored host-side via base64).

Defense-in-depth: the observe recorder now rejects relative screenshot paths
instead of resolving them against the bridge cwd (silent stat-miss blanked
the panel; a cwd file sharing the name would have been misread).

Per-edit review hardening: flow-lease acquisition asserted in gh-210 tests;
stale GH #136/A2 routing comments updated to the new contract.

Closes #422

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(cdp_run_action): CDP/JS fallback probe retries + surfaced skip reasons (#423)

Field root-cause chain (differs from the issue's framing): the park that the
issue presumed missing exists and works — cdp_run_action shares
createMaestroRunHandler → runFlowParked → stopFastRunner with maestro_run,
and a live experiment showed SIGTERM to the xcodebuild host tears down the
sim-side XCUITest runner in ~400ms. The actual dead end: WDA died at launch
(iOS 26.x, #317 family), the CDP/JS replay fallback was eligible (UNKNOWN is
in its trigger) but its single tree probe ran while CDP was mid-reconnect
after the flow's app relaunch, catch(() => null) swallowed it, and the
fallback silently skipped — surfacing an unexplained UNKNOWN after ~50s.

- probeTreeWithRetry: bounded retry (default 3×1.5s, clamped) until the probe
  testID is PRESENT — tolerates both a reconnecting CDP and a still-mounting
  app (per-edit review upgrade over tree-readable-only).
- Every skip is typed in meta.cdpJsFallback { attempted:false, reason:
  no-replay-deps | no-probe-testid | cdp-unreachable | testid-not-in-tree }.
- cdp-unreachable appends actionable guidance (cdp_status, reconnect, stop
  foreign XCUITest automation).

GH #422 hardening bundled from per-edit review (raw is now the primary iOS
pixel path, so its resolution rules tightened): simctl parsers only count iOS
runtimes (booted paired watch can't poison the pick), raw captures bind to
the open session's UDID, no-session resolution refuses on multi-sim
ambiguity instead of first-pick, capturer exceptions honor the
RawScreenshotResult contract, and the observe live panel binds to the
session device too. parseSimctlBootedUDID removed (single-pick semantics
were the hazard); parseSimctlBootedAll is the sole parser.

Closes #423

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* style: oxfmt reflow of gh-422/423/424 files (pre-push format gate)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: Lykhoyda

.changeset/gh-422-ios-screenshot-path.md

@@ -0,0 +1,14 @@
+---
+"rn-dev-agent-cdp": patch
+"rn-dev-agent-plugin": patch
+---
+
+iOS `device_screenshot` honors the caller's `path` (#422): iOS pixels now route
+to `xcrun simctl io screenshot` even with an rn-fast-runner session open — the
+runner's screenshot verb writes inside its own sandbox and returns a relative
+`tmp/…` path the host can never serve, which blanked the observe UI panel and
+broke `sips` resizing (`meta.resize.reason: no-dimensions`). simctl was already
+the flow-active and runner-down backend; it is now the sole iOS pixel path
+("pixels → simctl", D1249). Android is unchanged (its runner honors `outPath`
+host-side). Defense-in-depth: the observe recorder rejects relative screenshot
+paths instead of resolving them against the bridge cwd.

.changeset/gh-423-fallback-probe-resilience.md

@@ -0,0 +1,21 @@
+---
+"rn-dev-agent-cdp": patch
+"rn-dev-agent-plugin": patch
+---
+
+`cdp_run_action` no longer dead-ends in an opaque UNKNOWN when WDA dies at
+launch (#423). Root cause chain from the field failure: the #317 CDP/JS replay
+fallback covers this exact case, but its single tree probe ran while CDP was
+mid-reconnect (the failed flow had just relaunched the app), was silently
+swallowed, and the fallback never engaged. The probe now retries (bounded,
+default 3×1.5s) until the probe testID is actually present — tolerating both a
+reconnecting CDP and a still-mounting app — and every skip is surfaced as
+`meta.cdpJsFallback: { attempted: false, reason }`
+(`no-replay-deps | no-probe-testid | cdp-unreachable | testid-not-in-tree`).
+A `cdp-unreachable` skip appends actionable guidance (check `cdp_status`,
+reconnect, stop foreign XCUITest automation) instead of a bare
+"failure not auto-repairable". Also (#422 hardening): the simctl UDID parsers
+now only consider iOS runtimes (a booted paired watchOS/tvOS simulator can
+neither win the screenshot UDID pick nor make the single iPhone look ambiguous
+to `resolveIosUdid`), and raw captures bind to the open device session's UDID
+when platforms match instead of picking the first booted device.

.changeset/gh-424-cold-build-xctestrun.md

@@ -0,0 +1,14 @@
+---
+"rn-dev-agent-cdp": patch
+"rn-dev-agent-plugin": patch
+---
+
+iOS cold start persists a reusable `.xctestrun` (#424): `startFastRunner()` now
+runs `xcodebuild build-for-testing` first when no test product exists and then
+launches via the same `test-without-building` path as every warm start, instead
+of a single bare `xcodebuild test` — which never writes a `.xctestrun`, so
+self-built runners were permanently "not prebuilt" and every runner death cost
+another multi-minute cold build. The build phase keeps the 360s cold timeout;
+the launch phase uses the standard 30s ready window. The #418 stale-artifact
+rebuild tier funnels through the same path, so it also leaves a reusable
+artifact now.

scripts/cdp-bridge/dist/index.js

@@ -203,7 +203,12 @@ const liveDeps = buildLiveDeps({
     isFlowActive: () => arbiter.flowActive || foreignFlowGate.lastActive,
     getActiveSession,
     getClient: () => getClient(),
-    captureScreenshot: (platform, path) => tryRawScreenshot(platform, path),
+    captureScreenshot: (platform, path) => {
+        // GH #422: bind the live panel to the session device too — raw resolution
+        // refuses on multi-sim ambiguity instead of first-pick now.
+        const session = getActiveSession();
+        return tryRawScreenshot(platform, path, session && session.platform === platform ? session.deviceId : undefined);
+    },
     readRoute: (c) => readLiveRoute(c),
     readShotFile: (path) => {
         try {

scripts/cdp-bridge/dist/observability/recorder.js

@@ -1,12 +1,18 @@
 import { readFileSync, statSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
 import { RingBuffer } from '../ring-buffer.js';
 import { mapObservation, unwrapResult } from './events.js';
 const DEFAULT_CAP = 500;
 const MAX_SHOT_BYTES = 4_000_000;
+// GH #422: absolute paths only — a runner-internal relative path (e.g. iOS
+// "tmp/…") would resolve against the bridge cwd, silently blanking the panel
+// or reading an unrelated file that shares the name.
 function screenshotPath(result) {
     const data = (unwrapResult(result)?.data ?? result?.data);
     const p = data?.path ?? data?.message;
-    return typeof p === 'string' && (p.endsWith('.jpg') || p.endsWith('.jpeg') || p.endsWith('.png'))
+    return typeof p === 'string' &&
+        isAbsolute(p) &&
+        (p.endsWith('.jpg') || p.endsWith('.jpeg') || p.endsWith('.png'))
         ? p
         : null;
 }

scripts/cdp-bridge/dist/runners/rn-fast-runner-client.js

@@ -203,18 +203,20 @@ export function isFastRunnerAvailable() {
     return false;
 }
 /**
- * Decide which xcodebuild invocation launches the runner.
+ * Decide the ordered xcodebuild invocations that start the runner.
  *
- * `test-without-building` is the fast steady-state path, but it requires a prior
- * `build-for-testing` to have produced a .xctestrun. On a fresh machine that
- * artifact is absent (build/ is gitignored), so we fall back to a full `test`,
- * which compiles the project first and then runs it — making the runner
- * self-install on first use (D1219 follow-up).
+ * `test-without-building` is the fast steady-state launch, but it requires a
+ * prior `build-for-testing` to have produced a .xctestrun. On a fresh machine
+ * that artifact is absent (build/ is gitignored), so the cold path builds it
+ * first and then launches warm — making the runner self-install on first use
+ * (D1219 follow-up). GH #424: a bare `xcodebuild test` never writes a
+ * .xctestrun, so the previous single-invocation cold path left the runner
+ * permanently "not prebuilt" and every runner death cost another multi-minute
+ * cold build. The build step carries no -only-testing so it produces the same
+ * artifact as the documented manual prebuild.
  */
-export function resolveRunnerXcodebuildArgs(opts) {
-    const action = opts.hasBuiltTestProduct ? 'test-without-building' : 'test';
-    return [
-        action,
+export function resolveRunnerStartPlan(opts) {
+    const common = [
         '-project',
         opts.projectPath,
         '-scheme',
@@ -223,8 +225,14 @@ export function resolveRunnerXcodebuildArgs(opts) {
         `platform=iOS Simulator,id=${opts.deviceId}`,
         '-derivedDataPath',
         opts.derivedDataPath,
-        `-only-testing:${opts.onlyTesting}`,
     ];
+    const launch = {
+        action: 'test-without-building',
+        args: ['test-without-building', ...common, `-only-testing:${opts.onlyTesting}`],
+    };
+    if (opts.hasBuiltTestProduct)
+        return [launch];
+    return [{ action: 'build-for-testing', args: ['build-for-testing', ...common] }, launch];
 }
 /** True when a prior build-for-testing left a .xctestrun under DerivedData. */
 export function hasBuiltTestProduct(derivedDataPath) {
@@ -325,28 +333,64 @@ export function buildRunnerVersionEnv(pluginVersion) {
         TEST_RUNNER_RN_PLUGIN_VERSION: pluginVersion,
     };
 }
+/**
+ * GH #424: run a build-phase xcodebuild (build-for-testing) to completion.
+ * Unlike the launch invocation it exits on its own and emits no READY marker,
+ * so success is exit code 0 — the .xctestrun it writes is what makes every
+ * later start warm.
+ */
+function runXcodebuildToExit(args, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('xcodebuild', args, { stdio: ['ignore', 'ignore', 'pipe'] });
+        let stderrTail = '';
+        const timer = setTimeout(() => {
+            child.kill('SIGTERM');
+            reject(new Error(`xcodebuild ${args[0]} did not complete within ${timeoutMs / 1000}s (cold build — first run compiles the runner)`));
+        }, timeoutMs);
+        child.stderr.setEncoding('utf-8');
+        child.stderr.on('data', (chunk) => {
+            stderrTail = (stderrTail + chunk).slice(-2000);
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            reject(new Error(`Failed to spawn xcodebuild: ${err.message}`));
+        });
+        child.on('exit', (code) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`xcodebuild ${args[0]} failed (code ${code})${stderrTail ? `: ${stderrTail.trim()}` : ''}`));
+        });
+    });
+}
 export async function startFastRunner(deviceId, bundleId, port) {
     adoptPersistedFastRunnerState(deviceId);
     if (shouldReuseRunner(runnerState, deviceId))
         return runnerState;
     const desired = port ?? ((await isPortFree(DEFAULT_PORT)) ? DEFAULT_PORT : 0);
-    return new Promise((resolve, reject) => {
-        const projectPath = join(FAST_RUNNER_PROJECT, 'RnFastRunner', 'RnFastRunner.xcodeproj');
-        if (!existsSync(projectPath)) {
-            reject(new Error(`RnFastRunner.xcodeproj not found at ${projectPath}.`));
-            return;
+    const projectPath = join(FAST_RUNNER_PROJECT, 'RnFastRunner', 'RnFastRunner.xcodeproj');
+    if (!existsSync(projectPath)) {
+        throw new Error(`RnFastRunner.xcodeproj not found at ${projectPath}.`);
+    }
+    const derivedDataPath = derivedDataPathForRunner();
+    const plan = resolveRunnerStartPlan({
+        projectPath,
+        scheme: 'RnFastRunner',
+        deviceId,
+        derivedDataPath,
+        onlyTesting: 'RnFastRunnerUITests/RnFastRunnerTests/testCommand',
+        hasBuiltTestProduct: hasBuiltTestProduct(derivedDataPath),
+    });
+    for (const step of plan.slice(0, -1)) {
+        await runXcodebuildToExit(step.args, BUILD_READY_TIMEOUT_MS);
+        if (!hasBuiltTestProduct(derivedDataPath)) {
+            throw new Error(`xcodebuild ${step.action} completed but left no .xctestrun under ${derivedDataPath}/Build/Products — unexpected DerivedData layout`);
         }
-        const derivedDataPath = derivedDataPathForRunner();
-        const built = hasBuiltTestProduct(derivedDataPath);
-        const args = resolveRunnerXcodebuildArgs({
-            projectPath,
-            scheme: 'RnFastRunner',
-            deviceId,
-            derivedDataPath,
-            onlyTesting: 'RnFastRunnerUITests/RnFastRunnerTests/testCommand',
-            hasBuiltTestProduct: built,
-        });
-        const child = spawn('xcodebuild', args, {
+    }
+    const launch = plan[plan.length - 1];
+    return new Promise((resolve, reject) => {
+        const child = spawn('xcodebuild', launch.args, {
             env: {
                 ...process.env,
                 RN_FAST_RUNNER_PORT: String(desired),
@@ -358,12 +402,10 @@ export async function startFastRunner(deviceId, bundleId, port) {
         runnerProcess = child;
         const parser = createReadySignalParser();
         let resolved = false;
-        const readyTimeoutMs = built ? READY_TIMEOUT_MS : BUILD_READY_TIMEOUT_MS;
         const timer = setTimeout(() => {
             child.kill('SIGTERM');
-            const phase = built ? '' : ' (cold build — first run compiles the runner)';
-            reject(new Error(`Fast runner did not become ready within ${readyTimeoutMs / 1000}s${phase}`));
-        }, readyTimeoutMs);
+            reject(new Error(`Fast runner did not become ready within ${READY_TIMEOUT_MS / 1000}s`));
+        }, READY_TIMEOUT_MS);
         const handleChunk = (chunk) => {
             if (resolved)
                 return;

scripts/cdp-bridge/dist/tools/device-list.js

@@ -237,11 +237,17 @@ export function wrapResultWithAdvisories(result, advisories) {
  * - flow active + platform known → 'simctl' (OS-level, flow-safe).
  * - flow active + platform unknown → 'fail' (NEVER the runner — would hit XCUITest
  *   unleased and crash the flow, A3).
- * - no flow → 'runner' (rn-fast-runner primary; its own simctl fallback fires on error).
+ * - no flow, iOS → 'simctl' (GH #422: the rn-fast-runner screenshot verb writes
+ *   inside its own sandbox and returns a relative tmp/ path — the caller's `path`
+ *   cannot reach it over the wire, so simctl is the only iOS backend that can
+ *   honor it; "pixels → simctl" per D1249).
+ * - no flow, otherwise → 'runner' (Android's runner honors outPath host-side).
  */
 export function chooseScreenshotPath(input) {
     if (input.flowActive)
         return input.platform ? 'simctl' : 'fail';
+    if (input.platform === 'ios')
+        return 'simctl';
     return 'runner';
 }
 /**
@@ -287,7 +293,7 @@ export async function captureAndResizeScreenshot(args) {
     const rawResultFail = (platform, reason) => {
         const cli = platform === 'ios' ? 'xcrun simctl' : 'adb';
         const hint = reason === 'no-device'
-            ? `No booted ${platform === 'ios' ? 'iOS Simulator' : 'Android emulator'} detected by ${cli}. Boot one and retry; if your emulator is in 'offline' or 'unauthorized' state, restart it.`
+            ? `No booted ${platform === 'ios' ? 'iOS Simulator' : 'Android emulator'} was unambiguously resolvable by ${cli} — none booted, or several booted with no open device session. Boot exactly one, or open a session (device_snapshot action=open) to bind the target; if your emulator is 'offline'/'unauthorized', restart it.`
             : `Capture command failed (${cli}). The device may be transitioning state (booting, OOM, locked). Retry once it stabilizes.`;
         return failResult(`device_screenshot platform=${platform} failed: ${hint}`, 'SCREENSHOT_FAILED', { platform, reason });
     };
@@ -306,18 +312,24 @@ export async function captureAndResizeScreenshot(args) {
     }
     // simctl path: a flow owns the device (raw-ONLY — never fall through to the runner, A3),
     // OR the existing GH#136 explicit-platform disambiguation (no flow). Both hard-fail on error.
+    // GH #422: bind raw captures to the open session's device when platforms
+    // match — raw is now the primary iOS path and must not pick "first booted"
+    // over the session device on multi-sim setups.
+    const session = getActiveSession();
+    const sessionDeviceId = session && session.platform === args.platform ? session.deviceId : undefined;
     if ((route === 'simctl' || args.platformExplicit) &&
         (args.platform === 'ios' || args.platform === 'android')) {
-        const raw = await tryRawScreenshot(args.platform, requestedPath);
+        const raw = await tryRawScreenshot(args.platform, requestedPath, sessionDeviceId);
         if (raw.ok)
             result = rawResultOk(raw.path, args.platform);
         else
             return rawResultFail(args.platform, raw.reason);
     }
     if (!result) {
         // route === 'runner' (NO flow — runAgentDevice can never run while a flow is active here).
-        // A2: runIOS()/postCommand THROW when the runner is down, so the bare isError check is dead
-        // code for that path; catch it, then fall back to simctl so iOS never hard-fails.
+        // Since GH #422 a known-iOS platform never reaches this branch (routed to simctl above);
+        // it serves Android and the platform-unresolved case. A2: the runner client THROWS when
+        // down, so catch it, then fall back to raw capture when the platform is known.
         try {
             result = await runAgentDeviceFn(buildScreenshotArgs(argsWithPath), {
                 platform: args.platform ?? null,
@@ -327,7 +339,7 @@ export async function captureAndResizeScreenshot(args) {
             result = failResult(err instanceof Error ? err.message : String(err), 'SCREENSHOT_FAILED');
         }
         if (result.isError && (args.platform === 'ios' || args.platform === 'android')) {
-            const raw = await tryRawScreenshot(args.platform, requestedPath);
+            const raw = await tryRawScreenshot(args.platform, requestedPath, sessionDeviceId);
             if (raw.ok)
                 result = rawResultOk(raw.path, args.platform);
         }

scripts/cdp-bridge/dist/tools/device-screenshot-raw.js

@@ -8,9 +8,11 @@
  * `--platform` routing issue when both an iOS sim and an Android emu are
  * booted simultaneously (the field-reported bug from issue #136 #1).
  *
- * On any failure (resolution fails, command errors), the caller falls through
- * to the existing `runAgentDevice` path — no behavior change for users who
- * don't pass `platform` or who run a single device.
+ * Failure behavior (updated by GH #136 PR-B): callers on the explicit-platform
+ * or raw-only routes HARD-FAIL with an actionable SCREENSHOT_FAILED — falling
+ * through to another backend was the wrong-platform regression vector. Only
+ * the Android runner-error path still falls back here (see device-list.ts).
+ * Since GH #422 this raw path is also the primary iOS pixel backend.
  *
  * Test seams (`_setForTest`, `_resetForTest`) follow the GH #136 picker
  * precedent — allow unit tests to inject resolver/capturer fakes without
@@ -20,31 +22,9 @@ import { execFile, spawn } from 'node:child_process';
 import { createWriteStream, unlinkSync } from 'node:fs';
 import { promisify } from 'node:util';
 const execFileAsync = promisify(execFile);
-export function parseSimctlBootedUDID(jsonText) {
-    let data;
-    try {
-        data = JSON.parse(jsonText);
-    }
-    catch {
-        return null;
-    }
-    const runtimes = data?.devices;
-    if (!runtimes || typeof runtimes !== 'object')
-        return null;
-    for (const list of Object.values(runtimes)) {
-        if (!Array.isArray(list))
-            continue;
-        for (const device of list) {
-            if (device &&
-                device.state === 'Booted' &&
-                typeof device.udid === 'string' &&
-                device.udid.length > 0) {
-                return device.udid;
-            }
-        }
-    }
-    return null;
-}
+// GH #422: the single-pick parseSimctlBootedUDID was removed — first-booted
+// selection was a silent wrong-device capture once raw became the primary iOS
+// path. All resolution goes through parseSimctlBootedAll + exactly-one.
 export function parseSimctlBootedAll(jsonText) {
     let data;
     try {
@@ -57,7 +37,12 @@ export function parseSimctlBootedAll(jsonText) {
     if (!runtimes || typeof runtimes !== 'object')
         return [];
     const udids = [];
-    for (const list of Object.values(runtimes)) {
+    for (const [runtime, list] of Object.entries(runtimes)) {
+        // GH #422 hardening: a booted paired watchOS/tvOS sim must not make the
+        // single iOS sim look ambiguous to resolveIosUdid, nor be counted as an
+        // iOS device.
+        if (!runtime.includes('SimRuntime.iOS'))
+            continue;
         if (!Array.isArray(list))
             continue;
         for (const device of list) {
@@ -110,7 +95,11 @@ const defaultIosResolver = async () => {
             timeout: 5000,
             maxBuffer: 1024 * 1024,
         });
-        return parseSimctlBootedUDID(stdout);
+        // GH #422: raw is the primary iOS pixel path now, so a no-session resolve
+        // must be unambiguous — with several booted iOS sims, first-pick was a
+        // silent wrong-device capture. Callers with a session pass its UDID.
+        const all = parseSimctlBootedAll(stdout);
+        return all.length === 1 ? all[0] : null;
     }
     catch {
         return null;
@@ -249,12 +238,22 @@ export function _resetForTest() {
     iosCapturer = defaultIosCapturer;
     androidCapturer = defaultAndroidCapturer;
 }
-export async function tryRawScreenshot(platform, path) {
+export async function tryRawScreenshot(platform, path, preferredDeviceId) {
     const resolver = platform === 'ios' ? iosResolver : androidResolver;
     const capturer = platform === 'ios' ? iosCapturer : androidCapturer;
-    const id = await resolver();
+    // GH #422: raw is now the PRIMARY iOS pixel path, so it must inherit the
+    // session's device binding — with two booted sims, "first booted" could
+    // capture the wrong one. No session → single-booted resolution as before.
+    const id = preferredDeviceId ?? (await resolver());
     if (!id)
         return { ok: false, reason: 'no-device' };
-    const ok = await capturer(id, path);
-    return ok ? { ok: true, path } : { ok: false, reason: 'capture-failed' };
+    try {
+        const ok = await capturer(id, path);
+        return ok ? { ok: true, path } : { ok: false, reason: 'capture-failed' };
+    }
+    catch {
+        // Raw is the primary iOS path since GH #422 — a thrown capturer error
+        // (fs validation, spawn failure) must honor the result contract.
+        return { ok: false, reason: 'capture-failed' };
+    }
 }