@deeeed/metamask-harness 0.10.0 → 0.12.0

package/adapters/mobile/start-metro.sh

@@ -77,6 +77,72 @@ default_metro_workers() {
 # shellcheck disable=SC1091
 . "$SCRIPT_DIR/lib/tmux-viewer.sh"
 
+# Bridgeless RN gates console→Metro forwarding on console._isPolyfilled, which is
+# false with the Hermes native console — device logs (incl. DevLogger) never reach
+# metro.log. The forwarder attaches over CDP and appends them back. Kill switch:
+# METAMASK_RECIPE_CONSOLE_FORWARD=0.
+start_console_forwarder() {
+  local forwarder="$SCRIPT_DIR/bridge-runtime/console-forwarder.cjs"
+  local fwd_pid_file="$LOG_DIR/console-forwarder.pid"
+  [ "${METAMASK_RECIPE_CONSOLE_FORWARD:-1}" != "0" ] || return 0
+  { [ -f "$forwarder" ] && command -v node >/dev/null 2>&1; } || return 0
+  if [ -f "$fwd_pid_file" ]; then
+    local old_fwd
+    old_fwd="$(cat "$fwd_pid_file" 2>/dev/null || true)"
+    # A crash can leave a stale pid file and the OS can recycle the pid for an
+    # unrelated process — only kill when the command line is really ours.
+    if [ -n "$old_fwd" ]; then
+      case "$(ps -p "$old_fwd" -o command= 2>/dev/null)" in
+        *console-forwarder.cjs*) kill "$old_fwd" 2>/dev/null ;;
+      esac
+    fi
+    rm -f "$fwd_pid_file"
+  fi
+  nohup node "$forwarder" --port "$PORT" --out "$LOG_FILE" \
+    </dev/null >> "$LOG_DIR/console-forwarder.err" 2>&1 &
+  echo "$!" > "$fwd_pid_file"
+  disown 2>/dev/null || true
+  printf 'Device console → metro.log (CDP forwarder pid %s)\n' "$(cat "$fwd_pid_file")" >&2
+}
+
+write_metro_runner() {
+  local runner="$1"
+  local clear_flag=""
+  [ "$CLEAR" = true ] && clear_flag=' --clear'
+  cat > "$runner" <<EOF
+#!/usr/bin/env bash
+set -uo pipefail
+cd "$(printf '%q' "$TARGET")"
+: > "$(printf '%q' "$LOG_FILE")"
+set -a
+[ ! -f .js.env ]    || . ./.js.env
+[ ! -f .env ]       || . ./.env
+[ ! -f .env.local ] || . ./.env.local
+set +a
+[ -n "\${METAMASK_BUILD_TYPE:-}" ] || export METAMASK_BUILD_TYPE=main
+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
+EOF
+  chmod +x "$runner"
+}
+
+start_metro_tmux() {
+  command -v tmux >/dev/null 2>&1 || return 1
+  local session window runner
+  session="$(resolve_run_tmux_session "$LOG_DIR")"
+  { [ -n "$session" ] && tmux has-session -t "=$session" 2>/dev/null; } || return 1
+  window="metro-${PORT}"
+  runner="$LOG_DIR/run-metro-${PORT}.sh"
+  write_metro_runner "$runner"
+  tmux kill-window -t "${session}:${window}" >/dev/null 2>&1 || true
+  tmux new-window -d -t "$session" -n "$window" "exec $(printf '%q' "$runner")" || return 1
+  printf '%s:%s\n' "$session" "$window" > "$LOG_DIR/metro.tmux"
+  printf 'Metro server → tmux %s:%s\n' "$session" "$window" >&2
+  return 0
+}
+
 # --- main ---------------------------------------------------------------------
 
 # Detect stale metro.pid: if the pid file names a dead process, clean it up.
@@ -99,6 +165,7 @@ if metro_ready; then
     rm -f "$PID_FILE"
   elif metro_listener_valid; then
     printf 'Metro already running and valid on port %s\n' "$PORT" >&2
+    start_console_forwarder
     exit 0
   else
     stop_metro_listener || exit 1
@@ -116,42 +183,45 @@ printf 'Starting Metro on port %s (workers=%s%s)\n' \
   "$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.
-(
-  cd "$TARGET"
-  : > "$LOG_FILE"
-  # Source product env files (provides MM_INFURA_PROJECT_ID and friends).
-  set -a
-  # shellcheck disable=SC1091
-  [ ! -f .js.env ]    || . ./.js.env
-  # shellcheck disable=SC1091
-  [ ! -f .env ]       || . ./.env
-  # shellcheck disable=SC1091
-  [ ! -f .env.local ] || . ./.env.local
-  set +a
-  # The quick-launch runs `expo start` directly, bypassing scripts/build.sh which
-  # passes the build type as an argument (start:ios = build.sh ios main dev). The
-  # fixture .js.env ships METAMASK_BUILD_TYPE="" (empty), which Metro's transform
-  # 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
-  export EXPO_NO_TYPESCRIPT_SETUP=1
-  export WATCHER_PORT="${PORT}" METRO_PORT="${PORT}"
-  export METRO_MAX_WORKERS="${METRO_WORKERS}"
-  # shellcheck disable=SC2094
-  # 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"
-)
-
-start_viewer_window "$LOG_FILE"
+if ! start_metro_tmux; then
+  # Metro runs detached, writing to the log. The tmux window is a read-only tail.
+  (
+    cd "$TARGET"
+    : > "$LOG_FILE"
+    # Source product env files (provides MM_INFURA_PROJECT_ID and friends).
+    set -a
+    # shellcheck disable=SC1091
+    [ ! -f .js.env ]    || . ./.js.env
+    # shellcheck disable=SC1091
+    [ ! -f .env ]       || . ./.env
+    # shellcheck disable=SC1091
+    [ ! -f .env.local ] || . ./.env.local
+    set +a
+    # The quick-launch runs `expo start` directly, bypassing scripts/build.sh which
+    # passes the build type as an argument (start:ios = build.sh ios main dev). The
+    # fixture .js.env ships METAMASK_BUILD_TYPE="" (empty), which Metro's transform
+    # 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
+    export EXPO_NO_TYPESCRIPT_SETUP=1
+    export WATCHER_PORT="${PORT}" METRO_PORT="${PORT}"
+    export METRO_MAX_WORKERS="${METRO_WORKERS}"
+    # shellcheck disable=SC2094
+    # 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. 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 &
+    metro_pid="$!"
+    echo "$metro_pid" > "$PID_FILE"
+    disown "$metro_pid" 2>/dev/null || true
+  )
+
+  start_viewer_window "$LOG_FILE"
+fi
 
 # Attach a log-tui watcher for compact event display (best-effort; non-blocking).
 LOG_TUI="$(dirname "$0")/../shared/log-tui.mjs"
@@ -180,7 +250,11 @@ done
 [ -n "$TAIL_PID" ] && { kill "$TAIL_PID" 2>/dev/null; wait "$TAIL_PID" 2>/dev/null || true; }
 
 if [ "$READY" = true ]; then
+  ready_pids="$(metro_listener_pids)"
+  first_ready_pid="${ready_pids%% *}"
+  [ -z "$first_ready_pid" ] || printf '%s\n' "$first_ready_pid" > "$PID_FILE"
   printf 'Metro ready on port %s\n' "$PORT" >&2
+  start_console_forwarder
   printf '  Next: mm-harness logs  (tail Metro)\n' >&2
   exit 0
 fi

package/adapters/mobile/stop-metro.sh

@@ -62,6 +62,27 @@ fi
 set +e
 rm -f "$PID_FILE"
 
+# start-metro runs a per-checkout console-forwarder holding the device debugger
+# slot; Metro going down must take it too, or the orphan keeps polling and later
+# fights a fresh forwarder over the slot. Kill the pid this LOG_DIR recorded,
+# then sweep forwarders started under a different RECIPE_RUNTIME_DIR of this
+# same checkout (their pid files live elsewhere; match on the --out path).
+FWD_PID_FILE="$LOG_DIR/console-forwarder.pid"
+fwd_pid="$(cat "$FWD_PID_FILE" 2>/dev/null || true)"
+# A crash can leave a stale pid file and the OS can recycle the pid for an
+# unrelated process — only kill when the command line is really ours.
+if [ -n "$fwd_pid" ]; then
+  case "$(ps -p "$fwd_pid" -o command= 2>/dev/null)" in
+    *console-forwarder.cjs*)
+      if kill "$fwd_pid" 2>/dev/null; then
+        printf 'Stopped console forwarder (pid %s)\n' "$fwd_pid" >&2
+      fi
+      ;;
+  esac
+fi
+rm -f "$FWD_PID_FILE"
+pkill -f "console-forwarder.cjs --port .* --out $TARGET/" 2>/dev/null
+
 # Port-scoped stop above misses bundlers a prior launch left on a DIFFERENT port
 # (port drift / missing pid file). Sweep every Metro bound to this checkout so
 # stop fully cleans up — the leak that stacked bundlers across relaunches.

package/adapters/mobile/wait-for-bridge.sh

@@ -93,7 +93,21 @@ const fs = require('fs');
 try {
   const value = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
   const targets = Array.isArray(value) ? value : [value];
-  if (!targets.some((t) => t && typeof t === 'object' && t.route)) process.exit(1);
+  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);
 } catch { process.exit(1); }
 NODE
 }

package/adapters/shared/open-debug.mjs

@@ -126,6 +126,11 @@ async function tryDevSettingsCdpFallback(numericPort, normalizedAction) {
       : 'NativeModules.DevSettings.openDebugger()';
   const result = spawnSync(process.execPath, [bridgePath, 'eval', expression], {
     encoding: 'utf8',
+    // cdp-bridge resolves its debugger-slot lock (RECIPE_RUNTIME_DIR) against
+    // cwd; anchor it to the app checkout so the console forwarder sees the
+    // yield — APP_ROOT when a caller exports it, else the cwd mm-harness debug
+    // already set to the target.
+    cwd: process.env.APP_ROOT || process.cwd(),
     env: { ...process.env, WATCHER_PORT: String(numericPort) },
     timeout: 15000,
   });

package/dist/adapters.js

@@ -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, simulatorScreenshot } from "../library/actions/mobile/platform/bridge.mjs";
+import { bridgeCommand, evalSync, selectBridgeStatusEntry, simulatorScreenshot } from "../library/actions/mobile/platform/bridge.mjs";
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -106,6 +106,7 @@ function firstScalarText(record, keys, label, fallback) {
 }
 function traceText(value) {
   if (value === void 0 || value === null) return "";
+  if (value instanceof Error) return value.message;
   if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
     return String(value);
   }
@@ -189,22 +190,10 @@ function uiInputFor(context, input) {
 }
 function mobileProbeOutput(status, input, projectRoot) {
   const entries = Array.isArray(status) ? status : [status];
-  const preferredDevices = [
-    input.node?.ios_simulator,
-    input.node?.simulator,
-    input.node?.android_device,
-    input.node?.adb_serial,
-    process.env.IOS_SIMULATOR,
-    process.env.ANDROID_DEVICE,
-    process.env.ADB_SERIAL
-  ].filter((value) => typeof value === "string" && value.length > 0);
-  const selected = entries.find((entry) => {
-    if (!isRecord(entry)) return false;
-    return typeof entry.deviceName === "string" && preferredDevices.includes(entry.deviceName);
-  }) ?? entries.find((entry) => isRecord(entry) && isRecord(entry.route)) ?? null;
+  const selected = selectBridgeStatusEntry(status, input) ?? null;
   const route = isRecord(selected) && isRecord(selected.route) ? selected.route : null;
   return {
-    reachable: Boolean(selected),
+    reachable: isRecord(selected) && selected.agenticPresent === true && Boolean(route),
     bridge: mobileBridgePath(projectRoot),
     targetCount: entries.filter((entry) => isRecord(entry)).length,
     deviceName: isRecord(selected) && typeof selected.deviceName === "string" ? selected.deviceName : null,
@@ -327,10 +316,50 @@ async function handleMobileWaitFor(payload, context) {
 }
 async function handleMobileHud(payload, context) {
   const input = mobileUiInput(context, "hud", payload);
-  if (payload.clear === true) return bridgeCommand(input, ["hide-step"]);
+  if (payload.clear === true) {
+    try {
+      return await bridgeCommand(input, ["hide-step"]);
+    } catch (error) {
+      return mobileHudSkippedOrThrow(error);
+    }
+  }
   const hud = mobileHudPayload(payload, context);
-  const result = await bridgeCommand(input, ["show-step-json", JSON.stringify(hud.step)]);
-  return { hud: true, nodeId: hud.nodeId, status: hud.status, result };
+  try {
+    const result = await bridgeCommand(input, ["show-step-json", JSON.stringify(hud.step)]);
+    return { hud: true, nodeId: hud.nodeId, status: hud.status, result };
+  } catch (error) {
+    return mobileHudSkippedOrThrow(error, { nodeId: hud.nodeId, status: hud.status });
+  }
+}
+function mobileHudSkippedOrThrow(error, extra = {}) {
+  const reason = traceText(error);
+  if (isMobileHudLifecycleSkip(reason)) {
+    process.stderr.write(`app.hud skipped (bridge target down or transitioning): ${reason}
+`);
+    return {
+      hud: false,
+      skipped: true,
+      warning: "app.hud skipped because the mobile bridge target is down during lifecycle transition.",
+      ...extra,
+      reason
+    };
+  }
+  throw new Error(`app.hud bridge command failed outside a lifecycle/no-target transition: ${reason}`);
+}
+function isMobileHudLifecycleSkip(reason) {
+  return [
+    "no responding bridge target",
+    "Pinned android device",
+    "bridge probe failed",
+    "ECONNREFUSED",
+    "timed out",
+    "Timed out",
+    "No React Native bridge target",
+    // Dev-client foreground/reload kills the Hermes page mid-flight: pending
+    // CDP calls surface as a message timeout or a closed socket.
+    "CDP message timeout",
+    "WebSocket closed"
+  ].some((needle) => reason.includes(needle));
 }
 function animatedFlag(payload) {
   return payload.animated === true ? "--animated" : "--no-animated";
@@ -481,5 +510,6 @@ function targetProbeUrl(platform, targetPort) {
 }
 export {
   createMetaMaskAdapters,
-  createMetaMaskUiTransport
+  createMetaMaskUiTransport,
+  isMobileHudLifecycleSkip
 };

package/dist/app-lifecycle.js

@@ -0,0 +1,72 @@
+function resolveMetaMaskMobileLifecycleTarget(node, rawContext) {
+  const context = rawContext;
+  const platform = resolveMobilePlatform(node, context);
+  const port = scalar(node.watcher_port ?? node.metro_port, "app.lifecycle.metro_port") ?? context.env.WATCHER_PORT ?? context.env.METRO_PORT ?? process.env.WATCHER_PORT ?? process.env.METRO_PORT ?? "8081";
+  const launchUrl = scalar(node.launch_url ?? node.launchUrl ?? node.url, "app.lifecycle.launch_url") ?? expoDevClientUrl(port, platform);
+  if (platform === "android") {
+    return {
+      platform,
+      deviceId: scalar(node.adb_serial ?? node.android_device ?? node.device, "app.lifecycle.device") ?? context.env.ADB_SERIAL ?? context.env.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL,
+      appId: scalar(node.package_id ?? node.packageName ?? node.app_id, "app.lifecycle.package_id") ?? context.env.ANDROID_PACKAGE_ID ?? process.env.ANDROID_PACKAGE_ID ?? "io.metamask",
+      launchUrl,
+      metroPort: port,
+      prelaunchCalls: expoBundlePrewarmCalls(port, "android")
+    };
+  }
+  return {
+    platform: "ios-simulator",
+    deviceId: scalar(node.simulator ?? node.ios_simulator ?? node.device, "app.lifecycle.device") ?? context.env.IOS_SIMULATOR ?? context.env.SIM_UDID ?? process.env.IOS_SIMULATOR ?? process.env.SIM_UDID ?? "booted",
+    appId: scalar(node.bundle_id ?? node.bundleId ?? node.app_id, "app.lifecycle.bundle_id") ?? context.env.IOS_BUNDLE_ID ?? process.env.IOS_BUNDLE_ID ?? "io.metamask.MetaMask",
+    launchUrl,
+    prelaunchCalls: expoBundlePrewarmCalls(port, "ios")
+  };
+}
+function resolveMobilePlatform(node, context) {
+  const raw = scalar(node.platform, "app.lifecycle.platform") ?? context.env.PLATFORM ?? process.env.PLATFORM;
+  if (raw === "android" || raw === "ios") return raw;
+  if (node.adb_serial || node.android_device || context.env.ADB_SERIAL || context.env.ANDROID_SERIAL || process.env.ADB_SERIAL || process.env.ANDROID_SERIAL) {
+    return "android";
+  }
+  return "ios";
+}
+function expoDevClientUrl(port, platform) {
+  const scheme = (platform === "ios" ? process.env.IOS_DEV_CLIENT_SCHEME : process.env.ANDROID_DEV_CLIENT_SCHEME) ?? "expo-metamask";
+  const metroUrl = `http://localhost:${port}?disableOnboarding=1`;
+  return `${scheme}://expo-development-client/?url=${encodeURIComponent(metroUrl)}`;
+}
+function expoBundlePrewarmCalls(port, platform) {
+  const params = new URLSearchParams({
+    platform,
+    dev: "true",
+    hot: "false",
+    lazy: "true",
+    "transform.engine": "hermes",
+    "transform.bytecode": "1",
+    "transform.routerRoot": "app",
+    unstable_transformProfile: "hermes-stable"
+  });
+  return [
+    {
+      file: "curl",
+      args: [
+        "-fsS",
+        "-o",
+        "/dev/null",
+        "--max-time",
+        "60",
+        `http://localhost:${port}/index.bundle?${params}`
+      ]
+    }
+  ];
+}
+function scalar(value, label) {
+  if (value == null) return void 0;
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    const text = String(value);
+    return text.length > 0 ? text : void 0;
+  }
+  throw new Error(`${label} must be a string, number, or boolean.`);
+}
+export {
+  resolveMetaMaskMobileLifecycleTarget
+};

package/dist/cli-commands.js

@@ -13,7 +13,7 @@ const SPEC = {
     { name: "sync", desc: "Refresh harness + canonicalize wallet fixture", flags: ["--json"] },
     { name: "logs", aliases: ["tail"], desc: "Compact build events or full log", flags: ["--full", "-f", "--window", "--events", "--source", "--json"] },
     { name: "debug", aliases: ["devtools", "inspect"], desc: "Open DevTools UI", flags: ["--json", "--no-open"] },
-    { name: "fixtures", desc: "Manage the canonical wallet fixture (sync/set/generate)", args: ["sync", "set", "generate"], flags: ["--fixture", "--out", "--adapter", "--target", "--json"] },
+    { name: "fixtures", desc: "Manage the canonical wallet fixture (sync/set/generate)", args: ["sync", "set", "generate"], flags: ["--fixture", "--out", "--adapter", "--target", "--device", "--json"] },
     { name: "actions", desc: "List runnable recipe actions", flags: ["--json"] },
     { name: "doctor", desc: "Check harness/orchestration health", flags: ["--json", "--target", "--adapter", "--runtime-dir", "--expect-live", "--cdp-port", "--device"] },
     { name: "run", desc: "Execute a proof recipe (path or library name, e.g. run smoke)", args: ["recipe.json|name"], flags: ["--list", "--device"] },

package/dist/commands/device-target.js

@@ -1,16 +1,37 @@
+import { execFileSync } from "node:child_process";
 import { listConnectedDevices } from "../devices.js";
 import { optionString } from "./parse-args.js";
-function setAndroidDeviceEnv(id) {
+function normalizeDeviceName(value) {
+  return value.replace(/_/gu, " ").trim();
+}
+function resolveAndroidModel(serial) {
+  try {
+    const output = execFileSync("adb", ["-s", serial, "shell", "getprop", "ro.product.model"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5e3
+    }).trim();
+    return output || void 0;
+  } catch {
+    return void 0;
+  }
+}
+function setAndroidDeviceEnv(id, fallbackName) {
   process.env.ADB_SERIAL = id;
   process.env.ANDROID_SERIAL = id;
   process.env.ANDROID_DEVICE = id;
+  const model = resolveAndroidModel(id) ?? (fallbackName ? normalizeDeviceName(fallbackName) : void 0);
+  if (model) process.env.ANDROID_TARGET_DEVICE_NAME = model;
+  else delete process.env.ANDROID_TARGET_DEVICE_NAME;
   process.env.IOS_SIMULATOR = "";
 }
-function setIosDeviceEnv(id) {
-  process.env.IOS_SIMULATOR = id;
+function setIosDeviceEnv(id, fallbackName) {
+  process.env.IOS_SIMULATOR = fallbackName ? normalizeDeviceName(fallbackName) : id;
+  process.env.SIM_UDID = id;
   process.env.ADB_SERIAL = "";
   process.env.ANDROID_SERIAL = "";
   process.env.ANDROID_DEVICE = "";
+  process.env.ANDROID_TARGET_DEVICE_NAME = "";
 }
 function formatConnectedDevices(devices) {
   return devices.map((d) => `    - ${d.id}${d.name ? ` (${d.name})` : ""} [${d.state}] ${d.platform}`).join("\n");
@@ -30,7 +51,7 @@ function deviceSelected(device) {
   if (device.platform === "android") {
     return process.env.ADB_SERIAL === device.id || process.env.ANDROID_SERIAL === device.id;
   }
-  return process.env.IOS_SIMULATOR === device.id;
+  return process.env.IOS_SIMULATOR === device.id || process.env.SIM_UDID === device.id || process.env.IOS_SIMULATOR === device.name;
 }
 function isTargetable(device) {
   if (device.platform === "android") return device.state === "device";
@@ -54,19 +75,24 @@ function applyDeviceTargeting(command, adapter, options, opts) {
     const connected2 = listConnectedDevices();
     const androidById = connected2.find((d) => d.platform === "android" && d.id === device);
     if (androidById) {
-      setAndroidDeviceEnv(device);
+      setAndroidDeviceEnv(device, androidById.name);
       return { ok: true };
     }
     const iosById = connected2.find((d) => d.platform === "ios" && d.id === device);
     if (iosById) {
-      setIosDeviceEnv(device);
+      setIosDeviceEnv(device, iosById.name);
       return { ok: true };
     }
-    const byName = connected2.filter((d) => d.name === device);
+    const normalizedDevice = normalizeDeviceName(device);
+    const byName = connected2.filter((d) => {
+      const name = d.name ?? "";
+      const normalizedName = normalizeDeviceName(name);
+      return name === device || normalizedName === normalizedDevice || d.platform === "android" && normalizedDevice.startsWith(`${normalizedName} -`);
+    });
     if (byName.length === 1) {
       const matched = byName[0];
-      if (matched.platform === "android") setAndroidDeviceEnv(matched.id);
-      else setIosDeviceEnv(matched.id);
+      if (matched.platform === "android") setAndroidDeviceEnv(matched.id, matched.name);
+      else setIosDeviceEnv(matched.id, matched.name);
       return { ok: true };
     }
     if (byName.length > 1) {

package/dist/commands/fixtures.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { runnerDir, walletFixturePath } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
+import { applyDeviceTargeting } from "./device-target.js";
 import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, scriptOverride, spawnScript, spawnScriptStreaming, str, targetOf, usageOut } from "./shared.js";
 const FIXTURES_BOOLEANS = /* @__PURE__ */ new Set(["json"]);
 const RECOVERABLE_SETUP_WALLET_PATTERNS = [
@@ -19,6 +20,13 @@ const RECOVERABLE_SETUP_WALLET_PATTERNS = [
 function isRecoverableSetupWalletFailure(output) {
   return RECOVERABLE_SETUP_WALLET_PATTERNS.some((p) => output.includes(p));
 }
+function resolveMobileFixturePlatform(options) {
+  const explicit = str(options, "platform") ?? process.env["MOBILE_PLATFORM"];
+  if (explicit === "android" || explicit === "ios") return explicit;
+  if (process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || process.env.ANDROID_DEVICE) return "android";
+  if (process.env.IOS_SIMULATOR) return "ios";
+  return "ios";
+}
 async function handleFixtures(argv, deps) {
   const { positional, options } = parseFlags(argv, FIXTURES_BOOLEANS);
   const json = flag(options, "json");
@@ -31,6 +39,10 @@ async function handleFixtures(argv, deps) {
   if (!adapter) {
     return usageOut(json, "fixtures", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   }
+  const dtResult = applyDeviceTargeting("fixtures", adapter, options, { gate: false, rerun: "" });
+  if ("code" in dtResult) {
+    return usageOut(json, "fixtures", dtResult.message, "mm-harness fixtures set --adapter mobile --device <adb-serial|simulator-udid>");
+  }
   if (sub === "generate") return fixturesGenerate(adapter, target, options, json);
   if (sub === "finalize") return fixturesFinalize(adapter, target, options, json);
   const surface = getAdapterSurface(adapter);
@@ -64,7 +76,7 @@ async function handleFixtures(argv, deps) {
         process.env["RECIPE_SETUP_WALLET_RETRIED"] = "1";
         if (!json) process.stderr.write("  setup-wallet: recoverable failure \u2014 restarting Metro and retrying\n  Next: wait for relaunch, then wallet setup will retry automatically\n");
         const { prepareMobile } = await import("../adapters/mobile/prepare.js");
-        const platform = str(options, "platform") ?? process.env["MOBILE_PLATFORM"] ?? "ios";
+        const platform = resolveMobileFixturePlatform(options);
         const relaunchResult = await prepareMobile(target, { platform, json, preflightMode: "auto", clearMetro: true });
         if (relaunchResult.status === 0) {
           result = await spawnScriptStreaming(setupWalletSh, ["--fixture", fixturePath], target);