@deeeed/metamask-harness 0.51.5 → 0.51.6

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+## 0.51.6 - 2026-09-14
+
+### Added
+
+- Review knowledge composition: a team library's `review/antipatterns.md`, `review/parity.md`, and `owned-paths.json` compose on top of the harness's base review; the harness never copies them.
+  - `review checklist [--domain <name>] [--since <sha>] [--base <ref>] [--out <file>]`: phase-structured checklist (Setup, Base review, Domain patterns, Parity, Verdict) that `checklist mark` tracks; one line per `##` section of the library's anti-patterns; the other platform's checkout named as the parity reference or "not checked" with the reason; `--since` for an incremental re-review.
+    A library's `review/antipatterns.<adapter>.md` adds families for that adapter only.
+  - `help review [--domain <name>]`: the same composition as prose; never fetches.
+  - `domain`: a declared `--domain` / `MM_HARNESS_DOMAIN` wins, else the changed files are matched against every reachable library's `owned-paths.json`.
+  - `config`: per-engineer locations outside any repo (`~/.mm-harness/config.json`): `libraries.<name>`, `references.<mobile|extension|core>`.
+  - Resolution order: env (`RECIPE_LIBRARY_PATH`, `MM_HARNESS_REF_<ADAPTER>`) → config → sibling directory beside the checkout → shallow fetch into `<checkout>/.skills-cache/<name>` for known libraries (excluded through the checkout's git exclude file, worktrees included).
+
+### Fixed
+
+Extension fresh-launch and macOS focus fixes, first published off-main as 0.50.5 and 0.50.6 and now on main:
+
+- Avoid disabling and re-enabling the Extension after a fresh browser launch, which could cause `No SW` storage errors in reused wallet profiles. Keep build handoff for updates in an already-running browser.
+- Keep the previously focused macOS app in front while Chrome starts, instead of restoring only after CDP is up. Do not let caffeinate declare user activity during that launch.
+- Keep the Extension Chrome window visible, but restore the previously focused macOS app through Launch Services while Chrome starts so the window does not come to the front or take the keyboard. System Events hangs during that activation, so osascript restore cannot hold focus.
+- Reap every Chrome process that still owns the Extension profile before relaunch, and kill a macOS `open -n` browser that never exposes CDP, so repeated launches cannot stack headed Chrome instances on the same user-data-dir.
+- Close extra MetaMask home tabs after an Extension browser launch. `open -n` with a start URL against a still-live profile was stacking unlock tabs.
+- The macOS focus hold ends as soon as the operator brings any other app to the front, and the reopen launcher reaps a Chrome that never exposed CDP instead of leaving it behind.
+- Stop every Extension Chrome whose `--user-data-dir` is under this checkout's `temp/recipe/runtime/`, including uniquely named recipe profiles and checkout paths that contain spaces. The previous allow-list of `chrome-profile`, `chrome-profile-recipe`, and `chrome-profile-pw` left leftovers that `mm-harness stop` reported as already stopped. Nested `console-tail.mjs` log paths under that runtime dir are reaped the same way. Personal Chrome and other checkouts stay untouched.
+
 ## 0.51.5 - 2026-09-14
 
 ### Fixed

package/README.md

@@ -193,6 +193,31 @@ Teams maintain their library checkouts. Update them before starting a task;
 the harness records local revisions and recipe digests but does not fetch or
 check for upstream updates. Keep the selected library unchanged during a run.
 
+## Review a change
+
+```bash
+# Which team library owns the change (declared --domain wins, else owned-paths.json).
+mm-harness domain
+
+# The review guide: base review + the library's anti-pattern families and parity rule.
+mm-harness help review --domain perps
+
+# A checklist the mark shim can track: Setup, Base review, Domain patterns, Parity, Verdict.
+mm-harness review checklist --domain perps --out temp/tasks/review/TAT-1/CHECKLIST.md
+mm-harness review checklist --domain perps --since <last-reviewed-sha>   # incremental re-review
+
+# Where this machine keeps libraries and the other platform's checkout (outside any repo).
+mm-harness config set references.extension ~/dev/metamask-extension
+```
+
+A team library supplies `review/antipatterns.md` (one `##` section per family),
+optional `review/antipatterns.<adapter>.md` families appended for that adapter only,
+`review/parity.md`, and `owned-paths.json`; the harness composes them and never
+copies them. Locations resolve env (`RECIPE_LIBRARY_PATH`, `MM_HARNESS_REF_<ADAPTER>`)
+→ `mm-harness config` → sibling directory beside the checkout → shallow fetch into
+`<checkout>/.skills-cache/<name>`. A missing reference checkout degrades the parity
+step to "not checked" with the reason.
+
 ## Recover
 
 ```bash

package/adapters/extension/ensure-browser.sh

@@ -301,7 +301,8 @@ const {
   runtimeIdentityArgs,
   writeRuntimeIdentity,
 } = require(path.join('${SCRIPT_DIR}', 'lib/chrome-args.cjs'));
-const { captureMacFrontmostProcess, restoreMacFrontmostProcess } = require(path.join('${SCRIPT_DIR}', 'lib/macos-focus.cjs'));
+const { captureMacFrontmost, macBackgroundOpenArgs, preserveMacFrontmost, startMacFocusHold, stopMacFocusHold } = require(path.join('${SCRIPT_DIR}', 'lib/macos-focus.cjs'));
+const { stopProfileProcessesSync } = require(path.join('${SCRIPT_DIR}', 'lib/validation-process-ownership.cjs'));
 
 const SLOT_ID = '${SLOT_ID}';
 const AGENT_DIR = '${AGENT_DIR}';
@@ -322,6 +323,14 @@ const resumeWebpack = () => {
   if (WEBPACK_PID) { try { process.kill(-Number(WEBPACK_PID), 'SIGCONT'); } catch { try { process.kill(Number(WEBPACK_PID), 'SIGCONT'); } catch {} } }
 };
 
+const previousFrontmost = captureMacFrontmost();
+const chromiumApp = path.dirname(path.dirname(path.dirname(chromium.executablePath())));
+let focusHold = null;
+const releaseFocusHold = () => {
+  stopMacFocusHold(focusHold);
+  preserveMacFrontmost(previousFrontmost, chromiumApp);
+};
+
 (async () => {
   const runtimeNonce = createRuntimeIdentityNonce();
   const startedAt = Date.now();
@@ -343,9 +352,8 @@ const resumeWebpack = () => {
     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' });
+  focusHold = startMacFocusHold(previousFrontmost, chromiumApp);
+  execFileSync('open', macBackgroundOpenArgs(chromiumApp, args), { stdio: 'ignore' });
   for (let i = 0; i < 60; i++) {
     try {
       const version = await new Promise((resolve, reject) => {
@@ -360,7 +368,18 @@ const resumeWebpack = () => {
     } catch {}
     await new Promise(r => setTimeout(r, 1000));
   }
-  const browser = await chromium.connectOverCDP('http://127.0.0.1:' + CDP_PORT);
+  let browser;
+  try {
+    browser = await chromium.connectOverCDP('http://127.0.0.1:' + CDP_PORT);
+  } catch (error) {
+    // The submitted browser never exposed CDP: reap whatever owns the profile
+    // so the next launch cannot stack a second Chrome on the same user-data-dir.
+    stopProfileProcessesSync(PROFILE, { waitForAppearanceMs: 400 });
+    throw new Error(
+      'Reopened Chrome did not expose CDP on port ' + CDP_PORT + ': ' + (error && error.message ? error.message : String(error)) +
+      '. Next: inspect the slot browser process, then rerun: mm-harness launch --adapter extension --build'
+    );
+  }
   const ctx = browser.contexts()[0];
   let listenerPids;
   try {
@@ -396,6 +415,7 @@ const resumeWebpack = () => {
     } catch {}
   }
   if (!browserPid) {
+    stopProfileProcessesSync(PROFILE, { waitForAppearanceMs: 400 });
     throw new Error(
       'Reopened Chrome did not expose an owned CDP listener on port ' + CDP_PORT +
       '. Next: inspect the slot browser process, then rerun: mm-harness launch --adapter extension --build'
@@ -428,11 +448,12 @@ const resumeWebpack = () => {
   try {
     extId = execFileSync(RUNNER_BIN, ['resolve-extension', '--adapter', 'extension', '--target', REPO], { encoding: 'utf8' }).trim();
   } catch (err) {
+    releaseFocusHold();
     resumeWebpack();
     console.error('[FAIL] runner resolve-extension failed: ' + (err && err.message ? err.message : String(err)));
     process.exit(1);
   }
-  if (!/^[a-p]{32}$/.test(extId)) { resumeWebpack(); console.error('[FAIL] runner returned invalid extension id: ' + JSON.stringify(extId)); process.exit(1); }
+  if (!/^[a-p]{32}$/.test(extId)) { releaseFocusHold(); resumeWebpack(); console.error('[FAIL] runner returned invalid extension id: ' + JSON.stringify(extId)); process.exit(1); }
   console.log('[reopen] Extension: ' + extId + ' (via runner resolve-extension)');
 
   // Navigate to MetaMask home
@@ -498,8 +519,10 @@ const resumeWebpack = () => {
   if (process.env.MM_HARNESS_FOCUS_BROWSER === '1') {
     await page.bringToFront().catch(() => {});
   } else {
-    restoreMacFrontmostProcess(previousFrontmostPid);
+    await new Promise(r => setTimeout(r, 1000));
+    preserveMacFrontmost(previousFrontmost, chromiumApp);
   }
+  releaseFocusHold();
 
   fs.writeFileSync(path.join(AGENT_DIR, 'extension.id'), extId);
   console.log('[reopen] Ready \u2014 ' + SLOT_ID + (CDP_PORT ? ' CDP:' + CDP_PORT : ''));
@@ -509,6 +532,7 @@ const resumeWebpack = () => {
   if (WEBPACK_PID) console.log('[webpack] Resumed');
   process.exit(0);
 })().catch(e => {
+  releaseFocusHold();
   resumeWebpack();
   try { removeRuntimeIdentity(AGENT_DIR); } catch {}
   try { fs.unlinkSync(path.join(AGENT_DIR, 'browser.pid')); } catch {}

package/adapters/extension/launch-browser.cjs

@@ -24,7 +24,7 @@ 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 { profileProcessPids } = require('./lib/validation-process-ownership.cjs');
+const { profileProcessPids, stopProfileProcessesSync } = require('./lib/validation-process-ownership.cjs');
 const { acquireBuildHandoff } = require('./build-handoff.cjs');
 const {
   automationRuntimeArgs,
@@ -42,7 +42,13 @@ const {
   validationLaunchQuarantineError,
   writeRuntimeIdentity,
 } = require('./lib/chrome-args.cjs');
-const { captureMacFrontmostProcess, restoreMacFrontmostProcess } = require('./lib/macos-focus.cjs');
+const {
+  captureMacFrontmost,
+  macBackgroundOpenArgs,
+  preserveMacFrontmost,
+  startMacFocusHold,
+  stopMacFocusHold,
+} = require('./lib/macos-focus.cjs');
 
 if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log(
@@ -107,7 +113,7 @@ try {
       'Next: remove the invalid runtime identity and fix owner permissions, then rerun: mm-harness launch --adapter extension --build',
   );
 }
-terminatePids([...ownedPids]);
+stopProfileProcessesSync(args.profile, { extraPids: [...ownedPids] });
 if (args['reset-profile'] !== undefined) {
   fs.rmSync(args.profile, { recursive: true, force: true });
   fs.mkdirSync(args.profile, { recursive: true });
@@ -164,70 +170,85 @@ const chromeArgs = [
   initialUrl,
 ];
 const logFd = fs.openSync(args['chrome-log'], 'a');
-const previousFrontmostPid = captureMacFrontmostProcess();
+const previousFrontmost = captureMacFrontmost();
+const application = process.platform === 'darwin' ? macApplicationForExecutable(args['chrome-bin']) : null;
+const focusHold = startMacFocusHold(previousFrontmost, application);
 let browserPid;
 try {
-  const application = process.platform === 'darwin' ? macApplicationForExecutable(args['chrome-bin']) : null;
-  if (application) {
-    beginDetachedLaunch(cdpPort, args.profile, activeValidationLease);
-    execFileSync('open', ['-g', '-n', '-a', application, '--args', ...chromeArgs], {
-      env: sanitizedChildEnv(),
-      stdio: ['ignore', logFd, logFd],
+  try {
+    if (application) {
+      beginDetachedLaunch(cdpPort, args.profile, activeValidationLease);
+      execFileSync('open', macBackgroundOpenArgs(application, chromeArgs), {
+        env: sanitizedChildEnv(),
+        stdio: ['ignore', logFd, logFd],
+      });
+      browserPid = waitForOwnedCdpPid(cdpPort, args.profile, args['extension-dir']);
+      if (browserPid === null) {
+        stopProfileProcessesSync(args.profile, { waitForAppearanceMs: 400 });
+        throw new Error(
+          `Chrome launched but did not expose an owned CDP listener on 127.0.0.1:${cdpPort}. ` +
+            `Next: inspect ${args['chrome-log']}, then rerun: mm-harness launch --adapter extension --build`,
+        );
+      }
+    } else {
+      beginDetachedLaunch(cdpPort, args.profile, activeValidationLease);
+      const child = spawn(args['chrome-bin'], chromeArgs, {
+        detached: true,
+        env: sanitizedChildEnv(),
+        stdio: ['ignore', logFd, logFd],
+      });
+      child.unref();
+      browserPid = waitForOwnedCdpPid(cdpPort, args.profile, args['extension-dir']);
+      if (browserPid === null) {
+        stopProfileProcessesSync(args.profile, { extraPids: child.pid ? [child.pid] : [] });
+        throw new Error(
+          `Chrome launched but did not expose an owned CDP listener on 127.0.0.1:${cdpPort}. ` +
+            `Next: inspect ${args['chrome-log']}, then rerun: mm-harness launch --adapter extension --build`,
+        );
+      }
+    }
+    for (const problem of pruneExtraHomeTabs(cdpPort, args['extension-dir'])) {
+      process.stderr.write(`[launch] home-tab pruning: ${problem}\n`);
+    }
+  } finally {
+    fs.closeSync(logFd);
+  }
+  fs.writeFileSync(args['chrome-pid'], `${browserPid}\n`);
+  try {
+    writeRuntimeIdentity(runtimeDir, {
+      port: cdpPort,
+      pid: browserPid,
+      startedAt,
+      nonce: runtimeNonce,
     });
-    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}`);
+    clearDetachedLaunchUnproven(args.profile);
+    if (!activeValidationLease) {
+      clearValidationPortQuarantine(cdpPort, args.profile);
     }
-  } else {
-    beginDetachedLaunch(cdpPort, args.profile, activeValidationLease);
-    const child = spawn(args['chrome-bin'], chromeArgs, {
+  } catch (error) {
+    terminatePids([browserPid]);
+    fs.rmSync(args['chrome-pid'], { force: true });
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Failed to persist Extension runtime identity under ${runtimeDir}: ${detail}. ` +
+        'Next: fix owner write permissions for the runtime directory, then rerun: mm-harness launch --adapter extension --build',
+    );
+  }
+  if (process.platform === 'darwin') {
+    const wake = spawn('caffeinate', ['-dims', '-w', String(browserPid)], {
       detached: true,
-      env: sanitizedChildEnv(),
-      stdio: ['ignore', logFd, logFd],
+      stdio: 'ignore',
     });
-    child.unref();
-    browserPid = waitForOwnedCdpPid(cdpPort, args.profile, args['extension-dir']);
-    if (browserPid === null) {
-      if (child.pid) terminatePids([child.pid]);
-      throw new Error(
-        `Chrome launched but did not expose an owned CDP listener on 127.0.0.1:${cdpPort}. ` +
-          `Next: inspect ${args['chrome-log']}, then rerun: mm-harness launch --adapter extension --build`,
-      );
-    }
+    wake.unref();
+    // Chrome often activates when the first window paints, which can be after CDP
+    // is already listening. Keep the previous app frontmost through that paint.
+    const settleMs = Number(process.env.MM_HARNESS_FOCUS_SETTLE_MS);
+    const waitSec = Number.isFinite(settleMs) && settleMs >= 0 ? settleMs / 1000 : 1;
+    if (waitSec > 0) spawnSync('sleep', [String(waitSec)]);
   }
 } finally {
-  fs.closeSync(logFd);
-}
-fs.writeFileSync(args['chrome-pid'], `${browserPid}\n`);
-try {
-  writeRuntimeIdentity(runtimeDir, {
-    port: cdpPort,
-    pid: browserPid,
-    startedAt,
-    nonce: runtimeNonce,
-  });
-  clearDetachedLaunchUnproven(args.profile);
-  if (!activeValidationLease) {
-    clearValidationPortQuarantine(cdpPort, args.profile);
-  }
-} catch (error) {
-  terminatePids([browserPid]);
-  fs.rmSync(args['chrome-pid'], { force: true });
-  const detail = error instanceof Error ? error.message : String(error);
-  throw new Error(
-    `Failed to persist Extension runtime identity under ${runtimeDir}: ${detail}. ` +
-      'Next: fix owner write permissions for the runtime directory, then rerun: mm-harness launch --adapter extension --build',
-  );
-}
-if (process.platform === 'darwin') {
-  const wake = spawn('caffeinate', ['-dimsu', '-w', String(browserPid)], {
-    detached: true,
-    stdio: 'ignore',
-  });
-  wake.unref();
-}
-if (process.env.MM_HARNESS_FOCUS_BROWSER !== '1') {
-  restoreMacFrontmostProcess(previousFrontmostPid);
+  stopMacFocusHold(focusHold);
+  preserveMacFrontmost(previousFrontmost, application);
 }
 
 function sanitizedChildEnv() {
@@ -426,3 +447,77 @@ function extensionHomeUrl(extensionDir) {
   const id = extensionIdFromExtensionDir(extensionDir);
   return id ? `chrome-extension://${id}/home.html` : '';
 }
+
+function cdpHttp(port, pathname) {
+  const result = spawnSync(process.execPath, ['-e', `
+    const http = require('http');
+    http.get('http://127.0.0.1:${Number(port)}${pathname}', (res) => {
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        process.stdout.write(body);
+        process.exitCode = res.statusCode === 200 ? 0 : 1;
+      });
+    }).on('error', () => process.exit(1));
+  `], { encoding: 'utf8', timeout: 4000 });
+  if (result.status !== 0) return null;
+  return result.stdout;
+}
+
+// Best effort by design: CDP ownership is already proven and ensure-ready
+// converges home tabs again during verify, so a pruning failure must not fail
+// the launch. Every failure is returned so the launch log says why a duplicate
+// tab survived instead of hiding it.
+function pruneExtraHomeTabs(port, extensionDir) {
+  const id = extensionIdFromExtensionDir(extensionDir);
+  if (!id) return ['extension id unavailable; skipped'];
+  const raw = cdpHttp(port, '/json/list');
+  if (raw === null) return [`GET http://127.0.0.1:${port}/json/list failed`];
+  let targets;
+  try {
+    targets = JSON.parse(raw);
+  } catch (error) {
+    return [`/json/list returned malformed JSON: ${error.message}`];
+  }
+  if (!Array.isArray(targets)) return ['/json/list did not return a target list'];
+  const problems = [];
+  const close = (target) => {
+    if (cdpHttp(port, `/json/close/${target.id}`) === null) problems.push(`could not close ${target.url} (${target.id})`);
+  };
+  const homes = targets.filter((target) => (
+    target &&
+    target.type === 'page' &&
+    typeof target.id === 'string' &&
+    typeof target.url === 'string' &&
+    target.url.includes(`chrome-extension://${id}/`) &&
+    target.url.includes('/home.html')
+  ));
+  const strays = targets.filter((target) => (
+    target &&
+    target.type === 'page' &&
+    typeof target.id === 'string' &&
+    typeof target.url === 'string' &&
+    (
+      target.url === 'about:blank' ||
+      target.url === 'chrome://newtab/' ||
+      target.url.startsWith('chrome://new-tab-page')
+    )
+  ));
+  if (homes.length === 0) return problems;
+  const keeper = homes.find((target) => (
+    typeof target.title === 'string' &&
+    target.title.trim() !== '' &&
+    target.title.trim() !== 'MetaMask'
+  )) ?? homes[0];
+  if (homes.length > 1) {
+    for (const extra of homes) {
+      if (keeper && extra.id === keeper.id) continue;
+      close(extra);
+    }
+  }
+  for (const stray of strays) {
+    if (keeper && stray.id === keeper.id) continue;
+    close(stray);
+  }
+  return problems;
+}

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

@@ -1,32 +1,227 @@
 'use strict';
 
-const { execFileSync } = require('node:child_process');
+const { execFileSync, spawn } = require('node:child_process');
+const fs = require('node:fs');
 
-function captureMacFrontmostProcess() {
+const HOLD_INTERVAL_MS = 20;
+// Upper bound for one Launch Services query or `open -a`. A short bound made a
+// loaded Mac time out the first query, which silently disabled the whole hold.
+const LS_TIMEOUT_MS = 2000;
+// Hard cap on a hold whose parent is alive but never released it.
+const HOLD_MAX_MS = 120_000;
+const toolEnv = () => ({ ...process.env });
+
+function captureMacFrontmost() {
   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'], timeout: 1_000 }).trim();
-    const pid = Number.parseInt(value, 10);
+    const asn = execFileSync('lsappinfo', ['front'], {
+      encoding: 'utf8',
+      env: toolEnv(),
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: LS_TIMEOUT_MS,
+    }).trim();
+    if (!asn) return null;
+    return parseLsappinfo(execFileSync('lsappinfo', ['info', asn], {
+      encoding: 'utf8',
+      env: toolEnv(),
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: LS_TIMEOUT_MS,
+    }));
+  } catch {
+    return null;
+  }
+}
+
+function captureMacFrontmostProcess() {
+  return captureMacFrontmost()?.pid ?? null;
+}
+
+function parseLsappinfo(info) {
+  const pid = Number.parseInt((info.match(/\bpid\s*=\s*(\d+)/u) || info.match(/"pid"=(\d+)/u) || [])[1], 10);
+  const bundlePath = (info.match(/bundle path="([^"]+)"/u) || info.match(/"LSBundlePath"="([^"]+)"/u) || [])[1];
+  const name = (info.match(/^"([^"]+)"/mu) || info.match(/"LSDisplayName"="([^"]+)"/u) || [])[1];
+  if (!Number.isInteger(pid) || pid <= 0 || !bundlePath) return null;
+  return { pid, bundlePath, name: name || bundlePath };
+}
+
+function currentFrontmostPid() {
+  try {
+    const asn = execFileSync('lsappinfo', ['front'], {
+      encoding: 'utf8',
+      env: toolEnv(),
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: LS_TIMEOUT_MS,
+    }).trim();
+    if (!asn) return null;
+    const value = execFileSync('lsappinfo', ['info', '-only', 'pid', asn], {
+      encoding: 'utf8',
+      env: toolEnv(),
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: LS_TIMEOUT_MS,
+    }).trim();
+    const pid = Number.parseInt((value.match(/"pid"=(\d+)/u) || [])[1], 10);
     return Number.isInteger(pid) && pid > 0 ? pid : null;
   } catch {
     return null;
   }
 }
 
+function restoreMacFrontmost(target) {
+  if (process.platform !== 'darwin' || !target?.bundlePath) return false;
+  try {
+    execFileSync('open', ['-a', target.bundlePath], {
+      env: toolEnv(),
+      stdio: 'ignore',
+      timeout: LS_TIMEOUT_MS,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 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', timeout: 1_000 });
+    const asn = execFileSync('lsappinfo', ['find', `pid=${pid}`], {
+      encoding: 'utf8',
+      env: toolEnv(),
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: LS_TIMEOUT_MS,
+    }).trim();
+    if (!asn) return false;
+    return restoreMacFrontmost(parseLsappinfo(execFileSync('lsappinfo', ['info', asn], {
+      encoding: 'utf8',
+      env: toolEnv(),
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: LS_TIMEOUT_MS,
+    })));
+  } catch {
+    return false;
+  }
+}
+
+// Bring `target` back in front of the launched browser. With `launchedBundlePath`
+// given, any other frontmost app is an intentional operator switch and is kept.
+function preserveMacFrontmost(target, launchedBundlePath) {
+  if (process.env.MM_HARNESS_FOCUS_BROWSER === '1') return false;
+  if (process.platform !== 'darwin' || !target?.bundlePath || !Number.isInteger(target.pid) || target.pid <= 0) {
+    return false;
+  }
+  const front = captureMacFrontmost();
+  if (front && front.pid === target.pid) return true;
+  if (front && launchedBundlePath && !sameBundle(front.bundlePath, launchedBundlePath)) return false;
+  return restoreMacFrontmost(target);
+}
+
+function preserveMacFrontmostProcess(pid) {
+  if (process.env.MM_HARNESS_FOCUS_BROWSER === '1') return false;
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  const current = currentFrontmostPid();
+  if (current === pid) return true;
+  return restoreMacFrontmostProcess(pid);
+}
+
+function macBackgroundOpenArgs(application, chromeArgs) {
+  return ['-g', '-n', '-a', application, '--args', ...chromeArgs];
+}
+
+// Keep the previously focused app in front while `launchedBundlePath` starts.
+// The hold only counters the launched browser: the moment any other app is
+// brought to the front, the operator switched on purpose and the hold ends.
+function startMacFocusHold(targetOrPid, launchedBundlePath) {
+  if (process.env.MM_HARNESS_FOCUS_BROWSER === '1') return null;
+  if (process.platform !== 'darwin') return null;
+  const target = typeof targetOrPid === 'number'
+    ? { pid: targetOrPid, bundlePath: bundlePathForPid(targetOrPid) }
+    : targetOrPid;
+  if (!target?.bundlePath || !Number.isInteger(target.pid) || target.pid <= 0) return null;
+  return spawn(process.execPath, [
+    __filename,
+    '--hold',
+    String(target.pid),
+    target.bundlePath,
+    String(process.pid),
+    launchedBundlePath || '',
+  ], { stdio: 'ignore', env: toolEnv() });
+}
+
+function sameBundle(left, right) {
+  if (!left || !right) return false;
+  const real = (value) => {
+    try {
+      return fs.realpathSync(value);
+    } catch {
+      return value;
+    }
+  };
+  return real(left) === real(right);
+}
+
+function bundlePathForPid(pid) {
+  try {
+    const asn = execFileSync('lsappinfo', ['find', `pid=${pid}`], {
+      encoding: 'utf8',
+      env: toolEnv(),
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: LS_TIMEOUT_MS,
+    }).trim();
+    return parseLsappinfo(execFileSync('lsappinfo', ['info', asn], {
+      encoding: 'utf8',
+      env: toolEnv(),
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: LS_TIMEOUT_MS,
+    }))?.bundlePath ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function stopMacFocusHold(child) {
+  if (!child || !Number.isInteger(child.pid) || child.pid <= 0) return;
+  try {
+    process.kill(child.pid, 'SIGTERM');
+  } catch (error) {
+    if (error.code !== 'ESRCH') throw error;
+  }
+}
+
+function parentAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
     return true;
   } catch {
     return false;
   }
 }
 
-module.exports = { captureMacFrontmostProcess, restoreMacFrontmostProcess };
+if (require.main === module && process.argv[2] === '--hold') {
+  const pid = Number.parseInt(process.argv[3], 10);
+  const bundlePath = process.argv[4];
+  const parentPid = Number.parseInt(process.argv[5], 10);
+  const launchedBundlePath = process.argv[6] || '';
+  const target = { pid, bundlePath };
+  const hold = () => {
+    if (!parentAlive(parentPid)) process.exit(0);
+    const front = captureMacFrontmost();
+    if (front && front.pid === target.pid) return;
+    if (front && launchedBundlePath && !sameBundle(front.bundlePath, launchedBundlePath)) process.exit(0);
+    preserveMacFrontmost(target, launchedBundlePath);
+  };
+  hold();
+  setInterval(hold, HOLD_INTERVAL_MS);
+  setTimeout(() => process.exit(0), HOLD_MAX_MS);
+}
+
+module.exports = {
+  captureMacFrontmost,
+  captureMacFrontmostProcess,
+  macBackgroundOpenArgs,
+  preserveMacFrontmost,
+  preserveMacFrontmostProcess,
+  restoreMacFrontmost,
+  restoreMacFrontmostProcess,
+  startMacFocusHold,
+  stopMacFocusHold,
+};