@deeeed/metamask-harness 0.17.5 → 0.18.0

package/README.md

@@ -1,177 +1,131 @@
-# MetaMask Recipe Runner — `mm-harness`
+# mm-harness
 
-Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+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.
 
-**`mm-harness` is built for the agent but easy for the human to use and
-understand.** It is the MetaMask recipe harness: one front door to launch the app,
-prove behavior with recipes, and manage the per-checkout runtime overlay. It is a
-thin MetaMask adapter over the generic `@farmslot/recipe-harness` engine — the
-runner never re-implements graph execution, it binds to it. The agent gets full
-depth (explicit flags, `--json`, ports, build tiers); the human gets short
-commands, positional targets, good defaults, completions, and teaching
-help/errors. Run it from inside a MetaMask Mobile/Extension/Core checkout and the
-platform is auto-detected.
+- **Action:** one typed operation.
+- **Flow:** a reusable, parameterized sequence of actions.
+- **Recipe:** the complete proof for a task or regression.
 
-```
-DAILY LOOP        launch · logs · debug · fixtures     what a teammate runs many times a day
-DISCOVER          actions · call · flows               compose recipes from the vocabulary + flow library
-PROVE             run · doctor                         run recipes, check readiness
-RUNTIME OVERLAY   install · verify · cleanup           manage the per-checkout runtime overlay
-```
-
-**One bin, no per-platform binaries.** `mm-harness` is the only command. Grammar:
-`mm-harness <command> [target] [flags]` — the human types the bare command
-(platform auto-detected) or a positional target (`mm-harness launch ios`); depth
-lives in FLAGS with good defaults, never in extra command names. It ships shell
-completions (zsh + bash) for commands, targets, and flags.
-
-Naming: **"harness" is the tool** (`mm-harness`) and the generic engine package
-(`@farmslot/recipe-harness`); the files it installs into a checkout are the
-**runtime overlay**. Read [MENTAL-MODEL.md](docs/MENTAL-MODEL.md) first (the
-before→after map), then [CLI-SPEC.md](docs/CLI-SPEC.md) for the full contract.
+The generic graph engine and evidence schemas live in Farmslot packages.
+`mm-harness` owns MetaMask runtime control and domain capabilities.
 
-One package, two responsibilities:
+## Install
 
-- **Recipe layer:** manifests, recipes, Mobile/Extension adapters, proof output.
-- **Runtime layer:** start/reuse Metro or Chrome, seed fixtures, wait for readiness.
-
-Farmslot and skills are wrappers around this CLI; they should not copy runner
-logic.
-
-## Quick start
+```bash
+npm install -g @deeeed/metamask-harness@latest
+mm-harness --version
+mm-harness doctor
+```
 
-Run from inside a MetaMask checkout (platform auto-detected):
+`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
-# 1) Launch the app (installs the runtime overlay on first use, boots Metro/build)
-mm-harness launch ios                    # mobile: ios | android; extension: just `launch`
-
-# 2) Run a recipe and write evidence
-mm-harness run recipe.json --adapter mobile --artifacts-dir /tmp/recipe-artifacts --json
+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
 ```
 
-Outputs: `summary.json`, `trace.json`, screenshots, logs, and an artifact
-manifest.
+Use `mm-harness update` to update a published installation.
 
-## Mental model
+## Operate
 
-```text
-mm-harness launch   # runtime/orchestration: the app is ready
-mm-harness run      # runner/proof: actions execute and evidence is saved
+```bash
+# Extension
+mm-harness launch
+mm-harness launch --sidepanel
+
+# Mobile
+mm-harness launch ios
+mm-harness launch android
+
+# Any checkout
+mm-harness status
+mm-harness stop
+mm-harness logs
+mm-harness debug
+mm-harness fixtures set
 ```
 
-Do not mix those layers. library/ = what recipes ARE (recipes, actions,
-manifests — the content). src/ = what EXECUTES them (TypeScript CLI/engine glue,
-typed adapters). adapters/ = what CONTROLS the app and its instances (start,
-windows, wallet state, health, ports, parallel).
+Extension `launch` keeps its incremental watcher running. Refresh the active
+page after a successful rebuild; use `launch --build` only for a clean rebuild.
 
-## Useful commands
+Log sources stay separate:
 
 ```bash
-# Capabilities (compose recipes from the vocabulary + flow library)
-mm-harness actions --adapter mobile --json      # the action vocabulary
-mm-harness actions --adapter mobile --raw       # raw action-manifest dump
-mm-harness call unlock --adapter extension      # run one action via the real engine path
-mm-harness flows --json                         # reusable library flows, with provenance
-
-# Readiness + proof
-mm-harness doctor                               # read-only readiness check (no launch)
-mm-harness doctor --fix                         # heal the overlay without launching
-mm-harness run recipe.json --plan --adapter mobile   # validate + plan, touch nothing
-
-# Daily loop (run from inside a checkout)
-mm-harness launch ios                           # launch (mobile: ios | android)
-mm-harness logs                                 # tail Metro/webpack + app logs
-mm-harness debug                                # open the debug console
-mm-harness fixtures sync                        # sync fixtures; `fixtures set` seeds the wallet
-
-# Keep the install current
-mm-harness update                               # upgrade to the published latest (prints old → new)
-mm-harness update --check --json                # report only — { current, latest, updateAvailable }
+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
 ```
 
-### Human validation rule
-
-An exit code or `--json` result is not sufficient for a UI/debug command. After
-`launch --verify`, confirm the debugger is visibly connected to the current
-slot's app/profile. Repeat this check on every slot/platform that will be used
-before release.
-
-A passive once-a-day nudge prints one `stderr` line when a newer version is
-published (`mm-harness <cur> → <latest> available · run: mm-harness update`). It
-never blocks and never auto-updates. Silence it with `MM_HARNESS_NO_UPDATE_CHECK=1`
-(auto-off in CI).
-
-Set `RECIPE_LOG_UI=compact|full|quiet` (default `compact`) and `RECIPE_LOG_EVENTS=10`
-to tune the compact log view during launch and Metro/webpack startup.
-
-## Layout
-
-```text
-bin/            the mm-harness entrypoint
-src/            what EXECUTES recipes: TypeScript CLI/engine glue +
-                typed per-adapter logic (src/adapters/)
-adapters/       what CONTROLS the app and its instances: launch/live/
-                watch/windows/wallet state/health/inject/cleanup per
-                platform, shared glue, porcelain, overlay payload +
-                manifest.json
-library/        what recipes ARE: recipes/ (recipe JSONs), actions/
-                (per-platform implementations), manifests/ (capability)
-scripts/        dev tooling (yarn check, local farmslot link, e2e
-                validation, adapter-surface-doctor)
-docs/           details when this README is not enough
-```
+## Discover and prove
 
-Defaults for installed harness/runtime paths live in
-`adapters/shared/path-defaults.json`.
+```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
+```
 
-## Runtime-readiness ownership
+`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.
 
-Generic readiness mechanics live in `@farmslot/recipe-harness` (0.3+):
+For automation, `--json` emits one stable document. `run --json-stream` emits
+line-buffered JSONL progress and a terminal event.
 
-- `@farmslot/recipe-harness/runtime/deps-readiness` — install fingerprint + baseline
-- `@farmslot/recipe-harness/runtime/log-analysis` — bundle-log boundaries, unresolved-module scoping
-- `@farmslot/recipe-harness/runtime/metro-probe` — Metro `/status` reachability
+## Team libraries
 
-This repo adds **MetaMask adapters only**: `adapters/mobile/deps-markers.ts`,
-`adapters/mobile/runtime-decision.ts`, `adapters/extension/runtime-decision.ts`,
-and shell launch in `adapters/porcelain/mm-recipe` / `adapters/porcelain/mme-recipe`. Do not re-copy harness
-primitives into `adapters/shared/`. CI installs harness from npm — publish
-`@farmslot/recipe-harness` before bumping the dependency here.
+```bash
+export RECIPE_LIBRARY_PATH="team=$HOME/shared-library/team-recipes"
+mm-harness flows
+mm-harness run --list
+```
 
-## Dev/prod harness (`MM_HARNESS_BIN`)
+Shared libraries hold durable actions, flows, and recipes. Task acceptance
+criteria remain task-local. See [Recipes](docs/RECIPES.md).
 
-The global npm install owns the `mm-harness` on `PATH` — that is the **prod**
-harness. To run a **dev** checkout with active pre-release changes alongside it,
-set `MM_HARNESS_BIN` to that checkout's `bin/mm-harness`:
+## Recover
 
 ```bash
-export MM_HARNESS_BIN=/path/to/checkout/bin/mm-harness   # dev: this checkout owns the run
-unset MM_HARNESS_BIN                                       # prod: the installed/global bin
+mm-harness doctor
+mm-harness doctor --fix
+mm-harness verify
+mm-harness cleanup
 ```
 
-`MM_HARNESS_BIN` is the single override point: when set, the entrypoint hands the
-whole invocation to that path before doing any dependency work; when unset it
-resolves the installed bin. A dev checkout is never installed globally, so there is
-no `PATH` collision — dev is reached only through `MM_HARNESS_BIN` (or a shell
-alias). A per-farm environment can export it so the dev farm dispatches through the
-dev harness while the prod farm leaves it unset.
+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.
 
-## Runtime notes
+## Reference
 
-- `tmux` is recommended for long-lived Metro/webpack processes; standalone use
-  falls back to detached `nohup` where possible.
-- Mobile may inject a local development bridge/HUD into older checkouts. Do not
-  commit those product patches.
-- Extension does not patch product source; it drives `dist/chrome` through Chrome
-  CDP.
+- [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.
 
-## Validate changes
+For development, point the installed command at a source checkout:
 
 ```bash
-yarn check
-bash -n bin/mm-harness adapters/porcelain/{metamask-recipe,mm-recipe,mme-recipe} adapters/{mobile,extension,core}/*.sh
-node --check adapters/extension/inject.mjs adapters/extension/cleanup.mjs adapters/extension/readiness.mjs adapters/extension/launch-browser.cjs adapters/shared/open-debug.mjs adapters/shared/cli-home.mjs adapters/shared/log-tui.mjs adapters/shared/progress.mjs adapters/shared/recipe-paths.mjs scripts/check.mjs
+export MM_HARNESS_BIN=/path/to/metamask-harness/bin/mm-harness
+mm-harness --version
 ```
 
-More detail: [Architecture](docs/architecture.md), [Package boundaries](docs/package-boundaries.md), [Runtime file conventions](docs/runtime-file-conventions.md).
+Unset `MM_HARNESS_BIN` to return to the published installation.

package/adapters/extension/console-tail.mjs

@@ -8,7 +8,7 @@
 // the tab shows live extension logs (the equivalent of the Metro/webpack tabs).
 //
 // Usage:
-//   console-tail.mjs --cdp-port <port> [--log <file>]
+//   console-tail.mjs --cdp-port <port> [--extension-log <file>] [--dapp-log <file>]
 //
 // Resilience: MV3 service workers cycle on idle and UI pages open/close, so we
 // re-poll /json/list every ~2s and (re)attach to any extension target that is
@@ -19,9 +19,10 @@
 'use strict';
 
 import { appendFileSync } from 'node:fs';
+import path from 'node:path';
 
 function parseArgs(argv) {
-  const args = { cdpPort: null, log: null };
+  const args = { cdpPort: null, extensionLog: null, dappLog: null };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     switch (arg) {
@@ -29,12 +30,16 @@ function parseArgs(argv) {
         args.cdpPort = argv[++i];
         break;
       case '--log':
-        args.log = argv[++i];
+      case '--extension-log':
+        args.extensionLog = argv[++i];
+        break;
+      case '--dapp-log':
+        args.dappLog = argv[++i];
         break;
       case '-h':
       case '--help':
         process.stdout.write(
-          'Usage: console-tail.mjs --cdp-port <port> [--log <file>]\n',
+          'Usage: console-tail.mjs --cdp-port <port> [--extension-log <file>] [--dapp-log <file>]\n',
         );
         process.exit(0);
         break;
@@ -51,6 +56,9 @@ if (!Number.isInteger(cdpPort) || cdpPort <= 0) {
   throw new Error('console-tail requires a numeric --cdp-port.');
 }
 const HOST = `127.0.0.1:${cdpPort}`;
+if (args.extensionLog && !args.dappLog) {
+  args.dappLog = path.join(path.dirname(path.resolve(args.extensionLog)), 'dapp-console.log');
+}
 
 if (typeof WebSocket === 'undefined') {
   throw new Error('console-tail requires Node 22+ with a global WebSocket.');
@@ -65,9 +73,13 @@ const cooldown = new Map();
 // Writes formatted console-event strings (never raw HTTP response bodies) to
 // stdout and optionally to a caller-supplied log file. The source is the local
 // Chrome CDP WebSocket (127.0.0.1:<cdpPort>) — a trusted-local endpoint.
-function out(line) {
+function out(line, destination = null) {
   process.stdout.write(`${line}\n`);
-  if (args.log) appendFileSync(args.log, `${line}\n`);
+  if (destination) {
+    // This file is explicitly an untrusted application-console transcript; it is never executed or parsed as configuration.
+    // codeql[js/http-to-file-access]
+    appendFileSync(destination, `${line}\n`);
+  }
 }
 
 function stamp() {
@@ -95,6 +107,22 @@ function isExtensionTarget(target) {
   return String(target.url || '').startsWith('chrome-extension://');
 }
 
+function isDappTarget(target) {
+  if (!target || !target.webSocketDebuggerUrl || target.type !== 'page') return false;
+  try {
+    const url = new URL(String(target?.url || ''));
+    return url.protocol === 'http:' || url.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+function targetStream(target) {
+  if (isExtensionTarget(target)) return { kind: 'extension', log: args.extensionLog };
+  if (isDappTarget(target)) return { kind: 'dapp', log: args.dappLog };
+  return null;
+}
+
 function previewArg(arg) {
   if (!arg || typeof arg !== 'object') return String(arg);
   if ('value' in arg && arg.value !== undefined) {
@@ -108,29 +136,29 @@ function previewArg(arg) {
   return arg.subtype || arg.type || '?';
 }
 
-function emitConsole(label, params) {
+function emitConsole(label, params, destination) {
   const level = String(params.type || 'log').toUpperCase();
   const text = (params.args || []).map(previewArg).join(' ');
-  out(`${stamp()} [${label}] ${level}  ${text}`);
+  out(`${stamp()} [${label}] ${level}  ${text}`, destination);
 }
 
-function emitException(label, params) {
+function emitException(label, params, destination) {
   const d = params.exceptionDetails || {};
   const text =
     d.exception?.description ||
     d.exception?.value ||
     d.text ||
     'uncaught exception';
-  out(`${stamp()} [${label}] EXCEPTION  ${text}`);
+  out(`${stamp()} [${label}] EXCEPTION  ${text}`, destination);
 }
 
-function emitLogEntry(label, params) {
+function emitLogEntry(label, params, destination) {
   const e = params.entry || {};
   const level = String(e.level || 'log').toUpperCase();
-  out(`${stamp()} [${label}] ${level}  ${e.text || ''}`);
+  out(`${stamp()} [${label}] ${level}  ${e.text || ''}`, destination);
 }
 
-function handleMessage(label, data) {
+function handleMessage(label, destination, data) {
   let message;
   try {
     message = JSON.parse(data);
@@ -141,13 +169,13 @@ function handleMessage(label, data) {
   if (message.id != null) return; // command ack, not an event
   switch (message.method) {
     case 'Runtime.consoleAPICalled':
-      emitConsole(label, message.params || {});
+      emitConsole(label, message.params || {}, destination);
       break;
     case 'Runtime.exceptionThrown':
-      emitException(label, message.params || {});
+      emitException(label, message.params || {}, destination);
       break;
     case 'Log.entryAdded':
-      emitLogEntry(label, message.params || {});
+      emitLogEntry(label, message.params || {}, destination);
       break;
     default:
       break;
@@ -155,9 +183,11 @@ function handleMessage(label, data) {
 }
 
 function attach(target) {
-  const label = shortLabel(target);
+  const stream = targetStream(target);
+  if (!stream) return;
+  const label = `${stream.kind}:${shortLabel(target)}`;
   const ws = new WebSocket(target.webSocketDebuggerUrl);
-  const entry = { ws, label, opened: false };
+  const entry = { ws, label, destination: stream.log, opened: false };
   attached.set(target.id, entry);
 
   ws.addEventListener('open', () => {
@@ -166,16 +196,16 @@ function attach(target) {
     for (const method of ['Runtime.enable', 'Log.enable']) {
       ws.send(JSON.stringify({ id: ++id, method, params: {} }));
     }
-    out(`${stamp()} [${label}] [attached]`);
+    out(`${stamp()} [${label}] [attached]`, stream.log);
   });
   ws.addEventListener('message', (event) => {
-    handleMessage(label, typeof event.data === 'string' ? event.data : '');
+    handleMessage(label, stream.log, typeof event.data === 'string' ? event.data : '');
   });
   const drop = () => {
     if (attached.get(target.id) !== entry) return;
     attached.delete(target.id);
     if (entry.opened) {
-      out(`${stamp()} [${label}] [reconnect] target detached; will re-attach`);
+      out(`${stamp()} [${label}] [reconnect] target detached; will re-attach`, stream.log);
     } else {
       // Never connected (target gone / not debuggable yet): back off so a dead
       // target is not retried — and logged — on every 2s poll.
@@ -196,8 +226,9 @@ async function poll() {
     // CDP not reachable this tick (browser starting/restarting); retry next poll.
     return;
   }
-  for (const target of Array.isArray(targets) ? targets : []) {
-    if (!isExtensionTarget(target)) continue;
+  const targetList = Array.isArray(targets) ? targets : [];
+  for (const target of targetList) {
+    if (!targetStream(target)) continue;
     if (attached.has(target.id)) continue;
     const until = cooldown.get(target.id);
     if (until !== undefined) {
@@ -226,6 +257,6 @@ function shutdown() {
 process.on('SIGINT', shutdown);
 process.on('SIGTERM', shutdown);
 
-out(`${stamp()} [console-tail] streaming extension console via cdp ${cdpPort}`);
+out(`${stamp()} [console-tail] streaming extension and dapp consoles via cdp ${cdpPort}`);
 await poll();
 setInterval(poll, 2000);

package/adapters/extension/ensure-browser.sh

@@ -277,7 +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 { remoteDebuggingArgs } = require(path.join('${SCRIPT_DIR}', 'lib/chrome-args.cjs'));
+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}';
@@ -308,6 +309,7 @@ const resumeWebpack = () => {
     '--disable-renderer-backgrounding',
     '--no-first-run',
     '--no-default-browser-check',
+    ...isolatedProfileArgs(),
     '--window-size=420,800',
   ];
   // Debug-port trio (address + port + scoped allow-origins) from the shared module
@@ -318,6 +320,7 @@ const resumeWebpack = () => {
   }
 
   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 {
@@ -420,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

@@ -95,16 +95,16 @@ copyDir(path.join(runnerDir, 'library/recipes'), path.join(harnessDir, 'runner/r
 copyFile(path.join(runnerDir, 'library/library.json'), path.join(harnessDir, 'runner/library.json'));
 fs.mkdirSync(path.join(harnessDir, 'runner/flows'), { recursive: true });
 copyDir(path.join(runnerDir, 'library/flows'), path.join(harnessDir, 'runner/flows'));
-// Installed-layout back-compat (INTENTIONAL): targets keep a flat
-// <harness>/scripts/ subtree assembled from the runner trees, so installed
-// consumers are unaffected by runner-repo layout changes.
+// The installed overlay has a flat scripts/ runtime API independent of the
+// package's source layout.
 copyFile(path.join(runnerDir, 'adapters/extension/launch-browser.cjs'), path.join(harnessDir, 'scripts/launch-browser.cjs'));
-// installed back-compat alias: callers of the pre-rename installed name
-copyFile(path.join(runnerDir, 'adapters/extension/launch-browser.cjs'), path.join(harnessDir, 'scripts/launch-chrome-detached.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/console-tail.mjs'), path.join(harnessDir, 'scripts/console-tail.mjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/launch.sh'), path.join(harnessDir, 'scripts/launch.sh'));
 copyFile(path.join(runnerDir, 'adapters/extension/live.sh'), path.join(harnessDir, 'scripts/live.sh'));
 copyFile(path.join(runnerDir, 'adapters/extension/start-watch.sh'), path.join(harnessDir, 'scripts/start-watch.sh'));
+copyFile(path.join(runnerDir, 'adapters/extension/launch-webpack.cjs'), path.join(harnessDir, 'scripts/launch-webpack.cjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/sync-webpack-dist.cjs'), path.join(harnessDir, 'scripts/sync-webpack-dist.cjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/stamp-runtime-title.cjs'), path.join(harnessDir, 'scripts/stamp-runtime-title.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/stop-viewers.sh'), path.join(harnessDir, 'scripts/stop-viewers.sh'));
 copyFile(path.join(runnerDir, 'adapters/extension/snapshot-dist.sh'), path.join(harnessDir, 'scripts/snapshot-dist.sh'));
 copyFile(path.join(runnerDir, 'adapters/extension/pin-remote-flags.cjs'), path.join(harnessDir, 'scripts/pin-remote-flags.cjs'));
@@ -121,10 +121,6 @@ copyFile(path.join(runnerDir, 'adapters/shared/activate-repo-node.sh'), path.joi
 copyFile(path.join(runnerDir, 'adapters/shared/resolve-slot-ports.sh'), path.join(harnessDir, 'scripts/lib/resolve-slot-ports.sh'));
 copyFile(path.join(runnerDir, 'adapters/shared/resolve-slot-ports.mjs'), path.join(harnessDir, 'scripts/lib/resolve-slot-ports.mjs'));
 copyFile(path.join(runnerDir, 'adapters/shared/resolve-slot-ports-core.mjs'), path.join(harnessDir, 'scripts/lib/resolve-slot-ports-core.mjs'));
-// Back-compat shims (one release) so an overlay consumer using the old leaf names still resolves.
-copyFile(path.join(runnerDir, 'adapters/shared/resolve-farmslot-ports.sh'), path.join(harnessDir, 'scripts/lib/resolve-farmslot-ports.sh'));
-copyFile(path.join(runnerDir, 'adapters/shared/resolve-farmslot-ports.mjs'), path.join(harnessDir, 'scripts/lib/resolve-farmslot-ports.mjs'));
-copyFile(path.join(runnerDir, 'adapters/shared/resolve-farmslot-ports-core.mjs'), path.join(harnessDir, 'scripts/lib/resolve-farmslot-ports-core.mjs'));
 copyFile(path.join(runnerDir, 'adapters/shared/path-defaults.json'), path.join(harnessDir, 'scripts/lib/path-defaults.json'));
 copyFile(path.join(runnerDir, 'adapters/shared/json-field.sh'), path.join(harnessDir, 'scripts/lib/json-field.sh'));
 copyFile(path.join(runnerDir, 'adapters/shared/tmux-session.sh'), path.join(harnessDir, 'scripts/lib/tmux-session.sh'));
@@ -133,6 +129,7 @@ copyFile(path.join(runnerDir, 'adapters/shared/log-tui.mjs'), path.join(harnessD
 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`);
 

package/adapters/extension/launch-browser.cjs

@@ -24,7 +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 { remoteDebuggingArgs } = require('./lib/chrome-args.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(
@@ -98,6 +99,7 @@ const chromeArgs = [
   ...remoteDebuggingArgs(cdpPort),
   '--no-first-run',
   '--disable-first-run-ui',
+  ...isolatedProfileArgs(),
   '--disable-default-apps',
   '--disable-popup-blocking',
   '--disable-extensions-file-access-check',
@@ -111,6 +113,7 @@ 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;
@@ -136,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 {