@deeeed/metamask-harness 0.17.4 → 0.18.0

package/README.md

@@ -1,22 +1,15 @@
 # mm-harness
 
-`mm-harness` gives people and agents one CLI for operating MetaMask Mobile,
-Extension, and Core. Run it inside a checkout; the product is auto-detected.
+One CLI for operating MetaMask Extension, Mobile, and Core and producing
+reviewable recipe evidence. Run it inside a checkout; the product, slot, ports,
+and runtime paths are detected automatically.
 
-It has two jobs:
+- **Action:** one typed operation.
+- **Flow:** a reusable, parameterized sequence of actions.
+- **Recipe:** the complete proof for a task or regression.
 
-- operate the app with the same controls a developer needs: launch, logs, debug,
-  fixtures, actions, and reusable flows;
-- execute deterministic recipes and save reviewable proof.
-
-The generic graph engine lives in `@farmslot/recipe-harness`. This package owns
-only MetaMask-specific actions and runtime control.
-
-One mental model:
-
-- **Action** — one typed operation, such as reading wallet state.
-- **Flow** — a reusable, parameterized sequence of actions.
-- **Recipe** — the complete executable proof for a task or regression.
+The generic graph engine and evidence schemas live in Farmslot packages.
+`mm-harness` owns MetaMask runtime control and domain capabilities.
 
 ## Install
 
@@ -26,112 +19,113 @@ mm-harness --version
 mm-harness doctor
 ```
 
-Use `mm-harness update` to install the latest published version.
+`doctor` is read-only. `doctor --fix` repairs harness-owned runtime state but
+does not launch an app, invent credentials, or choose a wallet fixture.
+
+```bash
+mm-harness doctor --fix
+mm-harness fixtures init --from /secure/path/wallet-fixture.json
+# Disposable public testing only; never fund this wallet:
+mm-harness fixtures init --dev
+```
 
-## Daily workflow
+Use `mm-harness update` to update a published installation.
 
-From a MetaMask checkout:
+## Operate
 
 ```bash
 # Extension
-mm-harness launch              # starts/reuses Chrome and the incremental watcher
-mm-harness launch --sidepanel  # open the sidepanel surface
+mm-harness launch
+mm-harness launch --sidepanel
 
 # Mobile
 mm-harness launch ios
 mm-harness launch android
 
-# Any product
+# Any checkout
 mm-harness status
+mm-harness stop
 mm-harness logs
 mm-harness debug
 mm-harness fixtures set
 ```
 
-`launch` installs the checkout-local runtime overlay when needed. On Extension,
-the normal launch keeps `yarn start` running after the command exits. Source
-edits compile incrementally into the isolated runtime; refresh the active page or
-sidepanel to see them. Use `launch --build` only when a clean rebuild is needed.
+Extension `launch` keeps its incremental watcher running. Refresh the active
+page after a successful rebuild; use `launch --build` only for a clean rebuild.
 
-`debug` opens DevTools for the active Extension target in that checkout's Chrome
-profile. Mobile opens the React Native developer surface.
-
-Filter logs when needed:
+Log sources stay separate:
 
 ```bash
-mm-harness logs --source extension  # Extension console
-mm-harness logs --source dapp       # active dapp console
-mm-harness logs --source webpack    # Extension compiler
-mm-harness logs --source app        # Mobile app events
+mm-harness logs --source extension  # Extension page
+mm-harness logs --source dapp       # active dapp
+mm-harness logs --source webpack    # compiler
+mm-harness logs --source watcher    # watcher lifecycle
+mm-harness logs --source rebuild    # incremental rebuilds
+mm-harness logs --source app        # Mobile app
 mm-harness logs --source metro      # Mobile bundler
 ```
 
-## Build and run proof
+## Discover and prove
 
 ```bash
 mm-harness actions positions
 mm-harness actions --action metamask.wallet.ensure_unlocked
 mm-harness call metamask.wallet.ensure_unlocked
 mm-harness flows
+mm-harness flows describe perps.clean_market_testnet
 
+mm-harness run --list
+mm-harness run wallet.smoke --describe
 mm-harness run path/to/recipe.json --plan
-mm-harness run path/to/recipe.json --artifacts-dir temp/recipe-proof
-mm-harness run wallet.smoke --artifacts-dir temp/wallet-proof
+mm-harness run path/to/recipe.json
 ```
 
-`call` exercises one action. A recipe composes actions and flows into a
-deterministic proof.
-
-A run prints its findings, diagnostics, and absolute evidence paths. The artifact
-directory contains the executed recipe, summary, trace, diagnostics when
-applicable, screenshots/logs, and `artifact-manifest.json`. Core is headless, so
-browser/device diagnostics do not apply.
+`run` selects a checkout-local artifact directory unless
+`--artifacts-dir <dir>` overrides it. Human output prints diagnostics and
+absolute paths to the report, trace, executed recipe, and artifact manifest.
+Use `mm-harness last --json` to resume without repeating the last operation.
 
-Use `mm-harness last --json` to resume after interruption without repeating a
-side-effecting command.
+For automation, `--json` emits one stable document. `run --json-stream` emits
+line-buffered JSONL progress and a terminal event.
 
-## Team recipe libraries
-
-Add a named shared directory with `RECIPE_LIBRARY_PATH`:
+## Team libraries
 
 ```bash
 export RECIPE_LIBRARY_PATH="team=$HOME/shared-library/team-recipes"
 mm-harness flows
+mm-harness run --list
 ```
 
-Team flows can wrap repeated product behavior while each checklist or task keeps
-its own acceptance criteria. See [recipe libraries](docs/recipe-libraries.md).
+Shared libraries hold durable actions, flows, and recipes. Task acceptance
+criteria remain task-local. See [Recipes](docs/RECIPES.md).
 
-## Health and recovery
+## Recover
 
 ```bash
-mm-harness doctor        # inspect; does not launch
-mm-harness doctor --fix  # repair local harness setup; does not launch
-mm-harness verify        # verify the installed runtime overlay
-mm-harness cleanup       # remove the runtime overlay
+mm-harness doctor
+mm-harness doctor --fix
+mm-harness verify
+mm-harness cleanup
 ```
 
-Human output gives a next command. `--json` gives stable machine-readable errors
-and keeps stdout free of decoration. `--json-stream` emits line-delimited progress
-for long recipe runs.
+Failures name one exact next action. Core is headless; browser, device, logs,
+and debugger capabilities are reported as unavailable instead of fabricated.
+Stable exit codes are `1` runtime/action failure, `2` invalid CLI usage, `3`
+infrastructure failure, `4` bounded recovery refusal, and `5` validation/trust
+failure.
 
-## Development
+## Reference
 
-Use a source checkout without replacing the global install:
+- [Recipes](docs/RECIPES.md) — discover, compose, author, and share proof.
+- [Security](docs/SECURITY.md) — trust, approval, fixtures, and evidence safety.
+- [QA](docs/QA.md) — clean-machine and human release checks.
+- [Contributing](docs/CONTRIBUTING.md) — ownership, layout, and change gates.
+
+For development, point the installed command at a source checkout:
 
 ```bash
 export MM_HARNESS_BIN=/path/to/metamask-harness/bin/mm-harness
 mm-harness --version
 ```
 
-Unset `MM_HARNESS_BIN` to return to the published install.
-
-Validate changes with:
-
-```bash
-yarn check
-```
-
-Current references: [cheatsheet](docs/CHEATSHEET.md), [recipe libraries](docs/recipe-libraries.md),
-and [human QA](docs/CLI-ERGONOMICS-HUMAN-QA.md). Maintainers also have the
-[architecture](docs/architecture.md) and [video gate](docs/VIDEO-DEMO-VALIDATION.md).
+Unset `MM_HARNESS_BIN` to return to the published installation.

package/adapters/extension/ensure-browser.sh

@@ -277,6 +277,8 @@ const fs = require('fs');
 const http = require('http');
 const { execSync, execFileSync } = require('child_process');
 let chromium; try { chromium = require('@playwright/test').chromium; } catch { chromium = require('playwright').chromium; }
+const { isolatedProfileArgs, remoteDebuggingArgs } = require(path.join('${SCRIPT_DIR}', 'lib/chrome-args.cjs'));
+const { captureMacFrontmostProcess, restoreMacFrontmostProcess } = require(path.join('${SCRIPT_DIR}', 'lib/macos-focus.cjs'));
 
 const SLOT_ID = '${SLOT_ID}';
 const AGENT_DIR = '${AGENT_DIR}';
@@ -307,11 +309,18 @@ const resumeWebpack = () => {
     '--disable-renderer-backgrounding',
     '--no-first-run',
     '--no-default-browser-check',
+    ...isolatedProfileArgs(),
     '--window-size=420,800',
   ];
-  if (CDP_PORT) args.push('--remote-debugging-port=' + CDP_PORT);
+  // Debug-port trio (address + port + scoped allow-origins) from the shared module
+  // so the DevTools origin allow-list can never drift away from the port; without
+  // it Chrome 403s every browser DevTools WebSocket and mm-harness debug can't attach.
+  if (CDP_PORT) {
+    args.push(...remoteDebuggingArgs(CDP_PORT));
+  }
 
   const chromiumApp = path.dirname(path.dirname(path.dirname(chromium.executablePath())));
+  const previousFrontmostPid = captureMacFrontmostProcess();
   execFileSync('open', ['-g', '-n', '-a', chromiumApp, '--args', ...args], { stdio: 'ignore' });
   for (let i = 0; i < 60; i++) {
     try {
@@ -414,6 +423,8 @@ const resumeWebpack = () => {
   }
   if (process.env.MM_HARNESS_FOCUS_BROWSER === '1') {
     await page.bringToFront().catch(() => {});
+  } else {
+    restoreMacFrontmostProcess(previousFrontmostPid);
   }
 
   fs.writeFileSync(path.join(AGENT_DIR, 'extension.id'), extId);

package/adapters/extension/inject.mjs

@@ -24,6 +24,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import process from 'node:process';
 import { recipeHarnessRoot } from '../shared/recipe-harness-root.mjs';
+import { harnessSourceFingerprint } from '../shared/harness-source-fingerprint.mjs';
 
 function usage() {
   console.error('Usage: inject-extension-harness.mjs [--target <metamask-extension>] [--no-git-exclude]');
@@ -127,6 +128,8 @@ copyFile(path.join(runnerDir, 'adapters/shared/tmux-viewer.sh'), path.join(harne
 copyFile(path.join(runnerDir, 'adapters/shared/log-tui.mjs'), path.join(harnessDir, 'scripts/lib/log-tui.mjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/lib/extension-id.cjs'), path.join(harnessDir, 'scripts/lib/extension-id.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/lib/slot-title.cjs'), path.join(harnessDir, 'scripts/lib/slot-title.cjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/lib/chrome-args.cjs'), path.join(harnessDir, 'scripts/lib/chrome-args.cjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/lib/macos-focus.cjs'), path.join(harnessDir, 'scripts/lib/macos-focus.cjs'));
 makeExecutableTree(path.join(harnessDir, 'scripts'));
 fs.writeFileSync(path.join(harnessDir, 'installed-scripts.sha256'), `${dirContentHash(path.join(harnessDir, 'scripts'))}\n`);
 
@@ -136,6 +139,10 @@ const manifest = {
   adapter: 'extension',
   installedAt: new Date().toISOString(),
   runnerPackageVersion,
+  // Fingerprint of the runner source that produced this overlay. The launch-time
+  // freshness guard re-injects when the runner's fingerprint no longer matches,
+  // so a slot never silently runs a stale injected launcher.
+  sourceFingerprint: harnessSourceFingerprint(runnerDir),
   source: {
     runnerDir,
     runnerRevision,

package/adapters/extension/launch-browser.cjs

@@ -24,6 +24,8 @@ const os = require('node:os');
 const path = require('node:path');
 const { execFileSync, spawn, spawnSync } = require('node:child_process');
 const { extensionIdFromExtensionDir } = require('./lib/extension-id.cjs');
+const { isolatedProfileArgs, remoteDebuggingArgs } = require('./lib/chrome-args.cjs');
+const { captureMacFrontmostProcess, restoreMacFrontmostProcess } = require('./lib/macos-focus.cjs');
 
 if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log(
@@ -92,10 +94,12 @@ if (args['stop-only'] !== undefined) {
 const initialUrl = args['start-url'] || extensionHomeUrl(args['extension-dir']) || 'chrome://extensions/';
 const chromeArgs = [
   `--user-data-dir=${args.profile}`,
-  '--remote-debugging-address=127.0.0.1',
-  `--remote-debugging-port=${cdpPort}`,
+  // Debug-port trio (address + port + scoped allow-origins) from the shared module,
+  // so the DevTools origin allow-list can never drift away from the port.
+  ...remoteDebuggingArgs(cdpPort),
   '--no-first-run',
   '--disable-first-run-ui',
+  ...isolatedProfileArgs(),
   '--disable-default-apps',
   '--disable-popup-blocking',
   '--disable-extensions-file-access-check',
@@ -109,11 +113,11 @@ const chromeArgs = [
   initialUrl,
 ];
 const logFd = fs.openSync(args['chrome-log'], 'a');
+const previousFrontmostPid = captureMacFrontmostProcess();
 let browserPid;
 try {
   const application = process.platform === 'darwin' ? macApplicationForExecutable(args['chrome-bin']) : null;
   if (application) {
-    // Launch Services does not attach Chrome's stdio, so chrome.log may stay empty; CDP ownership is the readiness signal.
     execFileSync('open', ['-g', '-n', '-a', application, '--args', ...chromeArgs], {
       env: sanitizedChildEnv(),
       stdio: ['ignore', logFd, logFd],
@@ -135,6 +139,9 @@ try {
   fs.closeSync(logFd);
 }
 fs.writeFileSync(args['chrome-pid'], `${browserPid}\n`);
+if (process.env.MM_HARNESS_FOCUS_BROWSER !== '1') {
+  restoreMacFrontmostProcess(previousFrontmostPid);
+}
 
 function sanitizedChildEnv() {
   return {

package/adapters/extension/lib/chrome-args.cjs

@@ -0,0 +1,31 @@
+'use strict';
+// chrome-args.cjs — single source of truth for the remote-debugging launch flags
+// shared by BOTH extension launchers: the fresh spawn (launch-browser.cjs) and the
+// reopen path (ensure-browser.sh → reopen-browser.sh). Keeping the debug-port trio
+// here means `--remote-allow-origins` can never drift away from the port it scopes:
+// the two are declared once and always travel together. Without the allow-origins
+// entry Chrome 403s every browser DevTools WebSocket on the debug port and
+// `mm-harness debug` cannot attach a visible console.
+
+// The exact origin allowed is the locally-served bundled DevTools frontend, which
+// Chrome serves at http://127.0.0.1:<cdpPort>. Scoped to that origin — never `*`.
+function remoteDebuggingArgs(cdpPort) {
+  const port = Number(cdpPort);
+  if (!Number.isInteger(port) || port <= 0) {
+    throw new Error(`remoteDebuggingArgs: invalid cdp port: ${cdpPort}`);
+  }
+  return [
+    '--remote-debugging-address=127.0.0.1',
+    `--remote-debugging-port=${port}`,
+    `--remote-allow-origins=http://127.0.0.1:${port}`,
+  ];
+}
+
+// An isolated automation profile must never ask for or write credentials in the
+// operator's macOS login keychain. Chromium's mock keychain keeps profile-local
+// encryption deterministic and prevents modal prompts from blocking startup.
+function isolatedProfileArgs(platform = process.platform) {
+  return platform === 'darwin' ? ['--use-mock-keychain'] : [];
+}
+
+module.exports = { isolatedProfileArgs, remoteDebuggingArgs };

package/adapters/extension/lib/macos-focus.cjs

@@ -0,0 +1,32 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+
+function captureMacFrontmostProcess() {
+  if (process.platform !== 'darwin') return null;
+  try {
+    const value = execFileSync('osascript', [
+      '-e',
+      'tell application "System Events" to get unix id of first application process whose frontmost is true',
+    ], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    const pid = Number.parseInt(value, 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function restoreMacFrontmostProcess(pid) {
+  if (process.platform !== 'darwin' || !Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    execFileSync('osascript', [
+      '-e',
+      `tell application "System Events" to set frontmost of first application process whose unix id is ${pid} to true`,
+    ], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { captureMacFrontmostProcess, restoreMacFrontmostProcess };

package/adapters/extension/live.sh

@@ -32,6 +32,7 @@
 set -euo pipefail
 
 TARGET="$PWD"
+INVOCATION_DIR="$PWD"
 CDP_PORT=""
 ARTIFACTS=""
 OUT=""
@@ -39,7 +40,7 @@ PREPARE_CMD="${RECIPE_HARNESS_EXTENSION_LAUNCH_CMD:-}"
 LAUNCH_EXISTING_DIST=false
 START_WATCH=false
 DIST_DIR="dist/chrome"
-CHROME_USER_DATA_DIR=""
+CHROME_USER_DATA_DIR="${CHROME_USER_DATA_DIR:-}"
 REMOTE_FLAGS=""
 REMOTE_FLAGS_APPLIED=false
 while [ "$#" -gt 0 ]; do
@@ -60,6 +61,11 @@ while [ "$#" -gt 0 ]; do
   esac
 done
 
+case "$CHROME_USER_DATA_DIR" in
+  ""|/*) ;;
+  *) CHROME_USER_DATA_DIR="$INVOCATION_DIR/$CHROME_USER_DATA_DIR" ;;
+esac
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
 for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../shared/harness-path.sh"; do
@@ -211,11 +217,11 @@ try {
   executable = chromium.executablePath();
 } catch (error) {
   const message = error && error.message ? error.message : String(error);
-  console.error(`[recipe-harness] Could not resolve Playwright Chromium executable: ${message}. Manual approval required before installing the Playwright Chromium browser cache (no package.json changes); ask the user before running yarn exec playwright install chromium.`);
+  console.error(`[recipe-harness] Could not resolve Playwright Chromium executable: ${message}. Manual approval required before installing the Playwright Chromium browser cache (no package.json changes); ask the user before running yarn playwright install chromium.`);
   process.exit(1);
 }
 if (!fs.existsSync(executable)) {
-  console.error(`[recipe-harness] Playwright Chromium is not installed at ${executable}. Manual approval required before installing the Playwright Chromium browser cache (no package.json changes). Ask the user for approval; if they agree, run: cd ${shellQuote(process.cwd())} && yarn exec playwright install chromium`);
+  console.error(`[recipe-harness] Playwright Chromium is not installed at ${executable}. Manual approval required before installing the Playwright Chromium browser cache (no package.json changes). Ask the user for approval; if they agree, run: cd ${shellQuote(process.cwd())} && yarn playwright install chromium`);
   console.error('[recipe-harness] To use a browser that is already installed, set RECIPE_HARNESS_CHROME_BIN=/path/to/chrome explicitly.');
   process.exit(1);
 }
@@ -227,25 +233,9 @@ NODE
     rm -f "$_chrome_probe"
   fi
 
-  if [ -z "${CHROME_BIN:-}" ]; then
-    for candidate in \
-      "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
-      "/Applications/Chromium.app/Contents/MacOS/Chromium" \
-      "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary" \
-      "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"; do
-      if [ -x "$candidate" ]; then
-        CHROME_BIN="$candidate"
-        break
-      fi
-    done
-    if [ -n "${CHROME_BIN:-}" ]; then
-      echo "[recipe-harness] WARN: Playwright Chromium unavailable; falling back to system browser: $CHROME_BIN" >&2
-    fi
-  fi
-
   if [ -z "${CHROME_BIN:-}" ]; then
     [ -n "${CHROME_PROBE_LOG:-}" ] && cat "$CHROME_PROBE_LOG" >&2 2>/dev/null || true
-    echo "[recipe-harness] No approved Chromium binary selected; stopping before live Extension launch." >&2
+    echo "[recipe-harness] No compatible Chromium binary selected; stopping before build or live Extension launch." >&2
     exit 1
   fi
   quoted_chrome="$(printf '%q' "$CHROME_BIN")"

package/adapters/manifest.json

@@ -487,6 +487,14 @@
       "inputs": "--adapter extension|mobile [--cdp-port|--port] [--target page|worker] [--json] [--no-open]",
       "outputs": "debug URL/report on stdout; exit 0/1"
     },
+    {
+      "id": "lib/harness-source-fingerprint",
+      "entry": "adapters/shared/harness-source-fingerprint.mjs",
+      "kind": "lib",
+      "purpose": "Compute the deterministic source fingerprint stamped into injected extension harness manifests.",
+      "inputs": "imported by injection and launch freshness checks",
+      "outputs": "stable SHA-256 fingerprint"
+    },
     {
       "id": "lib/update-check-worker",
       "entry": "adapters/shared/update-check-worker.mjs",

package/adapters/mobile/open-device.sh

@@ -13,6 +13,7 @@
 #   --simulator <udid|name|"booted">    iOS simulator (default: IOS_SIMULATOR env, else "booted")
 #   --adb-serial <serial>               Android device serial (default: ADB_SERIAL env)
 #   --preflight-mode fast|auto|rebuild-native|clean  (default: fast; env MOBILE_PREFLIGHT_MODE)
+#   --ui-only                           iOS only: ensure Simulator.app is visible; do not relaunch the app
 # Outputs:
 #   Progress on stderr; exit 0 pass; 1 open failed; 2 bad args.
 #
@@ -25,6 +26,7 @@ SIMULATOR="${IOS_SIMULATOR:-${SIM_UDID:-booted}}"
 ADB_SERIAL_ARG="${ADB_SERIAL:-${ANDROID_SERIAL:-}}"
 PREFLIGHT_MODE="${MOBILE_PREFLIGHT_MODE:-fast}"
 PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
+UI_ONLY=false
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
@@ -34,10 +36,11 @@ while [ "$#" -gt 0 ]; do
     --adb-serial)     ADB_SERIAL_ARG="$2"; shift 2 ;;
     --preflight-mode) PREFLIGHT_MODE="$2"; shift 2 ;;
     --port)           PORT="$2"; shift 2 ;;
+    --ui-only)        UI_ONLY=true; shift ;;
     -h|--help)
       printf 'Usage: open-device.sh [--platform ios|android] [--target <dir>]\n'
       printf '  [--simulator <udid|name|booted>] [--adb-serial <serial>]\n'
-      printf '  [--preflight-mode fast|auto|rebuild-native|clean] [--port <n>]\n'
+      printf '  [--preflight-mode fast|auto|rebuild-native|clean] [--port <n>] [--ui-only]\n'
       exit 0
       ;;
     *) printf 'open-device: unknown arg: %s\n' "$1" >&2; exit 2 ;;
@@ -48,6 +51,10 @@ case "$PLATFORM" in
   ios|android) ;;
   *) printf 'open-device: --platform must be ios or android (got: %s)\n' "$PLATFORM" >&2; exit 2 ;;
 esac
+if $UI_ONLY && [ "$PLATFORM" != "ios" ]; then
+  printf 'open-device: --ui-only is supported only for ios.\n' >&2
+  exit 2
+fi
 
 TARGET="$(cd "$TARGET" && pwd)"
 
@@ -149,19 +156,46 @@ boot_simulator_if_needed() {
   xcrun simctl bootstatus "$udid" -b >/dev/null
 }
 
-show_simulator() {
+simulator_ui_running() {
+  pgrep -x Simulator >/dev/null 2>&1
+}
+
+open_simulator_in_background_if_needed() {
   local target="$1" udid=""
+  [ "${MM_HARNESS_SHOW_SIMULATOR:-1}" != "0" ] || return 0
+  simulator_ui_running && return 0
+  printf 'Opening Simulator UI in the background\n' >&2
   if [ "$target" = "booted" ]; then
-    printf 'Opening Simulator UI\n' >&2
-    open -a Simulator >/dev/null 2>&1 || true
+    open -g -a Simulator >/dev/null 2>&1 || {
+      printf 'open-device: failed to open Simulator UI.\n' >&2
+      return 1
+    }
   else
     udid="$(sim_udid_for_target "$target")"
     if [ -n "$udid" ]; then
-      open -a Simulator --args -CurrentDeviceUDID "$udid" >/dev/null 2>&1 || true
+      open -g -a Simulator --args -CurrentDeviceUDID "$udid" >/dev/null 2>&1 || {
+        printf 'open-device: failed to open Simulator UI for %s.\n' "$target" >&2
+        return 1
+      }
     else
-      open -a Simulator >/dev/null 2>&1 || true
+      open -g -a Simulator >/dev/null 2>&1 || {
+        printf 'open-device: failed to open Simulator UI.\n' >&2
+        return 1
+      }
     fi
   fi
+}
+
+focus_simulator() {
+  local target="$1" udid=""
+  if [ "$target" != "booted" ]; then
+    udid="$(sim_udid_for_target "$target")"
+  fi
+  if [ -n "$udid" ]; then
+    open -a Simulator --args -CurrentDeviceUDID "$udid" >/dev/null 2>&1 || true
+  else
+    open -a Simulator >/dev/null 2>&1 || true
+  fi
   osascript -e 'tell application "Simulator" to activate' >/dev/null 2>&1 || true
 }
 
@@ -220,8 +254,12 @@ if [ "$PLATFORM" = "ios" ]; then
   DEV_CLIENT_SCHEME="${IOS_DEV_CLIENT_SCHEME:-expo-metamask}"
 
   boot_simulator_if_needed "$SIM_TARGET" || exit 1
+  open_simulator_in_background_if_needed "$SIM_TARGET" || exit 1
   if [ "${MM_HARNESS_FOCUS_SIMULATOR:-0}" = "1" ]; then
-    show_simulator "$SIM_TARGET"
+    focus_simulator "$SIM_TARGET"
+  fi
+  if $UI_ONLY; then
+    exit 0
   fi
 
   LAUNCHED=false

package/adapters/mobile/verify.sh

@@ -329,9 +329,21 @@ JSON
 
 ensure_live_runtime() {
   local device_target="$1"
-  if live_status_ok "$ARTIFACTS/logs/app-status-precheck.log" "$device_target"; then
-    return 0
-  fi
+  local attempt
+  for attempt in 1 2 3 4 5; do
+    if live_status_ok "$ARTIFACTS/logs/app-status-precheck.log" "$device_target"; then
+      return 0
+    fi
+    # A freshly booted simulator can expose its Metro bridge just before
+    # `simctl list devices booted` publishes the device. Bound that launch→verify
+    # race instead of reporting a false DEVICE_NOT_FOUND immediately.
+    if [ "$attempt" -lt 5 ] && grep -q '"code"[[:space:]]*:[[:space:]]*"DEVICE_NOT_FOUND"' "$ARTIFACTS/logs/app-status-precheck.log"; then
+      echo "Waiting for Mobile device discovery (${attempt}/5): ${device_target:-configured target}" >&2
+      sleep 1
+      continue
+    fi
+    break
+  done
   if [ "$AUTO_START" = true ]; then
     cat >&2 <<'EOF'
 Mobile auto-start is not allowed from product-local scripts. Start or prepare the app through the runner/slot runtime, then rerun verify with --no-auto-start.

package/adapters/shared/harness-source-fingerprint.mjs

@@ -0,0 +1,49 @@
+// harness-source-fingerprint.mjs — deterministic fingerprint of the runner files
+// that get injected into a slot's harness overlay.
+//
+// inject.mjs stamps this into the slot manifest at install time; the launch-time
+// freshness guard recomputes it and re-injects when they differ, so a slot can
+// never silently run a stale injected launcher after the runner changes. This is
+// what makes the runner the single source of truth: edit a runner adapter file and
+// the next launch refreshes every slot from it.
+//
+// stat-only (size + mtime) so it is cheap enough to run on every launch; no file
+// contents are read and no Date.now()/random is used (both would break determinism).
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+// Trees whose contents are copied into <slot>/harness by inject.mjs. Any change
+// here means injected slots are stale.
+const SOURCE_DIRS = ['adapters/extension', 'adapters/shared', 'library'];
+
+export function harnessSourceFingerprint(runnerDir) {
+  const entries = [];
+  for (const rel of SOURCE_DIRS) {
+    collect(path.join(runnerDir, rel), runnerDir, entries);
+  }
+  entries.sort();
+  return crypto.createHash('sha256').update(entries.join('\n')).digest('hex');
+}
+
+function collect(dir, root, out) {
+  let dirents;
+  try {
+    dirents = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return; // absent tree contributes nothing
+  }
+  for (const dirent of dirents) {
+    // Skip hidden noise (.DS_Store, editor swap files) so the fingerprint tracks
+    // only real source and does not thrash re-injects.
+    if (dirent.name.startsWith('.')) continue;
+    const full = path.join(dir, dirent.name);
+    if (dirent.isDirectory()) {
+      collect(full, root, out);
+      continue;
+    }
+    if (!dirent.isFile()) continue;
+    const stat = fs.statSync(full);
+    out.push(`${path.relative(root, full)}|${stat.size}|${Math.floor(stat.mtimeMs)}`);
+  }
+}

package/adapters/shared/install-repo-deps.sh

@@ -4,11 +4,7 @@ set -euo pipefail
 TARGET=""
 while [[ $# -gt 0 ]]; do
   case "$1" in
-    --target)
-      [[ $# -ge 2 ]] || { echo "Usage: install-repo-deps.sh --target <checkout>" >&2; exit 2; }
-      TARGET="$2"
-      shift 2
-      ;;
+    --target) TARGET="$2"; shift 2 ;;
     -h|--help)
       echo "Usage: install-repo-deps.sh --target <checkout>"
       exit 0