@deeeed/metamask-harness 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## Unreleased
+
+### Fixed
+- Runner construction no longer fails with `Manifest action app.lifecycle has no registered adapter` when a manifest declaring `app.lifecycle` is used with a non-mobile adapter (e.g. `call --adapter core --action-manifest library/manifests/mobile.action-manifest.json`): lifecycle adapter registration is manifest-driven instead of gated on the mobile adapter. Executing the action outside a mobile run still fails explicitly at target resolution.
+
+## 0.12.0 - 2026-07-08
+
+### Added
+- Mobile console-forwarder: restores the device console (incl. DevLogger) in `metro.log` on RN 0.79+/Bridgeless via persistent CDP streaming (`Runtime.consoleAPICalled`) — one session per device JS-runtime page (shared target-discovery ranking, never the native C++ page), buffer replay + persisted last-seen cursor (timestamp + same-stamp texts) deduping across reconnects/app reloads, auto-started by `start-metro`; opt out with `METAMASK_RECIPE_CONSOLE_FORWARD=0`. Grep `[console:` for device lines. Zero-dependency transport (built-in Node 22+ WebSocket, like the CDP bridge client). Yields to interactive React Native DevTools: a session evicted by another debugger with no bridge lock present backs off for 5 minutes instead of evicting the human every discovery tick. Idles at the slow poll cadence while Metro is down; flushes pending lines and dedupe state synchronously on SIGTERM/SIGINT.
+
+### Fixed
+- `app.hud` no longer aborts recipes on `CDP message timeout` / `WebSocket closed` during dev-client lifecycle transitions (0.11.0 regression that failed every warm-start run at `foreground-app`/`ensure-unlocked`). Skips are loud: the reason is written to stderr and recorded in the action result, so a masked real failure remains visible.
+- cdp-bridge takes a runtime lock (`cdp-bridge.lock`) so the console-forwarder yields the single debugger slot during bridge commands — prevents mutual eviction and lost `Runtime.evaluate` replies. The forwarder honors the lock while the pid inside it is alive (`kill -0`), so long commands (wallet setup runs `CDP_TIMEOUT=120000`) are never evicted mid-flight while a crashed/killed bridge releases immediately; the bridge releases on SIGTERM/SIGINT, only unlinks a lock it still owns (last-writer-wins under overlap), and takes no lock for `--help`/unknown commands.
+- `stop-metro` and mobile `cleanup` stop the console-forwarder (recorded pid + checkout-scoped sweep), so no orphan forwarder outlives Metro or fights a later one for the debugger slot.
+- `open-debug` anchors its CDP-eval fallback to the app checkout so the bridge lock lands where the forwarder watches.
+
 ## 0.11.0 - 2026-07-07
 
 ### Added

package/adapters/mobile/bridge-runtime/cdp-bridge.cjs

@@ -605,6 +605,50 @@ const COMMANDS = {
 // Main
 // ---------------------------------------------------------------------------
 
+// Bridge-priority lock: the Hermes inspector proxy reliably serves one debugger
+// slot, so the console-forwarder yields it while a bridge command runs (it
+// watches this file and backfills from the runtime's console buffer afterward).
+const BRIDGE_LOCK_FILE = path.join(
+  process.env.RECIPE_RUNTIME_DIR || path.join('temp', 'recipe', 'runtime'),
+  'cdp-bridge.lock',
+);
+
+// Ownership semantics: last writer wins. Each bridge stamps its own pid; the
+// forwarder honors the lock while the pid IN THE FILE is alive. Overlapping
+// bridge commands therefore keep the slot guarded as long as the most recent
+// writer runs, and an earlier command that outlives it may lose the slot — one
+// bridge command at a time is the supported concurrency.
+let bridgeLockHeld = false;
+
+function acquireBridgeLock() {
+  try {
+    fs.writeFileSync(BRIDGE_LOCK_FILE, String(process.pid));
+    bridgeLockHeld = true;
+  } catch {
+    // Lock is best-effort: a missing runtime dir must not break bridge commands.
+  }
+}
+
+process.on('exit', () => {
+  // Only the current owner removes the lock: a no-lock invocation (--help,
+  // unknown command) or a bridge whose lock was overwritten by a later one
+  // must not release the slot under the still-running writer.
+  if (!bridgeLockHeld) return;
+  try {
+    if (fs.readFileSync(BRIDGE_LOCK_FILE, 'utf8').trim() === String(process.pid)) {
+      fs.unlinkSync(BRIDGE_LOCK_FILE);
+    }
+  } catch {
+    // Already gone.
+  }
+});
+
+// Signal-killed bridges (status-probe kills timed-out probes SIGTERM→SIGKILL)
+// skip 'exit' unless a handler turns the signal into process.exit — without
+// this the lock strands and mutes console forwarding until staleness lapses.
+process.on('SIGTERM', () => process.exit(143));
+process.on('SIGINT', () => process.exit(130));
+
 async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
@@ -657,6 +701,9 @@ Environment:
     process.exit(1);
   }
 
+  // Only a real command takes the debugger slot; help/unknown paths above never
+  // suppress the console forwarder.
+  acquireBridgeLock();
 
   const port = loadPort();
   const timeout = Number.parseInt(process.env.CDP_TIMEOUT || '5000', 10);

package/adapters/mobile/bridge-runtime/console-forwarder.cjs

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+// console-forwarder — stream device console lines into metro.log.
+//
+// React Native (Bridgeless) gates its legacy console→Metro forwarding on
+// `console._isPolyfilled` (setUpDeveloperTools.js, T214991636); with the Hermes
+// native console that gate is false, so app logs (incl. DevLogger) never reach
+// Metro's log. The supported contract for log consumption in modern RN is CDP —
+// this process does exactly what React Native DevTools does: hold a persistent
+// debugger session per device page, enable the Runtime domain once, and stream
+// `Runtime.consoleAPICalled` events as they happen.
+//
+// Recovery: on session loss the runtime's console buffer is replayed on the
+// next Runtime.enable, and a per-device cursor (last-seen timestamp + texts at
+// that timestamp, persisted next to the log) dedupes it — lines emitted during
+// a disconnect, an app reload, or a forwarder restart are backfilled once.
+// Dedupe keys on the runtime's console timestamps (fractional-ms doubles), so
+// a device clock stepping backwards can drop lines emitted below the cursor:
+// replay is a recovery path, not a ledger. Target discovery is a cheap HTTP
+// poll against Metro only (never the app runtime): fast while a device is
+// unattached, slow when all sessions are live. Never exits on its own; idles
+// while Metro is down.
+//
+// Usage: node console-forwarder.cjs --port <metroPort> --out <logFile>
+
+'use strict';
+
+const fs = require('node:fs');
+const http = require('node:http');
+const path = require('node:path');
+const { rankRuntimeCandidates } = require('./lib/target-discovery.cjs');
+
+// Built-in WebSocket (Node 22+), same zero-dependency transport choice as
+// lib/ws-client.cjs — the published package must not depend on `ws`.
+const HANDSHAKE_TIMEOUT_MS = 3000;
+
+const DISCOVER_ACTIVE_MS = 1000; // a device is unattached — look for it quickly
+const DISCOVER_STEADY_MS = 10000; // all known targets attached — cheap liveness tick
+const FLUSH_MS = 100;
+const MAX_LINE_CHARS = 4000;
+
+function parseArgs(argv) {
+  const args = { port: process.env.WATCHER_PORT || '8081', out: null };
+  for (let i = 2; i < argv.length; i += 1) {
+    if (argv[i] === '--port') args.port = argv[++i];
+    else if (argv[i] === '--out') args.out = argv[++i];
+  }
+  if (!args.out) {
+    process.stderr.write('console-forwarder: --out <logFile> is required\n');
+    process.exit(2);
+  }
+  return args;
+}
+
+const { port, out } = parseArgs(process.argv);
+const statePath = `${out}.forwarder-state.json`;
+
+// Bridge-priority coordination: the inspector proxy reliably serves one
+// debugger slot. cdp-bridge holds this lock while a command runs; we yield the
+// slot immediately and re-attach after a settle window — the runtime's console
+// buffer replay backfills everything missed, so no lines are lost.
+const LOCK_FILE = path.join(path.dirname(out), 'cdp-bridge.lock');
+const LOCK_SETTLE_MS = 1500;
+const LOCK_STALE_MS = 30000; // unreadable lock body: crashed bridge must not block logs forever
+// dev-middleware serves one debugger slot per device; when a debugger we do not
+// coordinate with (React Native DevTools) takes it, re-attaching would evict
+// the human back and start a mutual-eviction storm. Stand down for a long
+// window instead — bridge commands still work (they carry their own lock).
+const FOREIGN_DEBUGGER_BACKOFF_MS = 5 * 60 * 1000;
+
+function bridgeLockActive() {
+  // The lock body is the bridge pid, so liveness is the real signal: a bridge
+  // command may legitimately outlive any fixed mtime window (wallet setup runs
+  // with CDP_TIMEOUT=120000). mtime staleness only guards an unreadable body.
+  let body;
+  try {
+    body = fs.readFileSync(LOCK_FILE, 'utf8');
+  } catch {
+    return false;
+  }
+  const pid = Number.parseInt(body.trim(), 10);
+  if (Number.isInteger(pid) && pid > 0) {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (error) {
+      // EPERM: the pid is alive but owned by another user — still a live bridge.
+      return error.code === 'EPERM';
+    }
+  }
+  try {
+    return Date.now() - fs.statSync(LOCK_FILE).mtimeMs < LOCK_STALE_MS;
+  } catch {
+    return false;
+  }
+}
+
+function yieldSessions() {
+  for (const ws of sessions.values()) {
+    try {
+      ws.close();
+    } catch {}
+  }
+  sessions.clear();
+}
+
+let resumeTimer = null;
+try {
+  fs.watch(path.dirname(out), (_event, filename) => {
+    if (filename !== path.basename(LOCK_FILE)) return;
+    if (bridgeLockActive()) {
+      if (resumeTimer) {
+        clearTimeout(resumeTimer);
+        resumeTimer = null;
+      }
+      yieldSessions();
+    } else if (!resumeTimer) {
+      resumeTimer = setTimeout(() => {
+        resumeTimer = null;
+        discover();
+      }, LOCK_SETTLE_MS);
+    }
+  });
+} catch {
+  // fs.watch unavailable: the stale-mtime check in discover() still guards us.
+}
+
+/**
+ * deviceId -> { ts, seen } dedupe cursor: highest consoleAPICalled timestamp
+ * already written, plus the formatted texts already written AT that timestamp.
+ * Runtime stamps are fractional-ms doubles, but two logs in one tick share a
+ * stamp — a timestamp-only cursor dropped the second on replay. A device clock
+ * stepping backwards can still drop lines (ts below the cursor): replay is a
+ * recovery path, not a ledger.
+ */
+const lastByDevice = new Map();
+try {
+  for (const [device, value] of Object.entries(JSON.parse(fs.readFileSync(statePath, 'utf8')))) {
+    // Numeric values are state written by a timestamp-only forwarder build.
+    lastByDevice.set(
+      device,
+      typeof value === 'number'
+        ? { ts: value, seen: new Set() }
+        : { ts: Number(value.ts) || 0, seen: new Set(Array.isArray(value.seen) ? value.seen : []) },
+    );
+  }
+} catch {}
+
+function serializeState() {
+  const state = {};
+  for (const [device, cursor] of lastByDevice) {
+    state[device] = { ts: cursor.ts, seen: [...cursor.seen] };
+  }
+  return JSON.stringify(state);
+}
+
+/** deviceId -> live WebSocket session. */
+const sessions = new Map();
+
+/** deviceId -> epoch ms until which a foreign debugger owns the slot. */
+const foreignDebuggerUntil = new Map();
+
+/** Buffered lines, flushed together so replay bursts are one write. */
+let pending = [];
+let flushTimer = null;
+
+function flush() {
+  flushTimer = null;
+  if (pending.length === 0) return;
+  const lines = pending.join('\n');
+  pending = [];
+  fs.appendFile(out, `${lines}\n`, () => {});
+  fs.writeFile(statePath, serializeState(), () => {});
+}
+
+// Signal-path flush: process.exit() cancels queued async I/O, so the SIGTERM/
+// SIGINT handlers must write synchronously or pending lines and the last-seen
+// state are lost on every restart (a stale state file re-duplicates replay).
+function flushSync() {
+  if (flushTimer) {
+    clearTimeout(flushTimer);
+    flushTimer = null;
+  }
+  const lines = pending.length > 0 ? `${pending.join('\n')}\n` : '';
+  pending = [];
+  try {
+    if (lines) fs.appendFileSync(out, lines);
+  } catch {}
+  try {
+    fs.writeFileSync(statePath, serializeState());
+  } catch {}
+}
+
+function queueLine(line) {
+  pending.push(line);
+  if (!flushTimer) flushTimer = setTimeout(flush, FLUSH_MS);
+}
+
+function levelLabel(type) {
+  const t = String(type || 'log').toUpperCase();
+  return t === 'WARNING' ? 'WARN' : t;
+}
+
+function formatArgs(args) {
+  const text = (args || [])
+    .map((a) => (a.value !== undefined ? String(a.value) : (a.description ?? a.type ?? '')))
+    .join(' ');
+  return text.length > MAX_LINE_CHARS ? `${text.slice(0, MAX_LINE_CHARS)}…` : text;
+}
+
+function deviceNameFromTitle(title) {
+  const m = /\(([^)]+)\)\s*$/.exec(title || '');
+  return m ? m[1] : (title || 'device');
+}
+
+function deviceIdFromUrl(wsUrl) {
+  const m = /[?&]device=([^&]+)/.exec(wsUrl || '');
+  return m ? m[1] : wsUrl;
+}
+
+function connect(target) {
+  const deviceId = deviceIdFromUrl(target.webSocketDebuggerUrl);
+  const name = deviceNameFromTitle(target.title);
+  let ws;
+  try {
+    ws = new WebSocket(target.webSocketDebuggerUrl);
+  } catch {
+    return;
+  }
+  sessions.set(deviceId, ws);
+  // The built-in WebSocket has no handshake timeout; a hung connect would hold
+  // the session slot forever and block every future re-attach for this device.
+  const handshakeTimer = setTimeout(() => {
+    try {
+      ws.close();
+    } catch {}
+  }, HANDSHAKE_TIMEOUT_MS);
+  ws.addEventListener('open', () => {
+    clearTimeout(handshakeTimer);
+    ws.send(JSON.stringify({ id: 1, method: 'Runtime.enable' }));
+    process.stderr.write(`console-forwarder: attached ${name}\n`);
+  });
+  ws.addEventListener('message', (event) => {
+    let msg;
+    try {
+      msg = JSON.parse(String(event.data));
+    } catch {
+      return;
+    }
+    if (msg.method !== 'Runtime.consoleAPICalled') return;
+    const text = formatArgs(msg.params.args);
+    // dev-middleware emits this NOTE on every debugger attach (i.e. ours). Drop it.
+    if (text.includes('unsupported debugging client')) return;
+    const ts = msg.params.timestamp || Date.now();
+    const cursor = lastByDevice.get(deviceId);
+    if (cursor && ts < cursor.ts) return;
+    if (cursor && ts === cursor.ts) {
+      if (cursor.seen.has(text)) return;
+      cursor.seen.add(text);
+    } else {
+      lastByDevice.set(deviceId, { ts, seen: new Set([text]) });
+    }
+    const time = new Date(ts).toISOString().slice(11, 23);
+    queueLine(` ${levelLabel(msg.params.type)}  ${time} [console:${name}] ${text}`);
+  });
+  const drop = () => {
+    clearTimeout(handshakeTimer);
+    if (sessions.get(deviceId) === ws) {
+      sessions.delete(deviceId);
+      process.stderr.write(`console-forwarder: detached ${name}; will re-attach\n`);
+    }
+  };
+  ws.addEventListener('close', (event) => {
+    // dev-middleware closes the previous debugger with NEW_DEBUGGER_OPENED when
+    // another one attaches. With no bridge lock present that debugger is a
+    // human's DevTools session — back off long instead of evicting them back.
+    const why = event && event.reason ? String(event.reason) : '';
+    if (why.includes('NEW_DEBUGGER_OPENED') && !bridgeLockActive()) {
+      foreignDebuggerUntil.set(deviceId, Date.now() + FOREIGN_DEBUGGER_BACKOFF_MS);
+      process.stderr.write(
+        `console-forwarder: another debugger took ${name}; standing down for ${FOREIGN_DEBUGGER_BACKOFF_MS / 60000} min\n`,
+      );
+    }
+    drop();
+  });
+  ws.addEventListener('error', drop);
+}
+
+function discover() {
+  if (bridgeLockActive()) {
+    schedule(DISCOVER_ACTIVE_MS);
+    return;
+  }
+  http
+    .get({ host: 'localhost', port, path: '/json/list', timeout: 3000 }, (res) => {
+      let body = '';
+      res.on('data', (c) => (body += c));
+      res.on('end', () => {
+        let targets;
+        try {
+          targets = JSON.parse(body);
+        } catch {
+          schedule(DISCOVER_ACTIVE_MS);
+          return;
+        }
+        // Same candidate filter + JS-runtime-first ranking the bridge uses:
+        // devices expose multiple pages (page 1 = native C++ runtime) and the
+        // first ranked page per device is its JS runtime — attaching to the
+        // native page would stream nothing and block the right one.
+        let unattached = false;
+        const picked = new Set();
+        for (const t of rankRuntimeCandidates(targets)) {
+          const deviceId = deviceIdFromUrl(t.webSocketDebuggerUrl);
+          if (picked.has(deviceId)) continue;
+          picked.add(deviceId);
+          if (sessions.has(deviceId)) continue;
+          if ((foreignDebuggerUntil.get(deviceId) || 0) > Date.now()) continue;
+          foreignDebuggerUntil.delete(deviceId);
+          unattached = true;
+          connect(t);
+        }
+        schedule(unattached ? DISCOVER_ACTIVE_MS : DISCOVER_STEADY_MS);
+      });
+    })
+    .on('error', () => schedule(DISCOVER_STEADY_MS));
+}
+
+let discoverTimer = null;
+function schedule(ms) {
+  if (discoverTimer) clearTimeout(discoverTimer);
+  discoverTimer = setTimeout(discover, ms);
+}
+
+process.on('SIGTERM', () => {
+  flushSync();
+  process.exit(0);
+});
+process.on('SIGINT', () => {
+  flushSync();
+  process.exit(0);
+});
+
+process.stderr.write(`console-forwarder: streaming Metro :${port} → ${out}\n`);
+discover();

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

@@ -78,6 +78,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.
  *
@@ -103,16 +127,7 @@ async function discoverTarget(port) {
   }
 
   // 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):
@@ -216,7 +231,10 @@ async function discoverTarget(port) {
     );
   }
 
-  // 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);
@@ -250,23 +268,7 @@ async function discoverAllTargets(port) {
     );
   }
 
-  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 +299,4 @@ async function discoverAllTargets(port) {
   return results;
 }
 
-module.exports = { discoverTarget, discoverAllTargets };
+module.exports = { discoverTarget, discoverAllTargets, rankRuntimeCandidates };

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=""
@@ -137,6 +165,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
@@ -225,6 +254,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/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.js

@@ -334,6 +334,8 @@ async function handleMobileHud(payload, context) {
 function mobileHudSkippedOrThrow(error, extra = {}) {
   const reason = traceText(error);
   if (isMobileHudLifecycleSkip(reason)) {
+    process.stderr.write(`app.hud skipped (bridge target down or transitioning): ${reason}
+`);
     return {
       hud: false,
       skipped: true,
@@ -352,7 +354,11 @@ function isMobileHudLifecycleSkip(reason) {
     "ECONNREFUSED",
     "timed out",
     "Timed out",
-    "No React Native bridge target"
+    "No React Native bridge target",
+    // Dev-client foreground/reload kills the Hermes page mid-flight: pending
+    // CDP calls surface as a message timeout or a closed socket.
+    "CDP message timeout",
+    "WebSocket closed"
   ].some((needle) => reason.includes(needle));
 }
 function animatedFlag(payload) {
@@ -504,5 +510,6 @@ function targetProbeUrl(platform, targetPort) {
 }
 export {
   createMetaMaskAdapters,
-  createMetaMaskUiTransport
+  createMetaMaskUiTransport,
+  isMobileHudLifecycleSkip
 };

package/dist/runner.js

@@ -40,10 +40,10 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     })
   });
   const existing = new Set([...core, ...ui].map((entry) => entry.action));
-  const lifecycle = adapter === "mobile" ? createAppLifecycleAdapters({
+  const lifecycle = createAppLifecycleAdapters({
     actions,
     targetProvider: { resolveTarget: resolveMetaMaskMobileLifecycleTarget }
-  }) : [];
+  });
   const custom = createMetaMaskAdapters(adapter).filter(
     (entry) => declaredActions.has(entry.action) && !existing.has(entry.action) && !lifecycle.some((lifecycleEntry) => lifecycleEntry.action === entry.action)
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -69,4 +69,4 @@
     "url": "https://github.com/MetaMask/experimental-metamask-harness/issues"
   },
   "homepage": "https://github.com/MetaMask/experimental-metamask-harness#readme"
-}
+}