@deeeed/metamask-harness 0.69.0 → 0.70.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.70.0 - 2026-10-02
+
+### Added
+
+- Choose the Extension browser with `RECIPE_HARNESS_BROWSER=auto|cft|chrome|<path>` (default `auto`). Auto probe-launches the Playwright Chrome for Testing build the way the launcher starts it (launch method and headful/headless), requires a painted frame and a screenshot, and otherwise uses branded Google Chrome, loading the unpacked extension over CDP (`Extensions.loadUnpacked`) because branded Chrome ignores `--load-extension`. Crash verdicts are cached per OS build and browser binary; timeouts are retried after 30 minutes; concurrent probes are serialized through a directory of numbered lock tickets next to the cache, which grows by two small files per probe (the README gives a cleanup command for an idle machine). On a Mac whose Google Chrome is managed by policy (forced extensions or forced sign-in), auto uses Chrome for Testing and never falls back to the managed Chrome; doctor names the forced extensions. A slot profile keeps the kind of browser it was created with until the profile is reset: a Chrome for Testing profile follows the checkout's current build and moves to Google Chrome only on a proven crash; a Google Chrome or explicit-path profile keeps that binary, and an explicitly chosen binary (including a launcher given `--chrome-bin` directly) stays chosen across later auto launches. CDP loading runs only in the browser process that holds the slot profile's SingletonLock, wrote it on this host, and has the profile open (re-checked after connecting, within one deadline), checks the id against the manifest key, disables other user extensions in the slot profile (enterprise-pinned ones are recorded), and stops the browser on failure. `cft` forces the previous path; `RECIPE_HARNESS_CHROME_BIN` keeps its meaning. The chosen browser, version, source and loading method appear in `doctor --adapter extension`, the launch logs and each run's `product-provenance.json`, bound to the CDP port the run executed on (including a node's `cdp_port`, with `{{params.x}}` resolved from the run's params).
+
+### Changed
+
+- Shorten tutorials and correct template selection, report outputs, and static-review ownership; illustrate task progress with the fix-bug screenshot and watcher command.
+
 ## 0.69.0 - 2026-09-30
 
 ### Changed

package/README.md

@@ -113,6 +113,103 @@ Extension `launch` keeps its incremental watcher running. Refresh the active
 page after a successful rebuild; use `launch --build` only for an explicit
 production-like LavaMoat rebuild.
 
+### Extension browser
+
+`RECIPE_HARNESS_BROWSER` picks the browser that hosts the unpacked extension:
+
+| Value | Browser |
+|---|---|
+| `auto` (default) | The checkout's Playwright Chrome for Testing when it starts and paints on this machine, else Google Chrome |
+| `cft` | Chrome for Testing, never probed: the behaviour before auto existed |
+| `chrome` | Google Chrome |
+| `/abs/path` | That executable |
+
+`RECIPE_HARNESS_CHROME_BIN=/path` still overrides everything and is used as
+given. Google Chrome ignores `--load-extension`, so the harness loads the build
+over CDP (`Extensions.loadUnpacked`, with `--enable-unsafe-extension-debugging`)
+into the slot's own profile and checks the id against the manifest key. Other
+user extensions in that profile are disabled, as `--disable-extensions-except`
+does for Chrome for Testing; extensions an enterprise policy pins cannot be
+disabled, so the launch warns and records them with the run evidence.
+
+In `auto`, a launch with a new profile probe-launches Chrome for Testing the
+way the launcher starts it (headful, through Launch Services on macOS). The
+verdict lives in `~/.cache/mm-harness/browser-probe.json`: a crash is kept
+until the OS build or browser changes; a probe that only timed out is retried
+after 30 minutes. Concurrent launches wait for one probe per browser build
+(a `<cache>.<key>.locks/` directory of numbered tickets next to the cache; a
+holder older than 3 minutes counts as gone, so a probe that outlives it can
+overlap the next one, and during an upgrade from a build that used a `.lock`
+file one duplicate probe is possible). Tickets are never removed by the
+harness: each probe adds two small files, and a crashed holder's unreleased
+ticket stays (it no longer blocks once its process is gone). To reclaim the
+space, remove the lock directories while no launch or doctor is running:
+`rm -r ~/.cache/mm-harness/browser-probe.json.*.locks`.
+On a cold cache the probe can take up to about 80 seconds and
+shows a small (about 480×360) browser window; `doctor --adapter extension`
+runs the same probe.
+
+On a Mac whose Google Chrome is managed by policy (force-installed extensions
+in `/Library/Managed Preferences/…/com.google.Chrome.plist`, or forced
+sign-in), `auto` uses Chrome for Testing: it does not read those policies, so
+no forced extension can open windows in the slot. If Chrome for Testing does
+not start and paint there, the launch stops and names the two ways forward
+(`RECIPE_HARNESS_BROWSER=chrome`, accepting the forced extensions' windows, or
+a less loaded machine) instead of falling back to the managed Chrome. Doctor
+lists the forced extensions. A slot profile created on the managed Chrome keeps
+it, with a warning to reset the profile.
+
+A slot then keeps the kind of browser its profile was created with, until the
+profile is reset (`mm-harness fixtures set` or `fixtures reset`):
+
+- created on Chrome for Testing: the checkout's current Chrome for Testing
+  (a Playwright upgrade is followed and re-probed); it moves to Google Chrome
+  only once that build is proven to crash, never back;
+- created on Google Chrome or an explicit path: that binary; if it is removed,
+  the launch fails and says how to recover rather than switching browsers;
+- created with `RECIPE_HARNESS_CHROME_BIN`, a path in `RECIPE_HARNESS_BROWSER`,
+  or a launcher given `--chrome-bin` directly:
+  that exact binary on every later `auto` launch, even when it is a Chrome for
+  Testing build.
+
+A preserved slot stuck on Chrome for Testing that "renders no frames" (a
+transient verdict, which keeps it on Chrome for Testing) moves to Google Chrome
+without a profile reset: launch it once with `RECIPE_HARNESS_BROWSER=chrome`.
+The profile is then a Google Chrome profile and later `auto` launches keep
+Google Chrome. Going the other way opens a profile in an older browser, so
+reset the profile instead.
+
+Profiles created before this browser record existed have no record, so their
+first `auto` launch probes like a new profile and may move to Google Chrome.
+
+`mm-harness doctor --adapter extension` shows the current choice; each launch
+writes it to `temp/recipe/runtime/browser-resolution.json` with the browser
+process identity, and run evidence (`product-provenance.json`) names the
+browser the run drove only after checking that exact process still serves the
+CDP port the run executed on. The owner of a CDP port is the process named by
+the profile's `SingletonLock`, and only if the lock names this host, the
+process started before the lock was written (a reused pid did not), and it
+holds files open in the profile. That proof uses `lsof`, which macOS ships;
+without it the launch stops with an explanation. Start times are compared exactly as
+`ps -o lstart` prints them in UTC, so a record written by an earlier harness
+build (local time) binds nothing (`boundTo: none`) until the slot relaunches.
+
+On macOS the slot browser starts in the background with no startup window,
+and its first window opens over CDP as a background window. After the launch
+settles there is one focus check: only if the slot browser's own process is
+frontmost does the previously focused app get the front back, once
+(`MM_HARNESS_FOCUS_HOLD=0` turns this off). A click on the slot window right
+after launch can therefore be undone once.
+
+```bash
+# Roll back to Chrome for Testing with a fresh slot profile (a profile Google
+# Chrome has opened is not reopened in the older Chrome for Testing). Keep
+# RECIPE_HARNESS_BROWSER=cft set for later launches too: on a plain auto launch
+# the profile follows Chrome for Testing only until a probe proves it dies.
+RECIPE_HARNESS_BROWSER=cft mm-harness fixtures set
+rm ~/.cache/mm-harness/browser-probe.json        # forget probe verdicts
+```
+
 ### Remote feature flags
 
 `--remote-flag KEY=VALUE[,KEY=VALUE]` pins a remote feature flag for the launch,

package/adapters/extension/ensure-browser.sh

@@ -1,12 +1,14 @@
 #!/usr/bin/env bash
-# ensure-browser.sh — ensure the slot's Playwright Chromium is running
+# ensure-browser.sh — ensure the slot's browser is running
 # (auto-detects the slot, kills any existing browser by recorded PID,
 # relaunches against the existing dist/profile/port; requires an
 # already-prepared profile). Project-specific (MetaMask Extension).
 #
 # Purpose:
 #   Restarts the slot's Chromium against the existing profile + dist build,
-#   re-resolves the extension id via the installed runner, and unlocks.
+#   re-resolves the extension id via the installed runner, and unlocks. The
+#   browser comes from the shared resolver (RECIPE_HARNESS_BROWSER); branded
+#   Chrome gets the extension over CDP instead of --load-extension.
 #
 # Inputs (flags / env):
 #   --slot-id <id> (default <host>-<repo-basename>), --repo <checkout>,
@@ -16,7 +18,8 @@
 #   browser.pid/webpack.pid when omitted.
 #
 # Outputs:
-#   <runtime-dir>/{browser.pid,chromium.pid,extension.id}; progress on stdout.
+#   <runtime-dir>/{browser.pid,chromium.pid,extension.id,browser-resolution.json};
+#   progress on stdout.
 #   Exit 0 — browser reopened and ready; 1 — preflight/launch failure.
 #
 # Never touches: other slots' browsers (kills by recorded PID/profile only);
@@ -301,8 +304,21 @@ const {
   runtimeIdentityArgs,
   writeRuntimeIdentity,
 } = require(path.join('${SCRIPT_DIR}', 'lib/chrome-args.cjs'));
-const { captureMacFrontmost, macBackgroundOpenArgs, preserveMacFrontmost, startMacFocusHold, stopMacFocusHold } = require(path.join('${SCRIPT_DIR}', 'lib/macos-focus.cjs'));
+const { captureMacFrontmost, macBackgroundOpenArgs, restoreFrontmostIfOurs } = require(path.join('${SCRIPT_DIR}', 'lib/macos-focus.cjs'));
 const { stopProfileProcessesSync } = require(path.join('${SCRIPT_DIR}', 'lib/validation-process-ownership.cjs'));
+const {
+  CDP_LOAD_UNPACKED,
+  HEADFUL,
+  LAUNCH_SERVICES,
+  extensionLaunchArgs,
+  loadUnpackedOverPort,
+  waitForCdpOwner,
+  playwrightChromiumExecutable,
+  resolveBrowser,
+} = require([
+  path.join('${SCRIPT_DIR}', 'lib/browser-resolver.cjs'),
+  path.join('${SCRIPT_DIR}', '../shared/browser-resolver.cjs'),
+].find((candidate) => fs.existsSync(candidate)));
 
 const SLOT_ID = '${SLOT_ID}';
 const AGENT_DIR = '${AGENT_DIR}';
@@ -324,26 +340,40 @@ const resumeWebpack = () => {
 };
 
 const previousFrontmost = captureMacFrontmost();
-const chromiumApp = path.dirname(path.dirname(path.dirname(chromium.executablePath())));
-let focusHold = null;
+let chromiumApp = null;
+// Set once the CDP listener is proven to run with this slot's profile.
+let browserPid = '';
+// One check, at most one restore, and only if OUR browser (the proven CDP
+// owner pid) holds the front; any other app in front is left alone.
 const releaseFocusHold = () => {
-  stopMacFocusHold(focusHold);
-  preserveMacFrontmost(previousFrontmost, chromiumApp);
+  if (browserPid) restoreFrontmostIfOurs(previousFrontmost, [Number(browserPid)]);
 };
 
 (async () => {
+  // Reopen always reuses the slot profile, so auto keeps the browser recorded
+  // for it.
+  const resolution = await resolveBrowser({
+    cft: () => playwrightChromiumExecutable(REPO),
+    launchMethod: LAUNCH_SERVICES,
+    display: HEADFUL,
+    recorded: path.join(AGENT_DIR, 'browser-resolution.json'),
+  });
+  chromiumApp = path.dirname(path.dirname(path.dirname(resolution.bin)));
+  console.log('[reopen] Browser: ' + resolution.browser + ' ' + (resolution.version || '?') + ' (' + resolution.extensionLoading + ')');
   const runtimeNonce = createRuntimeIdentityNonce();
   const startedAt = Date.now();
   const args = [
     '--user-data-dir=' + PROFILE,
-    '--disable-extensions-except=' + EXTENSION,
-    '--load-extension=' + EXTENSION,
+    ...extensionLaunchArgs(EXTENSION, resolution.extensionLoading),
     ...automationRuntimeArgs(),
     ...runtimeIdentityArgs(runtimeNonce),
     '--no-first-run',
     '--no-default-browser-check',
     ...isolatedProfileArgs(),
     '--window-size=420,800',
+    // Started in the background with no window (Chrome activates itself when
+    // it opens one); the first window is opened over CDP as a background window.
+    '--no-startup-window',
   ];
   // Debug-port trio (address + port + scoped allow-origins) from the shared module
   // so the DevTools origin allow-list can never drift away from the port; without
@@ -352,7 +382,6 @@ const releaseFocusHold = () => {
     args.push(...remoteDebuggingArgs(CDP_PORT));
   }
 
-  focusHold = startMacFocusHold(previousFrontmost, chromiumApp);
   execFileSync('open', macBackgroundOpenArgs(chromiumApp, args), { stdio: 'ignore' });
   for (let i = 0; i < 60; i++) {
     try {
@@ -394,7 +423,7 @@ const releaseFocusHold = () => {
       'Next: install or restore lsof, then rerun: mm-harness launch --adapter extension --build'
     );
   }
-  let browserPid = '';
+  browserPid = '';
   for (const pid of listenerPids) {
     try {
       const command = execFileSync(
@@ -439,6 +468,28 @@ const releaseFocusHold = () => {
     );
   }
   console.log('[reopen] Chromium PID ' + browserPid);
+  let cdpLoad = null;
+  if (resolution.extensionLoading === CDP_LOAD_UNPACKED) {
+    cdpLoad = await loadUnpackedOverPort(Number(CDP_PORT), EXTENSION, { profile: PROFILE });
+    console.log('[reopen] Extension loaded over CDP: ' + cdpLoad.id);
+    for (const entry of cdpLoad.otherExtensions.policyPinned) {
+      console.log('[reopen] WARN: enterprise policy keeps ' + entry.id + ' (' + entry.name + ') enabled in the slot profile');
+    }
+  }
+  let owner = cdpLoad ? cdpLoad.owner : null;
+  if (!owner) {
+    try { owner = waitForCdpOwner(Number(CDP_PORT), PROFILE, { timeoutMs: 15000 }); } catch (error) { console.log('[reopen] WARN: could not record the browser identity: ' + error.message); }
+  }
+  fs.writeFileSync(path.join(AGENT_DIR, 'browser-resolution.json'), JSON.stringify({
+    ...resolution,
+    launch: {
+      pid: Number(browserPid),
+      cdpPort: Number(CDP_PORT),
+      startedAt: new Date(startedAt).toISOString(),
+      ...(owner ? { profile: owner.profile, processStartedAt: owner.startedAt } : {}),
+      ...(cdpLoad ? { extensionId: cdpLoad.id, otherExtensions: cdpLoad.otherExtensions } : {}),
+    },
+  }, null, 2) + '\n');
 
   // Detect extension ID via the recipe-runner — the single source of truth.
   // Deterministic id from the loaded dist's manifest key; replaces a fragile
@@ -458,7 +509,13 @@ const releaseFocusHold = () => {
 
   // Navigate to MetaMask home
   const homeUrl = 'chrome-extension://' + extId + '/home.html';
-  const page = ctx.pages().find(p => p.url().includes('chrome-extension://')) || ctx.pages()[0];
+  let page = ctx.pages().find(p => p.url().includes('chrome-extension://')) || ctx.pages()[0];
+  if (!page) {
+    const session = await browser.newBrowserCDPSession();
+    const opened = ctx.waitForEvent('page', { timeout: 15000 });
+    await session.send('Target.createTarget', { url: 'about:blank', newWindow: true, background: true });
+    page = await opened;
+  }
   await page.goto(homeUrl, { waitUntil: 'load', timeout: 15000 });
 
   // Set window title to slot ID (persists across SPA navigations)
@@ -522,9 +579,8 @@ const releaseFocusHold = () => {
     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();
   }
-  releaseFocusHold();
 
   fs.writeFileSync(path.join(AGENT_DIR, 'extension.id'), extId);
   console.log('[reopen] Ready \u2014 ' + SLOT_ID + (CDP_PORT ? ' CDP:' + CDP_PORT : ''));
@@ -534,6 +590,20 @@ const releaseFocusHold = () => {
   if (WEBPACK_PID) console.log('[webpack] Resumed');
   process.exit(0);
 })().catch(e => {
+  // A proven owner is stopped before its records go, so no browser outlives
+  // the identity and pid files that name it. If it cannot be stopped, the
+  // records stay so the next launch can still find and stop it.
+  if (browserPid) {
+    try {
+      stopProfileProcessesSync(PROFILE, { extraPids: [Number(browserPid)] });
+    } catch (stopError) {
+      releaseFocusHold();
+      resumeWebpack();
+      console.error(e);
+      console.error('[FAIL] could not stop browser pid ' + browserPid + ' after the failure above: ' + (stopError && stopError.message) + '. Its records are kept; stop it, then rerun.');
+      process.exit(1);
+    }
+  }
   releaseFocusHold();
   resumeWebpack();
   try { removeRuntimeIdentity(AGENT_DIR); } catch {}

package/adapters/extension/inject.mjs

@@ -126,6 +126,8 @@ copyFile(path.join(runnerDir, 'adapters/shared/json-field.sh'), path.join(harnes
 copyFile(path.join(runnerDir, 'adapters/shared/tmux-session.sh'), path.join(harnessDir, 'scripts/lib/tmux-session.sh'));
 copyFile(path.join(runnerDir, 'adapters/shared/tmux-viewer.sh'), path.join(harnessDir, 'scripts/lib/tmux-viewer.sh'));
 copyFile(path.join(runnerDir, 'adapters/shared/log-tui.mjs'), path.join(harnessDir, 'scripts/lib/log-tui.mjs'));
+copyFile(path.join(runnerDir, 'adapters/shared/browser-resolver.cjs'), path.join(harnessDir, 'scripts/lib/browser-resolver.cjs'));
+copyFile(path.join(runnerDir, 'adapters/shared/browser-cdp.cjs'), path.join(harnessDir, 'scripts/lib/browser-cdp.cjs'));
 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/playwright-cdp.cjs'), path.join(harnessDir, 'scripts/lib/playwright-cdp.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/lib/slot-title.cjs'), path.join(harnessDir, 'scripts/lib/slot-title.cjs'));

package/adapters/extension/launch-browser.cjs

@@ -3,7 +3,10 @@
 //
 // Purpose:
 //   Spawns a detached Chrome bound to 127.0.0.1:<cdp-port> with its own
-//   profile and the runtime dist loaded as an unpacked extension.
+//   profile and the runtime dist loaded as an unpacked extension: by
+//   --load-extension, or over CDP (Extensions.loadUnpacked) for branded Chrome,
+//   which ignores that flag. The browser choice comes from
+//   <runtime>/browser-resolution.json when it names --chrome-bin.
 //
 // Inputs (flags, all required):
 //   --cdp-port <port> --chrome-bin <path> --profile <dir>
@@ -11,7 +14,8 @@
 //   Env is sanitized for the child (DYLD_*, PYTHON*, BUNDLED_DEBUGPY_PATH).
 //
 // Outputs:
-//   <chrome-pid> pid file; <chrome-log> append-log.
+//   <chrome-pid> pid file; <chrome-log> append-log;
+//   <runtime>/browser-resolution.json (browser, version, loading method, pid).
 //   Exit 0 — spawned; non-zero — invalid/missing args, missing chrome binary,
 //   or missing dist manifest (thrown error message on stderr).
 //
@@ -24,6 +28,12 @@ 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');
+// The installed overlay flattens shared helpers into scripts/lib/.
+const browserResolverPath = [
+  path.join(__dirname, 'lib/browser-resolver.cjs'),
+  path.join(__dirname, '../shared/browser-resolver.cjs'),
+].find((candidate) => fs.existsSync(candidate));
+const { CDP_LOAD_UNPACKED, describeBrowser, extensionLaunchArgs, waitForCdpOwner } = require(browserResolverPath);
 const { profileProcessPids, stopProfileProcessesSync } = require('./lib/validation-process-ownership.cjs');
 const { acquireBuildHandoff } = require('./build-handoff.cjs');
 const {
@@ -45,14 +55,12 @@ const {
 const {
   captureMacFrontmost,
   macBackgroundOpenArgs,
-  preserveMacFrontmost,
-  startMacFocusHold,
-  stopMacFocusHold,
+  restoreFrontmostIfOurs,
 } = require('./lib/macos-focus.cjs');
 
 if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log(
-    'Usage: launch-browser.cjs --cdp-port <port> --chrome-bin <path> --profile <dir> --extension-dir <dist> --chrome-log <file> --chrome-pid <file>',
+    'Usage: launch-browser.cjs --cdp-port <port> --chrome-bin <path> --profile <dir> --extension-dir <dist> --chrome-log <file> --chrome-pid <file> [--browser-resolution <resolver record>]',
   );
   process.exit(0);
 }
@@ -145,6 +153,10 @@ if (requestedProfileQuarantined || (portQuarantine && !activeValidationLease)) {
 }
 
 const initialUrl = args['start-url'] || extensionHomeUrl(args['extension-dir']) || 'chrome://extensions/';
+const browser = launchBrowserResolution(args['browser-resolution'], args['chrome-bin']);
+const loadsOverCdp = browser.extensionLoading === CDP_LOAD_UNPACKED;
+let cdpLoad = null;
+let owner = null;
 const runtimeNonce = createRuntimeIdentityNonce();
 const startedAt = Date.now();
 const chromeArgs = [
@@ -162,17 +174,20 @@ const chromeArgs = [
   '--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,
+  ...extensionLaunchArgs(args['extension-dir'], browser.extensionLoading),
 ];
+// 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. On macOS the browser starts
+// through Launch Services in the background with no startup window (Chrome
+// activates itself when it opens one), and the first window is opened over
+// CDP as a background window. A CDP-loaded extension does not exist yet at
+// startup, so its window is opened after the load.
+const application = process.platform === 'darwin' ? macApplicationForExecutable(args['chrome-bin']) : null;
+if (application) chromeArgs.push('--no-startup-window');
+else chromeArgs.push(loadsOverCdp ? 'about:blank' : initialUrl);
 const logFd = fs.openSync(args['chrome-log'], 'a');
 const previousFrontmost = captureMacFrontmost();
-const application = process.platform === 'darwin' ? macApplicationForExecutable(args['chrome-bin']) : null;
-const focusHold = startMacFocusHold(previousFrontmost, application);
 let browserPid;
 try {
   try {
@@ -207,6 +222,9 @@ try {
         );
       }
     }
+    if (loadsOverCdp) cdpLoad = loadExtensionOverCdp(browserPid);
+    else if (application) openBackgroundWindow(initialUrl);
+    owner = cdpLoad?.owner ?? ownerIdentity(browserPid);
     for (const problem of pruneExtraHomeTabs(cdpPort, args['extension-dir'])) {
       process.stderr.write(`[launch] home-tab pruning: ${problem}\n`);
     }
@@ -214,6 +232,16 @@ try {
     fs.closeSync(logFd);
   }
   fs.writeFileSync(args['chrome-pid'], `${browserPid}\n`);
+  writeBrowserResolution(runtimeDir, {
+    ...browser,
+    launch: {
+      pid: browserPid,
+      cdpPort,
+      startedAt: new Date(startedAt).toISOString(),
+      ...(owner ? { profile: owner.profile, processStartedAt: owner.startedAt } : {}),
+      ...(cdpLoad ? { extensionId: cdpLoad.id, otherExtensions: cdpLoad.otherExtensions } : {}),
+    },
+  });
   try {
     writeRuntimeIdentity(runtimeDir, {
       port: cdpPort,
@@ -240,15 +268,109 @@ try {
       stdio: 'ignore',
     });
     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.
+    // Let the first window settle before the one focus check below.
     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 {
-  stopMacFocusHold(focusHold);
-  preserveMacFrontmost(previousFrontmost, application);
+  // One check, at most one restore, and only if OUR browser (this launch's
+  // CDP owner pid) holds the front; any other app in front is left alone.
+  if (browserPid) {
+    const outcome = restoreFrontmostIfOurs(previousFrontmost, [Number(browserPid)]);
+    if (outcome === 'restored') process.stderr.write(`[launch] focus: the slot browser took the front; restored ${previousFrontmost.name}\n`);
+  }
+}
+
+// The first window of a browser started without one, opened in the background.
+function openBackgroundWindow(url) {
+  const result = spawnSync(process.execPath, [browserResolverPath, 'open-window', '--port', String(cdpPort), '--url', url], {
+    encoding: 'utf8',
+    timeout: 30_000,
+  });
+  if (result.status !== 0) {
+    process.stderr.write(`[launch] could not open the start window: ${(result.stderr || result.error?.message || '').trim()}\n`);
+  }
+}
+
+// live.sh passes the record its resolver just wrote (--browser-resolution);
+// reuse it when it names the same binary. A direct --chrome-bin without it is
+// the caller's own explicit choice and is recorded as such, whatever an older
+// record of this profile says.
+function launchBrowserResolution(file, chromeBin) {
+  if (!file) return explicitResolution(chromeBin);
+  try {
+    const recorded = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (recorded && recorded.bin === chromeBin && typeof recorded.extensionLoading === 'string') {
+      const { launch: _previousLaunch, ...resolution } = recorded;
+      return resolution;
+    }
+  } catch {
+    // No resolver record for this launch; fall through to a direct description.
+  }
+  return explicitResolution(chromeBin);
+}
+
+function explicitResolution(chromeBin) {
+  return { schemaVersion: 2, ...describeBrowser(chromeBin), source: '--chrome-bin', mode: 'explicit', selection: 'explicit', resolvedAt: new Date().toISOString() };
+}
+
+function writeBrowserResolution(runtime, resolution) {
+  fs.writeFileSync(path.join(runtime, 'browser-resolution.json'), `${JSON.stringify(resolution, null, 2)}\n`);
+}
+
+function loadExtensionOverCdp(pid) {
+  const result = spawnSync(process.execPath, [
+    browserResolverPath,
+    'load-unpacked',
+    '--port', String(cdpPort),
+    '--path', args['extension-dir'],
+    '--profile', args.profile,
+    '--open-url', initialUrl,
+  ], { encoding: 'utf8', timeout: 130_000 });
+  if (result.status === 0) {
+    const loaded = JSON.parse(result.stdout);
+    process.stderr.write(`[launch] extension ${loaded.id} loaded over CDP\n`);
+    for (const entry of loaded.otherExtensions?.disabled ?? []) {
+      process.stderr.write(`[launch] disabled ${entry.id} (${entry.name}) in the slot profile\n`);
+    }
+    for (const entry of loaded.otherExtensions?.policyPinned ?? []) {
+      process.stderr.write(`[launch] WARN: enterprise policy keeps ${entry.id} (${entry.name}) enabled in the slot profile\n`);
+    }
+    return loaded;
+  }
+  // Ownership was proven; once the browser is stopped the launch markers would
+  // only quarantine a port and profile that nothing holds. If it cannot be
+  // stopped, the markers stay and both failures are reported.
+  const loadError = (result.stderr || result.error?.message || '').trim();
+  try {
+    stopProfileProcessesSync(args.profile, { extraPids: [pid] });
+  } catch (stopError) {
+    throw new Error(
+      `Chrome started but the extension did not load over CDP (${loadError}), and stopping it failed: ${stopError.message}. ` +
+        `The launch markers for port ${cdpPort} and ${args.profile} are kept. Next: stop pid ${pid}, then rerun.`,
+    );
+  }
+  clearDetachedLaunchUnproven(args.profile);
+  if (!activeValidationLease) clearValidationPortQuarantine(cdpPort, args.profile);
+  throw new Error(
+    `Chrome started but the extension did not load over CDP: ${loadError}. ` +
+      `Next: inspect ${args['chrome-log']}, or rerun with RECIPE_HARNESS_BROWSER=cft to use Chrome for Testing.`,
+  );
+}
+
+// Identity of the browser that holds the profile (pid + start time), recorded
+// so run evidence can later prove it names this exact process.
+// Best effort, so a short budget: a browser that never proves ownership (a
+// stub without a SingletonLock, say) costs seconds, not the full default.
+function ownerIdentity(pid) {
+  try {
+    const identity = waitForCdpOwner(cdpPort, args.profile, { timeoutMs: 15000 });
+    return identity.pid === pid ? identity : null;
+  } catch (error) {
+    process.stderr.write(`[launch] could not record the browser identity: ${error.message}\n`);
+    return null;
+  }
 }
 
 function sanitizedChildEnv() {