@deeeed/metamask-harness 0.17.5 → 0.19.0

package/adapters/mobile/launch-console-forwarder.cjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const args = { port: '', out: '', err: '' };
+for (let i = 2; i < process.argv.length; i += 1) {
+  const key = process.argv[i];
+  if (key === '--port') args.port = process.argv[++i] || '';
+  else if (key === '--out') args.out = process.argv[++i] || '';
+  else if (key === '--err') args.err = process.argv[++i] || '';
+  else if (key === '--help' || key === '-h') {
+    process.stdout.write('Usage: launch-console-forwarder.cjs --port <port> --out <app-log> --err <error-log>\n');
+    process.exit(0);
+  } else {
+    process.stderr.write(`launch-console-forwarder: unknown arg: ${key}\n`);
+    process.exit(2);
+  }
+}
+
+if (!args.port || !args.out || !args.err) {
+  process.stderr.write('launch-console-forwarder: --port, --out, and --err are required\n');
+  process.exit(2);
+}
+
+const forwarder = path.join(__dirname, 'bridge-runtime', 'console-forwarder.cjs');
+const errFd = fs.openSync(args.err, 'a');
+try {
+  const child = spawn(process.execPath, [forwarder, '--port', args.port, '--out', args.out], {
+    detached: true,
+    stdio: ['ignore', errFd, errFd],
+  });
+  child.unref();
+  process.stdout.write(`${child.pid}\n`);
+} finally {
+  fs.closeSync(errFd);
+}

package/adapters/mobile/open-device.sh

@@ -13,6 +13,7 @@
 #   --simulator <udid|name|"booted">    iOS simulator (default: IOS_SIMULATOR env, else "booted")
 #   --adb-serial <serial>               Android device serial (default: ADB_SERIAL env)
 #   --preflight-mode fast|auto|rebuild-native|clean  (default: fast; env MOBILE_PREFLIGHT_MODE)
+#   --ui-only                           iOS only: ensure Simulator.app is visible; do not relaunch the app
 # Outputs:
 #   Progress on stderr; exit 0 pass; 1 open failed; 2 bad args.
 #
@@ -25,6 +26,7 @@ SIMULATOR="${IOS_SIMULATOR:-${SIM_UDID:-booted}}"
 ADB_SERIAL_ARG="${ADB_SERIAL:-${ANDROID_SERIAL:-}}"
 PREFLIGHT_MODE="${MOBILE_PREFLIGHT_MODE:-fast}"
 PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
+UI_ONLY=false
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
@@ -34,10 +36,11 @@ while [ "$#" -gt 0 ]; do
     --adb-serial)     ADB_SERIAL_ARG="$2"; shift 2 ;;
     --preflight-mode) PREFLIGHT_MODE="$2"; shift 2 ;;
     --port)           PORT="$2"; shift 2 ;;
+    --ui-only)        UI_ONLY=true; shift ;;
     -h|--help)
       printf 'Usage: open-device.sh [--platform ios|android] [--target <dir>]\n'
       printf '  [--simulator <udid|name|booted>] [--adb-serial <serial>]\n'
-      printf '  [--preflight-mode fast|auto|rebuild-native|clean] [--port <n>]\n'
+      printf '  [--preflight-mode fast|auto|rebuild-native|clean] [--port <n>] [--ui-only]\n'
       exit 0
       ;;
     *) printf 'open-device: unknown arg: %s\n' "$1" >&2; exit 2 ;;
@@ -48,6 +51,10 @@ case "$PLATFORM" in
   ios|android) ;;
   *) printf 'open-device: --platform must be ios or android (got: %s)\n' "$PLATFORM" >&2; exit 2 ;;
 esac
+if $UI_ONLY && [ "$PLATFORM" != "ios" ]; then
+  printf 'open-device: --ui-only is supported only for ios.\n' >&2
+  exit 2
+fi
 
 TARGET="$(cd "$TARGET" && pwd)"
 
@@ -149,19 +156,46 @@ boot_simulator_if_needed() {
   xcrun simctl bootstatus "$udid" -b >/dev/null
 }
 
-show_simulator() {
+simulator_ui_running() {
+  pgrep -x Simulator >/dev/null 2>&1
+}
+
+open_simulator_in_background_if_needed() {
   local target="$1" udid=""
+  [ "${MM_HARNESS_SHOW_SIMULATOR:-1}" != "0" ] || return 0
+  simulator_ui_running && return 0
+  printf 'Opening Simulator UI in the background\n' >&2
   if [ "$target" = "booted" ]; then
-    printf 'Opening Simulator UI\n' >&2
-    open -a Simulator >/dev/null 2>&1 || true
+    open -g -a Simulator >/dev/null 2>&1 || {
+      printf 'open-device: failed to open Simulator UI.\n' >&2
+      return 1
+    }
   else
     udid="$(sim_udid_for_target "$target")"
     if [ -n "$udid" ]; then
-      open -a Simulator --args -CurrentDeviceUDID "$udid" >/dev/null 2>&1 || true
+      open -g -a Simulator --args -CurrentDeviceUDID "$udid" >/dev/null 2>&1 || {
+        printf 'open-device: failed to open Simulator UI for %s.\n' "$target" >&2
+        return 1
+      }
     else
-      open -a Simulator >/dev/null 2>&1 || true
+      open -g -a Simulator >/dev/null 2>&1 || {
+        printf 'open-device: failed to open Simulator UI.\n' >&2
+        return 1
+      }
     fi
   fi
+}
+
+focus_simulator() {
+  local target="$1" udid=""
+  if [ "$target" != "booted" ]; then
+    udid="$(sim_udid_for_target "$target")"
+  fi
+  if [ -n "$udid" ]; then
+    open -a Simulator --args -CurrentDeviceUDID "$udid" >/dev/null 2>&1 || true
+  else
+    open -a Simulator >/dev/null 2>&1 || true
+  fi
   osascript -e 'tell application "Simulator" to activate' >/dev/null 2>&1 || true
 }
 
@@ -220,8 +254,12 @@ if [ "$PLATFORM" = "ios" ]; then
   DEV_CLIENT_SCHEME="${IOS_DEV_CLIENT_SCHEME:-expo-metamask}"
 
   boot_simulator_if_needed "$SIM_TARGET" || exit 1
+  open_simulator_in_background_if_needed "$SIM_TARGET" || exit 1
   if [ "${MM_HARNESS_FOCUS_SIMULATOR:-0}" = "1" ]; then
-    show_simulator "$SIM_TARGET"
+    focus_simulator "$SIM_TARGET"
+  fi
+  if $UI_ONLY; then
+    exit 0
   fi
 
   LAUNCHED=false

package/adapters/mobile/start-console-forwarder.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# Ensure one runner-owned CDP console forwarder is alive for this Mobile slot.
+set -uo pipefail
+
+TARGET="$PWD"
+PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
+QUIET=false
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target) [ "$#" -ge 2 ] || { echo "Missing value for --target" >&2; exit 2; }; TARGET="$2"; shift 2 ;;
+    --port)   [ "$#" -ge 2 ] || { echo "Missing value for --port" >&2; exit 2; }; PORT="$2"; shift 2 ;;
+    --quiet)  QUIET=true; shift ;;
+    -h|--help)
+      printf 'Usage: start-console-forwarder.sh [--target <dir>] [--port <port>] [--quiet]\n'
+      exit 0
+      ;;
+    *) printf 'start-console-forwarder: unknown arg: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+[ "${METAMASK_RECIPE_CONSOLE_FORWARD:-1}" != "0" ] || exit 0
+TARGET="$(cd "$TARGET" && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/../shared/harness-path.sh"
+LOG_DIR="$TARGET/$(recipe_runtime_dir)" || exit 1
+FORWARDER="$SCRIPT_DIR/bridge-runtime/console-forwarder.cjs"
+PID_FILE="$LOG_DIR/console-forwarder.pid"
+APP_LOG_FILE="$LOG_DIR/app-console.log"
+
+{ [ -f "$FORWARDER" ] && command -v node >/dev/null 2>&1; } || exit 0
+mkdir -p "$LOG_DIR"
+
+# One debugger owns a React Native page. Reap any collector for this Metro port,
+# including one left by an older globally installed harness.
+while read -r pid cmd; do
+  case "$cmd" in
+    *console-forwarder.cjs*" --port $PORT "*|*console-forwarder.cjs*" --port=$PORT "*)
+      kill "$pid" 2>/dev/null || true
+      ;;
+  esac
+done < <(ps -axo pid=,command= 2>/dev/null || true)
+
+if [ -f "$PID_FILE" ]; then
+  old_pid="$(cat "$PID_FILE" 2>/dev/null || true)"
+  if [ -n "$old_pid" ]; then
+    case "$(ps -p "$old_pid" -o command= 2>/dev/null)" in
+      *console-forwarder.cjs*) kill "$old_pid" 2>/dev/null || true ;;
+    esac
+  fi
+  rm -f "$PID_FILE"
+fi
+
+: > "$APP_LOG_FILE"
+pid="$(node "$SCRIPT_DIR/launch-console-forwarder.cjs" \
+  --port "$PORT" \
+  --out "$APP_LOG_FILE" \
+  --err "$LOG_DIR/console-forwarder.err")" || exit 1
+printf '%s\n' "$pid" > "$PID_FILE"
+
+# A successful launch must never claim capture when the collector died at boot.
+sleep 0.1
+if ! kill -0 "$pid" 2>/dev/null; then
+  rm -f "$PID_FILE"
+  printf 'start-console-forwarder: collector exited during startup; inspect %s\n' \
+    "$LOG_DIR/console-forwarder.err" >&2
+  exit 1
+fi
+[ "$QUIET" = true ] || printf 'Device console → app-console.log (CDP forwarder pid %s)\n' "$pid" >&2

package/adapters/mobile/start-metro.sh

@@ -77,45 +77,6 @@ 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
-  # Only one debugger can own a React Native page. Reap any forwarder already
-  # attached to this Metro port, even if it was launched from another checkout or
-  # package install path and therefore does not own this runtime dir's pid file.
-  local pid cmd
-  while read -r pid cmd; do
-    case "$cmd" in
-      *console-forwarder.cjs*" --port $PORT "*|*console-forwarder.cjs*" --port=$PORT "*)
-        kill "$pid" 2>/dev/null || true
-        ;;
-    esac
-  done < <(ps -axo pid=,command= 2>/dev/null || true)
-  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=""
@@ -179,7 +140,6 @@ 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
@@ -269,7 +229,6 @@ 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/verify.sh

@@ -261,76 +261,19 @@ check_file "package.json"
 check_file "app/dev-tools/AgenticService/AgenticService.ts"
 
 if ! grep -q "AgenticService.install" "$TARGET/app/core/NavigationService/NavigationService.ts" 2>/dev/null; then
-  checks+=("{\"name\":\"NavigationService patch\",\"status\":\"fail\"}")
+  checks+=("{\"name\":\"NavigationService agentic bridge\",\"status\":\"fail\"}")
   status="fail"
 else
-  checks+=("{\"name\":\"NavigationService patch\",\"status\":\"pass\"}")
+  checks+=("{\"name\":\"NavigationService agentic bridge\",\"status\":\"pass\"}")
 fi
 
 if ! grep -q "AgentStepHud" "$TARGET/app/components/Nav/App/App.tsx" 2>/dev/null; then
-  checks+=("{\"name\":\"App AgentStepHud patch\",\"status\":\"fail\"}")
+  checks+=("{\"name\":\"App AgentStepHud\",\"status\":\"fail\"}")
   status="fail"
 else
-  checks+=("{\"name\":\"App AgentStepHud patch\",\"status\":\"pass\"}")
+  checks+=("{\"name\":\"App AgentStepHud\",\"status\":\"pass\"}")
 fi
 
-# Drift detection (read-only): compare the in-repo AgenticService/HUD against
-# the resolved runner overlay, not a runner-owned copy. The runner is the only
-# MetaMask-aware source of truth for Mobile injection.
-overlay_drift_check="$(
-  HARNESS_DIR_FOR_DRIFT="$HARNESS_DIR" TARGET_FOR_DRIFT="$TARGET" node <<'NODE'
-const fs = require('fs');
-const path = require('path');
-const name = 'agentic overlay matches runner (HUD freshness)';
-const harnessDir = process.env.HARNESS_DIR_FOR_DRIFT;
-const targetDir = path.join(process.env.TARGET_FOR_DRIFT, 'app', 'dev-tools', 'AgenticService');
-function readTrimmed(file) {
-  try { return fs.readFileSync(file, 'utf8').trim(); } catch { return ''; }
-}
-let runnerDir = readTrimmed(path.join(harnessDir, 'runner', '.runner-source'));
-if (!runnerDir) {
-  try {
-    const manifest = JSON.parse(fs.readFileSync(path.join(harnessDir, 'manifest.json'), 'utf8'));
-    runnerDir = manifest && manifest.source && manifest.source.runnerDir || '';
-  } catch {}
-}
-if (!runnerDir) {
-  process.stdout.write(JSON.stringify({ name, status: 'warn', detail: 'runner source unavailable; overlay freshness compare skipped' }));
-  process.exit(0);
-}
-const overlayDir = path.join(runnerDir, 'adapters', 'mobile', 'overlay', 'app', 'dev-tools', 'AgenticService');
-let checked = 0;
-const drifted = [];
-const missing = [];
-try {
-  for (const entry of fs.readdirSync(overlayDir)) {
-    if (!entry.endsWith('.patch')) continue;
-    if (/\.test\./u.test(entry)) continue;
-    const base = entry.slice(0, -'.patch'.length);
-    const targetFile = path.join(targetDir, base);
-    if (!fs.existsSync(targetFile)) { missing.push(base); continue; }
-    checked += 1;
-    if (fs.readFileSync(path.join(overlayDir, entry), 'utf8') !== fs.readFileSync(targetFile, 'utf8')) {
-      drifted.push(base);
-    }
-  }
-} catch (error) {
-  process.stdout.write(JSON.stringify({ name, status: 'warn', detail: 'runner overlay compare skipped: ' + String((error && error.message) || error) }));
-  process.exit(0);
-}
-if (drifted.length || missing.length) {
-  const parts = [];
-  if (drifted.length) parts.push('behind runner: ' + drifted.join(', '));
-  if (missing.length) parts.push('absent in repo: ' + missing.join(', '));
-  process.stdout.write(JSON.stringify({ name, status: 'warn', detail: parts.join('; ') + ' — rerun mm-harness install --force-overlay or mm-harness fixtures sync to refresh the in-repo HUD/AgenticService from the runner' }));
-} else if (checked === 0) {
-  process.stdout.write(JSON.stringify({ name, status: 'pass' }));
-} else {
-  process.stdout.write(JSON.stringify({ name, status: 'pass' }));
-}
-NODE
-)"
-checks+=("$overlay_drift_check")
 run_with_timeout() {
   local log_path="$1"
   local timeout_s="$2"
@@ -362,16 +305,14 @@ live_status_ok() {
   local device_target="$2"
   cat > "$ARTIFACTS/mobile-status-smoke.recipe.json" <<'JSON'
 {
-  "schema_version": 1,
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
   "title": "Mobile runner status smoke",
   "description": "Checks that the installed runner can read Mobile app status before live verification.",
-  "validate": {
-    "workflow": {
-      "entry": "status",
-      "nodes": {
-        "status": { "action": "app.status", "intent": "Read Mobile app status through the runner-owned bridge", "next": "done" },
-        "done": { "action": "end", "status": "pass" }
-      }
+  "workflow": {
+    "entry": "status",
+    "nodes": {
+      "status": { "action": "app.status", "intent": "Read Mobile app status through the runner-owned bridge", "next": "done" },
+      "done": { "action": "end", "status": "pass" }
     }
   }
 }
@@ -380,15 +321,27 @@ JSON
     cd "$TARGET"
     device_args=()
     [ -n "$device_target" ] && device_args=(--device "$device_target")
-    "$RUNNER_BIN" run "$ARTIFACTS/mobile-status-smoke.recipe.json" --adapter mobile --project-root "$TARGET" "${device_args[@]}" --artifacts-dir "$ARTIFACTS/runner-status-smoke" --json
+    "$RUNNER_BIN" run "$ARTIFACTS/mobile-status-smoke.recipe.json" --adapter mobile --target "$TARGET" "${device_args[@]}" --artifacts-dir "$ARTIFACTS/runner-status-smoke" --json
   ) > "$log_path" 2>&1
 }
 
 ensure_live_runtime() {
   local device_target="$1"
-  if live_status_ok "$ARTIFACTS/logs/app-status-precheck.log" "$device_target"; then
-    return 0
-  fi
+  local attempt
+  for attempt in 1 2 3 4 5; do
+    if live_status_ok "$ARTIFACTS/logs/app-status-precheck.log" "$device_target"; then
+      return 0
+    fi
+    # A freshly booted simulator can expose its Metro bridge just before
+    # `simctl list devices booted` publishes the device. Bound that launch→verify
+    # race instead of reporting a false DEVICE_NOT_FOUND immediately.
+    if [ "$attempt" -lt 5 ] && grep -q '"code"[[:space:]]*:[[:space:]]*"DEVICE_NOT_FOUND"' "$ARTIFACTS/logs/app-status-precheck.log"; then
+      echo "Waiting for Mobile device discovery (${attempt}/5): ${device_target:-configured target}" >&2
+      sleep 1
+      continue
+    fi
+    break
+  done
   if [ "$AUTO_START" = true ]; then
     cat >&2 <<'EOF'
 Mobile auto-start is not allowed from product-local scripts. Start or prepare the app through the runner/slot runtime, then rerun verify with --no-auto-start.
@@ -434,17 +387,15 @@ if [ "$STATIC_ONLY" = false ]; then
 
   cat > "$ARTIFACTS/mobile-v1-live-smoke.recipe.json" <<'JSON'
 {
-  "schema_version": 1,
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
   "title": "Mobile v1 runner live bridge smoke",
   "description": "Verifies the installed MetaMask runner can read the React Native debug bridge without mutating wallet state.",
-  "validate": {
-    "workflow": {
-      "entry": "status",
-      "nodes": {
-        "status": { "action": "app.status", "intent": "Read Mobile app status through the v1 runner", "next": "cdp-probe" },
-        "cdp-probe": { "action": "cdp.target", "intent": "Verify the React Native debug bridge target is reachable", "required": true, "timeout_ms": 15000, "next": "done" },
-        "done": { "action": "end", "status": "pass" }
-      }
+  "workflow": {
+    "entry": "status",
+    "nodes": {
+      "status": { "action": "app.status", "intent": "Read Mobile app status through the v1 runner", "next": "cdp-probe" },
+      "cdp-probe": { "action": "cdp.target", "intent": "Verify the React Native debug bridge target is reachable", "require_reachable": true, "timeout_ms": 15000, "next": "done" },
+      "done": { "action": "end", "status": "pass" }
     }
   }
 }
@@ -460,7 +411,7 @@ JSON
     IOS_SIMULATOR="${IOS_SIMULATOR:-$ios_simulator_resolved}" \
     ADB_SERIAL="${ADB_SERIAL:-$adb_serial_resolved}" \
     ANDROID_SERIAL="${ANDROID_SERIAL:-$adb_serial_resolved}" \
-    "$RUNNER_BIN" run "$ARTIFACTS/mobile-v1-live-smoke.recipe.json" --adapter mobile --project-root "$TARGET" "${device_args[@]}" --artifacts-dir "$ARTIFACTS/runner-live-smoke" --json
+    "$RUNNER_BIN" run "$ARTIFACTS/mobile-v1-live-smoke.recipe.json" --adapter mobile --target "$TARGET" "${device_args[@]}" --artifacts-dir "$ARTIFACTS/runner-live-smoke" --json
   ) > "$ARTIFACTS/logs/runner-live-smoke.log" 2>&1; then
     checks+=("{\"name\":\"runner v1 live bridge smoke\",\"status\":\"pass\"}")
   else

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

@@ -24,10 +24,10 @@ 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 ;;
+    --target)     [ "$#" -ge 2 ] || { echo "Missing value for --target" >&2; exit 2; }; TARGET="$2"; shift 2 ;;
+    --port)       [ "$#" -ge 2 ] || { echo "Missing value for --port" >&2; exit 2; }; PORT="$2"; shift 2 ;;
+    --max-polls)  [ "$#" -ge 2 ] || { echo "Missing value for --max-polls" >&2; exit 2; }; MAX_POLLS="$2"; shift 2 ;;
+    --platform)   [ "$#" -ge 2 ] || { echo "Missing value for --platform" >&2; exit 2; }; REQUIRE_PLATFORM="$2"; shift 2 ;;
     -h|--help)
       printf 'Usage: wait-for-bridge.sh [--target <dir>] [--port <n>] [--max-polls <n>] [--platform ios|android]\n'
       exit 0
@@ -36,7 +36,12 @@ while [ "$#" -gt 0 ]; do
   esac
 done
 
-TARGET="$(cd "$TARGET" && pwd)"
+case "$MAX_POLLS" in
+  ''|*[!0-9]*) echo "wait-for-bridge: --max-polls must be an integer of at least 2." >&2; exit 2 ;;
+esac
+[ "$MAX_POLLS" -ge 2 ] || { echo "wait-for-bridge: --max-polls must be at least 2 for stable readiness." >&2; exit 2; }
+
+TARGET="$(cd "$TARGET" && pwd -P)"
 
 # 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.
@@ -128,15 +133,24 @@ try {
 ' "$MATCH_LIB" "$STATUS_LOG" 2>/dev/null || printf 'none'
 }
 
+READY_STREAK=0
 for ATTEMPT in $(seq 1 "$MAX_POLLS"); do
   if bridge_has_route; then
-    printf 'Mobile bridge ready\n' >&2
-    exit 0
+    READY_STREAK=$((READY_STREAK + 1))
+    # The bridge can appear briefly while React Native is still completing its
+    # startup navigation/reload. Require two consecutive healthy snapshots so a
+    # following command never inherits that transient gap.
+    if [ "$READY_STREAK" -ge 2 ]; then
+      printf 'Mobile bridge ready\n' >&2
+      exit 0
+    fi
+  else
+    READY_STREAK=0
   fi
   if [ "$ATTEMPT" = "1" ] || [ $((ATTEMPT % 5)) -eq 0 ]; then
     printf 'Waiting for Mobile bridge (%s/%s): %s\n' "$ATTEMPT" "$MAX_POLLS" "$(bridge_wait_reason)" >&2
   fi
-  sleep 2
+  [ "$ATTEMPT" -ge "$MAX_POLLS" ] || sleep 2
 done
 
 cat "$STATUS_LOG" >&2 || true

package/adapters/shared/harness-source-fingerprint.mjs

@@ -12,27 +12,29 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { pathToFileURL } from 'node:url';
 
-// Trees whose contents are copied into <slot>/harness by inject.mjs. Any change
-// here means injected slots are stale.
-const SOURCE_DIRS = ['adapters/extension', 'adapters/shared', 'library'];
-
-export function harnessSourceFingerprint(runnerDir) {
+export function harnessSourceFingerprint(runnerDir, adapter = 'extension') {
+  if (adapter !== 'extension' && adapter !== 'mobile') {
+    throw new Error(`Unsupported harness fingerprint adapter: ${adapter}`);
+  }
+  const sourceDirs = [`adapters/${adapter}`, 'adapters/shared', 'library'];
   const entries = [];
-  for (const rel of SOURCE_DIRS) {
+  for (const rel of sourceDirs) {
     collect(path.join(runnerDir, rel), runnerDir, entries);
   }
   entries.sort();
   return crypto.createHash('sha256').update(entries.join('\n')).digest('hex');
 }
 
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.stdout.write(`${harnessSourceFingerprint(path.resolve(process.argv[2] ?? '.'), process.argv[3])}\n`);
+}
+
 function collect(dir, root, out) {
-  let dirents;
-  try {
-    dirents = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return; // absent tree contributes nothing
-  }
+  // These trees are required runner inputs. Fail closed instead of producing a
+  // weaker fingerprint that could make a stale injected harness appear current.
+  const dirents = fs.readdirSync(dir, { withFileTypes: true });
   for (const dirent of dirents) {
     // Skip hidden noise (.DS_Store, editor swap files) so the fingerprint tracks
     // only real source and does not thrash re-injects.

package/adapters/shared/resolve-slot-ports-core.mjs

@@ -172,10 +172,10 @@ function extensionRuntimeContextPath(repo) {
   const repoRoot = path.resolve(repo);
   const envCtx = process.env.RECIPE_RUNTIME_CONTEXT;
   if (envCtx) {
-    const resolved = path.resolve(envCtx);
-    if (resolved === repoRoot || resolved.startsWith(`${repoRoot}${path.sep}`)) {
-      return resolved;
-    }
+    // Farmslot may manage runtime context outside the checkout. Treat the
+    // explicit environment override as authoritative; containment is not a
+    // security boundary and silently dropping it selects the wrong port.
+    return path.resolve(envCtx);
   }
   return path.join(repoRoot, recipeRuntimeDir(), 'agentic-runtime.json');
 }
@@ -198,12 +198,22 @@ export function resolveExtensionRuntimeContext(repo) {
   }
 }
 
-// Checkout-scoped extension ports: runtime context (authoritative) → pool → suffix formula.
-export function formatExtensionSlotPorts(repo) {
+// Context and pool describe checkout identity and therefore replace stale
+// inherited env values. The suffix formula is only a fallback and is applied
+// separately by callers so an explicitly supplied env port can still win.
+export function formatExtensionIdentityPorts(repo) {
   const realRepo = path.resolve(repo);
   return mergeKvLayers(
     { source: resolveExtensionRuntimeContext(realRepo), overwrite: true },
     { source: resolveSlotPortsByRepo(realRepo), overwrite: false },
+  );
+}
+
+// Checkout-scoped extension ports: runtime context (authoritative) → pool → suffix formula.
+export function formatExtensionSlotPorts(repo) {
+  const realRepo = path.resolve(repo);
+  return mergeKvLayers(
+    { source: formatExtensionIdentityPorts(realRepo), overwrite: true },
     { source: resolveDefaultExtensionPorts(realRepo), overwrite: false },
   );
 }
@@ -285,6 +295,7 @@ export const cliFns = {
   // Back-compat cli key for one release.
   resolve_farmslot_ports_by_repo: resolveSlotPortsByRepo,
   resolve_default_extension_ports: resolveDefaultExtensionPorts,
+  resolve_extension_identity_ports: (repo) => formatExtensionIdentityPorts(repo) || null,
   resolve_extension_runtime_context: resolveExtensionRuntimeContext,
   resolve_extension_slot_ports: (repo) => formatExtensionSlotPorts(repo) || null,
   resolve_extension_runtime_ports: (repo) => resolveExtensionRuntimePorts(repo) || null,

package/adapters/shared/resolve-slot-ports.sh

@@ -52,12 +52,13 @@ apply_extension_slot_ports() {
   local repo="${1:-.}" line key val resolved="" ctx_file="" runtime_rel="${RECIPE_RUNTIME_DIR:-temp/recipe/runtime}"
   repo="$(cd "$repo" && pwd)"
   ctx_file="$repo/$runtime_rel/agentic-runtime.json"
-  if [ -f "$ctx_file" ]; then
+  if [ -z "${RECIPE_RUNTIME_CONTEXT:-}" ] && [ -f "$ctx_file" ]; then
     RECIPE_RUNTIME_CONTEXT="$ctx_file"
-  else
-    unset RECIPE_RUNTIME_CONTEXT
   fi
-  resolved="$(_resolve_ports_cli resolve_extension_slot_ports "$repo" 2>/dev/null)" || return 0
+  export RECIPE_RUNTIME_CONTEXT
+  # Context/pool are authoritative checkout identity. Formula ports are only
+  # fallback values and must not replace explicitly supplied env ports.
+  resolved="$(_resolve_ports_cli resolve_extension_identity_ports "$repo" 2>/dev/null)" || resolved=""
   while IFS= read -r line; do
     [ -n "$line" ] || continue
     key="${line%%=*}"
@@ -68,6 +69,17 @@ apply_extension_slot_ports() {
       SLOT_ID) RECIPE_SLOT_ID="$val" ;;
     esac
   done <<< "$resolved"
+  resolved="$(_resolve_ports_cli resolve_default_extension_ports "$repo" 2>/dev/null)" || return 0
+  while IFS= read -r line; do
+    [ -n "$line" ] || continue
+    key="${line%%=*}"
+    val="${line#*=}"
+    case "$key" in
+      CDP_PORT) [ -n "${CDP_PORT:-}" ] || CDP_PORT="$val" ;;
+      WATCHER_PORT) [ -n "${WATCHER_PORT:-}" ] || WATCHER_PORT="$val" ;;
+      SLOT_ID) [ -n "${RECIPE_SLOT_ID:-}" ] || RECIPE_SLOT_ID="$val" ;;
+    esac
+  done <<< "$resolved"
 }
 
 apply_resolved_extension_ports() {
@@ -111,4 +123,4 @@ apply_resolved_mobile_ports() {
         ;;
     esac
   done <<< "$resolved"
-}
+}