@deeeed/metamask-harness 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.11.0 - 2026-07-07
+
+### 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.
+
+### 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).
+
+### Fixed
+- `launch ios --device <udid|name>` again accepts a shutdown simulator target: launch preserves the requested simulator identity and lets `open-device.sh` boot it instead of requiring it to appear in the booted-device list first.
+- iOS UDID pins are exported as both `SIM_UDID` and simulator name where available, so downstream simulator tooling can use the stable name while preserving the exact pin.
+- `metamask.wallet.ensure_unlocked` now waits for the pinned agentic bridge target, tolerates transient status drops during the unlocked stability check, and avoids the old full password-unlock fallback for brief bridge gaps.
+- Automatic `app.hud` updates are best-effort only while the mobile bridge target is down during app lifecycle transitions; ordinary HUD bridge failures now fail loudly.
+- Mobile `cdp.target` required checks only pass when the responding target has `agenticPresent === true`, avoiding false positives from non-instrumented React Native targets.
+- Mobile Metro startup is hardened around tmux/PID ownership: stale PID files and dead tmux windows are cleaned before reuse, and Metro survives the launching shell.
+- `wait-for-bridge` now matches the selected Android target with the same boundary-safe device-name rules as device targeting and waits for the selected target, not just any target on the Metro port.
+
 ## 0.10.0 - 2026-07-07
 
 ### Added

package/adapters/mobile/start-metro.sh

@@ -77,6 +77,44 @@ default_metro_workers() {
 # shellcheck disable=SC1091
 . "$SCRIPT_DIR/lib/tmux-viewer.sh"
 
+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.
@@ -116,42 +154,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,6 +221,9 @@ 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
   printf '  Next: mm-harness logs  (tail Metro)\n' >&2
   exit 0

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/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,44 @@ 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)) {
+    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"
+  ].some((needle) => reason.includes(needle));
 }
 function animatedFlag(payload) {
   return payload.animated === true ? "--animated" : "--no-animated";

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

package/dist/commands/launch/index.js

@@ -25,6 +25,7 @@ import {
 } from "../../heal-bounds.js";
 import { extensionDepsBlock, extensionRuntimeReusable, launchExtension } from "./extension.js";
 import { launchMobile } from "./mobile.js";
+import { applyDeviceTargeting } from "../device-target.js";
 const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
   "build",
   "watch",
@@ -80,7 +81,10 @@ async function handleLaunch(argv) {
       );
     }
   }
-  applyLaunchEnvOverrides(options, adapter, mobileTarget, target);
+  const envResult = applyLaunchEnvOverrides(options, adapter, mobileTarget, target);
+  if (envResult && "code" in envResult) {
+    return usageOut(json, "launch", envResult.message, "mm-harness launch android --device <adb-serial|device-name>");
+  }
   if (adapter === "extension" && typeof options["url"] === "string" && options["url"]) {
     process.env.EXTENSION_START_URL = options["url"];
   }
@@ -168,12 +172,32 @@ function applyLaunchEnvOverrides(options, adapter, mobileTarget, target) {
   getAdapterSurface(adapter).resolveSlotPorts(target);
   const device = str(options, "device");
   if (device && adapter === "mobile") {
-    if (mobileTarget === "android") {
-      process.env.ADB_SERIAL = device;
-      process.env.ANDROID_SERIAL = device;
-      process.env.ANDROID_DEVICE = device;
-    } else {
-      process.env.IOS_SIMULATOR = device;
+    const result = applyDeviceTargeting("launch", adapter, options, { gate: false, rerun: "" });
+    if ("code" in result) {
+      if (mobileTarget === "ios" && result.code === "DEVICE_NOT_FOUND") {
+        process.env.IOS_SIMULATOR = device;
+        process.env.SIM_UDID = isIosSimulatorUdid(device) ? device : "";
+        process.env.ADB_SERIAL = "";
+        process.env.ANDROID_SERIAL = "";
+        process.env.ANDROID_DEVICE = "";
+        process.env.ANDROID_TARGET_DEVICE_NAME = "";
+      } else {
+        return result;
+      }
+    }
+    if (mobileTarget === "android" && !process.env.ADB_SERIAL && !process.env.ANDROID_SERIAL) {
+      return {
+        ok: false,
+        code: "DEVICE_WRONG_PLATFORM",
+        message: `--device ${device} did not resolve to an Android device for launch android.`
+      };
+    }
+    if (mobileTarget === "ios" && !process.env.IOS_SIMULATOR) {
+      return {
+        ok: false,
+        code: "DEVICE_WRONG_PLATFORM",
+        message: `--device ${device} did not resolve to an iOS simulator for launch ios.`
+      };
     }
   }
   const cdpPort = str(options, "cdpPort");
@@ -187,6 +211,10 @@ function applyLaunchEnvOverrides(options, adapter, mobileTarget, target) {
     process.env.RECIPE_WATCHER_PORT = watcherPort;
     process.env.METRO_PORT = watcherPort;
   }
+  return { ok: true };
+}
+function isIosSimulatorUdid(value) {
+  return /^[0-9A-Fa-f-]{36}$/u.test(value);
 }
 function nativeInputsChanged(target, adapter) {
   const baselineFile = recipeRuntimePath(target, ".last-build-ref");

package/dist/commands/run-engine.js

@@ -97,6 +97,7 @@ function recipeRunEnv(adapter, runtimeOptions = {}) {
     METRO_PORT: process.env.METRO_PORT ?? process.env.WATCHER_PORT ?? base.CDP_PORT ?? base.RECIPE_CDP_PORT,
     IOS_SIMULATOR: process.env.IOS_SIMULATOR,
     ANDROID_DEVICE: process.env.ANDROID_DEVICE,
+    ANDROID_TARGET_DEVICE_NAME: process.env.ANDROID_TARGET_DEVICE_NAME,
     ADB_SERIAL: process.env.ADB_SERIAL,
     ANDROID_SERIAL: process.env.ANDROID_SERIAL
   };

package/dist/mm-harness-cli.js

@@ -411,6 +411,7 @@ Example:
   --extension-id-file <path>         finalize: optional file to read/write the resolved extension id
   --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
+  --device <udid|serial|name>        Mobile only: target this device for sync/set
   --json                             Machine-readable output
 
 Example:

package/dist/paths.js

@@ -113,6 +113,12 @@ async function importRecipeHarnessRuntimeCdp() {
     "packages/recipe-harness/src/runtime/cdp.ts"
   );
 }
+async function importRecipeHarnessAppLifecycle() {
+  return importProtocolPackage(
+    "@farmslot/recipe-harness/adapters/app-lifecycle",
+    "packages/recipe-harness/src/adapters/app-lifecycle.ts"
+  );
+}
 async function importRecipeHarnessRuntimeBrowserExtension() {
   return importProtocolPackage(
     "@farmslot/recipe-harness/runtime/browser-extension",
@@ -154,7 +160,7 @@ async function importProtocolPackage(packageName, localSourceEntry) {
 function isMissingPackageError(error, packageName) {
   if (!(error instanceof Error)) return false;
   const code = error.code;
-  return code === "ERR_MODULE_NOT_FOUND" && error.message.includes(packageName);
+  return (code === "ERR_MODULE_NOT_FOUND" || code === "ERR_PACKAGE_PATH_NOT_EXPORTED") && error.message.includes(packageName);
 }
 export {
   DEFAULT_RECIPE_HARNESS_ROOT,
@@ -162,6 +168,7 @@ export {
   assertAdapter,
   extensionIdPath,
   importRecipeHarness,
+  importRecipeHarnessAppLifecycle,
   importRecipeHarnessCli,
   importRecipeHarnessRuntimeBrowserExtension,
   importRecipeHarnessRuntimeCdp,