@deeeed/metamask-harness 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,9 +1,17 @@
 # Changelog
 
-## Unreleased
+## 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
 

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');
 
@@ -746,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

@@ -28,6 +28,7 @@ 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`.
@@ -201,10 +202,7 @@ function levelLabel(type) {
 }
 
 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;
+  return formatConsoleArgs(args, MAX_LINE_CHARS);
 }
 
 function deviceNameFromTitle(title) {

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 };

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);
@@ -117,13 +118,14 @@ 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
@@ -181,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) {
@@ -211,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;
     }
@@ -226,8 +228,9 @@ 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,
     );
   }
 
@@ -263,8 +266,9 @@ 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,
     );
   }
 

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/start-metro.sh

@@ -120,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")"
@@ -203,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}"

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/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
 };

package/dist/adapters.js

@@ -2,7 +2,7 @@ import http from "node:http";
 import { compatibilityMode, fixtureSummary, repoShape } from "./doctor.js";
 import { runLiveAdapterScript } from "./live-adapter-contract.js";
 import { withExtensionPage } from "../library/actions/extension/platform/cdp.mjs";
-import { bridgeCommand, evalSync, selectBridgeStatusEntry, simulatorScreenshot } from "../library/actions/mobile/platform/bridge.mjs";
+import { bridgeCommand, evalSync, MOBILE_BRIDGE_ERROR_CODES, selectBridgeStatusEntry, simulatorScreenshot } from "../library/actions/mobile/platform/bridge.mjs";
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -331,9 +331,21 @@ async function handleMobileHud(payload, context) {
     return mobileHudSkippedOrThrow(error, { nodeId: hud.nodeId, status: hud.status });
   }
 }
+async function hideMobileHudOnTeardown(projectRoot, env = {}) {
+  if (process.env.METAMASK_RECIPE_AUTO_HUD === "0" || process.env.METAMASK_RECIPE_AUTO_HUD === "false") return;
+  const input = {
+    node: { bridge_timeout_ms: 8e3, cdp_timeout_ms: 5e3 },
+    context: { nodeId: "teardown", projectRoot, artifactsDir: projectRoot, env }
+  };
+  try {
+    await bridgeCommand(input, ["hide-step"]);
+  } catch {
+  }
+}
 function mobileHudSkippedOrThrow(error, extra = {}) {
   const reason = traceText(error);
-  if (isMobileHudLifecycleSkip(reason)) {
+  const code = isRecord(error) && typeof error.code === "string" ? error.code : void 0;
+  if (isMobileHudLifecycleSkip(reason, code)) {
     process.stderr.write(`app.hud skipped (bridge target down or transitioning): ${reason}
 `);
     return {
@@ -346,20 +358,30 @@ function mobileHudSkippedOrThrow(error, extra = {}) {
   }
   throw new Error(`app.hud bridge command failed outside a lifecycle/no-target transition: ${reason}`);
 }
-function isMobileHudLifecycleSkip(reason) {
+const HUD_LIFECYCLE_SKIP_CODES = /* @__PURE__ */ new Set([
+  MOBILE_BRIDGE_ERROR_CODES.NO_TARGET,
+  MOBILE_BRIDGE_ERROR_CODES.CDP_TIMEOUT,
+  MOBILE_BRIDGE_ERROR_CODES.WS_CLOSED,
+  MOBILE_BRIDGE_ERROR_CODES.METRO_UNREACHABLE
+]);
+function isMobileHudLifecycleSkip(reason, code) {
+  if (code && HUD_LIFECYCLE_SKIP_CODES.has(code)) return true;
+  const haystack = reason.toLowerCase();
   return [
     "no responding bridge target",
-    "Pinned android device",
+    "pinned android device",
     "bridge probe failed",
-    "ECONNREFUSED",
+    "econnrefused",
     "timed out",
-    "Timed out",
-    "No React Native bridge target",
+    "no react native bridge target",
+    // Metro down mid-run: HUD cannot paint, so skip rather than abort (the real
+    // action fails on its own). Matches the METRO_UNREACHABLE code branch above.
+    "cannot reach metro",
     // 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));
+    "cdp message timeout",
+    "websocket closed"
+  ].some((needle) => haystack.includes(needle));
 }
 function animatedFlag(payload) {
   return payload.animated === true ? "--animated" : "--no-animated";
@@ -511,5 +533,6 @@ function targetProbeUrl(platform, targetPort) {
 export {
   createMetaMaskAdapters,
   createMetaMaskUiTransport,
+  hideMobileHudOnTeardown,
   isMobileHudLifecycleSkip
 };

package/dist/commands/call.js

@@ -6,8 +6,10 @@ import { loadActionManifest } from "../manifest.js";
 import { importRecipeProtocol } from "../paths.js";
 import { recipeRunning } from "../heal-bounds.js";
 import { EXIT } from "./shared.js";
+import { describeManifestActions, fuzzyResolveActions } from "./manifest.js";
 import {
   parseArgs,
+  isRecord,
   optionFlag,
   optionString,
   resolveAdapter,
@@ -153,6 +155,82 @@ Artifacts: ${result.artifactManifestPath}`);
   }
   return result.status === "pass" ? EXIT.ok : EXIT.runtime;
 }
+async function handleCallHelp(argv, genericHelp) {
+  const { action: shortName, rest } = parseCallArgs(argv.filter((arg) => arg !== "--help" && arg !== "-h"));
+  const { options } = parseArgs(rest, "call");
+  let adapter;
+  let manifest;
+  try {
+    ({ adapter } = resolveAdapter(options));
+    manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
+  } catch {
+    process.stdout.write(`${genericHelp}
+`);
+    return EXIT.ok;
+  }
+  const matches = shortName ? fuzzyResolveActions(describeManifestActions(manifest), shortName) : [];
+  if (matches.length === 0) {
+    process.stdout.write(`${genericHelp}
+`);
+    if (shortName) {
+      process.stdout.write(
+        `
+No action matches "${shortName}" for the ${adapter} adapter.
+  Next: mm-harness actions --adapter ${adapter}   # list the action vocabulary
+`
+      );
+    }
+    return EXIT.ok;
+  }
+  for (const entry of matches) process.stdout.write(renderCallActionHelp(entry));
+  process.stdout.write(`${genericHelp}
+`);
+  return EXIT.ok;
+}
+function renderCallActionHelp(entry) {
+  const short = entry.name.split(".").pop() ?? entry.name;
+  const schema = isRecord(entry.schema) ? entry.schema : {};
+  const properties = isRecord(schema.properties) ? schema.properties : {};
+  const required = new Set(
+    Array.isArray(schema.required) ? schema.required.filter((r) => typeof r === "string") : []
+  );
+  const lines = [`mm-harness call ${entry.name} [--arg k=v ...] [flags]`, ""];
+  if (entry.description) lines.push(`  ${entry.description}`, "");
+  const names = Object.keys(properties).sort();
+  if (names.length === 0) {
+    lines.push("  Fields: (none)");
+  } else {
+    lines.push("  Fields (pass with --arg <name>=<value>):");
+    const width = Math.max(...names.map((name) => name.length));
+    for (const name of names) {
+      const prop = isRecord(properties[name]) ? properties[name] : {};
+      const type = typeof prop.type === "string" ? prop.type : "any";
+      const req = required.has(name) ? " (required)" : "";
+      const desc = typeof prop.description === "string" ? ` \u2014 ${prop.description}` : "";
+      const enumVals = Array.isArray(prop.enum) ? ` [one of: ${prop.enum.join(", ")}]` : "";
+      lines.push(`    ${name.padEnd(width)}  ${type}${req}${desc}${enumVals}`);
+    }
+  }
+  const examples = renderCallExamples(short, entry.examples);
+  if (examples.length > 0) {
+    lines.push("", "  Examples:");
+    for (const example of examples) lines.push(`    ${example}`);
+  }
+  return `${lines.join("\n")}
+
+`;
+}
+function renderCallExamples(short, examples) {
+  if (!Array.isArray(examples)) return [];
+  const out = [];
+  for (const example of examples.slice(0, 2)) {
+    const node = isRecord(example) && isRecord(example.node) ? example.node : void 0;
+    if (!node) continue;
+    const tokens = Object.entries(node).filter(([key]) => key !== "action" && key !== "intent").map(([key, value]) => `--arg ${key}=${typeof value === "string" ? value : JSON.stringify(value)}`);
+    out.push(`mm-harness call ${short} ${tokens.join(" ")}`.trim());
+  }
+  return out;
+}
 function parseCallArgs(argv) {
   const args = {};
   const rest = [];
@@ -191,5 +269,6 @@ function pickCallExampleAction(names) {
   return names[0] ?? "command";
 }
 export {
-  handleCall
+  handleCall,
+  handleCallHelp
 };

package/dist/commands/manifest.js

@@ -87,6 +87,8 @@ function describeManifestAction(name, kind, metadata) {
   };
 }
 export {
+  describeManifestActions,
+  fuzzyResolveActions,
   handleActions,
   handleManifest
 };

package/dist/commands/run-engine.js

@@ -68,7 +68,15 @@ async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManif
         recordVideo: useFramedExtensionRecording ? false : recordVideo,
         ...runtimeOptions.librarySources ? { librarySources: runtimeOptions.librarySources } : {}
       };
-      const result = await runner.run(runRequest);
+      let result;
+      try {
+        result = await runner.run(runRequest);
+      } finally {
+        if (adapter === "mobile") {
+          const { hideMobileHudOnTeardown } = await import("../adapters.js");
+          await hideMobileHudOnTeardown(projectRoot, recipeRunEnv(adapter, runtimeOptions));
+        }
+      }
       await stopRecipeRecording(recording, result);
       return result;
     } finally {

package/dist/mm-harness-cli.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { color } from "./cli-color.js";
 import { handleUpdate, maybeNudge } from "./commands/update.js";
+import { handleCallHelp } from "./commands/call.js";
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 globalThis.__MM_HARNESS_WRAPPER__ = true;
 const { main: recipeMain } = await import("./cli.js");
@@ -614,6 +615,13 @@ function hasPassthroughHelp(argv) {
   if (divider === -1) return false;
   return argv.slice(divider + 1).some((arg) => arg === "-h" || arg === "--help");
 }
+function isCallActionHelp(argv) {
+  if (argv[0] !== "call") return false;
+  if (!argv[1] || argv[1].startsWith("-")) return false;
+  const divider = argv.indexOf("--");
+  const scope = divider === -1 ? argv : argv.slice(0, divider);
+  return scope.includes("--help") || scope.includes("-h");
+}
 if (rawArgv.length === 0) {
   process.stdout.write(groupedHelp());
   process.exit(0);
@@ -621,4 +629,8 @@ if (rawArgv.length === 0) {
 if (hasPassthroughHelp(rawArgv)) {
   process.exit(await delegate(rawArgv));
 }
+if (isCallActionHelp(rawArgv)) {
+  const callHelp = REAL.find((command) => command.name === "call")?.helpText ?? "";
+  process.exit(await handleCallHelp(rawArgv.slice(1), callHelp));
+}
 await program.parseAsync(process.argv);

package/library/actions/mobile/platform/bridge.mjs

@@ -3,9 +3,35 @@ import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import bridgeErrors from '../../../../adapters/mobile/bridge-runtime/lib/bridge-errors.cjs';
+
+const {
+  BRIDGE_ERROR_CODES,
+  ERROR_CODE_BY_EXIT_CODE,
+  classifyBridgeErrorMessage,
+  coded,
+  parseErrorMarker,
+} = bridgeErrors;
+
+// Re-exported so the TS adapter classifies on the same code constants without a
+// second import path into the cjs bridge-runtime.
+export const MOBILE_BRIDGE_ERROR_CODES = BRIDGE_ERROR_CODES;
 
 const execFileAsync = promisify(execFile);
 
+// Recover the typed code a cdp-bridge child reported: the stderr marker is
+// authoritative (it carries the class the bridge classified at the source), the
+// coded exit status is the fallback for output-less failures, and a raw message
+// needle covers a bridge that predates the codes.
+function bridgeChildErrorCode(exitCode, output) {
+  return (
+    parseErrorMarker(output) ||
+    ERROR_CODE_BY_EXIT_CODE[exitCode] ||
+    classifyBridgeErrorMessage(output) ||
+    null
+  );
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -169,12 +195,12 @@ export function selectBridgeStatusEntry(status, input) {
     }
     // Pinned android but no android entry answered — failing fast beats letting the
     // caller read the iOS entry and report misleading wallet state.
-    throw new Error(
+    throw coded(new Error(
       `Pinned android device ${adbSerial} has no responding bridge target.\n` +
       `  Bridge status entries:\n` +
       entries.map((entry) => `    - ${entry.deviceName ?? '?'} [${entry.platform || 'unknown'}]`).join('\n') +
       `\n  Next: mm-harness launch android   # bring the app back to the foreground`,
-    );
+    ), BRIDGE_ERROR_CODES.NO_TARGET);
   }
   if (iosSimulator) {
     const sim = entries.find((entry) => entry.deviceName === iosSimulator);
@@ -239,11 +265,16 @@ export async function bridgeCommand(input, args) {
   });
   if (result.timedOut) {
     const command = ['node', path.relative(input.context.projectRoot, script), ...redactBridgeArgs(args)].join(' ');
-    throw new Error(`Mobile CDP bridge command timed out after ${result.timeoutMs}ms: ${command}`);
+    throw coded(
+      new Error(`Mobile CDP bridge command timed out after ${result.timeoutMs}ms: ${command}`),
+      BRIDGE_ERROR_CODES.CDP_TIMEOUT,
+    );
   }
   if (result.exitCode !== 0) {
     const command = ['node', path.relative(input.context.projectRoot, script), ...redactBridgeArgs(args)].join(' ');
-    throw new Error(`Mobile CDP bridge command failed: ${command}\n${redactBridgeOutput(result.stderr || result.stdout, sensitiveBridgeArgs(args))}`);
+    const code = bridgeChildErrorCode(result.exitCode, result.stderr || result.stdout);
+    const error = new Error(`Mobile CDP bridge command failed: ${command}\n${redactBridgeOutput(result.stderr || result.stdout, sensitiveBridgeArgs(args))}`);
+    throw code ? coded(error, code) : error;
   }
   // For transient commands, stdout of '' or 'undefined' means the state is not yet
   // settled (e.g. mid-navigation). Return null so callers like waitForRoute can poll

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"