@deeeed/metamask-harness 0.11.0 → 0.13.0

package/adapters/mobile/bridge-runtime/lib/match-bridge-target.cjs

@@ -0,0 +1,82 @@
+'use strict';
+
+// Boundary-safe matcher for CDP bridge targets, shared by wait-for-bridge and the
+// launch ready-path confirm. A launch (or its confirm) may only accept a target
+// belonging to the REQUESTED platform — and the requested device when one is pinned.
+//
+// The requested platform is authoritative and is passed explicitly
+// (WAIT_FOR_BRIDGE_PLATFORM), so it wins over env inference. On a dual-platform slot
+// the other platform's device identity is ambiently injected (a slot-context
+// IOS_SIMULATOR while launching android, or vice versa); without an explicit platform
+// the matcher would fall back to that ambient identity and confirm against the wrong
+// platform's target. Binding the platform up front closes that corner.
+
+function matchesBridgeTarget(target, env) {
+  const e = env || process.env;
+  if (!target || typeof target !== 'object') return false;
+
+  const requirePlatform = e.WAIT_FOR_BRIDGE_PLATFORM || '';
+  // Requested platform is authoritative: never accept the other platform's target,
+  // whatever device env is ambiently present.
+  if (requirePlatform && target.platform !== requirePlatform) return false;
+
+  const androidName = e.ANDROID_TARGET_DEVICE_NAME || e.ANDROID_DEVICE || '';
+  const adbSerial = e.ADB_SERIAL || e.ANDROID_SERIAL || '';
+  const iosSimulator = e.IOS_SIMULATOR || '';
+
+  // Android device pin applies only when android is requested (or nothing constrains
+  // the platform); it must never redirect a platform-bound iOS confirm — a slot-context
+  // ADB_SERIAL while launching iOS must not reject every iOS target. Symmetric with the
+  // iOS-simulator branch below.
+  if ((adbSerial || androidName) && (!requirePlatform || requirePlatform === 'android')) {
+    // Require android + boundary-safe device-name match.
+    if (target.platform !== 'android') return false;
+    if (!androidName) return true;
+    const deviceName = String(target.deviceName || '');
+    return deviceName === androidName || deviceName.startsWith(`${androidName} -`);
+  }
+
+  // iOS simulator pin applies only when iOS is requested (or nothing constrains the
+  // platform); it must never redirect a platform-bound android confirm.
+  if (iosSimulator && (!requirePlatform || requirePlatform === 'ios')) {
+    return target.platform !== 'android' && target.deviceName === iosSimulator;
+  }
+
+  // No device pin: the platform gate above is the only constraint.
+  return true;
+}
+
+// True when at least one answering target matches the request AND carries a route
+// (an in-app agentic bridge is live), not merely a registered debug target.
+function hasMatchingRoute(value, env) {
+  const targets = Array.isArray(value) ? value : [value];
+  return targets.some((t) => matchesBridgeTarget(t, env) && t && t.route);
+}
+
+// Human summary of the targets that answered (platform / deviceName), for teaching on
+// a timeout — e.g. an iOS target answering an android launch.
+function describeTargets(value) {
+  const targets = (Array.isArray(value) ? value : [value]).filter((t) => t && typeof t === 'object');
+  if (!targets.length) return 'none';
+  return targets
+    .map((t) => `${t.platform || '?'}${t.deviceName ? `/'${t.deviceName}'` : ''}${t.route ? '' : ' (no route)'}`)
+    .join(', ');
+}
+
+// Human summary of what the run is pinned to, for the same teaching line.
+function describeRequested(env) {
+  const e = env || process.env;
+  const platform = e.WAIT_FOR_BRIDGE_PLATFORM || '';
+  const androidName = e.ANDROID_TARGET_DEVICE_NAME || e.ANDROID_DEVICE || '';
+  const adbSerial = e.ADB_SERIAL || e.ANDROID_SERIAL || '';
+  const iosSimulator = e.IOS_SIMULATOR || '';
+  // Explicit requested platform wins over device-env inference: an iOS-bound confirm
+  // with an ambient ADB_SERIAL is still iOS.
+  if (platform === 'android') return `android${androidName ? ` / ${androidName}` : ''}`;
+  if (platform === 'ios') return `ios${iosSimulator ? ` / ${iosSimulator}` : ''}`;
+  if (adbSerial || androidName) return `android${androidName ? ` / ${androidName}` : ''}`;
+  if (iosSimulator) return `ios${iosSimulator ? ` / ${iosSimulator}` : ''}`;
+  return 'any platform';
+}
+
+module.exports = { matchesBridgeTarget, hasMatchingRoute, describeTargets, describeRequested };

package/adapters/mobile/bridge-runtime/lib/target-discovery.cjs

@@ -3,6 +3,7 @@
 const http = require('node:http');
 const { loadSimulatorName, loadAndroidDevice, loadAndroidTargetDeviceName } = require('./config.cjs');
 const { createWSClient } = require('./ws-client.cjs');
+const { BRIDGE_ERROR_CODES, coded } = require('./bridge-errors.cjs');
 
 const FETCH_TIMEOUT_MS = Number.parseInt(process.env.CDP_TIMEOUT || '30000', 10);
 const FETCH_RETRIES = Number.parseInt(process.env.CDP_DISCOVERY_RETRIES || '3', 10);
@@ -78,6 +79,30 @@ async function probeTargetDetailed(wsUrl) {
   }
 }
 
+/**
+ * Filter Metro /json/list targets to debugger-capable RN/Hermes pages and rank
+ * them JS-runtime-first. Pre-RN-0.81 titles say "React Native"/"Hermes";
+ * RN 0.81+ Bridgeless titles are bundle-id-only (e.g. "io.metamask.MetaMask
+ * (mm-5)") with the runtime kind in `description`. Each device exposes
+ * multiple pages — page 1 is the native C++ runtime; the JS runtime (console,
+ * __AGENTIC__) has a higher page number, so after the sort the first candidate
+ * per device is its JS runtime.
+ */
+function rankRuntimeCandidates(targets) {
+  const candidates = (Array.isArray(targets) ? targets : []).filter(
+    (t) =>
+      t.webSocketDebuggerUrl &&
+      ((t.title && (/react/i.test(t.title) || /hermes/i.test(t.title))) ||
+        /bridgeless|hermes/i.test(t.description || '')),
+  );
+  candidates.sort((a, b) => {
+    const aPage = Number.parseInt((a.id || '').split('-').pop() || '0', 10);
+    const bPage = Number.parseInt((b.id || '').split('-').pop() || '0', 10);
+    return bPage - aPage;
+  });
+  return candidates;
+}
+
 /**
  * Discover the Hermes CDP WebSocket URL from Metro's /json/list endpoint.
  *
@@ -93,26 +118,18 @@ async function discoverTarget(port) {
   try {
     targets = await fetchJSON(listUrl);
   } catch (e) {
-    throw new Error(
-      `Cannot reach Metro at ${listUrl}. Is Metro running?\n  ${e.message}`,
+    throw coded(
+      new Error(`Cannot reach Metro at ${listUrl}. Is Metro running?\n  ${e.message}`),
+      BRIDGE_ERROR_CODES.METRO_UNREACHABLE,
     );
   }
 
   if (!Array.isArray(targets) || targets.length === 0) {
-    throw new Error(`No debug targets found at ${listUrl}`);
+    throw coded(new Error(`No debug targets found at ${listUrl}`), BRIDGE_ERROR_CODES.NO_TARGET);
   }
 
   // Filter to React Native / Hermes targets with a WebSocket URL
-  let candidates = targets.filter(
-    (t) =>
-      t.webSocketDebuggerUrl &&
-      // Pre-RN-0.81 titles say "React Native"/"Hermes". RN 0.81+ Bridgeless
-      // titles are bundle-id-only (e.g. "io.metamask.MetaMask (mm-5)") and
-      // the runtime kind is in `description` instead.
-      ((t.title &&
-        (/react/i.test(t.title) || /hermes/i.test(t.title))) ||
-        /bridgeless|hermes/i.test(t.description || '')),
-  );
+  let candidates = rankRuntimeCandidates(targets);
 
   // Android pin identities (loaded before the simulator filter so an explicit
   // android pin can take precedence over an ambient simulator name):
@@ -166,25 +183,25 @@ async function discoverTarget(port) {
         const ambiguousList = androidFiltered
           .map((t) => `  deviceName=${JSON.stringify(t.deviceName || '')} ws=${t.webSocketDebuggerUrl || ''}`)
           .join('\n');
-        throw new Error(
+        throw coded(new Error(
           `Pinned Android device is ambiguous: model '${androidTargetName}' matches ${androidFiltered.length} Metro targets.\n` +
           `  Requested --device (ADB_SERIAL): ${adbSerial || '(not set)'}\n` +
           `  Matching Metro targets:\n${ambiguousList}\n` +
           `  Set ANDROID_DEVICE to the exact Metro deviceName to disambiguate.`,
-        );
+        ), BRIDGE_ERROR_CODES.NO_TARGET);
       }
       if (androidFiltered.length === 0) {
         // Pinned device could not be matched — never silently pick another target.
         const candidateList = targets
           .map((t) => `  deviceName=${JSON.stringify(t.deviceName || '')} ws=${t.webSocketDebuggerUrl || ''}`)
           .join('\n');
-        throw new Error(
+        throw coded(new Error(
           `Pinned Android device did not match any Metro target.\n` +
           `  Requested --device (ADB_SERIAL): ${adbSerial || '(not set)'}\n` +
           `  Resolved model (ANDROID_TARGET_DEVICE_NAME): ${androidTargetName}\n` +
           `  ANDROID_DEVICE: ${androidDevice || '(not set)'}\n` +
           `  Metro /json/list candidates:\n${candidateList}`,
-        );
+        ), BRIDGE_ERROR_CODES.NO_TARGET);
       }
       candidates = androidFiltered;
     } else if (androidDevice) {
@@ -196,11 +213,11 @@ async function discoverTarget(port) {
         const candidateList = targets
           .map((t) => `  deviceName=${JSON.stringify(t.deviceName || '')} ws=${t.webSocketDebuggerUrl || ''}`)
           .join('\n');
-        throw new Error(
+        throw coded(new Error(
           `Pinned Android device (ANDROID_DEVICE='${androidDevice}') did not match any Metro target.\n` +
           `  ADB_SERIAL: ${adbSerial || '(not set)'}\n` +
           `  Metro /json/list candidates:\n${candidateList}`,
-        );
+        ), BRIDGE_ERROR_CODES.NO_TARGET);
       }
       candidates = androidFiltered;
     }
@@ -211,12 +228,16 @@ async function discoverTarget(port) {
   }
 
   if (candidates.length === 0) {
-    throw new Error(
-      `No suitable debug target found. Targets:\n${JSON.stringify(targets, null, 2)}`,
+    throw coded(
+      new Error(`No suitable debug target found. Targets:\n${JSON.stringify(targets, null, 2)}`),
+      BRIDGE_ERROR_CODES.NO_TARGET,
     );
   }
 
-  // Sort by page number descending (JS runtime has higher page number than C++ native)
+  // Sort by page number descending (JS runtime has higher page number than C++
+  // native). rankRuntimeCandidates output arrives pre-sorted; this re-sort is
+  // load-bearing only when the raw targets.filter() fallback above repopulated
+  // the candidate list.
   candidates.sort((a, b) => {
     const aPage = Number.parseInt((a.id || '').split('-').pop() || '0', 10);
     const bPage = Number.parseInt((b.id || '').split('-').pop() || '0', 10);
@@ -245,28 +266,13 @@ async function discoverAllTargets(port) {
   try {
     targets = await fetchJSON(listUrl);
   } catch (e) {
-    throw new Error(
-      `Cannot reach Metro at ${listUrl}. Is Metro running?\n  ${e.message}`,
+    throw coded(
+      new Error(`Cannot reach Metro at ${listUrl}. Is Metro running?\n  ${e.message}`),
+      BRIDGE_ERROR_CODES.METRO_UNREACHABLE,
     );
   }
 
-  const candidates = (targets || []).filter(
-    (t) =>
-      t.webSocketDebuggerUrl &&
-      // Pre-RN-0.81 titles say "React Native"/"Hermes". RN 0.81+ Bridgeless
-      // titles are bundle-id-only (e.g. "io.metamask.MetaMask (mm-5)") and
-      // the runtime kind is in `description` instead.
-      ((t.title &&
-        (/react/i.test(t.title) || /hermes/i.test(t.title))) ||
-        /bridgeless|hermes/i.test(t.description || '')),
-  );
-
-  // Sort by page number descending (JS runtime has higher page number)
-  candidates.sort((a, b) => {
-    const aPage = Number.parseInt((a.id || '').split('-').pop() || '0', 10);
-    const bPage = Number.parseInt((b.id || '').split('-').pop() || '0', 10);
-    return bPage - aPage;
-  });
+  const candidates = rankRuntimeCandidates(targets);
 
   // Group by deviceName, probe each to find the JS runtime target. Prefer the
   // device's __AGENTIC__-bearing target; when a device has none, keep its first
@@ -297,4 +303,4 @@ async function discoverAllTargets(port) {
   return results;
 }
 
-module.exports = { discoverTarget, discoverAllTargets };
+module.exports = { discoverTarget, discoverAllTargets, rankRuntimeCandidates };

package/adapters/mobile/bridge-runtime/lib/ws-client.cjs

@@ -2,6 +2,8 @@
 
 /* global globalThis */
 
+const { BRIDGE_ERROR_CODES, coded } = require('./bridge-errors.cjs');
+
 /**
  * Minimal CDP client using the built-in ws-like interface over raw WebSocket.
  * Node 22+ has a built-in WebSocket; for older versions we use the ws package
@@ -32,7 +34,7 @@ function createWSClient(wsUrl, timeout) {
 
     const timer = setTimeout(() => {
       ws.close();
-      reject(new Error(`CDP connection timeout after ${timeout}ms`));
+      reject(coded(new Error(`CDP connection timeout after ${timeout}ms`), BRIDGE_ERROR_CODES.CDP_TIMEOUT));
     }, timeout);
 
     ws.onopen = () => {
@@ -45,8 +47,11 @@ function createWSClient(wsUrl, timeout) {
             const timer = setTimeout(() => {
               pending.delete(id);
               rej(
-                new Error(
-                  `CDP message timeout after ${msgTimeout}ms for ${method}`,
+                coded(
+                  new Error(
+                    `CDP message timeout after ${msgTimeout}ms for ${method}`,
+                  ),
+                  BRIDGE_ERROR_CODES.CDP_TIMEOUT,
                 ),
               );
             }, msgTimeout);
@@ -92,13 +97,13 @@ function createWSClient(wsUrl, timeout) {
 
     ws.onerror = (err) => {
       clearTimeout(timer);
-      reject(new Error(`WebSocket error: ${err.message || err}`));
+      reject(coded(new Error(`WebSocket error: ${err.message || err}`), BRIDGE_ERROR_CODES.WS_CLOSED));
     };
 
     ws.onclose = () => {
       clearTimeout(timer);
       for (const [, { reject: rej }] of pending) {
-        rej(new Error('WebSocket closed'));
+        rej(coded(new Error('WebSocket closed'), BRIDGE_ERROR_CODES.WS_CLOSED));
       }
       pending.clear();
     };

package/adapters/mobile/cleanup.sh

@@ -45,6 +45,10 @@ if ! command -v harness_root >/dev/null 2>&1; then
   exit 1
 fi
 HARNESS_DIR="$(harness_dir "$TARGET" mobile)"
+
+# A console-forwarder left running would keep polling for this checkout's Metro
+# after cleanup orphans it; stop any forwarder scoped to this checkout first.
+pkill -f "console-forwarder.cjs --port .* --out $TARGET/" 2>/dev/null || true
 if GIT_BACKUP_PATH="$(git -C "$TARGET" rev-parse --git-path recipe-harness/mobile/backup 2>/dev/null)"; then
   case "$GIT_BACKUP_PATH" in
     /*) BACKUP_DIR="$GIT_BACKUP_PATH" ;;

package/adapters/mobile/start-metro.sh

@@ -77,6 +77,34 @@ default_metro_workers() {
 # shellcheck disable=SC1091
 . "$SCRIPT_DIR/lib/tmux-viewer.sh"
 
+# Bridgeless RN gates console→Metro forwarding on console._isPolyfilled, which is
+# false with the Hermes native console — device logs (incl. DevLogger) never reach
+# metro.log. The forwarder attaches over CDP and appends them back. Kill switch:
+# METAMASK_RECIPE_CONSOLE_FORWARD=0.
+start_console_forwarder() {
+  local forwarder="$SCRIPT_DIR/bridge-runtime/console-forwarder.cjs"
+  local fwd_pid_file="$LOG_DIR/console-forwarder.pid"
+  [ "${METAMASK_RECIPE_CONSOLE_FORWARD:-1}" != "0" ] || return 0
+  { [ -f "$forwarder" ] && command -v node >/dev/null 2>&1; } || return 0
+  if [ -f "$fwd_pid_file" ]; then
+    local old_fwd
+    old_fwd="$(cat "$fwd_pid_file" 2>/dev/null || true)"
+    # A crash can leave a stale pid file and the OS can recycle the pid for an
+    # unrelated process — only kill when the command line is really ours.
+    if [ -n "$old_fwd" ]; then
+      case "$(ps -p "$old_fwd" -o command= 2>/dev/null)" in
+        *console-forwarder.cjs*) kill "$old_fwd" 2>/dev/null ;;
+      esac
+    fi
+    rm -f "$fwd_pid_file"
+  fi
+  nohup node "$forwarder" --port "$PORT" --out "$LOG_FILE" \
+    </dev/null >> "$LOG_DIR/console-forwarder.err" 2>&1 &
+  echo "$!" > "$fwd_pid_file"
+  disown 2>/dev/null || true
+  printf 'Device console → metro.log (CDP forwarder pid %s)\n' "$(cat "$fwd_pid_file")" >&2
+}
+
 write_metro_runner() {
   local runner="$1"
   local clear_flag=""
@@ -92,6 +120,9 @@ set -a
 [ ! -f .env.local ] || . ./.env.local
 set +a
 [ -n "\${METAMASK_BUILD_TYPE:-}" ] || export METAMASK_BUILD_TYPE=main
+# build.sh remaps MM_SENTRY_DSN from MM_SENTRY_DSN_DEV for dev builds; quick-launch
+# bypasses it, so without this Sentry never initializes in the dev client.
+[ -n "\${MM_SENTRY_DSN:-}" ] || export MM_SENTRY_DSN="\${MM_SENTRY_DSN_DEV:-}"
 export EXPO_NO_TYPESCRIPT_SETUP=1
 export WATCHER_PORT="$(printf '%q' "$PORT")" METRO_PORT="$(printf '%q' "$PORT")"
 export METRO_MAX_WORKERS="$(printf '%q' "$METRO_WORKERS")"
@@ -137,6 +168,7 @@ if metro_ready; then
     rm -f "$PID_FILE"
   elif metro_listener_valid; then
     printf 'Metro already running and valid on port %s\n' "$PORT" >&2
+    start_console_forwarder
     exit 0
   else
     stop_metro_listener || exit 1
@@ -174,6 +206,10 @@ if ! start_metro_tmux; then
     # rejects. Default to the main dev client (what runway installs / launch targets)
     # so already-installed slots work without re-syncing fixtures.
     [ -n "${METAMASK_BUILD_TYPE:-}" ] || export METAMASK_BUILD_TYPE=main
+    # build.sh remaps MM_SENTRY_DSN from MM_SENTRY_DSN_DEV for dev builds (start:ios
+    # = build.sh ios main dev); quick-launch bypasses build.sh, so without this the
+    # dev client's MM_SENTRY_DSN stays empty and Sentry never initializes.
+    [ -n "${MM_SENTRY_DSN:-}" ] || export MM_SENTRY_DSN="${MM_SENTRY_DSN_DEV:-}"
     export EXPO_NO_TYPESCRIPT_SETUP=1
     export WATCHER_PORT="${PORT}" METRO_PORT="${PORT}"
     export METRO_MAX_WORKERS="${METRO_WORKERS}"
@@ -225,6 +261,7 @@ if [ "$READY" = true ]; then
   first_ready_pid="${ready_pids%% *}"
   [ -z "$first_ready_pid" ] || printf '%s\n' "$first_ready_pid" > "$PID_FILE"
   printf 'Metro ready on port %s\n' "$PORT" >&2
+  start_console_forwarder
   printf '  Next: mm-harness logs  (tail Metro)\n' >&2
   exit 0
 fi

package/adapters/mobile/stop-metro.sh

@@ -62,6 +62,27 @@ fi
 set +e
 rm -f "$PID_FILE"
 
+# start-metro runs a per-checkout console-forwarder holding the device debugger
+# slot; Metro going down must take it too, or the orphan keeps polling and later
+# fights a fresh forwarder over the slot. Kill the pid this LOG_DIR recorded,
+# then sweep forwarders started under a different RECIPE_RUNTIME_DIR of this
+# same checkout (their pid files live elsewhere; match on the --out path).
+FWD_PID_FILE="$LOG_DIR/console-forwarder.pid"
+fwd_pid="$(cat "$FWD_PID_FILE" 2>/dev/null || true)"
+# A crash can leave a stale pid file and the OS can recycle the pid for an
+# unrelated process — only kill when the command line is really ours.
+if [ -n "$fwd_pid" ]; then
+  case "$(ps -p "$fwd_pid" -o command= 2>/dev/null)" in
+    *console-forwarder.cjs*)
+      if kill "$fwd_pid" 2>/dev/null; then
+        printf 'Stopped console forwarder (pid %s)\n' "$fwd_pid" >&2
+      fi
+      ;;
+  esac
+fi
+rm -f "$FWD_PID_FILE"
+pkill -f "console-forwarder.cjs --port .* --out $TARGET/" 2>/dev/null
+
 # Port-scoped stop above misses bundlers a prior launch left on a DIFFERENT port
 # (port drift / missing pid file). Sweep every Metro bound to this checkout so
 # stop fully cleans up — the leak that stacked bundlers across relaunches.

package/adapters/mobile/wait-for-bridge.sh

@@ -9,6 +9,8 @@
 #   --target <metamask-mobile dir>  (default $PWD)
 #   --port <number>                 (default WATCHER_PORT env, else METRO_PORT, else 8081)
 #   --max-polls <n>                 (default MOBILE_BRIDGE_READY_POLLS env, else 90; 2s each = 180s)
+#   --platform ios|android          bind the required platform: the answering target
+#                                   must belong to it, regardless of ambient device env
 # Outputs:
 #   Progress on stderr; exit 0 bridge ready; 1 timeout.
 #
@@ -18,14 +20,16 @@ set -uo pipefail
 TARGET="$PWD"
 PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
 MAX_POLLS="${MOBILE_BRIDGE_READY_POLLS:-90}"
+REQUIRE_PLATFORM=""
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --target)     TARGET="$2"; shift 2 ;;
     --port)       PORT="$2"; shift 2 ;;
     --max-polls)  MAX_POLLS="$2"; shift 2 ;;
+    --platform)   REQUIRE_PLATFORM="$2"; shift 2 ;;
     -h|--help)
-      printf 'Usage: wait-for-bridge.sh [--target <dir>] [--port <n>] [--max-polls <n>]\n'
+      printf 'Usage: wait-for-bridge.sh [--target <dir>] [--port <n>] [--max-polls <n>] [--platform ios|android]\n'
       exit 0
       ;;
     *) printf 'wait-for-bridge: unknown arg: %s\n' "$1" >&2; exit 2 ;;
@@ -34,6 +38,10 @@ done
 
 TARGET="$(cd "$TARGET" && pwd)"
 
+# The matcher reads the required platform from the environment so the value survives
+# into the node subprocess that runs the shared matcher against the status output.
+export WAIT_FOR_BRIDGE_PLATFORM="$REQUIRE_PLATFORM"
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
 . "$SCRIPT_DIR/../shared/harness-path.sh"
@@ -45,6 +53,7 @@ LOG_DIR="$TARGET/$(recipe_runtime_dir)" || exit 1
 mkdir -p "$LOG_DIR"
 
 BRIDGE_CJS="$(dirname "$0")/bridge-runtime/cdp-bridge.cjs"
+MATCH_LIB="$(dirname "$0")/bridge-runtime/lib/match-bridge-target.cjs"
 STATUS_LOG="$LOG_DIR/bridge-status.log"
 METRO_LOG="$LOG_DIR/metro.log"
 
@@ -86,30 +95,37 @@ bridge_wait_reason() {
   bundle_progress "$METRO_LOG"
 }
 
+# Matcher is the shared boundary-safe module (match-bridge-target.cjs), so the
+# launch ready-path confirm and this poll enforce identical platform/device rules.
 bridge_has_route() {
   (cd "$TARGET" && APP_ROOT="$TARGET" node "$BRIDGE_CJS" status > "$STATUS_LOG" 2>&1) \
-  && node - "$STATUS_LOG" <<'NODE'
-const fs = require('fs');
+  && node -e '
+const { hasMatchingRoute } = require(process.argv[1]);
+const fs = require("fs");
 try {
-  const value = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
-  const targets = Array.isArray(value) ? value : [value];
-  const androidName = process.env.ANDROID_TARGET_DEVICE_NAME || process.env.ANDROID_DEVICE || '';
-  const adbSerial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || '';
-  const iosSimulator = process.env.IOS_SIMULATOR || '';
-  const matchesTarget = (target) => {
-    if (!target || typeof target !== 'object') return false;
-    if (adbSerial || androidName) {
-      if (target.platform !== 'android') return false;
-      if (!androidName) return true;
-      const deviceName = String(target.deviceName || '');
-      return deviceName === androidName || deviceName.startsWith(`${androidName} -`);
-    }
-    if (iosSimulator) return target.deviceName === iosSimulator;
-    return true;
-  };
-  if (!targets.some((t) => matchesTarget(t) && t.route)) process.exit(1);
+  const value = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+  process.exit(hasMatchingRoute(value) ? 0 : 1);
 } catch { process.exit(1); }
-NODE
+' "$MATCH_LIB" "$STATUS_LOG"
+}
+
+# The device/platform this run is pinned to — the bridge target must belong to it.
+requested_target() {
+  node -e 'process.stdout.write(require(process.argv[1]).describeRequested())' "$MATCH_LIB" 2>/dev/null \
+    || printf 'any platform'
+}
+
+# Summarise the targets that DID answer (platform / deviceName), so a timeout teaches
+# what responded vs what was requested — e.g. an iOS target answering an android launch.
+answered_targets() {
+  [ -s "$STATUS_LOG" ] || { printf 'none'; return; }
+  node -e '
+const { describeTargets } = require(process.argv[1]);
+const fs = require("fs");
+try {
+  process.stdout.write(describeTargets(JSON.parse(fs.readFileSync(process.argv[2], "utf8"))));
+} catch { process.stdout.write("none"); }
+' "$MATCH_LIB" "$STATUS_LOG" 2>/dev/null || printf 'none'
 }
 
 for ATTEMPT in $(seq 1 "$MAX_POLLS"); do
@@ -124,7 +140,9 @@ for ATTEMPT in $(seq 1 "$MAX_POLLS"); do
 done
 
 cat "$STATUS_LOG" >&2 || true
-printf 'wait-for-bridge: bridge did not become ready on port %s (%s polls × 2s = %ss)\n' \
-  "$PORT" "$MAX_POLLS" "$((MAX_POLLS * 2))" >&2
+printf 'wait-for-bridge: no bridge target matched the requested %s on port %s (%s polls × 2s = %ss)\n' \
+  "$(requested_target)" "$PORT" "$MAX_POLLS" "$((MAX_POLLS * 2))" >&2
+printf '  requested: %s\n' "$(requested_target)" >&2
+printf '  answered:  %s\n' "$(answered_targets)" >&2
 printf '  Next: check %s — or run mm-harness app-status\n' "$STATUS_LOG" >&2
 exit 1

package/adapters/shared/open-debug.mjs

@@ -126,6 +126,11 @@ async function tryDevSettingsCdpFallback(numericPort, normalizedAction) {
       : 'NativeModules.DevSettings.openDebugger()';
   const result = spawnSync(process.execPath, [bridgePath, 'eval', expression], {
     encoding: 'utf8',
+    // cdp-bridge resolves its debugger-slot lock (RECIPE_RUNTIME_DIR) against
+    // cwd; anchor it to the app checkout so the console forwarder sees the
+    // yield — APP_ROOT when a caller exports it, else the cwd mm-harness debug
+    // already set to the target.
+    cwd: process.env.APP_ROOT || process.cwd(),
     env: { ...process.env, WATCHER_PORT: String(numericPort) },
     timeout: 15000,
   });

package/dist/adapters/mobile/prepare.js

@@ -3,8 +3,10 @@ import { recordDepsBaseline } from "@farmslot/recipe-harness/runtime/deps-readin
 import { EXIT, spawnScriptStreaming } from "../../commands/shared.js";
 import { runnerDir } from "../../paths.js";
 import {
-  decideMobileReadiness
+  decideMobileReadiness,
+  launchActions
 } from "./runtime-decision.js";
+const READY_BRIDGE_CONFIRM_POLLS = 3;
 const POD_PROBE_ENV = {
   FORCE_COLOR: "0",
   NO_COLOR: "1",
@@ -42,6 +44,24 @@ async function prepareMobile(target, opts = {}) {
     return { status: EXIT.runtime, output: msg };
   }
   if (report.decision === "ready") {
+    const confirm = await dispatchAction(
+      { id: "wait-for-bridge", cwd: target, argv: ["--max-polls", String(READY_BRIDGE_CONFIRM_POLLS)] },
+      target,
+      platform,
+      json,
+      preflightMode
+    );
+    if (confirm.status === 0) return { status: 0, output: "" };
+    if (!json) {
+      process.stderr.write(
+        `launch: runtime looked ready but no ${platform} bridge target answered; launching the app.
+`
+      );
+    }
+    for (const action of launchActions(path.resolve(target))) {
+      const result = await dispatchAction(action, target, platform, json, preflightMode);
+      if (result.status !== 0) return result;
+    }
     return { status: 0, output: "" };
   }
   if (report.decision === "unknown") {
@@ -115,7 +135,8 @@ async function dispatchAction(action, target, platform, json, preflightMode = "f
     }
     case "wait-for-bridge": {
       const leaf = path.join(runnerDir, "adapters/mobile/wait-for-bridge.sh");
-      return spawnScriptStreaming(leaf, ["--target", cwd], target);
+      const extra = action.argv ?? [];
+      return spawnScriptStreaming(leaf, ["--target", cwd, "--platform", platform, ...extra], target);
     }
     case "clear-metro-cache": {
       const leaf = path.join(runnerDir, "adapters/mobile/start-metro.sh");

package/dist/adapters/mobile/runtime-decision.js

@@ -313,5 +313,6 @@ async function computeMobileReadiness(resolved, options, fast) {
   };
 }
 export {
-  decideMobileReadiness
+  decideMobileReadiness,
+  launchActions
 };