@deeeed/metamask-harness 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.13.0 - 2026-07-08
+
+### Added
+- Typed cdp-bridge failure codes (`NO_TARGET`, `CDP_TIMEOUT`, `WS_CLOSED`, `METRO_UNREACHABLE`): the bridge classifies a failure at its source and reports it three ways a caller can recover — an `ERROR[<CODE>]:` stderr marker, a code-specific exit status (10–13), and a `Next:` teaching line for the caller's actual situation. `bridge.mjs` attaches the code to the error it throws, and `app.hud` lifecycle-skip classification (`isMobileHudLifecycleSkip`) branches on the code first, keeping the substring needles only as a fallback for output from a bridge that predates the codes. The needle fallback is now case-insensitive, closing a gap where target-discovery's `Pinned Android device …` (capital A) missed a lowercase needle.
+- Console-forwarder now expands object/array console arguments in `metro.log` from the Hermes-supplied inline `preview` (e.g. `{ symbol: "BTC", px: 42 }` instead of the literal `Object`), bounded one level deep and rendered synchronously so the stream never blocks; objects without a preview degrade to their description.
+- `mm-harness call <action> --help` now renders the named action's own field schema (name, type, required, description, example — from the action manifest) above the generic call flags, instead of printing only the generic call help. Fuzzy short-name resolves like `call` (an ambiguous prefix shows every match); an unresolvable name falls back to the generic help plus a pointer to `mm-harness actions`. `run <recipe> --help` is unchanged (recipe-specific help is a separate, larger surface — recipes are not in the action manifest).
+
+### 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.
+- Mobile run teardown always clears any HUD step left painted on-device, so a failed run no longer strands a FAIL banner for the next run. Best-effort and bounded: a down/transitioning bridge simply has nothing to clear and never masks the run's real outcome.
+- start-metro quick-launch now applies the dev Sentry DSN remap (`MM_SENTRY_DSN` defaults to `MM_SENTRY_DSN_DEV` when unset) at both launch paths. The quick-launch runs `expo start` directly and bypasses `scripts/build.sh`, which normally performs this remap, so without it Sentry never initialized in quick-launched dev clients.
+- `launch ios|android` no longer claims `app + bridge ready` when the app is not actually up for the requested platform. On a dual-platform slot (one iOS simulator + one Android device sharing a Metro), a "ready" verdict could be reached from a shared successful bundle plus a cached OS process, and an answering bridge target belonging to the OTHER platform satisfied the claim — so `launch android` printed ✓ while nothing ran on the Android device. The quick-relaunch path now confirms a bridge target bound to the REQUESTED platform before claiming ready: the platform is passed explicitly to `wait-for-bridge` (`--platform ios|android`), so a slot-injected `IOS_SIMULATOR`/`ADB_SERIAL` for the other platform can no longer decide the match. The boundary-safe platform/device matcher is now a single shared module (`bridge-runtime/lib/match-bridge-target.cjs`) used by both `wait-for-bridge` and the confirm. If no matched target answers it launches the app for real, and if the platform-matched target still cannot be brought up it fails loudly. `wait-for-bridge` timeouts now name what was requested vs what answered.
+
+## 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

@@ -21,6 +21,12 @@ const path = require('node:path');
 const { loadPort } = require('./lib/config.cjs');
 const { discoverTarget } = require('./lib/target-discovery.cjs');
 const { createWSClient } = require('./lib/ws-client.cjs');
+const {
+  EXIT_CODE_BY_ERROR_CODE,
+  TEACHING_BY_ERROR_CODE,
+  classifyBridgeErrorMessage,
+  formatErrorMarker,
+} = require('./lib/bridge-errors.cjs');
 const { cdpEval, cdpEvalAsync } = require('./lib/cdp-eval.cjs');
 const { buildArmSnippet, buildCollectSnippet } = require('./lib/issue-capture.cjs');
 
@@ -605,6 +611,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 +707,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);
@@ -699,6 +752,16 @@ Environment:
 }
 
 main().catch((err) => {
+  // Typed failure: a code stamped at the throw site wins; otherwise classify the
+  // message here (still at the bridge, not by a needle far away in adapters.ts).
+  // The marker + teaching go to stderr and the exit code carries the class, so a
+  // caller recovers the code from either channel.
+  const code = err && err.code ? err.code : classifyBridgeErrorMessage(err && err.message);
+  if (code) {
+    console.error(formatErrorMarker(code, err.message));
+    if (TEACHING_BY_ERROR_CODE[code]) console.error(TEACHING_BY_ERROR_CODE[code]);
+    process.exit(EXIT_CODE_BY_ERROR_CODE[code] || 1);
+  }
   console.error(`ERROR: ${err.message}`);
   process.exit(1);
 });

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

@@ -0,0 +1,341 @@
+#!/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');
+const { formatArgs: formatConsoleArgs } = require('./lib/console-format.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) {
+  return formatConsoleArgs(args, MAX_LINE_CHARS);
+}
+
+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/bridge-errors.cjs

@@ -0,0 +1,106 @@
+'use strict';
+
+// Typed bridge failure codes — the single source of truth for classifying a
+// cdp-bridge failure. Substring needles on a critical path are brittle; the
+// bridge classifies at the source and stamps a code, so callers (bridge.mjs,
+// adapters.ts) branch on the code and only fall back to needles for output
+// produced by an older bridge that predates the codes.
+//
+//   NO_TARGET          no debug target answered (app backgrounded / not attached
+//                      / a device pin matched nothing).
+//   CDP_TIMEOUT        the CDP connection or a single CDP message timed out.
+//   WS_CLOSED          the Hermes debug socket closed mid-command (app reload).
+//   METRO_UNREACHABLE  Metro's inspector HTTP endpoint could not be reached.
+const BRIDGE_ERROR_CODES = {
+  NO_TARGET: 'NO_TARGET',
+  CDP_TIMEOUT: 'CDP_TIMEOUT',
+  WS_CLOSED: 'WS_CLOSED',
+  METRO_UNREACHABLE: 'METRO_UNREACHABLE',
+};
+
+// Process exit code the bridge returns per failure code so a caller that only
+// sees the child's exit status (no stderr) can still recover the code. Kept
+// clear of exit 1 (unknown/uncoded) and 2 (usage).
+const EXIT_CODE_BY_ERROR_CODE = {
+  NO_TARGET: 10,
+  CDP_TIMEOUT: 11,
+  WS_CLOSED: 12,
+  METRO_UNREACHABLE: 13,
+};
+
+const ERROR_CODE_BY_EXIT_CODE = Object.fromEntries(
+  Object.entries(EXIT_CODE_BY_ERROR_CODE).map(([code, exit]) => [exit, code]),
+);
+
+// Every coded failure teaches the escape for the caller's ACTUAL situation — a
+// down/transitioning target is recoverable, so the Next: line names the action
+// that brings it back rather than leaving the operator to guess.
+const TEACHING_BY_ERROR_CODE = {
+  NO_TARGET:
+    'Next: bring the app to the foreground with `mm-harness launch <platform>` so a debug target is available.',
+  CDP_TIMEOUT:
+    'Next: the app is reloading or busy — retry, or `mm-harness launch <platform>` to foreground it.',
+  WS_CLOSED:
+    'Next: the Hermes debug page closed (app reload/backgrounded) — retry once the app settles.',
+  METRO_UNREACHABLE:
+    'Next: start Metro with `mm-harness start-metro` (if it is already up, check the slot WATCHER_PORT).',
+};
+
+// Needle → code fallback for uncoded output (older bridge). Case-insensitive,
+// first match wins, so order the more specific Metro/no-target needles ahead of
+// the generic 'timed out'.
+const NEEDLE_CODES = [
+  ['cannot reach metro', BRIDGE_ERROR_CODES.METRO_UNREACHABLE],
+  ['is metro running', BRIDGE_ERROR_CODES.METRO_UNREACHABLE],
+  ['timeout fetching', BRIDGE_ERROR_CODES.METRO_UNREACHABLE],
+  ['no responding bridge target', BRIDGE_ERROR_CODES.NO_TARGET],
+  ['no debug targets found', BRIDGE_ERROR_CODES.NO_TARGET],
+  ['no suitable debug target', BRIDGE_ERROR_CODES.NO_TARGET],
+  ['did not match any metro target', BRIDGE_ERROR_CODES.NO_TARGET],
+  ['pinned android device', BRIDGE_ERROR_CODES.NO_TARGET],
+  ['no react native bridge target', BRIDGE_ERROR_CODES.NO_TARGET],
+  ['websocket closed', BRIDGE_ERROR_CODES.WS_CLOSED],
+  ['websocket error', BRIDGE_ERROR_CODES.WS_CLOSED],
+  ['cdp connection timeout', BRIDGE_ERROR_CODES.CDP_TIMEOUT],
+  ['cdp message timeout', BRIDGE_ERROR_CODES.CDP_TIMEOUT],
+  ['evaluation timed out', BRIDGE_ERROR_CODES.CDP_TIMEOUT],
+  ['timed out', BRIDGE_ERROR_CODES.CDP_TIMEOUT],
+];
+
+function classifyBridgeErrorMessage(message) {
+  const text = String(message == null ? '' : message).toLowerCase();
+  for (const [needle, code] of NEEDLE_CODES) {
+    if (text.includes(needle)) return code;
+  }
+  return null;
+}
+
+// Attach a code to an error at its throw site (source classification).
+function coded(error, code) {
+  if (error && typeof error === 'object') error.code = code;
+  return error;
+}
+
+// The bridge prints this marker on stderr so a caller recovers the code without
+// relying on the exit status alone.
+const MARKER = /^ERROR\[([A-Z_]+)\]:/mu;
+
+function formatErrorMarker(code, message) {
+  return `ERROR[${code}]: ${message}`;
+}
+
+function parseErrorMarker(text) {
+  const match = MARKER.exec(String(text == null ? '' : text));
+  return match ? match[1] : null;
+}
+
+module.exports = {
+  BRIDGE_ERROR_CODES,
+  EXIT_CODE_BY_ERROR_CODE,
+  ERROR_CODE_BY_EXIT_CODE,
+  TEACHING_BY_ERROR_CODE,
+  classifyBridgeErrorMessage,
+  coded,
+  formatErrorMarker,
+  parseErrorMarker,
+};

package/adapters/mobile/bridge-runtime/lib/console-format.cjs

@@ -0,0 +1,53 @@
+'use strict';
+
+// Render CDP Runtime.consoleAPICalled args (RemoteObjects) into a log line.
+// Primitives carry `value`; objects/arrays do not — a bare console.log(obj)
+// arrived as the literal "Object". Hermes ships an inline `preview` (the same
+// one React Native DevTools renders in its console), so objects expand from it
+// synchronously — no extra CDP round-trip, so the stream never blocks. Depth is
+// bounded because previews nest one level via `valuePreview`; beyond that the
+// child preview's own description is used.
+
+const MAX_PREVIEW_DEPTH = 2;
+
+function formatPropertyValue(prop, depth) {
+  if (prop.valuePreview && depth < MAX_PREVIEW_DEPTH) {
+    return formatPreview(prop.valuePreview, depth + 1);
+  }
+  if (prop.type === 'string' && prop.value !== undefined) return JSON.stringify(prop.value);
+  if (prop.value !== undefined) return String(prop.value);
+  return prop.subtype || prop.type || '';
+}
+
+function formatPreview(preview, depth) {
+  const properties = Array.isArray(preview.properties) ? preview.properties : [];
+  const overflow = preview.overflow ? ', …' : '';
+  if (preview.subtype === 'array') {
+    return `[${properties.map((p) => formatPropertyValue(p, depth)).join(', ')}${overflow}]`;
+  }
+  const body = properties.map((p) => `${p.name}: ${formatPropertyValue(p, depth)}`).join(', ');
+  // Name a non-plain constructor (Error, Map, custom class) so the class is not lost.
+  const ctor = preview.description && preview.description !== 'Object' ? `${preview.description} ` : '';
+  return properties.length > 0 || overflow ? `${ctor}{ ${body}${overflow} }` : `${ctor}{}`;
+}
+
+function formatRemoteObject(a) {
+  if (!a || typeof a !== 'object') return String(a == null ? '' : a);
+  // Primitives (number/boolean/string) carry a directly-usable value.
+  if (a.type !== 'object' && a.type !== 'function' && a.value !== undefined) return String(a.value);
+  if (a.type === 'undefined') return 'undefined';
+  if (a.subtype === 'null') return 'null';
+  if (a.preview) return formatPreview(a.preview, 1);
+  // Functions, errors, and objects with no preview: the description is the best
+  // available text (className / Error stack / etc.); fall back to bare value/type.
+  if (a.description !== undefined) return a.description;
+  if (a.value !== undefined) return String(a.value);
+  return a.type || '';
+}
+
+function formatArgs(args, maxLineChars) {
+  const text = (args || []).map(formatRemoteObject).join(' ');
+  return maxLineChars && text.length > maxLineChars ? `${text.slice(0, maxLineChars)}…` : text;
+}
+
+module.exports = { formatArgs, formatRemoteObject, formatPreview };