@deeeed/metamask-harness 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.9.1 - 2026-07-07
+
+### Fixed
+- **Metro survives the launching shell.** `start-metro.sh` spawned Metro without SIGHUP protection, so closing the launching tmux window/shell killed it, leaving a stale `metro.pid` and hanging every subsequent bridge/fixtures call. Metro now starts under `nohup` (argv spawn, no `bash -c` string interpolation), and a stale `metro.pid` naming a dead process is detected and cleaned before start.
+- **`--device <adb serial>` reaches CDP target selection.** The runner's ambiguity gate resolved the serial, but target discovery compared it against Metro's `deviceName` ("Pixel 6 - 16 - API 36") — never a serial — so with an iOS simulator also attached, a recipe pinned to the physical Android device could silently drive the simulator. The serial is now mapped to the Metro identity via `adb -s <serial> shell getprop ro.product.model` with model-prefix matching (scoped to non-simulator targets); an unmatchable or ambiguous pin (two same-model devices) fails fast listing every Metro `/json/list` candidate instead of silently picking one. `--device <serial>` remains the only thing users pass.
+- **Bridge commands always emit valid JSON.** `get-route` printed the literal string `undefined` when the route was transiently unavailable mid-navigation, so `bridgeCommand()` threw on parse and `waitForRoute()` aborted instead of polling. `get-route`/`navigate`/`go-back` now normalise a missing route to `null`, `bridgeCommand()` treats `''`/`undefined` stdout as not-settled-yet only for transient-legitimate commands, and `waitForRoute()` polls through `null` until timeout — the timeout error carries the expected route, last parsed route, last bridge reply and the device pin.
+- **Wallet setup env propagation.** `bridgeEnv()` became async with the serial mapping; the wallet setup action now awaits it instead of spreading a Promise, which would have handed `setup-wallet.sh` an almost-empty environment.
+
 ## 0.9.0 - 2026-07-07
 
 ### Added

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

@@ -104,7 +104,17 @@ const COMMANDS = {
       client,
       'globalThis.__AGENTIC__?.getRoute()',
     );
-    return { navigated: routeName, params, previousRoute, currentRoute, deviceName, platform };
+    // Normalize route values: cdpEval returns undefined when the optional-chain
+    // short-circuits (mid-navigation transient or bridge not yet installed).
+    // null is valid JSON; undefined produces the literal string "undefined".
+    return {
+      navigated: routeName,
+      params,
+      previousRoute: previousRoute ?? null,
+      currentRoute: currentRoute ?? null,
+      deviceName,
+      platform,
+    };
   },
 
   async 'get-route'(client) {
@@ -112,7 +122,10 @@ const COMMANDS = {
       client,
       'globalThis.__AGENTIC__?.getRoute()',
     );
-    return route;
+    // cdpEval returns undefined when the optional-chain short-circuits (bridge not
+    // yet installed, mid-navigation, or route state transiently missing). Return null
+    // so JSON.stringify produces valid JSON ("null") instead of literal "undefined".
+    return route ?? null;
   },
 
   async 'get-state'(client, args) {
@@ -168,7 +181,9 @@ const COMMANDS = {
       client,
       'globalThis.__AGENTIC__?.getRoute()',
     );
-    return { currentRoute: route, deviceName, platform };
+    // Same normalization as navigate/get-route: a transiently-missing route must
+    // serialize as "currentRoute": null, not have the key silently omitted.
+    return { currentRoute: route ?? null, deviceName, platform };
   },
 
   async status(client, _args, { deviceName, platform } = {}) {

package/adapters/mobile/bridge-runtime/lib/config.cjs

@@ -30,10 +30,22 @@ function loadSimulatorName() {
   return loadEnvValue('IOS_SIMULATOR') || '';
 }
 
-/** Read ANDROID_DEVICE serial from .js.env or env (default: none — accept any device) */
+/** Read ANDROID_DEVICE from .js.env or env (default: none — accept any device) */
 function loadAndroidDevice() {
   if ('ANDROID_DEVICE' in process.env) return process.env.ANDROID_DEVICE;
   return loadEnvValue('ANDROID_DEVICE') || '';
 }
 
-module.exports = { loadEnvValue, loadPort, loadSimulatorName, loadAndroidDevice };
+/**
+ * Read ANDROID_TARGET_DEVICE_NAME from env — the Metro-compatible model prefix
+ * resolved from an adb serial by bridge.mjs. Used by target-discovery to select
+ * the correct Metro CDP target when multiple devices are connected.
+ *
+ * Set automatically by the bridge when --device <serial> is used. Users never
+ * need to set this; pass --device <adb-serial> and the harness maps it internally.
+ */
+function loadAndroidTargetDeviceName() {
+  return process.env.ANDROID_TARGET_DEVICE_NAME || '';
+}
+
+module.exports = { loadEnvValue, loadPort, loadSimulatorName, loadAndroidDevice, loadAndroidTargetDeviceName };

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

@@ -1,7 +1,7 @@
 'use strict';
 
 const http = require('node:http');
-const { loadSimulatorName, loadAndroidDevice } = require('./config.cjs');
+const { loadSimulatorName, loadAndroidDevice, loadAndroidTargetDeviceName } = require('./config.cjs');
 const { createWSClient } = require('./ws-client.cjs');
 
 const FETCH_TIMEOUT_MS = Number.parseInt(process.env.CDP_TIMEOUT || '30000', 10);
@@ -125,14 +125,76 @@ async function discoverTarget(port) {
     }
   }
 
-  // Filter by device name if ANDROID_DEVICE is set
+  // Android device filtering: support two identity layers.
+  //   ANDROID_TARGET_DEVICE_NAME — Metro-compatible model prefix resolved by bridge.mjs
+  //     from the adb serial via `adb -s <serial> shell getprop ro.product.model`.
+  //     Example: "Pixel 6" matches Metro deviceName "Pixel 6 - 16 - API 36".
+  //   ANDROID_DEVICE — exact Metro deviceName (backward compat / user-specified).
+  //
+  // When a device is pinned and multiple candidates remain, we MUST NOT silently fall
+  // back to another target (e.g. an iOS simulator). If the pin cannot be matched,
+  // fail fast with diagnostics so the operator can diagnose the mismatch.
+  const androidTargetName = loadAndroidTargetDeviceName();
   const androidDevice = loadAndroidDevice();
-  if (androidDevice && candidates.length > 1) {
-    const deviceFiltered = candidates.filter(
-      (t) => t.deviceName === androidDevice,
-    );
-    if (deviceFiltered.length > 0) {
-      candidates = deviceFiltered;
+  const adbSerial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || '';
+
+  if (candidates.length > 1) {
+    let androidFiltered = [];
+
+    if (androidTargetName) {
+      // Model prefix match: "Pixel 6" matches "Pixel 6 - 16 - API 36". Metro's
+      // /json/list has no explicit platform field, so scope the ANDROID pin by
+      // excluding the one iOS identity we do know (the pinned simulator name) —
+      // a simulator named to shadow a model string must not satisfy an android pin.
+      androidFiltered = candidates.filter(
+        (t) => t.deviceName !== simName &&
+               (t.deviceName === androidTargetName ||
+                (t.deviceName != null && t.deviceName.startsWith(androidTargetName))),
+      );
+      if (androidFiltered.length > 1) {
+        // Two same-model devices produce identical Metro model prefixes — the pin
+        // is genuinely ambiguous; picking one silently is exactly the bug this
+        // path exists to prevent.
+        const ambiguousList = androidFiltered
+          .map((t) => `  deviceName=${JSON.stringify(t.deviceName || '')} ws=${t.webSocketDebuggerUrl || ''}`)
+          .join('\n');
+        throw 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.`,
+        );
+      }
+      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(
+          `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}`,
+        );
+      }
+      candidates = androidFiltered;
+    } else if (androidDevice) {
+      // Exact Metro deviceName match (user set ANDROID_DEVICE to the Metro name, or
+      // legacy path where ANDROID_DEVICE was not resolved from serial).
+      androidFiltered = candidates.filter((t) => t.deviceName === androidDevice);
+      if (androidFiltered.length === 0) {
+        // Pinned by exact Metro name but no candidate matched — fail fast.
+        const candidateList = targets
+          .map((t) => `  deviceName=${JSON.stringify(t.deviceName || '')} ws=${t.webSocketDebuggerUrl || ''}`)
+          .join('\n');
+        throw 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}`,
+        );
+      }
+      candidates = androidFiltered;
     }
   }
 

package/adapters/mobile/start-metro.sh

@@ -79,6 +79,18 @@ default_metro_workers() {
 
 # --- main ---------------------------------------------------------------------
 
+# Detect stale metro.pid: if the pid file names a dead process, clean it up.
+# A stale file survives when Metro is killed externally (session close, SIGKILL)
+# and the normal stop path never ran. Cleaning it here keeps metro_ready and the
+# log from attributing a new start to the old process id.
+if [ -f "$PID_FILE" ]; then
+  stale_pid="$(cat "$PID_FILE" 2>/dev/null || true)"
+  if [ -n "$stale_pid" ] && ! kill -0 "$stale_pid" 2>/dev/null; then
+    printf 'start-metro: stale metro.pid (pid %s no longer alive); cleaning up\n' "$stale_pid" >&2
+    rm -f "$PID_FILE"
+  fi
+fi
+
 # Decide whether to (re)start or skip.
 if metro_ready; then
   if [ "$CLEAR" = true ]; then
@@ -97,11 +109,11 @@ fi
 stop_metro_listener || exit 1
 
 METRO_WORKERS="${METRO_MAX_WORKERS:-$(default_metro_workers)}"
-CLEAR_SUFFIX=""
-[ "$CLEAR" = true ] && CLEAR_SUFFIX=" --clear"
+CLEAR_LABEL=""
+[ "$CLEAR" = true ] && CLEAR_LABEL=", clear"
 
 printf 'Starting Metro on port %s (workers=%s%s)\n' \
-  "$PORT" "$METRO_WORKERS" "${CLEAR:+, clear}" >&2
+  "$PORT" "$METRO_WORKERS" "$CLEAR_LABEL" >&2
 printf '(Full log: %s — mm-harness logs | mm-harness logs --full)\n' "$LOG_FILE" >&2
 
 # Metro runs detached, writing to the log. The tmux window is a read-only tail.
@@ -127,12 +139,17 @@ printf '(Full log: %s — mm-harness logs | mm-harness logs --full)\n' "$LOG_FIL
   export WATCHER_PORT="${PORT}" METRO_PORT="${PORT}"
   export METRO_MAX_WORKERS="${METRO_WORKERS}"
   # shellcheck disable=SC2094
-  bash -c "exec yarn expo start --port ${PORT}${CLEAR_SUFFIX}" \
+  # nohup sets SIGHUP to ignored (inherited across exec), so Metro survives the
+  # launching shell or tmux window closing; when this subshell exits the process
+  # is reparented to init. That alone is the detach guarantee — Metro was never
+  # in the parent shell's job table, so there is nothing to disown.
+  # nohup.out is suppressed (stdout/stderr both go to $LOG_FILE via >>).
+  metro_args=(expo start --port "$PORT")
+  [ "$CLEAR" = true ] && metro_args+=(--clear)
+  nohup yarn "${metro_args[@]}" \
     </dev/null >> "$LOG_FILE" 2>&1 &
   echo "$!" > "$PID_FILE"
 )
-# Disown the background process so it outlives this script.
-disown "$(cat "$PID_FILE" 2>/dev/null || true)" 2>/dev/null || true
 
 start_viewer_window "$LOG_FILE"
 

package/docs/CLI-SPEC.md

@@ -439,7 +439,9 @@ Readiness check for a checkout without launching the app. Doctor is the single p
 
 ## `--device <id>` — first-class mobile device targeting (REAL)
 
-`--device` is the uniform mobile device selector on `run`, `call`, and `doctor`. It sets the **same env `launch` does** before the engine reads `process.env`, so the engine needs no changes: an Android serial → `ADB_SERIAL` + `ANDROID_SERIAL` + `ANDROID_DEVICE`; an iOS UDID/simulator name → `IOS_SIMULATOR`. The android-vs-ios decision comes from matching the id against the connected-device lists (`adb devices -l` + booted `xcrun simctl` simulators); an id that matches neither list is a teaching usage error that lists the connected devices.
+`--device` is the uniform mobile device selector on `run`, `call`, and `doctor`. Pass the **adb serial** for Android (from `adb devices`) or the **UDID / simulator name** for iOS. The harness resolves the adb serial to the Metro CDP target identity internally — users never need to know or set `ANDROID_DEVICE='Pixel 6 - 16 - API 36'`.
+
+**Internal Android identity mapping**: `ADB_SERIAL` / `ANDROID_SERIAL` carry the raw adb serial. The bridge resolves the device model via `adb -s <serial> shell getprop ro.product.model` and propagates it as `ANDROID_TARGET_DEVICE_NAME`. Target-discovery uses `ANDROID_TARGET_DEVICE_NAME` for Metro `deviceName` prefix matching (e.g. `"Pixel 6"` matches `"Pixel 6 - 16 - API 36"`). When the pinned model cannot be matched to any Metro `/json/list` candidate and multiple candidates exist, the bridge fails fast with a diagnostic listing every candidate's `deviceName` — it never silently selects the wrong device. iOS UDID/simulator name → `IOS_SIMULATOR` (unchanged).
 
 | Verb | `--device` given | `--device` omitted (mobile) |
 |---|---|---|

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

@@ -1,8 +1,11 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { spawn } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+const execFileAsync = promisify(execFile);
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -34,7 +37,30 @@ function runtimeDir() {
   return fileURLToPath(new URL('../../../../adapters/mobile/bridge-runtime', import.meta.url));
 }
 
-export function bridgeEnv(input) {
+/**
+ * Resolve the Android model name from an adb serial.
+ * Returns the trimmed ro.product.model value, or null when adb is unavailable
+ * or the serial does not respond. Uses execFile (never shell interpolation).
+ */
+async function resolveAndroidModel(adbSerial) {
+  try {
+    const { stdout } = await execFileAsync(
+      'adb',
+      ['-s', adbSerial, 'shell', 'getprop', 'ro.product.model'],
+      { timeout: 5000, encoding: 'utf8' },
+    );
+    const model = stdout.trim();
+    return model || null;
+  } catch {
+    // Recovery is correct: model resolution for Metro target selection is advisory.
+    // If adb is unavailable or the serial is unreachable, discovery falls through to
+    // the exact ANDROID_DEVICE match or probe-and-pick. The error will surface from
+    // the CDP connection attempt if the wrong target is selected.
+    return null;
+  }
+}
+
+export async function bridgeEnv(input) {
   /** @type {NodeJS.ProcessEnv} */
   const env = {
     ...process.env,
@@ -53,6 +79,20 @@ export function bridgeEnv(input) {
     env.ADB_SERIAL = String(adbSerial);
     env.ANDROID_SERIAL = String(adbSerial);
   }
+  // When --device passes an adb serial, device-target.ts sets both ANDROID_DEVICE and
+  // ADB_SERIAL to the same value. ANDROID_DEVICE must be the Metro deviceName for
+  // target-discovery to select the right CDP target; it cannot be a raw adb serial.
+  // Resolve the device model via adb getprop and propagate it as
+  // ANDROID_TARGET_DEVICE_NAME so target-discovery can match by model prefix
+  // (e.g. "Pixel 6" matches Metro deviceName "Pixel 6 - 16 - API 36").
+  const serialStr = adbSerial != null ? String(adbSerial) : '';
+  const deviceStr = androidDevice != null ? String(androidDevice) : '';
+  if (serialStr && deviceStr === serialStr) {
+    const model = await resolveAndroidModel(serialStr);
+    if (model) {
+      env.ANDROID_TARGET_DEVICE_NAME = model;
+    }
+  }
   return env;
 }
 
@@ -65,13 +105,20 @@ function resolveMobileTarget(input) {
   return { watcherPort, iosSimulator, androidDevice, adbSerial };
 }
 
+// Commands where a transient undefined/empty stdout means "not yet settled", not failure.
+// get-route returns undefined mid-navigation when the route state is momentarily unavailable;
+// waitForRoute polls through these nulls rather than aborting on a parse error.
+const TRANSIENT_NULL_COMMANDS = new Set(['get-route']);
+
 export async function bridgeCommand(input, args) {
   const script = bridgeScript(input);
+  // bridgeEnv is async: it may call `adb getprop` to resolve the Metro device name.
+  const env = await bridgeEnv(input);
   const result = await new Promise((resolve, reject) => {
     const timeoutMs = Number(input.node?.bridge_timeout_ms ?? input.node?.cdp_timeout_ms ?? process.env.CDP_TIMEOUT ?? 30000);
     const child = spawn(process.execPath, [script, ...args], {
       cwd: input.context.projectRoot,
-      env: { ...bridgeEnv(input), APP_ROOT: input.context.projectRoot },
+      env: { ...env, APP_ROOT: input.context.projectRoot },
       stdio: ['ignore', 'pipe', 'pipe'],
     });
     let stdout = '';
@@ -111,6 +158,14 @@ export async function bridgeCommand(input, args) {
     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))}`);
   }
+  // 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
+  // rather than aborting on a JSON parse error.
+  const command = String(args[0] ?? '');
+  const trimmedStdout = result.stdout.trim();
+  if ((trimmedStdout === '' || trimmedStdout === 'undefined') && TRANSIENT_NULL_COMMANDS.has(command)) {
+    return null;
+  }
   try {
     const parsed = JSON.parse(result.stdout);
     if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && parsed.ok === false) {
@@ -195,13 +250,35 @@ function routeName(route) {
 export async function waitForRoute(input, expectedRoute, timeoutMs = 15000) {
   const expected = String(expectedRoute);
   const deadline = Date.now() + timeoutMs;
+  // lastRoute is null when bridgeCommand returns null (transient: route not yet
+  // settled mid-navigation). Null means "not ready yet" — keep polling.
   let lastRoute = null;
+  let pollCount = 0;
   while (Date.now() < deadline) {
     lastRoute = await bridgeCommand(input, ['get-route']);
     if (routeName(lastRoute) === expected) return lastRoute;
+    pollCount += 1;
     await sleep(250);
   }
-  throw new Error(`Timed out waiting for Mobile route ${expected}; last route was ${JSON.stringify(lastRoute)}`);
+  const target = resolveMobileTarget(input);
+  const deviceHint = [
+    target.adbSerial && `ADB_SERIAL=${target.adbSerial}`,
+    target.androidDevice && target.androidDevice !== target.adbSerial && `ANDROID_DEVICE=${target.androidDevice}`,
+    target.iosSimulator && `IOS_SIMULATOR=${target.iosSimulator}`,
+  ].filter(Boolean).join(', ') || 'no device pin';
+  // bridgeCommand already parsed (or null-normalized) the reply, so raw stdout is
+  // not available here — describe the reply honestly instead of relabeling the
+  // parsed value as "raw".
+  const lastReply = lastRoute === null
+    ? 'empty/undefined (route transiently unavailable — bridge not yet settled)'
+    : JSON.stringify(lastRoute);
+  throw new Error(
+    `Timed out waiting for Mobile route '${expected}' after ${timeoutMs}ms (${pollCount} polls).\n` +
+    `  Expected route: ${expected}\n` +
+    `  Last parsed route: ${JSON.stringify(lastRoute)}\n` +
+    `  Last bridge reply: ${lastReply}\n` +
+    `  Device: ${deviceHint}`,
+  );
 }
 
 export async function simulatorScreenshot(input, relPath) {

package/library/actions/mobile/wallet/setup.mjs

@@ -112,7 +112,10 @@ function setupWalletScript() {
   return fileURLToPath(new URL('../../../../adapters/mobile/bridge-runtime/setup-wallet.sh', import.meta.url));
 }
 
-function runSetupWallet(input, fixture) {
+async function runSetupWallet(input, fixture) {
+  // bridgeEnv is async (it may shell adb to resolve the Metro device name);
+  // spreading its un-awaited Promise would hand the child an almost-empty env.
+  const env = await bridgeEnv(input);
   return new Promise((resolve, reject) => {
     const timeoutMs = Number(
       input.node?.setup_timeout_ms ?? input.node?.timeout_ms ?? 120000,
@@ -122,7 +125,7 @@ function runSetupWallet(input, fixture) {
       [setupWalletScript(), '--fixture', fixture.absolutePath],
       {
         cwd: input.context.projectRoot,
-        env: { ...bridgeEnv(input), CDP_TIMEOUT: String(timeoutMs), APP_ROOT: input.context.projectRoot },
+        env: { ...env, CDP_TIMEOUT: String(timeoutMs), APP_ROOT: input.context.projectRoot },
         stdio: ['ignore', 'pipe', 'pipe'],
       },
     );

package/package.json

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