@deeeed/metamask-harness 0.51.5 → 0.51.7

package/CHANGELOG.md

@@ -1,6 +1,38 @@
 # Changelog
 
-## Unreleased
+## 0.51.7 - 2026-09-14
+
+### Added
+
+- `pr-body render <task-dir>` writes `artifacts/pr-body.md`: the worker's `artifacts/pr-description.md` with the "Validation Recipe", "Validation Logs" (and "Recipe Workflow" when `artifacts/workflow.mmd` exists) sections rendered from the task artifacts with fences that cannot break, replacing any pasted by hand. The farm publication step and the Cook evidence packaging call the same command.
+
+### Changed
+
+- Extension launch focus hold polls every 80 ms instead of 20 ms, and the reopen launcher honours `MM_HARNESS_FOCUS_SETTLE_MS` like the primary launcher.
+
+## 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
 

package/README.md

@@ -193,6 +193,45 @@ 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.
 
+## Publish a change
+
+```bash
+# Write artifacts/pr-description.md in the repository PR template shape (prose
+# only), then render the publishable body.
+mm-harness pr-body render temp/tasks/dev/TAT-1 --command 'mm-harness run artifacts/recipe.json'
+```
+
+`pr-body render` writes `artifacts/pr-body.md`: the description with the "Validation
+Recipe" and "Validation Logs" sections rendered from `artifacts/recipe.json` and
+`artifacts/recipe-run/report.md` (and "Recipe Workflow" from `artifacts/workflow.mmd`
+when it exists), replacing any pasted by hand. The worker never pastes artifacts
+into markdown, so fences cannot break.
+
+## 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,12 @@ const resumeWebpack = () => {
   if (process.env.MM_HARNESS_FOCUS_BROWSER === '1') {
     await page.bringToFront().catch(() => {});
   } else {
-    restoreMacFrontmostProcess(previousFrontmostPid);
+    const settleMs = Number(process.env.MM_HARNESS_FOCUS_SETTLE_MS);
+    const waitMs = Number.isFinite(settleMs) && settleMs >= 0 ? settleMs : 1000;
+    if (waitMs > 0) await new Promise(r => setTimeout(r, waitMs));
+    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 +534,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() {
@@ -387,11 +408,11 @@ function cdpListenerPids(port) {
 function terminatePids(pids) {
   const unique = [...new Set(pids)].filter((pid) => pid !== process.pid);
   for (const pid of unique) signalPid(pid, 'SIGTERM');
-  for (let i = 0; i < 10 && unique.some(pidAlive); i += 1) {
+  for (let i = 0; i < 10 && unique.some(processRespondsToSignal); i += 1) {
     spawnSync('sleep', ['0.2']);
   }
   for (const pid of unique) {
-    if (pidAlive(pid)) signalPid(pid, 'SIGKILL');
+    if (processRespondsToSignal(pid)) signalPid(pid, 'SIGKILL');
   }
 }
 
@@ -405,7 +426,7 @@ function signalPid(pid, signal) {
   }
 }
 
-function pidAlive(pid) {
+function processRespondsToSignal(pid) {
   try {
     process.kill(pid, 0);
     return true;
@@ -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;
+}