@deeeed/metamask-harness 0.14.7 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## Unreleased
+
+## 0.15.0 - 2026-07-13
+
+### Changed
+
+- Extension `status` and `doctor` now report the webpack dev server as `up` only when a target-owned watcher is alive; historical successful build logs no longer imply liveness after `stop`.
+- Mobile overlay freshness no longer reports `pass` when every checkable runner overlay file is absent from the target; missing or drifted files are classified before the empty-overlay success case.
+- Mobile live verification now compares AgenticService/HUD freshness against the canonical `app/dev-tools/AgenticService` runner and product paths instead of skipping the check through the obsolete `app/core/AgenticService` layout.
+- `check diff` now rejects only newly added ESLint directive comments before running repository tools, without treating prose or string literals containing `eslint-disable` as suppressions; pre-existing suppressions remain untouched.
+- Mobile `run`/`call` now fingerprints bundle-affecting source and environment state against the last successful app reload; default infra healing performs one `app.lifecycle restart` before proof when the loaded source is missing or stale, while `--heal off` stops with the exact recovery command.
+- Mobile `metamask.perps.start_state` now restores the fixture-backed unlocked wallet before navigation, so required post-edit app restarts do not race a locked/initializing runtime.
+- Mobile `ui.wait_for` discovery now exposes its `test_id`, `expected`, text, and timeout schema plus an `expected=absent` example; shared recipe examples use the same supported `expected` field instead of the ignored `visibility` spelling.
+- Mobile fast-preflight dependency failures now present numbered standalone vs orchestrated recovery choices, so interactive agents can relay a portable one-character choice instead of inventing an option from an unnumbered `Next:` hint.
+- `checklist mark` now blocks a `mm-harness check diff` gate until that task's own `artifacts/validation-summary.json` records a real diff-check PASS, preventing stale or failed validation from being marked complete.
+- Changed-file ESLint now respects the repository's configured warning severity instead of failing unchanged warnings via `--max-warnings=0`; real failures tell agents at the harness boundary to use existing patterns/tokens rather than suppressing or hiding violations, weakening configuration, or bypassing `check diff`.
+- Mobile Perps `start_state` now enters the requested Perps route before reading orders or positions, initializing the provider client on a freshly launched wallet instead of timing out with `CLIENT_NOT_INITIALIZED`.
+
+- Updated the compatible Farmslot runtime set to protocol 0.8, recipe-harness 0.5, and agent-runtime 0.2, making passive `ui.screen`/`ui.visible` observation support available to adapters that declare those observers without a local Farmslot checkout.
+- Checklist terminal signals are monotonic through `mm-harness`: a late numeric or `start` mark can no longer regress a completed or blocked task back to `running`.
+- Core `check diff` now runs changed package tests through their owning Yarn workspaces instead of passing workspace paths to the root Jest configuration.
+
+- Mobile iOS launch no longer opens or activates Simulator.app during normal automation; set `MM_HARNESS_FOCUS_SIMULATOR=1` only when an operator explicitly wants the Simulator UI foregrounded.
+
+- Public Extension `stop` now tears down the checkout-owned watcher, Chrome/CDP profile processes, viewer tails/windows, and stale runtime PID/lock markers; explicit `--port` overrides only the watcher port and no longer hides the runtime-context CDP owner.
+- Tmux log viewers now require an explicit `RECIPE_TMUX_SESSION` or checkout `agentic-runtime.json` session; merely running from another tmux session never creates, sweeps, or marker-closes windows there, while stale markers are discarded and file logs remain available.
+- Extension `run`/`call --heal auto` now rebuild or reload before proof when source, `dist/chrome`, and the loaded runtime snapshot are out of sync; healing-off runs stop before execution with the exact `launch --build --verify` recovery command.
+- Extension launch, readiness, reattach, actions, and screenshots preserve the operator's keyboard focus by default while retaining a headed, isolated CDP browser; macOS app launch uses Launch Services in the background, and explicit window focus remains available with `MM_HARNESS_FOCUS_BROWSER=1`.
+- `mm-harness check diff --fix` now repairs only changed files with the checkout's direct ESLint and oxfmt/Prettier binaries, then runs the normal bounded validation, so agents do not need to guess repository lint scripts.
+- Recipe-run infra healing now performs the adapter's runtime recovery before retrying instead of only recording a recovery label and immediately rerunning the recipe.
+- Extension `doctor --fix` now enables the checkout-local Perps build flag when `.metamaskrc` has it disabled, so packaged Perps actions cannot launch against a build that omits their product surface.
+- Extension `ui.screenshot` now falls back from a failed capture-helper window snapshot to bounded Chrome-native capture, then to an explicitly labeled computed-style DOM raster when the headed Chrome screenshot domain is unavailable.
+- Mobile `ui.screenshot` now validates simctl/adb output as PNG evidence before registration and records the native provider, command mode, selected device, and MIME type in artifact provenance.
+- `checklist mark ... complete` now teaches the exact compact quality input, canonical builder command, and coverage artifact when a recipe activates those terminal requirements, instead of forcing agents to reverse-engineer the artifact validator.
+
+### Added
+- Checkout-scoped operation locking prevents concurrent launch, fixture mutation, and recipe execution in one repository while allowing other checkouts/slots to run independently; stale locks from exited processes are reclaimed.
+- `doctor --fix` creates an ignored, checkout-scoped `agentic-runtime.json` when absent, with stable claimed local ports for ordinary standalone clones while preserving explicit or Farmslot-provided slot resources.
+- `fixtures init --from <path>|--dev` initializes the canonical checkout wallet fixture explicitly; `--dev` is a disposable public test wallet and is never suitable for real funds.
+
+### Fixed
+- Missing checkout targets now return the structured usage envelope before lock acquisition in `run` and `doctor`; recovery bounds distinguish a consumed successful repair, adapter helpers preserve explicit runtime/device pins, checklist-only runtime resolution is lazy, and fixture finalization is time-bounded.
+- Checkout contention now uses one bounded JSON contract across `call`, `launch`, `doctor --fix`, `fixtures`, and `run`: exit 4 with `SANDBOX_BUSY` and an actionable lock path.
+- Extension loaded-snapshot checks now use size/mtime comparison instead of full checksums, fall back to an in-process comparison when `rsync` is unavailable, and report comparison failures without forcing a misleading relaunch.
+- Mobile Perps environment repair now publishes `.js.env` atomically without following destination symlinks, and Mobile source preflight returns an actionable `MOBILE_SOURCE_UNAVAILABLE` error for non-Git targets.
+- Mobile no longer translates the Extension-only `visible=true` wait alias into an unsupported enum; `call --arg` accepts quoted JSON strings for numeric-looking string values.
+- Timed streaming leaves now settle as soon as a SIGTERM-terminated direct child exits, reap SIGTERM-ignoring descendants, and forward Ctrl+C/SIGTERM to detached child trees before the harness exits.
+- `doctor --fix` now schema-validates, quarantines, and recreates malformed, semantically invalid, or cross-adapter-contaminated checkout runtime context without touching product data; wallet-fixture recovery commands use `--force` only for invalid or incomplete existing fixtures, while a missing fixture retains the safe unforced initialization command.
+- `logs --source app` now resolves the adapter-owned application console (`extension-console.log` on Extension and the CDP-forwarded `metro.log` on Mobile); an absent console returns `APP_LOG_UNAVAILABLE` instead of falling back to a dev-server log or reporting a usage error.
+- Doctor JSON now retains runtime probe failures, marks every diagnostic check as required or optional, derives its status from required checks, and reports runtime readiness separately.
+- Debug JSON now preserves the leaf target, method, endpoint, and detail; `--no-open` reaches the leaf, and Mobile reports its debug endpoint without invoking it.
+- Checklist diff gates and terminal-signal preservation now share agent-runtime's numeric step semantics, preventing exponent-form step tokens from bypassing a required PASS or regressing a terminal task.
+- Extension Perps config repair and fixture initialization now stage validated, mode-correct regular files before atomic publication, preserve existing config modes, refuse no-force overwrites, do not follow destination symlinks, and reject runtime-ancestor symlinks.
+- Mobile Metro startup now reaps an existing same-port console forwarder even when macOS `ps` pads a short PID, while retaining command-and-port ownership checks.
+- Extension and Core dependency readiness now requires Yarn's node-modules install state when the checkout selects `nodeLinker: node-modules`, preventing a leftover `.yarn/install-state.gz` from reporting removed dependencies as current.
+- Non-tmux Mobile Metro launch now uses a repository-shipped detached Node launcher instead of a same-process-group `nohup` child, so Metro survives the launching terminal/process-group boundary while retaining exact checkout PID, port, env, log, and public-stop ownership.
+- Mobile launch now fingerprints `.js.env`, `.env`, and `.env.local` per runtime directory; a missing or changed successful-bundle baseline forces exactly one cache-cleared Metro restart, while failed starts and mid-launch env changes cannot bless stale transforms.
+- Mobile `fixtures set` now bounds wallet application at 120 seconds, uses short bridge-readiness probes against the resolved slot Metro port, terminates only its owned child process group on timeout, releases the checkout lock, and leaves runtime relaunch to the explicit recovery command.
+- Mobile `doctor --fix` now adds `MM_PERPS_ENABLED=true` and `OVERRIDE_REMOTE_FEATURE_FLAGS=true` to `.js.env` only when each key is absent, while preserving explicit repository or Farmslot values such as `false`; read-only doctor reports both effective local settings.
+- Extension `metamask.perps.start_state` now rejects `page: false` during planning because the action must enter Perps before controller convergence; teardown retains `false` as its skip-navigation option.
+- `run --plan` now rejects `validate.workflow.startState`, which execution ignores, and directs authors to the supported recipe-root `startState` field.
+- `check diff` now uses checkout-configured oxfmt when present, falling back to Prettier, so formatting follows each repository's declared tool.
+- `check diff` no longer passes ESLint 9's `--no-warn-ignored` flag to repositories on ESLint 8, so changed-file lint runs instead of failing during CLI argument parsing.
+- Extension fixture seeding now fails immediately with the visible MetaMask fatal-startup detail instead of waiting through unlock/setup polling when the product cannot initialize.
+- Extension harness fixtures now initialize Perps on testnet; start-state enters the current `#/perps-home` surface before controller convergence, reads the persisted controller network without requiring an initialized Perps request channel, and proves a requested toggle with a bounded poll.
+- Extension `ui.wait_for` now documents its fields and accepts `visible=true|false` as a concise alias for visible/absent assertions.
+- `mm-harness call` now parses JSON-like numbers, booleans, arrays, and objects from its documented `key=value` syntax, so typed action fields do not arrive as invalid strings.
+- Extension launch auto-healing now repairs missing or stale dependencies with the checkout's pinned Node version instead of teaching agents to guess a host tool manager.
+- Extension `metamask.perps.ensure_positions state=open` now preserves the position-selection result across the CDP metadata wrapper instead of treating the wrapped result as an array.
+- Checkout locks are reentrant for nested `mm-harness` subprocesses carrying the owning operation's token, so `launch --verify` cannot block its own runner smoke while unrelated processes remain excluded.
+- `doctor --fix` now reports top-level `status: "fail"` and exits nonzero when any repair remains unresolved, so missing fixtures and other sandbox blockers cannot look ready to agents.
+- Fixture sync now fails with an actionable initialization command when no usable source exists, and Core accepts the same canonical signing fixture consumed by its Perps controller actions.
+- `launch --verify` now performs the selected quick or `--build` launch before verification instead of bypassing launch through the legacy live path; `--build --verify` no longer drops the build request.
+- Extension `verify` and `live` infer the same checkout-scoped CDP port as `status`, `doctor`, and `launch --verify` via the shared `formatExtensionSlotPorts` ladder (runtime context → pool → slot-suffix formula), so standalone verify passes on healthy prepared slots without `--cdp-port`.
+
 ## 0.14.7 - 2026-07-10
 
 ### Changed
@@ -232,11 +307,11 @@ The "version people use": every remaining identified fix/improvement batched on
   `--json` error envelope) instead of throwing.
 - **`run` auto-detects the adapter** from the target/cwd when `--adapter` is absent
   (parity with call/doctor); teaches when the repo type cannot be detected.
-- **Log-tail windows follow a run-owned session ladder** — `RECIPE_TMUX_SESSION` →
-  the checkout's `agentic-runtime.json` `session` → the current tmux client — with no
-  slot-number derivation (the orchestrator names the session; the harness only
-  populates windows). Stale `metro-<port>` windows whose port has no live listener
-  are swept on Metro start.
+- **Log-tail windows follow an explicitly owned session ladder** —
+  `RECIPE_TMUX_SESSION` → the checkout's `agentic-runtime.json` `session`, with no
+  current-session or slot-number inference (the orchestrator names the session; the
+  harness only populates windows). Stale `metro-<port>` windows whose port has no
+  live listener are swept only inside that resolved session on Metro start.
 - **Extension slot ports fill independently** — the resolver no longer early-returns
   once CDP is known, so a context that pins only `cdpPort` still gets `WATCHER_PORT`
   from the pool/formula.
@@ -398,7 +473,7 @@ Minor release: the adapter-surface architecture plus the day's feature wave (0.3
 - **Deps baseline recorded the instant a setup leaf succeeds** — `prepareMobile` records the deps fingerprint baseline immediately after any successful `yarn-setup`, unconditionally (previously only a later `record: true` re-decide did, gated on the original decision being `install` and on `RECIPE_UP_INSTALL_ATTEMPTED`). Genuine-drift detection is fingerprint-based and self-sustaining after one good install.
 - **CocoaPods no longer crashes on non-UTF-8 podspecs under a locale-less env** — pod-triggering spawns (`yarn setup` / native `yarn start:*`) now pin a UTF-8 `LANG`/`LC_ALL` when the caller has none. A gateway/tmux parent env without a locale made Ruby parse podspecs as US-ASCII and die on the first multibyte byte (`Invalid react-native-mmkv.podspec: "\xE2" on US-ASCII`).
 - **`launch` no longer reports a dead app as ready** — the mobile readiness decision treated a healthy Metro + successful bundle as `ready` without checking the target device, so a dev client that had crashed or was never opened produced `✓ ready` while nothing was running. The decision now probes the device (`xcrun simctl spawn … launchctl list` / `adb shell ps -A`, fail-closed) and returns `launch`/`app-not-running` (relaunch the client) unless the app is actually alive.
-- **Metro log-tail window no longer leaks into an unrelated tmux session** — running `start-metro` outside a tmux client fell back to `tmux display-message` (the last-attached session, e.g. the user's own) and created its `metro-<port>` window — with a `tail -F` — there, outliving the run. The viewer now opens a window only in a session that belongs to this run (a named slot session that exists, or the current session when actually inside tmux) and otherwise skips it; Metro still runs detached to the log. Extracted to `adapters/mobile/lib/tmux-viewer.sh` so the rule is unit-tested; contract tests stub tmux hermetically so no suite run can create a real window.
+- **Metro log-tail window no longer leaks into an unrelated tmux session** — running `start-metro` without an explicit session previously fell back to whichever tmux client was current or last attached. The viewer now opens a window only from `RECIPE_TMUX_SESSION` or the checkout runtime context and otherwise skips it; Metro still runs detached to the log. Extracted to `adapters/mobile/lib/tmux-viewer.sh` so the rule is unit-tested; contract tests stub tmux hermetically so no suite run can create a real window.
 
 ### Added
 - **Adapter surface — one seam for per-platform behavior** — `src/adapters/surface.ts` defines `AdapterSurface` + a `getAdapterSurface(adapter)` registry that owns the behavior commands used to hand-roll with `if (adapter === …)` ladders (slot-port resolution, read-only runtime status, dev-server describe/stop, log sources, and platform-phrased Next: hints), with thin `mobile`/`extension`/`core` implementations that delegate to the existing readiness/port plumbing (re-homed to `src/adapters/slot-ports.ts`). `doctor`, `launch`, `stop`, `logs`, `debug`, and `fixtures` now resolve platform behavior through the surface instead of branching. This closes the platform-blind class of bug (a platform handled in one command but forgotten in another). Documented in `docs/ADAPTER-SURFACE.md`; enforces `docs/UX-PRINCIPLES.md` principle 1.

package/adapters/extension/ensure-browser.sh

@@ -312,7 +312,7 @@ const resumeWebpack = () => {
   if (CDP_PORT) args.push('--remote-debugging-port=' + CDP_PORT);
 
   const chromiumApp = path.dirname(path.dirname(path.dirname(chromium.executablePath())));
-  execFileSync('open', ['-n', '-a', chromiumApp, '--args', ...args], { stdio: 'ignore' });
+  execFileSync('open', ['-g', '-n', '-a', chromiumApp, '--args', ...args], { stdio: 'ignore' });
   for (let i = 0; i < 60; i++) {
     try {
       const version = await new Promise((resolve, reject) => {
@@ -412,7 +412,9 @@ const resumeWebpack = () => {
       await p.close().catch(() => {});
     }
   }
-  await page.bringToFront().catch(() => {});
+  if (process.env.MM_HARNESS_FOCUS_BROWSER === '1') {
+    await page.bringToFront().catch(() => {});
+  }
 
   fs.writeFileSync(path.join(AGENT_DIR, 'extension.id'), extId);
   console.log('[reopen] Ready \u2014 ' + SLOT_ID + (CDP_PORT ? ' CDP:' + CDP_PORT : ''));

package/adapters/extension/launch-browser.cjs

@@ -89,45 +89,84 @@ if (args['stop-only'] !== undefined) {
   process.exit(0);
 }
 
+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}`,
+  '--no-first-run',
+  '--disable-first-run-ui',
+  '--disable-default-apps',
+  '--disable-popup-blocking',
+  '--disable-extensions-file-access-check',
+  '--disable-extensions-content-verification',
+  '--disable-features=ExtensionContentVerification,DisableLoadExtensionCommandLineSwitch',
+  `--disable-extensions-except=${args['extension-dir']}`,
+  `--load-extension=${args['extension-dir']}`,
+  // Initial tab: caller's dapp URL when provided, else the extension home. The
+  // extension home avoids leaving disposable chrome://newtab/ or extensions
+  // manager tabs in the operator's slot browser.
+  initialUrl,
+];
 const logFd = fs.openSync(args['chrome-log'], 'a');
-let child;
+let browserPid;
 try {
-  const initialUrl = args['start-url'] || extensionHomeUrl(args['extension-dir']) || 'chrome://extensions/';
-  child = spawn(args['chrome-bin'], [
-    `--user-data-dir=${args.profile}`,
-    '--remote-debugging-address=127.0.0.1',
-    `--remote-debugging-port=${cdpPort}`,
-    '--no-first-run',
-    '--disable-first-run-ui',
-    '--disable-default-apps',
-    '--disable-popup-blocking',
-    '--disable-extensions-file-access-check',
-    '--disable-extensions-content-verification',
-    '--disable-features=ExtensionContentVerification,DisableLoadExtensionCommandLineSwitch',
-    `--disable-extensions-except=${args['extension-dir']}`,
-    `--load-extension=${args['extension-dir']}`,
-    // Initial tab: caller's dapp URL when provided, else the extension home. The
-    // extension home avoids leaving disposable chrome://newtab/ or extensions
-    // manager tabs in the operator's slot browser.
-    initialUrl,
-  ], {
-    detached: true,
-    env: {
-      ...process.env,
-      BUNDLED_DEBUGPY_PATH: undefined,
-      PYTHONHOME: undefined,
-      PYTHONPATH: undefined,
-      DYLD_LIBRARY_PATH: undefined,
-      DYLD_FALLBACK_LIBRARY_PATH: undefined,
-      DYLD_INSERT_LIBRARIES: undefined,
-    },
-    stdio: ['ignore', logFd, logFd],
-  });
+  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],
+    });
+    browserPid = waitForOwnedCdpPid(cdpPort, args.profile, args['extension-dir']);
+    if (browserPid === null) {
+      throw new Error(`Chrome launched but did not expose CDP on 127.0.0.1:${cdpPort}`);
+    }
+  } else {
+    const child = spawn(args['chrome-bin'], chromeArgs, {
+      detached: true,
+      env: sanitizedChildEnv(),
+      stdio: ['ignore', logFd, logFd],
+    });
+    child.unref();
+    browserPid = child.pid;
+  }
 } finally {
   fs.closeSync(logFd);
 }
-child.unref();
-fs.writeFileSync(args['chrome-pid'], `${child.pid}\n`);
+fs.writeFileSync(args['chrome-pid'], `${browserPid}\n`);
+
+function sanitizedChildEnv() {
+  return {
+    ...process.env,
+    BUNDLED_DEBUGPY_PATH: undefined,
+    PYTHONHOME: undefined,
+    PYTHONPATH: undefined,
+    DYLD_LIBRARY_PATH: undefined,
+    DYLD_FALLBACK_LIBRARY_PATH: undefined,
+    DYLD_INSERT_LIBRARIES: undefined,
+  };
+}
+
+function macApplicationForExecutable(executable) {
+  let current = path.resolve(executable);
+  while (current !== path.dirname(current)) {
+    if (current.endsWith('.app')) return current;
+    current = path.dirname(current);
+  }
+  return null;
+}
+
+function waitForOwnedCdpPid(port, profile, extensionDir) {
+  for (let i = 0; i < 300; i += 1) {
+    const pid = cdpListenerPids(port).find((candidate) =>
+      processIsOwnedHarnessBrowser(candidate, profile, extensionDir),
+    );
+    if (pid !== undefined) return pid;
+    spawnSync('sleep', ['0.1']);
+  }
+  return null;
+}
 
 function parseArgs(argv) {
   const parsed = {};

package/adapters/extension/live.sh

@@ -10,7 +10,7 @@
 #
 # Inputs (flags / env):
 #   --target <metamask-extension> (default $PWD)
-#   --cdp-port <port> (required, numeric-validated)
+#   --cdp-port <port> (optional; inferred from checkout context/pool when omitted)
 #   --launch-existing-dist | --start-watch | --prepare-cmd <cmd>
 #       (env RECIPE_HARNESS_EXTENSION_LAUNCH_CMD)
 #   --dist-dir <rel> (default dist/chrome), --chrome-user-data-dir <dir>,
@@ -55,18 +55,11 @@ while [ "$#" -gt 0 ]; do
     --dist-dir) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; DIST_DIR="$2"; shift 2 ;;
     --chrome-user-data-dir) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; CHROME_USER_DATA_DIR="$2"; shift 2 ;;
     --remote-flag) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; REMOTE_FLAGS="$2"; shift 2 ;;
-    -h|--help) echo "Usage: live.sh [--target <metamask-extension>] [--out <recipes-dir>] --cdp-port <port> [--launch-existing-dist|--start-watch|--prepare-cmd <cmd>] [--dist-dir dist/chrome] [--remote-flag KEY=VARIANT] [--artifacts-dir <dir>]"; exit 0 ;;
+    -h|--help) echo "Usage: live.sh [--target <metamask-extension>] [--out <recipes-dir>] [--cdp-port <port>] [--launch-existing-dist|--start-watch|--prepare-cmd <cmd>] [--dist-dir dist/chrome] [--remote-flag KEY=VARIANT] [--artifacts-dir <dir>]"; exit 0 ;;
     *) echo "Unknown arg: $1" >&2; exit 2 ;;
   esac
 done
 
-[ -n "$CDP_PORT" ] || { echo "Missing --cdp-port for Extension live validation" >&2; exit 2; }
-# Reject a non-numeric port before it is interpolated into the Chrome launch
-# command and the CDP HTTP probes.
-case "$CDP_PORT" in
-  *[!0-9]*) echo "Invalid --cdp-port (must be numeric): $CDP_PORT" >&2; exit 2 ;;
-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
@@ -77,6 +70,25 @@ if ! command -v harness_root >/dev/null 2>&1; then
   echo "mm-harness: shared lib adapters/shared/harness-path.sh not found; reinstall the runner." >&2
   exit 1
 fi
+TARGET="$(cd "$TARGET" && pwd)"
+# Infer checkout-scoped CDP when omitted (context → pool → formula).
+if [ -z "$CDP_PORT" ]; then
+  for _rsp in "$SCRIPT_DIR/lib/resolve-slot-ports.sh" "$SCRIPT_DIR/../shared/resolve-slot-ports.sh"; do
+    [ -f "$_rsp" ] && { # shellcheck disable=SC1090
+      . "$_rsp"; break; }
+  done
+  unset _rsp
+  if command -v apply_extension_slot_ports >/dev/null 2>&1; then
+    apply_extension_slot_ports "$TARGET"
+  fi
+fi
+[ -n "$CDP_PORT" ] || { echo "Could not infer extension CDP port for $TARGET; pass --cdp-port or prepare the slot." >&2; exit 2; }
+# Reject a non-numeric port before it is interpolated into the Chrome launch
+# command and the CDP HTTP probes.
+case "$CDP_PORT" in
+  *[!0-9]*) echo "Invalid --cdp-port (must be numeric): $CDP_PORT" >&2; exit 2 ;;
+esac
+
 # verify.sh is a recipe-tree feature: co-located in installed copies, under
 # adapters/extension in a repo checkout.
 VERIFY_SH=""
@@ -88,7 +100,6 @@ if [ -z "$VERIFY_SH" ]; then
   echo "mm-harness: extension verify.sh not found next to $SCRIPT_DIR; reinstall the runner." >&2
   exit 1
 fi
-TARGET="$(cd "$TARGET" && pwd)"
 RUNTIME_DIR="$(recipe_runtime_dir)"
 RUNTIME_DIST_DIR="${RECIPE_RUNTIME_DIST_DIR:-runtime-dist}"
 CHROME_PROFILE_NAME="${RECIPE_CHROME_PROFILE_NAME:-chrome-profile}"

package/adapters/extension/reattach.sh

@@ -299,9 +299,9 @@ async function closePages(context, predicate) {
       if (!startUrl && (url.startsWith('http://') || url.startsWith('https://'))) return true;
       return false;
     });
-    await home.bringToFront().catch(() => {
-      // Foreground is an operator affordance; health is verified separately.
-    });
+    if (process.env.MM_HARNESS_FOCUS_BROWSER === '1') {
+      await home.bringToFront().catch(() => {});
+    }
   }
   if (typeof browser.disconnect === 'function') await browser.disconnect();
   else await browser.close();

package/adapters/extension/sidepanel-toggle.sh

@@ -100,6 +100,10 @@ json_list() {
   curl -s "http://127.0.0.1:${CDP_PORT}/json/list"
 }
 
+focus_browser() {
+  [ "${MM_HARNESS_FOCUS_BROWSER:-}" = "1" ]
+}
+
 find_sidepanel_id() {
   json_list | python3 -c "import json,sys; d=json.load(sys.stdin); ids=[t.get('id','') for t in d if t.get('type')=='page' and 'sidepanel.html' in t.get('url','')]; print(ids[0] if ids else '')"
 }
@@ -143,7 +147,7 @@ activate_sandbox_page() {
   target_id="$(
     EXT_ID="$ext_id" json_list | python3 -c "import json,os,sys; d=json.load(sys.stdin); ext=os.environ.get('EXT_ID',''); pages=[t for t in d if t.get('type')=='page']; target=next((t for t in pages if ext and t.get('url','').startswith('chrome-extension://'+ext+'/') and 'sidepanel.html' not in t.get('url','')), None) or next((t for t in pages if t.get('url','').startswith('http://') or t.get('url','').startswith('https://')), None) or (pages[0] if pages else None); print(target.get('id','') if target else '')"
   )"
-  if [ -n "$target_id" ]; then
+  if [ -n "$target_id" ] && focus_browser; then
     curl -s "http://127.0.0.1:${CDP_PORT}/json/activate/${target_id}" >/dev/null || true
   fi
 }
@@ -177,7 +181,7 @@ activate_dapp_tab() {
   target_id="$(
     json_list | python3 -c "import json,sys; d=json.load(sys.stdin); pages=[t for t in d if t.get('type')=='page']; target=next((t for t in pages if t.get('url','').startswith('http://') or t.get('url','').startswith('https://')), None); print(target.get('id','') if target else '')"
   )"
-  if [ -n "$target_id" ]; then
+  if [ -n "$target_id" ] && focus_browser; then
     curl -s "http://127.0.0.1:${CDP_PORT}/json/activate/${target_id}" >/dev/null || true
   fi
 }
@@ -259,7 +263,9 @@ const { chromium } = require('playwright');
     });
   }
 
-  await page.bringToFront();
+  if (process.env.MM_HARNESS_FOCUS_BROWSER === '1') {
+    await page.bringToFront();
+  }
   const result = await page.evaluate(async () => {
     const currentWindow = await chrome.windows.getCurrent();
     const id = '__recipe_open_sidepanel__';
@@ -331,7 +337,7 @@ const { chromium } = require('playwright');
   const dappPage = context
     .pages()
     .find((candidate) => candidate.url().startsWith('http://') || candidate.url().startsWith('https://'));
-  if (dappPage) {
+  if (dappPage && process.env.MM_HARNESS_FOCUS_BROWSER === '1') {
     try {
       await dappPage.bringToFront();
     } catch {

package/adapters/extension/start-watch.sh

@@ -235,8 +235,8 @@ nohup env -u BUNDLED_DEBUGPY_PATH ${path_prefix:+PATH="${path_prefix}${PATH}"} $
 started_pid=$!
 printf '%s\n' "$started_pid" > "$watch_pid_file"
 # The orchestrator names the session; the harness only populates windows. Resolve
-# via the run-owned ladder (RECIPE_TMUX_SESSION → agentic-runtime.json session →
-# current tmux client) — no slot-number derivation.
+# via the run-owned ladder (RECIPE_TMUX_SESSION → agentic-runtime.json session) —
+# no current-session fallback or slot-number derivation.
 for _tv_src in "$SCRIPT_DIR/lib/tmux-viewer.sh" "$SCRIPT_DIR/../shared/tmux-viewer.sh"; do
   # shellcheck disable=SC1091
   [ -f "$_tv_src" ] && { . "$_tv_src"; break; }

package/adapters/extension/verify.sh

@@ -155,6 +155,23 @@ else
   refresh_extension_id
 fi
 
+# Infer checkout-scoped CDP port when caller omitted --cdp-port.
+if [ -z "$CDP_PORT" ]; then
+  for _rsp in "$SCRIPT_DIR/lib/resolve-slot-ports.sh" "$SCRIPT_DIR/../../adapters/shared/resolve-slot-ports.sh" "$SCRIPT_DIR/../shared/resolve-slot-ports.sh"; do
+    [ -f "$_rsp" ] && { # shellcheck disable=SC1090
+      . "$_rsp"; break; }
+  done
+  unset _rsp
+  if command -v apply_extension_slot_ports >/dev/null 2>&1; then
+    apply_extension_slot_ports "$TARGET"
+  fi
+fi
+if [ -n "$CDP_PORT" ]; then
+  case "$CDP_PORT" in
+    *[!0-9]*) echo "Invalid inferred --cdp-port (must be numeric): $CDP_PORT" >&2; exit 2 ;;
+  esac
+fi
+
 status="pass"
 checks=()
 
@@ -378,8 +395,8 @@ if [ "$STATIC_ONLY" = false ]; then
   checks+=("{\"name\":\"fixture/profile status\",\"status\":\"$(node -e 'const fs=require("fs"); const file=process.argv[process.argv.length - 1]; const v=JSON.parse(fs.readFileSync(file,"utf8")); console.log(v.status === "READY" ? "pass" : "warn");' "$ARTIFACTS/logs/fixture-status.json")\"}")
 
   if [ -z "$CDP_PORT" ]; then
-    echo "Live extension verify requires --cdp-port. Static checks may pass, but runtime proof is missing." > "$ARTIFACTS/logs/live-missing-cdp.log"
-    checks+=("{\"name\":\"live runtime CDP port\",\"status\":\"fail\",\"detail\":\"missing --cdp-port\"}")
+    echo "Live extension verify could not infer a checkout CDP port. Run from a prepared slot checkout or pass --cdp-port." > "$ARTIFACTS/logs/live-missing-cdp.log"
+    checks+=("{\"name\":\"live runtime CDP port\",\"status\":\"fail\",\"detail\":\"missing CDP port (checkout-scoped inference failed)\"}")
     status="fail"
     live_mode="missing-cdp"
   else

package/adapters/extension/wallet-fixture-state.cjs

@@ -503,6 +503,9 @@ async function generate(args) {
     data.PreferencesController.autoLockTimeLimit = 0;
   }
   data.PerpsController ??= {};
+  // Harness-owned fixtures default Perps mutations to testnet. This is both
+  // deterministic and prevents an autonomous recipe from initializing mainnet.
+  data.PerpsController.isTestnet = true;
   data.PerpsController.isFirstTimeUser = { mainnet: false, testnet: false };
   data.PerpsController.hasPlacedFirstOrder = { mainnet: true, testnet: true };
   patchAccountTracker(
@@ -705,6 +708,15 @@ async function waitForWalletScreen(page) {
   const unlockSelector = '[data-testid="unlock-password"]';
   const deadline = Date.now() + 45000;
   while (Date.now() < deadline) {
+    const fatalStartup = await page
+      .evaluate(() => {
+        const text = document.body?.innerText || '';
+        return text.includes('MetaMask had trouble starting') ? text.slice(0, 500) : null;
+      })
+      .catch(() => null);
+    if (fatalStartup) {
+      return { state: 'fatal', selector: null, detail: fatalStartup };
+    }
     for (const selector of readySelectors) {
       if (await locatorVisible(page.locator(selector))) {
         return { state: 'unlocked', selector };
@@ -762,7 +774,8 @@ async function unlockIfNeeded(page, password) {
     state = await waitForWalletScreen(page);
   }
   if (state.state !== 'unlocked') {
-    throw new Error(`Wallet did not reach unlocked home screen after fixture seeding (state=${state.state}). Next: mm-harness call ensure_unlocked   # then relaunch`);
+    const detail = state.detail ? `: ${state.detail.replace(/\s+/gu, ' ').trim()}` : '';
+    throw new Error(`Wallet did not reach unlocked home screen after fixture seeding (state=${state.state})${detail}. Next: inspect the product startup error before retrying launch`);
   }
   return state;
 }

package/adapters/manifest.json

@@ -18,6 +18,14 @@
       "inputs": "--target --port --clear; env WATCHER_PORT, METRO_PORT, MOBILE_METRO_REQUIRED_ENV, METRO_MAX_WORKERS",
       "outputs": "Metro PID file + log; exit 0 ready / 1 timeout / 2 bad args"
     },
+    {
+      "id": "mobile/launch-metro",
+      "entry": "adapters/mobile/launch-metro.cjs",
+      "kind": "node",
+      "purpose": "Launch Metro detached from the invoking process group so the runtime survives command cleanup.",
+      "inputs": "--target --port --log --pid-file [--workers] [--clear]",
+      "outputs": "Metro PID/launch metadata and redirected log; exit 0/1/2"
+    },
     {
       "id": "mobile/stop-metro",
       "entry": "adapters/mobile/stop-metro.sh",
@@ -310,8 +318,8 @@
       "id": "lib/tmux-session",
       "entry": "adapters/shared/tmux-session.sh",
       "kind": "lib",
-      "purpose": "resolve_run_tmux_session: the run-owned tmux session a log-tail window belongs in (RECIPE_TMUX_SESSION -> agentic-runtime.json session -> current client; no slot-number derivation).",
-      "inputs": "resolve_run_tmux_session [runtime-dir]; env RECIPE_TMUX_SESSION, RECIPE_RUNTIME_CONTEXT, TMUX",
+      "purpose": "resolve_run_tmux_session: the explicitly owned tmux session a log-tail window belongs in (RECIPE_TMUX_SESSION -> agentic-runtime.json session; no current-session or slot-number inference).",
+      "inputs": "resolve_run_tmux_session [runtime-dir]; env RECIPE_TMUX_SESSION, RECIPE_RUNTIME_CONTEXT",
       "outputs": "resolved session name on stdout (empty when none)"
     },
     {
@@ -319,7 +327,7 @@
       "entry": "adapters/shared/tmux-viewer.sh",
       "kind": "lib",
       "purpose": "Run-owned tmux log viewer helpers that open, replace, and clean prefixed viewer windows without slot-name inference.",
-      "inputs": "tmux_viewer_open/close_marker/sweep_prefix functions; env RECIPE_TMUX_SESSION, RECIPE_RUNTIME_CONTEXT, TMUX",
+      "inputs": "tmux_viewer_open/close_marker/sweep_prefix functions; env RECIPE_TMUX_SESSION, RECIPE_RUNTIME_CONTEXT",
       "outputs": "viewer windows and marker files; no-op when no run-owned session is available"
     },
     {
@@ -346,6 +354,14 @@
       "inputs": "ensure-runner-deps.sh [RUNNER_DIR]; env FARMSLOT_ROOT / METAMASK_RUNNER_PROTOCOL_ROOT optional local link target",
       "outputs": "installed node_modules in RUNNER_DIR; exit 0 when deps ready"
     },
+    {
+      "id": "lib/install-repo-deps",
+      "entry": "adapters/shared/install-repo-deps.sh",
+      "kind": "bash",
+      "purpose": "Install a checkout's pinned dependencies through its repository Node toolchain.",
+      "inputs": "--target <checkout>",
+      "outputs": "corepack yarn install output; exit 0/1/2"
+    },
     {
       "id": "lib/resolve-slot-ports",
       "entry": "adapters/shared/resolve-slot-ports.mjs",

package/adapters/mobile/bridge-runtime/setup-wallet.sh

@@ -115,15 +115,17 @@ echo "Fixture OK: password + ${ACCOUNT_COUNT} entry(ies), ${EXPECTED_ETH_TOTAL}
 
 wait_for_cdp_bridge() {
   local waited=0
-  local max="${CDP_READY_TIMEOUT:-90}"
+  local max="${CDP_READY_TIMEOUT:-30}"
+  local probe_timeout="${CDP_READY_PROBE_TIMEOUT:-1000}"
+  local started="$SECONDS"
   local output=""
-  while [ "$waited" -lt "$max" ]; do
-    if output=$($CDP eval "JSON.stringify({ok:true})" 2>&1); then
+  while [ "$((SECONDS - started))" -lt "$max" ]; do
+    if output=$(CDP_TIMEOUT="$probe_timeout" CDP_DISCOVERY_RETRIES=1 $CDP eval "JSON.stringify({ok:true})" 2>&1); then
       echo "CDP bridge connected."
       return 0
     fi
     sleep 1
-    waited=$((waited + 1))
+    waited=$((SECONDS - started))
     [ "$waited" -eq 5 ] && echo "Waiting for CDP bridge..."
   done
   echo "ERROR: CDP not reachable after ${max}s"