fix(cdp): fast-fail cdp_status when the Dev Client picker blocks the bundle (closes #184) (#187)

cdp_status with the Expo Dev Client "Development servers" picker up AND Metro
running hung ~33.5s: stale C++ targets pass filterValidTargets, the 1+1 probe
passes, and performSetup's waitForReact then burns its full 30s before returning
a misleading ok:true.

Fix: thread a connect intent ('default' | 'status') through
autoConnect -> discoverAndConnect -> connectToTarget. For a status-scoped connect
against a non-Hermes target, run a bounded React-reachability probe (default 5s,
RN_PICKER_PROBE_BUDGET_MS-overridable) BEFORE setup()'s 30s waitForReact. If
React isn't reachable, throw the typed PickerBlockingBundleError, which bypasses
both the connectToTarget retry loop and the discoverAndConnect candidate loop;
status.ts maps it to a fast failResult with code PICKER_BLOCKING and an
actionable message ("select your Metro server, then retry cdp_status").

Deliberately NOT changing the global REACT_READY_TIMEOUT_MS (shared by every
connect path) and NOT adding a pre-autoConnect target-shape heuristic (which
false-positives on healthy reloads). Hermes targets skip the probe entirely, so
legitimate slow first-builds keep the full budget; non-status connect paths are
unchanged.

New pure helpers (tested without a real WebSocket, per the repo's
formatConnectFailureMessage/stickyPlatformFilters convention):
- probeReactReachable(evaluate, budgetMs, pollMs) -> boolean (setup.ts)
- shouldRunPickerProbe(intent, target), PickerBlockingBundleError (connect.ts)

Full suite 1563 pass; tsc clean. End-to-end picker-up assertion belongs to the
deferred Dev Client harness CI (DC-Task 9 / #136).

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Lykhoyda

scripts/cdp-bridge/dist/cdp-client.js

@@ -132,11 +132,11 @@ export class CDPClient {
         }
         return ok;
     }
-    async autoConnect(portHint, filtersOrPlatform) {
+    async autoConnect(portHint, filtersOrPlatform, intent = 'default') {
         const filters = typeof filtersOrPlatform === 'string'
             ? { platform: filtersOrPlatform }
             : (filtersOrPlatform ?? {});
-        return autoConnectFn(this.buildConnectCtx(), portHint, filters);
+        return autoConnectFn(this.buildConnectCtx(), portHint, filters, intent);
     }
     async listTargets(portHint) {
         return discoverForList(this._port, portHint);

scripts/cdp-bridge/dist/cdp/connect.js

@@ -4,7 +4,41 @@ import { resolveBundleId } from '../project-config.js';
 import { discover } from './discovery.js';
 import { sleep } from './state.js';
 import { CDP_TIMEOUT_FAST } from './timeout-config.js';
-export async function autoConnect(ctx, portHint, filters) {
+import { probeReactReachable } from './setup.js';
+// Budget for the status-scoped React-reachability probe. Generous enough to
+// clear a normal Bridgeless reload (React ready in <~2s) but far below setup()'s
+// 30s waitForReact, so cdp_status fails fast instead of hanging when the Dev
+// Client picker blocks the bundle. Env-overridable for tuning/tests.
+const PICKER_PROBE_BUDGET_MS = (() => {
+    const n = parseInt(process.env.RN_PICKER_PROBE_BUDGET_MS ?? '', 10);
+    return Number.isFinite(n) && n > 0 ? n : 5000;
+})();
+/**
+ * GH #184: thrown when a status-scoped connect can't reach React within the
+ * bounded budget on a non-Hermes target — the signature of the Expo Dev Client
+ * "Development servers" picker leaving stale C++ targets advertised while the
+ * bundle never loads. status.ts maps it to a fast, actionable failResult
+ * instead of letting setup() burn the full 30s waitForReact.
+ */
+export class PickerBlockingBundleError extends Error {
+    target;
+    constructor(target) {
+        super(`Dev Client picker appears to be blocking the bundle: React was not reachable on target ` +
+            `"${target.title}" (vm=${target.vm}). If the Expo "Development servers" picker is showing on ` +
+            `the simulator, select your Metro server, then retry cdp_status. (If the bundle is still building, just retry.)`);
+        this.name = 'PickerBlockingBundleError';
+        this.target = target;
+    }
+}
+/**
+ * GH #184: run the bounded picker probe only for a status-intent connect against
+ * a non-Hermes target. Hermes targets are skipped so a genuinely slow Hermes
+ * first-build keeps the full waitForReact budget rather than being aborted.
+ */
+export function shouldRunPickerProbe(intent, target) {
+    return intent === 'status' && target.vm !== 'Hermes';
+}
+export async function autoConnect(ctx, portHint, filters, intent = 'default') {
     if (ctx.getState() === 'connecting' || ctx.isReconnecting()) {
         throw new Error('Already connecting to Metro...');
     }
@@ -25,12 +59,15 @@ export async function autoConnect(ctx, portHint, filters) {
         if (resolved)
             effective.preferredBundleId = resolved;
     }
-    return discoverAndConnect(ctx, portHint, effective);
+    return discoverAndConnect(ctx, portHint, effective, discover, intent);
 }
 export async function discoverAndConnect(ctx, portHint, filters, 
 // B111 (D643): injectable for unit tests — defaults to real discover. Production
 // call sites pass nothing, so behavior is unchanged. Tests pass a stub.
-discoverFn = discover) {
+discoverFn = discover, 
+// GH #184: connect intent threaded to connectToTarget. Kept last so existing
+// callers (and tests passing discoverFn as the 4th arg) are unaffected.
+intent = 'default') {
     if (ctx.isDisposed()) {
         throw new Error('Client is disposed. Create a new CDPClient instance.');
     }
@@ -71,7 +108,7 @@ discoverFn = discover) {
         const candidate = sorted[idx];
         const isLast = idx === sorted.length - 1;
         try {
-            await connectToTarget(ctx, candidate);
+            await connectToTarget(ctx, candidate, 5, intent);
             const devCheck = await ctx.evaluate('typeof __DEV__ !== "undefined" && __DEV__ === true');
             if (devCheck.value === true) {
                 connectedTarget = candidate;
@@ -89,6 +126,12 @@ discoverFn = discover) {
             connectedTarget = candidate;
         }
         catch (err) {
+            // GH #184: picker-blocking affects the whole bundle — every other
+            // candidate is the same stale C++ target, so don't waste a probe on each.
+            if (err instanceof PickerBlockingBundleError) {
+                ctx.setState('disconnected');
+                throw err;
+            }
             if (!isLast)
                 continue;
             throw err;
@@ -151,7 +194,7 @@ export function formatConnectFailureMessage(retries, attempts, bundleHint, lastE
         : '';
     return `Failed to connect after ${retries} attempts.${hint}`;
 }
-async function connectToTarget(ctx, target, retries = 5) {
+async function connectToTarget(ctx, target, retries = 5, intent = 'default') {
     let lastError = null;
     // GH #105 / B154: track per-attempt outcome (handshake ok vs probe timeout).
     // Fed into formatConnectFailureMessage at the end.
@@ -187,10 +230,28 @@ async function connectToTarget(ctx, target, retries = 5) {
             // M11: stamp connection time so cdp_console_log / cdp_network_log can reason
             // about "how long have we been connected with nothing happening?"
             ctx.setConnectedAt(ctx.now());
+            // GH #184: for a status-scoped connect, bounded-probe React reachability
+            // BEFORE the up-to-30s waitForReact inside setup(). A non-Hermes target
+            // that can't reach React within the budget is a stale C++ connection the
+            // Dev Client picker leaves advertised — abort fast with a typed error
+            // instead of hanging. Hermes targets are skipped (legit slow builds).
+            if (shouldRunPickerProbe(intent, target)) {
+                const reachable = await probeReactReachable((expr) => ctx.evaluate(expr), PICKER_PROBE_BUDGET_MS);
+                if (!reachable)
+                    throw new PickerBlockingBundleError(target);
+            }
             await ctx.setup();
             return;
         }
         catch (err) {
+            // GH #184: the picker-blocking abort is deterministic, not transient —
+            // don't burn the retry budget on it; clean up and surface it immediately.
+            if (err instanceof PickerBlockingBundleError) {
+                closeAndResetWs(ctx);
+                ctx.setConnectedTarget(null);
+                ctx.setState('disconnected');
+                throw err;
+            }
             lastError = err instanceof Error ? err : new Error(String(err));
             attempts.push({ handshakeOk, probeTimedOut });
             closeAndResetWs(ctx);

scripts/cdp-bridge/dist/cdp/setup.js

@@ -118,6 +118,28 @@ export async function reinjectHelpers(evaluate, waitTimeout) {
     }
     return true;
 }
+/**
+ * GH #184: bounded variant of waitForReact that RETURNS whether React became
+ * reachable within `budgetMs` (vs waitForReact which always resolves void after
+ * logging). Used by the status-scoped picker-blocking probe to decide fast,
+ * before the full REACT_READY_TIMEOUT_MS wait in setup(), whether a non-Hermes
+ * target is a stale (picker-blocked) connection.
+ */
+export async function probeReactReachable(evaluate, budgetMs, pollMs = REACT_READY_POLL_MS) {
+    const start = Date.now();
+    while (Date.now() - start < budgetMs) {
+        try {
+            const result = await evaluate(REACT_READY_PROBE_JS);
+            if (result.value === true)
+                return true;
+        }
+        catch {
+            // not ready yet
+        }
+        await sleep(pollMs);
+    }
+    return false;
+}
 export async function waitForReact(evaluate, timeout, pollInterval) {
     const effectiveTimeout = timeout ?? REACT_READY_TIMEOUT_MS;
     const effectivePoll = pollInterval ?? REACT_READY_POLL_MS;

scripts/cdp-bridge/dist/tools/status.js

@@ -1,5 +1,6 @@
 import { okResult, failResult, warnResult } from '../utils.js';
 import { handleDevClientPicker, isDevClientPickerShowing } from './dev-client-picker.js';
+import { PickerBlockingBundleError } from '../cdp/connect.js';
 import { getSessionReloadCount } from './reload.js';
 import { supportsNativeMultiDebugger } from '../cdp/multiplexer.js';
 // M10 / Phase 110: narrow `appInfo.architecture` to the StatusResult union.
@@ -111,7 +112,7 @@ export function createStatusHandler(getClient, setClient, createClient) {
                     }
                 }
                 catch { /* fall through to autoConnect */ }
-                await client.autoConnect(args.metroPort, args.platform);
+                await client.autoConnect(args.metroPort, args.platform, 'status');
             }
             else if (args.platform) {
                 // GH #21: Already connected — check if the current target matches the requested platform
@@ -123,7 +124,7 @@ export function createStatusHandler(getClient, setClient, createClient) {
                     await client.disconnect();
                     client = createClient(client.metroPort);
                     setClient(client);
-                    await client.autoConnect(args.metroPort, args.platform);
+                    await client.autoConnect(args.metroPort, args.platform, 'status');
                 }
             }
             const status = await buildStatusResult(client);
@@ -203,6 +204,12 @@ export function createStatusHandler(getClient, setClient, createClient) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
+            // GH #184: the status-scoped connect aborted fast because React was
+            // unreachable on a non-Hermes target (picker blocking the bundle, or it's
+            // still building). The message is already actionable; still attempt the
+            // best-effort auto-dismiss below (helps when a device session is open),
+            // then surface it with a typed code instead of a generic failure.
+            const pickerBlocking = err instanceof PickerBlockingBundleError;
             // If connection failed, check if the Dev Client picker is blocking
             try {
                 const pickerResult = await handleDevClientPicker();
@@ -227,7 +234,7 @@ export function createStatusHandler(getClient, setClient, createClient) {
                 }
             }
             catch { /* picker check failed, return original error */ }
-            return failResult(message);
+            return pickerBlocking ? failResult(message, 'PICKER_BLOCKING') : failResult(message);
         }
     };
 }

scripts/cdp-bridge/src/cdp-client.ts

@@ -19,7 +19,7 @@ import {
   autoConnect as autoConnectFn,
   discoverAndConnect as discoverAndConnectFn,
 } from './cdp/connect.js';
-import type { ConnectContext, ConnectFilters } from './cdp/connect.js';
+import type { ConnectContext, ConnectFilters, ConnectIntent } from './cdp/connect.js';
 import {
   handleClose as handleCloseFn,
   reconnect as reconnectFn,
@@ -167,11 +167,11 @@ export class CDPClient {
     return ok;
   }
 
-  async autoConnect(portHint?: number, filtersOrPlatform?: string | ConnectFilters): Promise<string> {
+  async autoConnect(portHint?: number, filtersOrPlatform?: string | ConnectFilters, intent: ConnectIntent = 'default'): Promise<string> {
     const filters: ConnectFilters = typeof filtersOrPlatform === 'string'
       ? { platform: filtersOrPlatform }
       : (filtersOrPlatform ?? {});
-    return autoConnectFn(this.buildConnectCtx(), portHint, filters);
+    return autoConnectFn(this.buildConnectCtx(), portHint, filters, intent);
   }
 
   async listTargets(portHint?: number): Promise<{ port: number; targets: HermesTarget[] }> {

scripts/cdp-bridge/src/cdp/connect.ts

@@ -5,8 +5,52 @@ import { discover } from './discovery.js';
 import type { SelectTargetFilters } from './discovery.js';
 import { sleep } from './state.js';
 import { CDP_TIMEOUT_FAST } from './timeout-config.js';
+import { probeReactReachable } from './setup.js';
 import type { CDPClientState, EvaluateResult, HermesTarget } from '../types.js';
 
+// GH #184: distinguishes a quick health-check connect (cdp_status) from every
+// other connect path. Only 'status' connects run the bounded picker probe; all
+// other paths keep the full waitForReact budget for legitimate slow builds.
+export type ConnectIntent = 'default' | 'status';
+
+// Budget for the status-scoped React-reachability probe. Generous enough to
+// clear a normal Bridgeless reload (React ready in <~2s) but far below setup()'s
+// 30s waitForReact, so cdp_status fails fast instead of hanging when the Dev
+// Client picker blocks the bundle. Env-overridable for tuning/tests.
+const PICKER_PROBE_BUDGET_MS = (() => {
+  const n = parseInt(process.env.RN_PICKER_PROBE_BUDGET_MS ?? '', 10);
+  return Number.isFinite(n) && n > 0 ? n : 5000;
+})();
+
+/**
+ * GH #184: thrown when a status-scoped connect can't reach React within the
+ * bounded budget on a non-Hermes target — the signature of the Expo Dev Client
+ * "Development servers" picker leaving stale C++ targets advertised while the
+ * bundle never loads. status.ts maps it to a fast, actionable failResult
+ * instead of letting setup() burn the full 30s waitForReact.
+ */
+export class PickerBlockingBundleError extends Error {
+  readonly target: HermesTarget;
+  constructor(target: HermesTarget) {
+    super(
+      `Dev Client picker appears to be blocking the bundle: React was not reachable on target ` +
+      `"${target.title}" (vm=${target.vm}). If the Expo "Development servers" picker is showing on ` +
+      `the simulator, select your Metro server, then retry cdp_status. (If the bundle is still building, just retry.)`,
+    );
+    this.name = 'PickerBlockingBundleError';
+    this.target = target;
+  }
+}
+
+/**
+ * GH #184: run the bounded picker probe only for a status-intent connect against
+ * a non-Hermes target. Hermes targets are skipped so a genuinely slow Hermes
+ * first-build keeps the full waitForReact budget rather than being aborted.
+ */
+export function shouldRunPickerProbe(intent: ConnectIntent, target: HermesTarget): boolean {
+  return intent === 'status' && target.vm !== 'Hermes';
+}
+
 export interface ConnectFilters {
   platform?: string;
   targetId?: string;
@@ -50,6 +94,7 @@ export async function autoConnect(
   ctx: ConnectContext,
   portHint?: number,
   filters?: ConnectFilters,
+  intent: ConnectIntent = 'default',
 ): Promise<string> {
   if (ctx.getState() === 'connecting' || ctx.isReconnecting()) {
     throw new Error('Already connecting to Metro...');
@@ -69,7 +114,7 @@ export async function autoConnect(
     const resolved = resolveBundleId(effective.platform ?? 'ios');
     if (resolved) effective.preferredBundleId = resolved;
   }
-  return discoverAndConnect(ctx, portHint, effective);
+  return discoverAndConnect(ctx, portHint, effective, discover, intent);
 }
 
 export async function discoverAndConnect(
@@ -79,6 +124,9 @@ export async function discoverAndConnect(
   // B111 (D643): injectable for unit tests — defaults to real discover. Production
   // call sites pass nothing, so behavior is unchanged. Tests pass a stub.
   discoverFn: typeof discover = discover,
+  // GH #184: connect intent threaded to connectToTarget. Kept last so existing
+  // callers (and tests passing discoverFn as the 4th arg) are unaffected.
+  intent: ConnectIntent = 'default',
 ): Promise<string> {
   if (ctx.isDisposed()) {
     throw new Error('Client is disposed. Create a new CDPClient instance.');
@@ -123,7 +171,7 @@ export async function discoverAndConnect(
     const candidate = sorted[idx];
     const isLast = idx === sorted.length - 1;
     try {
-      await connectToTarget(ctx, candidate);
+      await connectToTarget(ctx, candidate, 5, intent);
       const devCheck = await ctx.evaluate('typeof __DEV__ !== "undefined" && __DEV__ === true');
       if (devCheck.value === true) {
         connectedTarget = candidate;
@@ -140,6 +188,12 @@ export async function discoverAndConnect(
       console.error('CDP: no target with __DEV__=true found, using last available target');
       connectedTarget = candidate;
     } catch (err) {
+      // GH #184: picker-blocking affects the whole bundle — every other
+      // candidate is the same stale C++ target, so don't waste a probe on each.
+      if (err instanceof PickerBlockingBundleError) {
+        ctx.setState('disconnected');
+        throw err;
+      }
       if (!isLast) continue;
       throw err;
     }
@@ -218,6 +272,7 @@ async function connectToTarget(
   ctx: ConnectContext,
   target: HermesTarget,
   retries = 5,
+  intent: ConnectIntent = 'default',
 ): Promise<void> {
   let lastError: Error | null = null;
   // GH #105 / B154: track per-attempt outcome (handshake ok vs probe timeout).
@@ -253,9 +308,26 @@ async function connectToTarget(
       // M11: stamp connection time so cdp_console_log / cdp_network_log can reason
       // about "how long have we been connected with nothing happening?"
       ctx.setConnectedAt(ctx.now());
+      // GH #184: for a status-scoped connect, bounded-probe React reachability
+      // BEFORE the up-to-30s waitForReact inside setup(). A non-Hermes target
+      // that can't reach React within the budget is a stale C++ connection the
+      // Dev Client picker leaves advertised — abort fast with a typed error
+      // instead of hanging. Hermes targets are skipped (legit slow builds).
+      if (shouldRunPickerProbe(intent, target)) {
+        const reachable = await probeReactReachable((expr) => ctx.evaluate(expr), PICKER_PROBE_BUDGET_MS);
+        if (!reachable) throw new PickerBlockingBundleError(target);
+      }
       await ctx.setup();
       return;
     } catch (err) {
+      // GH #184: the picker-blocking abort is deterministic, not transient —
+      // don't burn the retry budget on it; clean up and surface it immediately.
+      if (err instanceof PickerBlockingBundleError) {
+        closeAndResetWs(ctx);
+        ctx.setConnectedTarget(null);
+        ctx.setState('disconnected');
+        throw err;
+      }
       lastError = err instanceof Error ? err : new Error(String(err));
       attempts.push({ handshakeOk, probeTimedOut });
       closeAndResetWs(ctx);