@deeeed/metamask-harness 0.2.0

package/orchestration/extension/extension-id.ts

@@ -0,0 +1,107 @@
+// extension-id.ts — deterministic extension (CRX) id resolution.
+// App control: derives the id from the loaded dist manifest key. Name keeps
+// the extension- prefix: this is the CRX id, not an instance/slot id.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Single source of truth for "which extension id is this MetaMask build".
+ *
+ * WHY THIS EXISTS. The id was resolved in three different, drifting places —
+ * host `launch-browser.sh` (Playwright candidate loop), `reopen-browser.sh`
+ * (`serviceWorkers()[0]`, which grabs Chrome's *component* extensions and broke
+ * recovery), and the harness CDP target selector. They disagreed. This module
+ * makes the runner the one resolver host launchers defer to.
+ *
+ * The id is **deterministic**: Chrome derives an unpacked extension's id from
+ * the `key` in its manifest (base64-decode → sha256 → first 16 bytes → each
+ * nibble mapped to a-p). Since the browser is launched with `--load-extension`
+ * pointing at exactly this dist, the computed id IS the loaded extension's id —
+ * no service-worker/page guessing, robust even when the MV3 worker is idle.
+ *
+ * `--cdp-port` (optional) only *verifies* the computed id is actually present in
+ * the running browser; it never changes the answer.
+ */
+
+export interface ResolveExtensionResult {
+  adapter: 'extension';
+  target: string;
+  extensionId: string | null;
+  source: 'manifest-key' | 'cdp-target' | 'none';
+  verified: boolean | null;
+}
+
+const DIST_MANIFEST = 'dist/chrome/manifest.json';
+
+/** Chrome's unpacked-extension id derivation from a manifest `key` (base64 DER). */
+export function extensionIdFromKey(keyBase64: string): string {
+  const der = Buffer.from(keyBase64, 'base64');
+  const hash = crypto.createHash('sha256').update(der).digest();
+  let id = '';
+  for (let i = 0; i < 16; i += 1) {
+    id += String.fromCharCode(97 + (hash[i] >> 4));
+    id += String.fromCharCode(97 + (hash[i] & 0xf));
+  }
+  return id;
+}
+
+function idFromDistManifest(target: string): string | null {
+  const manifestPath = path.join(target, DIST_MANIFEST);
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as { key?: unknown };
+    return typeof manifest.key === 'string' && manifest.key.length > 0
+      ? extensionIdFromKey(manifest.key)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/** chrome-extension ids visible to CDP (page targets + service workers). */
+async function cdpExtensionIds(cdpPort: number): Promise<string[]> {
+  try {
+    const res = await fetch(`http://127.0.0.1:${cdpPort}/json/list`, { signal: AbortSignal.timeout(4000) });
+    if (!res.ok) return [];
+    const targets = (await res.json()) as Array<{ url?: string }>;
+    const ids = new Set<string>();
+    for (const t of targets) {
+      const m = /^chrome-extension:\/\/([^/]+)/u.exec(String(t.url ?? ''));
+      if (m) ids.add(m[1]);
+    }
+    return [...ids];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve the MetaMask extension id for a checkout. Pure file/crypto by default;
+ * `--cdp-port` adds a presence check (and a fallback when the dist has no `key`).
+ */
+export async function resolveExtensionId(
+  target: string,
+  options: { cdpPort?: number } = {},
+): Promise<ResolveExtensionResult> {
+  const resolved = path.resolve(target);
+  const fromKey = idFromDistManifest(resolved);
+  let cdpIds: string[] | null = null;
+  if (options.cdpPort) cdpIds = await cdpExtensionIds(options.cdpPort);
+
+  if (fromKey) {
+    return {
+      adapter: 'extension',
+      target: resolved,
+      extensionId: fromKey,
+      source: 'manifest-key',
+      verified: cdpIds ? cdpIds.includes(fromKey) : null,
+    };
+  }
+  // No `key` in the dist manifest (rare). Fall back to a live CDP id if exactly
+  // one extension is loaded; otherwise we cannot disambiguate deterministically.
+  if (cdpIds && cdpIds.length === 1) {
+    return { adapter: 'extension', target: resolved, extensionId: cdpIds[0], source: 'cdp-target', verified: true };
+  }
+  return { adapter: 'extension', target: resolved, extensionId: null, source: 'none', verified: cdpIds ? false : null };
+}

package/orchestration/extension/inject.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+// inject.mjs — install the extension harness overlay
+//
+// Purpose:
+//   Installs the runner delegate, action manifests, recipe snapshots and
+//   helper scripts into the target's ignored harness dir (overlay only).
+//
+// Inputs (flags / env):
+//   --target <metamask-extension> (default $PWD)
+//   --no-git-exclude              skip .git/info/exclude updates
+//   env RECIPE_HARNESS_ROOT, METAMASK_RUNNER_DIR,
+//   METAMASK_RUNNER_PROTOCOL_ROOT > FARMSLOT_ROOT > <runner>/.farmslot-root
+//
+// Outputs:
+//   <harness>/{manifest.json,action-manifest.json,runner/,scripts/,
+//   installed-scripts.sha256,added-git-exclude}; pass JSON on stdout.
+//   Exit 0 — installed; 2 — bad args; non-zero — refusal (not an extension
+//   checkout, symlink path component) via thrown error.
+//
+// Never touches: product source files; anything outside the target's
+// harness dir and the target's .git/info/exclude.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import process from 'node:process';
+import { recipeHarnessRoot } from '../lib/recipe-paths.mjs';
+
+function usage() {
+  console.error('Usage: inject-extension-harness.mjs [--target <metamask-extension>] [--no-git-exclude]');
+}
+
+let target = process.cwd();
+let gitExclude = true;
+for (let i = 2; i < process.argv.length; i += 1) {
+  const arg = process.argv[i];
+  if (arg === '--target') {
+    if (i + 1 >= process.argv.length) { usage(); process.exit(2); }
+    target = process.argv[++i];
+  } else if (arg === '--no-git-exclude') {
+    gitExclude = false;
+  } else if (arg === '-h' || arg === '--help') {
+    usage(); process.exit(0);
+  } else {
+    console.error(`inject-extension-harness: unknown arg: ${arg}`);
+    usage(); process.exit(2);
+  }
+}
+
+target = path.resolve(target);
+const runnerRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../..');
+const harnessRoot = harnessRootValue();
+const harnessRel = `${harnessRoot}/extension`;
+const harnessDir = path.join(target, harnessRel);
+const runnerDir = process.env.METAMASK_RUNNER_DIR || runnerRoot;
+const runnerRevision = gitHead(runnerDir);
+const runnerPackageVersion = readPackageVersion(runnerDir);
+const protocolRoot = process.env.METAMASK_RUNNER_PROTOCOL_ROOT || process.env.METAMASK_RUNNER_FARMSLOT_ROOT || process.env.FARMSLOT_ROOT || configuredProtocolRoot(runnerDir);
+
+assertExtensionRoot(target);
+for (const rel of [harnessRel, `${harnessRel}/runner`, `${harnessRel}/action-manifest.json`]) {
+  refuseSymlinkDestination(target, rel);
+}
+
+fs.rmSync(path.join(harnessDir, 'runner'), { recursive: true, force: true });
+fs.mkdirSync(path.join(harnessDir, 'runner/bin'), { recursive: true });
+fs.mkdirSync(path.join(harnessDir, 'runner/manifests'), { recursive: true });
+fs.mkdirSync(path.join(harnessDir, 'runner/recipes'), { recursive: true });
+fs.rmSync(path.join(harnessDir, 'scripts'), { recursive: true, force: true });
+fs.mkdirSync(path.join(harnessDir, 'scripts/lib'), { recursive: true });
+
+const delegate = [
+  '#!/usr/bin/env bash',
+  'set -euo pipefail',
+  protocolRoot ? `export FARMSLOT_ROOT=\${FARMSLOT_ROOT:-${shellQuote(protocolRoot)}}` : null,
+  `exec ${shellQuote(path.join(runnerDir, 'orchestration/porcelain/metamask-recipe'))} "$@"`,
+].filter(Boolean).join('\n') + '\n';
+fs.writeFileSync(path.join(harnessDir, 'runner/bin/metamask-recipe'), delegate, { mode: 0o755 });
+if (protocolRoot) fs.writeFileSync(path.join(harnessDir, 'runner/.farmslot-root'), `${protocolRoot}\n`);
+fs.writeFileSync(path.join(harnessDir, 'runner/.runner-source'), `${runnerDir}\n`);
+copyFile(path.join(runnerDir, 'library/manifests/mobile.action-manifest.json'), path.join(harnessDir, 'runner/manifests/mobile.action-manifest.json'));
+copyFile(path.join(runnerDir, 'library/manifests/extension.action-manifest.json'), path.join(harnessDir, 'runner/manifests/extension.action-manifest.json'));
+copyFile(path.join(runnerDir, 'library/manifests/extension.action-manifest.json'), path.join(harnessDir, 'action-manifest.json'));
+copyDir(path.join(runnerDir, 'library/recipes'), path.join(harnessDir, 'runner/recipes'));
+// Canonical recipe-library snapshot: flows/ + library.json so the installed
+// harness mirrors the runner's library layout.
+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.
+copyFile(path.join(runnerDir, 'orchestration/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, 'orchestration/extension/launch-browser.cjs'), path.join(harnessDir, 'scripts/launch-chrome-detached.cjs'));
+copyFile(path.join(runnerDir, 'orchestration/extension/console-tail.mjs'), path.join(harnessDir, 'scripts/console-tail.mjs'));
+copyFile(path.join(runnerDir, 'orchestration/extension/launch.sh'), path.join(harnessDir, 'scripts/launch.sh'));
+copyFile(path.join(runnerDir, 'orchestration/extension/live.sh'), path.join(harnessDir, 'scripts/live.sh'));
+copyFile(path.join(runnerDir, 'orchestration/extension/start-watch.sh'), path.join(harnessDir, 'scripts/start-watch.sh'));
+copyFile(path.join(runnerDir, 'orchestration/extension/snapshot-dist.sh'), path.join(harnessDir, 'scripts/snapshot-dist.sh'));
+copyFile(path.join(runnerDir, 'orchestration/extension/pin-remote-flags.cjs'), path.join(harnessDir, 'scripts/pin-remote-flags.cjs'));
+copyFile(path.join(runnerDir, 'orchestration/extension/seed-fixture.sh'), path.join(harnessDir, 'scripts/seed-fixture.sh'));
+copyFile(path.join(runnerDir, 'orchestration/extension/sidepanel-toggle.sh'), path.join(harnessDir, 'scripts/sidepanel-toggle.sh'));
+copyFile(path.join(runnerDir, 'orchestration/extension/readiness.mjs'), path.join(harnessDir, 'scripts/readiness.mjs'));
+copyFile(path.join(runnerDir, 'orchestration/extension/wallet-fixture-state.cjs'), path.join(harnessDir, 'scripts/wallet-fixture-state.cjs'));
+copyFile(path.join(runnerDir, 'runner/extension/verify.sh'), path.join(harnessDir, 'scripts/verify.sh'));
+copyFile(path.join(runnerDir, 'orchestration/extension/refresh-build.sh'), path.join(harnessDir, 'scripts/refresh-build.sh'));
+copyFile(path.join(runnerDir, 'orchestration/extension/ensure-browser.sh'), path.join(harnessDir, 'scripts/reopen-browser.sh'));
+copyFile(path.join(runnerDir, 'orchestration/lib/harness-path.sh'), path.join(harnessDir, 'scripts/lib/harness-path.sh'));
+copyFile(path.join(runnerDir, 'orchestration/lib/activate-repo-node.sh'), path.join(harnessDir, 'scripts/lib/activate-repo-node.sh'));
+copyFile(path.join(runnerDir, 'orchestration/lib/resolve-farmslot-ports.sh'), path.join(harnessDir, 'scripts/lib/resolve-farmslot-ports.sh'));
+copyFile(path.join(runnerDir, 'orchestration/lib/path-defaults.json'), path.join(harnessDir, 'scripts/lib/path-defaults.json'));
+copyFile(path.join(runnerDir, 'orchestration/lib/recipe-paths.mjs'), path.join(harnessDir, 'scripts/lib/recipe-paths.mjs'));
+copyFile(path.join(runnerDir, 'orchestration/lib/json-field.sh'), path.join(harnessDir, 'scripts/lib/json-field.sh'));
+copyFile(path.join(runnerDir, 'orchestration/lib/cli-color.mjs'), path.join(harnessDir, 'scripts/lib/cli-color.mjs'));
+copyFile(path.join(runnerDir, 'orchestration/lib/log-tui.mjs'), path.join(harnessDir, 'scripts/lib/log-tui.mjs'));
+copyFile(path.join(runnerDir, 'orchestration/lib/progress.mjs'), path.join(harnessDir, 'scripts/lib/progress.mjs'));
+copyFile(path.join(runnerDir, 'orchestration/lib/cli-version.mjs'), path.join(harnessDir, 'scripts/lib/cli-version.mjs'));
+makeExecutableTree(path.join(harnessDir, 'scripts'));
+fs.writeFileSync(path.join(harnessDir, 'installed-scripts.sha256'), `${dirContentHash(path.join(harnessDir, 'scripts'))}\n`);
+
+const cleanupScript = path.join(runnerDir, 'orchestration/extension/cleanup.mjs');
+const cleanupCommand = `RECIPE_HARNESS_ROOT=${harnessRoot} ${shellQuote(cleanupScript)} --target ${shellQuote(target)}`;
+const manifest = {
+  adapter: 'extension',
+  installedAt: new Date().toISOString(),
+  runnerPackageVersion,
+  source: {
+    runnerDir,
+    runnerRevision,
+    runnerSourceKind: process.env.METAMASK_RUNNER_SOURCE_KIND || 'runner-self',
+  },
+  target,
+  protocolVersion: 'v1',
+  actionManifestPath: `${harnessRel}/action-manifest.json`,
+  runnerEntrypoint: `${harnessRel}/runner/bin/metamask-recipe`,
+  installedPaths: [`${harnessRel}/scripts`, `${harnessRel}/runner`, `${harnessRel}/action-manifest.json`, `${harnessRel}/manifest.json`],
+  runtimeHelpers: {
+    live: `${harnessRel}/scripts/live.sh`,
+    refreshBuild: `${harnessRel}/scripts/refresh-build.sh`,
+    reopenBrowser: `${harnessRel}/scripts/reopen-browser.sh`,
+    sidepanelToggle: `${harnessRel}/scripts/sidepanel-toggle.sh`,
+  },
+  patchedFiles: [],
+  backupDir: null,
+  cleanupCommand,
+  productDiffExcludes: [`:(exclude)${harnessRoot}`],
+};
+fs.writeFileSync(path.join(harnessDir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+
+if (gitExclude) addGitExclude(target, `${harnessRoot}/`, harnessDir);
+
+const ensureDeps = path.join(runnerDir, 'orchestration/lib/ensure-runner-deps.sh');
+if (fs.existsSync(ensureDeps)) {
+  const ensured = spawnSync('bash', [ensureDeps, runnerDir], { stdio: 'inherit' });
+  if (ensured.status !== 0) process.exit(ensured.status ?? 1);
+}
+
+console.log(JSON.stringify({ status: 'pass', adapter: 'extension', harnessDir, manifestPath: path.join(harnessDir, 'manifest.json'), runnerEntrypoint: manifest.runnerEntrypoint }, null, 2));
+
+function harnessRootValue() {
+  return recipeHarnessRoot();
+}
+
+function assertExtensionRoot(dir) {
+  const packageJson = path.join(dir, 'package.json');
+  if (!fs.existsSync(packageJson)) throw new Error(`Target is not a MetaMask Extension checkout: ${dir}`);
+  const text = fs.readFileSync(packageJson, 'utf8');
+  if (!text.includes('metamask-extension') && !path.basename(dir).startsWith('metamask-extension')) {
+    throw new Error(`Target is not a MetaMask Extension checkout: ${dir}`);
+  }
+}
+
+function refuseSymlinkDestination(root, rel) {
+  let current = root;
+  for (const part of rel.split('/').filter(Boolean)) {
+    current = path.join(current, part);
+    if (fs.existsSync(current) && fs.lstatSync(current).isSymbolicLink()) {
+      throw new Error(`Refusing extension recipe harness install: ${rel} contains symlink component ${current}`);
+    }
+  }
+}
+
+function copyFile(src, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+function copyDir(src, dest) {
+  fs.rmSync(dest, { recursive: true, force: true });
+  fs.mkdirSync(dest, { recursive: true });
+  if (!fs.existsSync(src)) return;
+  fs.cpSync(src, dest, { recursive: true });
+}
+
+function makeExecutableTree(dir) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const file = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      makeExecutableTree(file);
+    } else if (/\.(?:sh|js|cjs|mjs)$/u.test(entry.name)) {
+      fs.chmodSync(file, 0o755);
+    }
+  }
+}
+
+function dirContentHash(dir) {
+  const files = [];
+  collectFiles(dir, files);
+  const hashes = files.sort().map((file) => {
+    const relative = path.relative(dir, file);
+    const content = spawnSync('shasum', ['-a', '256', file], { encoding: 'utf8' });
+    if (content.status !== 0) throw new Error(`Failed to hash ${file}: ${content.stderr}`);
+    return `${content.stdout.trim()}  ${relative}`;
+  }).join('\n');
+  const result = spawnSync('shasum', ['-a', '256'], { input: hashes, encoding: 'utf8' });
+  if (result.status !== 0) throw new Error(`Failed to hash extension scripts: ${result.stderr}`);
+  return result.stdout.trim().split(/\s+/u)[0];
+}
+
+function collectFiles(dir, files) {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const file = path.join(dir, entry.name);
+    if (entry.isDirectory()) collectFiles(file, files);
+    else if (entry.isFile()) files.push(file);
+  }
+}
+
+function gitHead(dir) {
+  const result = spawnSync('git', ['-C', dir, 'rev-parse', 'HEAD'], { encoding: 'utf8' });
+  return result.status === 0 ? result.stdout.trim() : 'unknown';
+}
+
+function readPackageVersion(dir) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    return pkg.version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function configuredProtocolRoot(dir) {
+  const file = path.join(dir, '.farmslot-root');
+  return fs.existsSync(file) ? fs.readFileSync(file, 'utf8').trim() : '';
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function addGitExclude(repo, entry, harnessDir) {
+  const check = spawnSync('git', ['-C', repo, 'check-ignore', '-q', entry.replace(/\/$/u, '')]);
+  if (check.status === 0) return;
+  const gitDirResult = spawnSync('git', ['-C', repo, 'rev-parse', '--git-dir'], { encoding: 'utf8' });
+  if (gitDirResult.status !== 0) return;
+  let gitDir = gitDirResult.stdout.trim();
+  if (!path.isAbsolute(gitDir)) gitDir = path.join(repo, gitDir);
+  const excludeFile = path.join(gitDir, 'info/exclude');
+  fs.mkdirSync(path.dirname(excludeFile), { recursive: true });
+  const existing = fs.existsSync(excludeFile) ? fs.readFileSync(excludeFile, 'utf8').split('\n') : [];
+  if (!existing.includes(entry)) {
+    fs.appendFileSync(excludeFile, `${entry}\n`);
+    fs.appendFileSync(path.join(harnessDir, 'added-git-exclude'), `${entry}\n`);
+  }
+}

package/orchestration/extension/launch-browser.cjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+// launch-browser.cjs — per-instance isolated detached Chrome spawn
+//
+// 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.
+//
+// Inputs (flags, all required):
+//   --cdp-port <port> --chrome-bin <path> --profile <dir>
+//   --extension-dir <dist> --chrome-log <file> --chrome-pid <file>
+//   Env is sanitized for the child (DYLD_*, PYTHON*, BUNDLED_DEBUGPY_PATH).
+//
+// Outputs:
+//   <chrome-pid> pid file; <chrome-log> append-log.
+//   Exit 0 — spawned; non-zero — invalid/missing args, missing chrome binary,
+//   or missing dist manifest (thrown error message on stderr).
+//
+// Never touches: the extension dist (read-only), anything outside the
+// profile/log/pid paths it was given.
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync, spawn, spawnSync } = require('node:child_process');
+
+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>',
+  );
+  process.exit(0);
+}
+
+const args = parseArgs(process.argv.slice(2));
+const cdpPort = Number(args['cdp-port']);
+if (!Number.isInteger(cdpPort) || cdpPort <= 0) {
+  throw new Error(`Invalid --cdp-port: ${args['cdp-port'] || ''}`);
+}
+for (const key of ['chrome-bin', 'profile', 'extension-dir', 'chrome-log', 'chrome-pid']) {
+  if (!args[key]) throw new Error(`Missing --${key}`);
+}
+if (!fs.existsSync(args['chrome-bin'])) throw new Error(`Chrome binary not found: ${args['chrome-bin']}`);
+if (!fs.existsSync(path.join(args['extension-dir'], 'manifest.json'))) {
+  throw new Error(`Extension dist manifest not found: ${path.join(args['extension-dir'], 'manifest.json')}`);
+}
+
+// Isolation guard: a standalone launch must use a per-checkout profile, never a
+// shared (e.g. ~/.chrome-farmslot) or the OS-default browser profile. Farm dispatch
+// injects its own already-isolated profile via runtime-context, so this only trips
+// on a genuinely personal/shared path — protecting the user's browser data.
+assertIsolatedProfile(args.profile);
+
+fs.mkdirSync(args.profile, { recursive: true });
+fs.mkdirSync(path.dirname(args['chrome-log']), { recursive: true });
+fs.mkdirSync(path.dirname(args['chrome-pid']), { recursive: true });
+
+// Ownership guard: only ever take over a CDP endpoint we provably launched. A pid
+// on this port is ours iff its command line loads our --user-data-dir; anything
+// else is a browser this harness did not launch (possibly the user's personal
+// Chrome), so we refuse rather than kill it or attach to it.
+const listenerPids = cdpListenerPids(cdpPort);
+const foreignPids = listenerPids.filter((pid) => !processLoadsProfile(pid, args.profile));
+if (foreignPids.length > 0) {
+  throw new Error(
+    `Refusing to launch on CDP port ${cdpPort}: it is held by a browser this harness did not launch (pid ${foreignPids.join(', ')}). ` +
+    `Next: pick a free --cdp-port, or stop that browser.`,
+  );
+}
+const ownedPids = new Set(listenerPids);
+const previousPid = readPidFile(args['chrome-pid']);
+if (previousPid !== null && processLoadsProfile(previousPid, args.profile)) ownedPids.add(previousPid);
+terminatePids([...ownedPids]);
+removeProfileSingletonLocks(args.profile);
+
+const logFd = fs.openSync(args['chrome-log'], 'a');
+let child;
+try {
+  child = spawn(args['chrome-bin'], [
+    `--user-data-dir=${args.profile}`,
+    '--remote-debugging-address=127.0.0.1',
+    `--remote-debugging-port=${cdpPort}`,
+    '--no-first-run',
+    '--disable-first-run-ui',
+    '--disable-default-apps',
+    '--disable-popup-blocking',
+    '--disable-extensions-file-access-check',
+    '--disable-extensions-content-verification',
+    '--disable-features=ExtensionContentVerification,DisableLoadExtensionCommandLineSwitch',
+    `--disable-extensions-except=${args['extension-dir']}`,
+    `--load-extension=${args['extension-dir']}`,
+    'chrome://extensions/',
+  ], {
+    detached: true,
+    env: {
+      ...process.env,
+      BUNDLED_DEBUGPY_PATH: undefined,
+      PYTHONHOME: undefined,
+      PYTHONPATH: undefined,
+      DYLD_LIBRARY_PATH: undefined,
+      DYLD_FALLBACK_LIBRARY_PATH: undefined,
+      DYLD_INSERT_LIBRARIES: undefined,
+    },
+    stdio: ['ignore', logFd, logFd],
+  });
+} finally {
+  fs.closeSync(logFd);
+}
+child.unref();
+fs.writeFileSync(args['chrome-pid'], `${child.pid}\n`);
+
+function parseArgs(argv) {
+  const parsed = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) throw new Error(`Unknown positional argument: ${arg}`);
+    if (i + 1 >= argv.length) throw new Error(`Missing value for ${arg}`);
+    parsed[arg.slice(2)] = argv[i + 1];
+    i += 1;
+  }
+  return parsed;
+}
+
+function assertIsolatedProfile(profile) {
+  const resolved = path.resolve(profile);
+  const home = os.homedir();
+  const osDefaults = [
+    path.join(home, 'Library/Application Support/Google/Chrome'),
+    path.join(home, 'Library/Application Support/Chromium'),
+    path.join(home, 'Library/Application Support/Microsoft Edge'),
+    path.join(home, '.config/google-chrome'),
+    path.join(home, '.config/chromium'),
+    path.join(home, '.config/microsoft-edge'),
+  ];
+  const underDefault = (dir) => resolved === dir || resolved.startsWith(`${dir}${path.sep}`);
+  if (resolved === home || resolved.includes(`${path.sep}.chrome-farmslot`) || osDefaults.some(underDefault)) {
+    throw new Error(
+      `Refusing to launch: --profile ${resolved} is a shared or default browser profile; ` +
+      `standalone launches must use a per-checkout profile under the harness runtime dir.`,
+    );
+  }
+}
+
+// Proof of ownership: a process is ours iff its command line loads the exact
+// --user-data-dir we launch with. If the process can't be inspected we treat it
+// as NOT ours (fail safe — never assume ownership of an opaque process).
+function processLoadsProfile(pid, profile) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    const command = execFileSync('ps', ['-ww', '-o', 'command=', '-p', String(pid)], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return command.includes(`--user-data-dir=${profile}`);
+  } catch {
+    return false;
+  }
+}
+
+function readPidFile(file) {
+  if (!fs.existsSync(file)) return null;
+  const pid = Number.parseInt(fs.readFileSync(file, 'utf8').trim(), 10);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+function cdpListenerPids(port) {
+  try {
+    return execFileSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+      .split(/\s+/u)
+      .map((value) => Number.parseInt(value, 10))
+      .filter((pid) => Number.isInteger(pid) && pid > 0);
+  } catch (error) {
+    if (error.status === 1) return [];
+    throw error;
+  }
+}
+
+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) {
+    spawnSync('sleep', ['0.2']);
+  }
+  for (const pid of unique) {
+    if (pidAlive(pid)) signalPid(pid, 'SIGKILL');
+  }
+}
+
+function signalPid(pid, signal) {
+  try {
+    process.kill(pid, signal);
+    return true;
+  } catch (error) {
+    if (error.code === 'ESRCH') return false;
+    throw error;
+  }
+}
+
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error.code === 'ESRCH') return false;
+    throw error;
+  }
+}
+
+function removeProfileSingletonLocks(profile) {
+  for (const name of ['SingletonLock', 'SingletonSocket', 'SingletonCookie']) {
+    const file = path.join(profile, name);
+    if (fs.existsSync(file)) fs.rmSync(file, { force: true });
+  }
+}