@deeeed/metamask-harness 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -1,9 +1,30 @@
 # Changelog
 
-## Unreleased
+## 0.14.0 - 2026-07-08
+
+### Added
+- `mm-harness call` accepts action fields as direct `key=value` shorthand in addition to repeated `--arg k=v`, so commands like `mm-harness call ui.navigate page=perps` now match the examples agents naturally write.
+- Packaged recipes are grouped by domain under `library/recipes/<domain>/` and still resolve by dotted names (`perps.smoke`, `runner.smoke`) with legacy aliases for the former flat names.
+- Packaged `perps.smoke` recipes for mobile, extension, and core provide an explicit non-mutating Perps domain smoke. The existing bare `smoke` alias remains a runner/transport smoke for compatibility.
+
+### Fixed
+- `status` now hydrates slot runtime context before device enumeration, so a Farmslot checkout pinned to `IOS_SIMULATOR=mm-1` reports only the selected slot simulator instead of every booted simulator/device on the machine. Live status also updates `Next:` to `mm-harness logs` when the selected bridge is reachable.
+- The tmux Metro window opened by `launch ios|android` now streams the Metro output it writes to `metro.log` instead of opening a blank server window.
+- `log-tui watch` now matches success/failure patterns only against log content emitted after the watcher starts, so stale markers already present in long-lived Metro/webpack logs cannot false-pass readiness checks.
+- `start-metro` now reaps any existing mobile console-forwarder attached to the same Metro port before spawning this slot's forwarder, even when the old process was launched from another checkout or package install path.
+
+## 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
 
@@ -21,7 +42,7 @@
 ### Added
 - Mobile recipes can now use the standard outer `app.lifecycle` action for deterministic performance start states without rebuilding (Android background/foreground/terminate/restart, iOS simulator launch/terminate/restart through the shared Farmslot lifecycle adapter).
 - `fixtures set --device <serial|udid|name>` now pins mobile fixture sync to the requested device using the same targeting rules as `run`, `call`, and `doctor`.
-- New lifecycle-controlled measured flows in the packaged library: `app-lifecycle-android-smoke`, `perps-performance-warm-start`, `perps-performance-background-resume`, `perps-performance-cold-start`; performance recipes now keep lifecycle/unlock in `setup[]`/`startState` so measured nodes carry only CUF timings.
+- New lifecycle-controlled measured flows in the packaged library: `app.lifecycle.android-smoke`, `perps.performance.warm-start`, `perps.performance.background-resume`, `perps.performance.cold-start`; performance recipes now keep lifecycle/unlock in `setup[]`/`startState` so measured nodes carry only CUF timings.
 
 ### Changed
 - `@farmslot/recipe-harness` dependency raised to `^0.4.0` (ships the `app.lifecycle` adapter — the `FARMSLOT_ROOT` local-source fallback is no longer needed at runtime).
@@ -38,9 +59,9 @@
 ## 0.10.0 - 2026-07-07
 
 ### Added
-- **Canonical `perps-performance` measured flow** (`library/recipes/perps-performance.mobile.recipe.json`): unlock → open the Perps market list → read live state → open a market detail — one node per user-visible step with stable node names, so the per-node `duration`s in `trace.json` are the timings you monitor. Run pinned: `mm-harness run perps-performance --device <serial> --heal off`. Device-proven end-to-end on a physical Pixel.
+- **Canonical `perps.performance` measured flow** (`library/recipes/perps/performance.mobile.recipe.json`): unlock → open the Perps market list → read live state → open a market detail — one node per user-visible step with stable node names, so the per-node `duration`s in `trace.json` are the timings you monitor. Run pinned: `mm-harness run perps.performance --device <serial> --heal off`. Device-proven end-to-end on a physical Pixel.
 - **`run <name>` resolves personal/team recipe libraries.** Previously only the packaged library was probed by name; custom recipes ran by path. Sources resolve in library-precedence order (personal > team shadow the packaged canonical — a same-named personal recipe wins), path-shaped args never probe libraries, and a miss teaches which sources were searched. Zero-flag default: `$FARMSLOT_HOME/recipe-library`.
-- **Custom-library walkthrough** ("Your own measured flow" in `docs/recipe-libraries.md`): a peer engineer scaffolds a personal library, copies the canonical flow, retargets the nodes to their journey, and runs it by name. Every step is executed by the `perps-performance-recipe` contract test, so the doc cannot drift from reality.
+- **Custom-library walkthrough** ("Your own measured flow" in `docs/recipe-libraries.md`): a peer engineer scaffolds a personal library, copies the canonical flow, retargets the nodes to their journey, and runs it by name. Every step is executed by the `perps.performance-recipe` contract test, so the doc cannot drift from reality.
 - **`call` declared on mobile and extension manifests** (was core-only) with self-discovery metadata — personal `flows/` segments are now usable from mobile/extension recipes. Honest limitation documented: flows carry no adapter dimension in the protocol yet, so a cross-adapter `call` fails at live-run rather than plan time.
 
 ### Fixed
@@ -63,7 +84,7 @@
 ## 0.8.0 - 2026-07-07
 
 ### Added
-- **`run <name>` — the recipe positional resolves packaged-library recipe names.** An existing file path (absolute or cwd-relative) wins; otherwise the arg is a library recipe name, adapter-scoped first (`run smoke` on mobile → `smoke.mobile.recipe.json`), then adapterless (`run perps-lifecycle`), then the exact library filename. A miss teaches `RECIPE_NOT_FOUND` naming the library recipes available for the adapter — no more `$LIB`-style path prefixes in docs or demo scripts. A directory shadowing a library name never wins, and path-shaped args (containing a separator) never fall through to the library.
+- **`run <name>` — the recipe positional resolves packaged-library recipe names.** An existing file path (absolute or cwd-relative) wins; otherwise the arg is a library recipe name, adapter-scoped first (`run smoke` on mobile → `library/recipes/runner/smoke.mobile.recipe.json`), then adapterless (`run perps.lifecycle` → `library/recipes/perps/lifecycle.recipe.json`), then the exact library filename. A miss teaches `RECIPE_NOT_FOUND` naming the library recipes available for the adapter — no more `$LIB`-style path prefixes in docs or demo scripts. A directory shadowing a library name never wins, and path-shaped args (containing a separator) never fall through to the library.
 - **`--device <udid|serial|name>` — first-class mobile device targeting on `run`, `call`, and `doctor`.** Resolves against connected devices (adb + booted simulators; exact id first, then exact name with an ambiguity teaching error) and sets the same env `launch --device` does. Mobile `run`/`call` **without** `--device` while more than one targetable device is connected (across android + ios; android state `device`, iOS `Booted`) fail fast listing the devices and the `--device` hint, so a recipe never lands on the wrong device silently. `run --plan`/`--list` are exempt; extension/core teach. Errors honor `--json` with structured envelopes.
 - **`status` gains `devices[]`** (additive): `{platform, id, name, state, selected}` for connected android devices and booted iOS simulators on mobile checkouts — the `yarn a:status` successor; `selected` reflects the current env pinning.
 

package/adapters/extension/verify.sh

@@ -88,7 +88,7 @@ RUNNER_BIN="$HARNESS_DIR/runner/bin/mm-harness"
 # --out (optional): a task-local recipes dir. Resolve it safely within the target
 # (resolve_harness_out rejects absolute/.. escapes) and prefer its smoke recipe so
 # `live --out <dir>` does not silently fall back to the installed default.
-SMOKE_RECIPE="$HARNESS_DIR/runner/recipes/smoke.extension.recipe.json"
+SMOKE_RECIPE="$HARNESS_DIR/runner/recipes/runner/smoke.extension.recipe.json"
 if [ -n "$OUT" ]; then
   # Fail fast on a task-local --out that does not contain the requested recipe.
   # Silently falling back to the installed default would validate a different
@@ -98,11 +98,11 @@ if [ -n "$OUT" ]; then
     echo "extension verify: --out '$OUT' did not resolve to a safe path under the target." >&2
     exit 2
   fi
-  if [ ! -f "$OUT_ABS/smoke.extension.recipe.json" ]; then
-    echo "extension verify: --out '$OUT' (resolved: $OUT_ABS) has no smoke.extension.recipe.json. Refusing to fall back to the installed default recipe; place the recipe under --out or omit --out." >&2
+  if [ ! -f "$OUT_ABS/runner/smoke.extension.recipe.json" ]; then
+    echo "extension verify: --out '$OUT' (resolved: $OUT_ABS) has no runner/smoke.extension.recipe.json. Refusing to fall back to the installed default recipe; place the recipe under --out or omit --out." >&2
     exit 2
   fi
-  SMOKE_RECIPE="$OUT_ABS/smoke.extension.recipe.json"
+  SMOKE_RECIPE="$OUT_ABS/runner/smoke.extension.recipe.json"
 fi
 ARTIFACTS="${ARTIFACTS:-$HARNESS_DIR/verify/$(date -u +%Y%m%dT%H%M%SZ)}"
 mkdir -p "$ARTIFACTS/logs"

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

@@ -86,6 +86,20 @@ start_console_forwarder() {
   local fwd_pid_file="$LOG_DIR/console-forwarder.pid"
   [ "${METAMASK_RECIPE_CONSOLE_FORWARD:-1}" != "0" ] || return 0
   { [ -f "$forwarder" ] && command -v node >/dev/null 2>&1; } || return 0
+  # Only one debugger can own a React Native page. Reap any forwarder already
+  # attached to this Metro port, even if it was launched from another checkout or
+  # package install path and therefore does not own this runtime dir's pid file.
+  while IFS= read -r line; do
+    local pid cmd
+    pid="${line%% *}"
+    cmd="${line#* }"
+    [ "$pid" != "$line" ] || continue
+    case "$cmd" in
+      *console-forwarder.cjs*" --port $PORT "*|*console-forwarder.cjs*" --port=$PORT "*)
+        kill "$pid" 2>/dev/null || true
+        ;;
+    esac
+  done < <(ps -axo pid=,command= 2>/dev/null || true)
   if [ -f "$fwd_pid_file" ]; then
     local old_fwd
     old_fwd="$(cat "$fwd_pid_file" 2>/dev/null || true)"
@@ -120,10 +134,13 @@ 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")"
-exec yarn expo start --port "$(printf '%q' "$PORT")"$clear_flag >> "$(printf '%q' "$LOG_FILE")" 2>&1
+yarn expo start --port "$(printf '%q' "$PORT")"$clear_flag 2>&1 | tee -a "$(printf '%q' "$LOG_FILE")"
 EOF
   chmod +x "$runner"
 }
@@ -203,6 +220,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}"