@deeeed/metamask-harness 0.50.0 → 0.50.1

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.50.1 - 2026-09-08
+
+- Hand Extension builds to a fresh background worker before readiness, including watched edits and quick reloads, while preserving wallet profiles and native sidepanels. Refuse development copies over release artifacts.
+
 ## 0.50.0 - 2026-09-08
 
 - Bind Mobile order assertions and cleanup to accepted receipts, exact TP/SL values and complete snapshots. iOS passed one limit cancellation and one protected-market close; protected limits, full recipes, CUF and Android remain unvalidated.

package/adapters/extension/build-handoff.cjs

@@ -0,0 +1,198 @@
+// Replace an unpacked build while its extension is disabled, preserving storage and native panels.
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { connectBrowserViaCdp, evaluatePageViaCdp } = require('./lib/playwright-cdp.cjs');
+const { RUNTIME_IDENTITY_FILENAME, RUNTIME_NONCE_PREFIX } = require('./lib/chrome-args.cjs');
+const { stampRuntimeTitles } = require('./stamp-runtime-title.cjs');
+
+function acquireBuildHandoff(runtimeDir) {
+  const lock = path.join(runtimeDir, 'extension-build-handoff.lock');
+  const deadline = Date.now() + 30_000;
+  while (true) {
+    try {
+      const descriptor = fs.openSync(lock, 'wx', 0o600);
+      fs.writeFileSync(descriptor, String(process.pid));
+      fs.closeSync(descriptor);
+      return () => fs.rmSync(lock, { force: true });
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      let owner;
+      try { owner = Number(fs.readFileSync(lock, 'utf8')); } catch (readError) {
+        if (readError.code === 'ENOENT') continue;
+        throw readError;
+      }
+      if (Number.isInteger(owner) && owner > 0) {
+        try { process.kill(owner, 0); } catch (ownerError) {
+          if (ownerError.code !== 'ESRCH') throw ownerError;
+          fs.rmSync(lock, { force: true });
+          continue;
+        }
+      }
+      if (Date.now() >= deadline) throw new Error('Extension build handoff is busy. Next: wait for the current launch to finish.');
+      spawnSync('sleep', ['0.1']);
+    }
+  }
+}
+
+async function sidePanelContexts(context, url, windowIds = []) {
+  const page = await context.newPage();
+  const session = await context.newCDPSession(page);
+  const key = 'mm-harness:build-handoff:side-panel';
+  let preload;
+  try {
+    await session.send('Page.enable');
+    // Capture Chrome APIs before LavaMoat scuttles globals in the extension page.
+    preload = await session.send('Page.addScriptToEvaluateOnNewDocument', {
+      source: `(() => {
+        const read = chrome.runtime.getContexts.bind(chrome.runtime);
+        const open = chrome.sidePanel.open.bind(chrome.sidePanel);
+        const listWindows = chrome.windows.getAll.bind(chrome.windows);
+        globalThis[Symbol.for(${JSON.stringify(key)})] = async (windowIds) => {
+          await Promise.all(windowIds.map(windowId => open({ windowId })));
+          const [panels, windows] = await Promise.all([read({ contextTypes: ['SIDE_PANEL'] }), listWindows({ windowTypes: ['normal'] })]);
+          // Chromium can omit a panel's window ID; only one normal window is unambiguous.
+          return panels.map(panel => ({ ...panel, windowId: panel.windowId >= 0 ? panel.windowId : windows.length === 1 ? windows[0].id : -1 }));
+        };
+      })();`,
+    });
+    await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 15_000 });
+    const result = await session.send('Runtime.evaluate', {
+      expression: `globalThis[Symbol.for(${JSON.stringify(key)})](${JSON.stringify(windowIds)})`,
+      userGesture: windowIds.length > 0,
+      awaitPromise: true,
+      returnByValue: true,
+    });
+    if (result.exceptionDetails) throw new Error(`Extension sidepanel restoration failed: ${result.exceptionDetails.exception?.description ?? result.exceptionDetails.text}. Next: mm-harness launch --adapter extension --display-mode fullscreen`);
+    return result.result.value;
+  } finally {
+    if (!page.isClosed()) {
+      if (preload) await session.send('Page.removeScriptToEvaluateOnNewDocument', { identifier: preload.identifier });
+      await session.send('Runtime.evaluate', { expression: `delete globalThis[Symbol.for(${JSON.stringify(key)})]` });
+      await session.detach();
+      await page.close();
+    }
+  }
+}
+
+async function handoffRuntimeBuild({ target, runtimeDist, dist, cdpPort }) {
+  const runtimeDir = path.dirname(runtimeDist);
+  const release = acquireBuildHandoff(runtimeDir);
+  let browser;
+  let manager;
+  try {
+    if (dist && fs.existsSync(path.join(runtimeDir, 'extension-release-artifact.json'))) {
+      throw new Error('Development builds cannot replace a release artifact runtime. Next: launch the development runtime explicitly.');
+    }
+    const identityPath = path.join(runtimeDir, RUNTIME_IDENTITY_FILENAME);
+    // A watcher must not publish while a full launch has stopped the browser.
+    if (!fs.existsSync(identityPath)) {
+      if (cdpPort) throw new Error('Extension runtime ownership is missing. Next: mm-harness launch --adapter extension');
+      return false;
+    }
+    const identity = JSON.parse(fs.readFileSync(identityPath, 'utf8'));
+    if (cdpPort && Number(cdpPort) !== identity.port) throw new Error('Extension CDP port differs from its runtime owner.');
+    browser = await connectBrowserViaCdp(`http://127.0.0.1:${identity.port}`);
+    const session = await browser.newBrowserCDPSession();
+    const { arguments: command } = await session.send('Browser.getBrowserCommandLine');
+    if (!command.includes(`${RUNTIME_NONCE_PREFIX}${identity.nonce}`) || !command.includes(`--load-extension=${runtimeDist}`)) {
+      throw new Error('Extension build handoff refused a foreign browser.');
+    }
+    const context = browser.contexts()[0];
+    manager = await context.newPage();
+    await manager.goto('chrome://extensions/', { waitUntil: 'domcontentloaded', timeout: 15_000 });
+    const extensions = await evaluatePageViaCdp(manager, () => new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('Extension management timed out.')), 15_000);
+      chrome.developerPrivate.getExtensionsInfo({ includeDisabled: true, includeTerminated: true }, (entries) => {
+        clearTimeout(timer);
+        if (chrome.runtime.lastError) reject(new Error(chrome.runtime.lastError.message));
+        else resolve(entries.map(({ id, path: directory }) => ({ id, directory })));
+      });
+    }));
+    const extensionId = extensions.find((entry) => entry.directory === fs.realpathSync(runtimeDist))?.id;
+    if (!extensionId) throw new Error('Chrome has not registered the requested unpacked extension directory.');
+    const prefix = `chrome-extension://${extensionId}/`;
+    const pages = context.pages().filter((page) => page.url().startsWith(prefix)).map((page) => ({ page, url: page.url() }));
+    const oldManifest = JSON.parse(fs.readFileSync(path.join(runtimeDist, 'manifest.json'), 'utf8'));
+    const panelUrl = oldManifest.side_panel?.default_path && new URL(oldManifest.side_panel.default_path, prefix).href;
+    const panels = panelUrl && pages.some((entry) => new URL(entry.url).pathname === new URL(panelUrl).pathname)
+      ? await sidePanelContexts(context, panelUrl)
+      : [];
+    const panelWindowIds = [...new Set(panels.map((panel) => panel.windowId))];
+    if (panelWindowIds.some((id) => !Number.isInteger(id) || id < 0)) {
+      throw new Error('Extension sidepanel window is ambiguous. Next: close extra windows in this profile before reloading.');
+    }
+    const oldTargets = (await session.send('Target.getTargets')).targetInfos.filter((entry) => entry.url.startsWith(prefix));
+    async function setEnabled(enabled) {
+      await evaluatePageViaCdp(manager, ({ id, enabled: next }) => new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('Extension enable/disable timed out.')), 15_000);
+        chrome.management.setEnabled(id, next, () => {
+          clearTimeout(timer);
+          if (chrome.runtime.lastError) reject(new Error(chrome.runtime.lastError.message));
+          else resolve(true);
+        });
+      }), { id: extensionId, enabled });
+    }
+    await setEnabled(false);
+    if (dist) {
+      const copied = spawnSync('rsync', ['-a', '--delete', '--exclude', '_metadata', `${dist}/`, `${runtimeDist}/`], { encoding: 'utf8' });
+      if (copied.status !== 0) throw new Error(`Extension build copy failed: ${copied.stderr || copied.stdout}`);
+      const configured = spawnSync(process.execPath, [path.join(__dirname, 'configure-runtime-manifest.cjs'), '--target', target, '--manifest', path.join(runtimeDist, 'manifest.json')], { encoding: 'utf8' });
+      if (configured.status !== 0) throw new Error(`Extension runtime configuration failed: ${configured.stderr || configured.stdout}`);
+      stampRuntimeTitles({ target, runtimeDist });
+    }
+    await setEnabled(true);
+    for (const entry of pages) {
+      if (entry.page.isClosed() && panels.length && new URL(entry.url).pathname === new URL(panelUrl).pathname) continue;
+      const page = entry.page.isClosed() ? await context.newPage() : entry.page;
+      await page.goto(entry.url, { waitUntil: 'domcontentloaded', timeout: 15_000 });
+    }
+    const manifest = JSON.parse(fs.readFileSync(path.join(runtimeDist, 'manifest.json'), 'utf8'));
+    if (panels.length) {
+      if (!manifest.side_panel?.default_path) {
+        throw new Error('Extension sidepanel has no restorable window. Next: mm-harness launch --adapter extension --display-mode fullscreen');
+      }
+      await sidePanelContexts(context, new URL(manifest.side_panel.default_path, prefix).href, panelWindowIds);
+    }
+    if (manifest.background?.service_worker) {
+      const expected = `${prefix}${manifest.background.service_worker}`;
+      const deadline = Date.now() + 15_000;
+      let replaced = false;
+      while (Date.now() < deadline) {
+        const { targetInfos } = await session.send('Target.getTargets');
+        replaced = targetInfos.some((entry) => entry.type === 'service_worker' && entry.url === expected && !oldTargets.some((old) => old.targetId === entry.targetId));
+        if (replaced) break;
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      }
+      if (!replaced) throw new Error('Extension build handoff did not start a new background worker. Next: mm-harness launch --adapter extension');
+    }
+    return true;
+  } finally {
+    try {
+      if (manager) await manager.close().catch(() => {});
+      if (browser) await browser.close();
+    } finally {
+      release();
+    }
+  }
+}
+
+module.exports = { acquireBuildHandoff, handoffRuntimeBuild };
+
+if (require.main === module) {
+  const args = {};
+  for (let index = 2; index < process.argv.length; index += 2) {
+    const flag = process.argv[index];
+    if (flag === '--help') {
+      console.log('Usage: build-handoff.cjs --target <checkout> --runtime-dist <directory> [--dist <build>] [--cdp-port <port>]');
+      process.exit(0);
+    }
+    if (!flag.startsWith('--') || !process.argv[index + 1]) throw new Error(`Missing value for ${flag}`);
+    args[flag.slice(2)] = process.argv[index + 1];
+  }
+  if (!args.target || !args['runtime-dist']) throw new Error('build-handoff requires --target and --runtime-dist.');
+  handoffRuntimeBuild({ target: path.resolve(args.target), runtimeDist: path.resolve(args['runtime-dist']), dist: args.dist && path.resolve(args.dist), cdpPort: args['cdp-port'] })
+    .catch((error) => { console.error(`build-handoff: ${error.message}`); process.exitCode = 1; });
+}

package/adapters/extension/inject.mjs

@@ -94,6 +94,7 @@ fs.rmSync(path.join(harnessDir, 'runner/library.json'), { force: true });
 // The installed overlay has a flat scripts/ runtime API independent of the
 // package's source layout.
 copyFile(path.join(runnerDir, 'adapters/extension/launch-browser.cjs'), path.join(harnessDir, 'scripts/launch-browser.cjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/build-handoff.cjs'), path.join(harnessDir, 'scripts/build-handoff.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/console-tail.mjs'), path.join(harnessDir, 'scripts/console-tail.mjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/launch.sh'), path.join(harnessDir, 'scripts/launch.sh'));
 copyFile(path.join(runnerDir, 'adapters/extension/live.sh'), path.join(harnessDir, 'scripts/live.sh'));

package/adapters/extension/launch-browser.cjs

@@ -25,6 +25,7 @@ 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 { acquireBuildHandoff } = require('./build-handoff.cjs');
 const {
   automationRuntimeArgs,
   clearDetachedLaunchUnproven,
@@ -78,6 +79,8 @@ if (args['reset-profile'] !== undefined) assertResettableProfile(args.profile, r
 fs.mkdirSync(args.profile, { recursive: true });
 fs.mkdirSync(path.dirname(args['chrome-log']), { recursive: true });
 fs.mkdirSync(path.dirname(args['chrome-pid']), { recursive: true });
+const releaseBuildHandoff = acquireBuildHandoff(runtimeDir);
+process.on('exit', releaseBuildHandoff);
 
 // 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

package/adapters/extension/live.sh

@@ -228,6 +228,7 @@ NODE
   quoted_check_infura="$(printf '%q' "$SCRIPT_DIR/check-infura-readiness.cjs")"
   quoted_stamp_title="$(printf '%q' "$SCRIPT_DIR/stamp-runtime-title.cjs")"
   quoted_chrome_launcher="$(printf '%q' "$SCRIPT_DIR/launch-browser.cjs")"
+  quoted_build_handoff="$(printf '%q' "$SCRIPT_DIR/build-handoff.cjs")"
   quoted_artifact_state="$(printf '%q' "$SCRIPT_DIR/artifact-runtime-state.cjs")"
   quoted_fixture_state="$(printf '%q' "$FIXTURE_STATE_ABS")"
   quoted_fixture_validation="$(printf '%q' "$FIXTURE_VALIDATION_ABS")"
@@ -301,6 +302,9 @@ NODE
   quoted_chrome_log="$(printf '%q' "$ARTIFACTS/logs/chrome.log")"
   quoted_chrome_pid="$(printf '%q' "$ARTIFACTS/logs/chrome.pid")"
   prepare_parts=()
+  reset_profile_arg=""
+  $RESET_PROFILE && reset_profile_arg=" --reset-profile 1"
+  prepare_parts+=("node ${quoted_chrome_launcher} --stop-only 1${reset_profile_arg} --chrome-bin ${quoted_chrome} --profile ${quoted_profile} --cdp-port ${CDP_PORT} --extension-dir ${quoted_runtime_dist} --chrome-log ${quoted_chrome_log} --chrome-pid ${quoted_chrome_pid}")
   if $EXTERNAL_ARTIFACT; then
     quoted_artifact_provenance="$(printf '%q' "$ARTIFACT_PROVENANCE")"
   else
@@ -326,9 +330,6 @@ NODE
   if ! $EXTERNAL_ARTIFACT; then
     prepare_parts+=("node ${quoted_configure_manifest} --target ${quoted_target} --manifest ${quoted_runtime_dist}/manifest.json")
   fi
-  reset_profile_arg=""
-  $RESET_PROFILE && reset_profile_arg=" --reset-profile 1"
-  prepare_parts+=("node ${quoted_chrome_launcher} --stop-only 1${reset_profile_arg} --chrome-bin ${quoted_chrome} --profile ${quoted_profile} --cdp-port ${CDP_PORT} --extension-dir ${quoted_runtime_dist} --chrome-log ${quoted_chrome_log} --chrome-pid ${quoted_chrome_pid}")
   if ! $EXTERNAL_ARTIFACT; then
     prepare_parts+=("node ${quoted_stamp_title} --target ${quoted_target} --runtime-dist ${quoted_runtime_dist} --runtime-dir ${quoted_runtime_dir}")
   fi
@@ -352,6 +353,7 @@ NODE
   fi
   prepare_parts+=("$chrome_launch_cmd")
   prepare_parts+=("for i in {1..60}; do curl -fsS --max-time 1 http://127.0.0.1:${CDP_PORT}/json/version >/dev/null 2>&1 && break; sleep 1; done; curl -fsS --max-time 1 http://127.0.0.1:${CDP_PORT}/json/version >/dev/null")
+  prepare_parts+=("node ${quoted_build_handoff} --target ${quoted_target} --runtime-dist ${quoted_runtime_dist} --cdp-port ${CDP_PORT}")
   if [ -n "$WALLET_FIXTURE_ABS" ]; then
     prepare_parts+=("bash ${quoted_seed_fixture} seed-cdp --target ${quoted_target} --fixture ${quoted_wallet_fixture} --state ${quoted_fixture_state} --cdp-port ${CDP_PORT} --extension-dir ${quoted_runtime_dist} --extension-id-file ${quoted_extension_id_file} --out ${quoted_fixture_validation}")
   fi

package/adapters/extension/reattach.sh

@@ -93,18 +93,13 @@ else
   RUNTIME_DIR="${RECIPE_RUNTIME_DIR:-temp/recipe/runtime}"
 fi
 RUNTIME_DIST_DIR="${RECIPE_RUNTIME_DIST_DIR:-runtime-dist}"
-# The running Chrome loads this unpacked extension directory. Do not recreate or
-# rsync-delete it while Chrome is live: Chrome can keep the intended
-# chrome-extension:// target URL but serve chrome-error://chromewebdata after its
-# loaded directory is replaced underneath it. Fresh snapshots belong to the clean
-# relaunch path; quick reattach only reloads the already-loaded runtime.
+# Disable the extension before replacing its build so cached workers cannot
+# request assets from a different compilation.
 RUNTIME_DIST_ABS="$TARGET/$RUNTIME_DIR/$RUNTIME_DIST_DIR"
 echo "[reattach] reusing loaded runtime-dist: $RUNTIME_DIST_ABS" >&2
 if [ -d "$DIST_ABS" ] && [ -d "$RUNTIME_DIST_ABS" ]; then
   echo "[reattach] refreshing loaded runtime-dist in place" >&2
-  rsync -a --exclude _metadata "$DIST_ABS/" "$RUNTIME_DIST_ABS/" >&2
-  node "$SCRIPT_DIR/configure-runtime-manifest.cjs" --target "$TARGET" --manifest "$RUNTIME_DIST_ABS/manifest.json" >&2
-  node "$SCRIPT_DIR/stamp-runtime-title.cjs" --target "$TARGET" --runtime-dist "$RUNTIME_DIST_ABS" --runtime-dir "$RUNTIME_DIR" >&2
+  (cd "$TARGET" && node "$SCRIPT_DIR/build-handoff.cjs" --target "$TARGET" --dist "$DIST_ABS" --runtime-dist "$RUNTIME_DIST_ABS" --cdp-port "$CDP_PORT") >&2
 fi
 
 # Resolve the extension id: explicit flag, then the recorded id file, else CDP.
@@ -225,11 +220,8 @@ async function closePages(context, predicate) {
 }
 
 (async () => {
-  // Phase 1: attach to the already-loaded extension page. Do not call
-  // chrome.runtime.reload() here: on the slot Chrome version it can leave the
-  // target URL as chrome-extension://.../home.html while the actual document is
-  // chrome-error://chromewebdata. Clean relaunch owns loading a new unpacked
-  // runtime-dist; quick reattach only refreshes/foregrounds the live UI.
+  // The build handoff has already replaced the background worker. Reattach only
+  // arranges the requested wallet and dapp pages.
   let { browser, context } = await connect();
   const providedExtId = extensionIdFromRuntimeDist() || validExtensionId(process.env.EXT_ID);
   const extId = extensionIdFrom(context, providedExtId);

package/adapters/extension/sync-webpack-dist.cjs

@@ -1,10 +1,9 @@
 #!/usr/bin/env node
 'use strict';
 
-const { spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
-const { stampRuntimeTitles } = require('./stamp-runtime-title.cjs');
+const { handoffRuntimeBuild } = require('./build-handoff.cjs');
 
 const args = {};
 for (let index = 2; index < process.argv.length; index += 1) {
@@ -49,37 +48,16 @@ function removeOwnPidFile() {
   }
 }
 
-function syncRuntimeDist() {
+async function syncRuntimeDist() {
   if (!fs.existsSync(path.join(dist, 'manifest.json')) || !fs.existsSync(runtimeDist)) return;
-  const result = spawnSync('rsync', ['-a', '--delete', '--delay-updates', '--exclude', '_metadata', `${dist}${path.sep}`, `${runtimeDist}${path.sep}`], {
-    encoding: 'utf8',
-  });
-  if (result.status !== 0) {
-    process.stderr.write(`runtime-dist sync failed: ${(result.stderr || result.stdout || `rsync exited ${result.status}`).trim()}\n`);
-    return;
+  if (await handoffRuntimeBuild({ target: path.resolve(args.target), dist, runtimeDist })) {
+    process.stdout.write(`runtime-dist updated with a fresh background worker (${new Date().toISOString()})\n`);
+  } else {
+    process.stdout.write('build ready; waiting for an owned browser launch\n');
   }
-  const configure = spawnSync(
-    process.execPath,
-    [
-      path.join(__dirname, 'configure-runtime-manifest.cjs'),
-      '--target',
-      path.resolve(args.target),
-      '--manifest',
-      path.join(runtimeDist, 'manifest.json'),
-    ],
-    { encoding: 'utf8' },
-  );
-  if (configure.status !== 0) {
-    process.stderr.write(
-      `runtime-dist configuration failed: ${(configure.stderr || configure.stdout || `node exited ${configure.status}`).trim()}\n`,
-    );
-    return;
-  }
-  stampRuntimeTitles({ target: path.resolve(args.target), runtimeDist });
-  process.stdout.write(`runtime-dist updated after webpack compile (${new Date().toISOString()})\n`);
 }
 
-function poll() {
+async function poll() {
   if (!processAlive(watcherPid)) {
     removeOwnPidFile();
     process.exit(0);
@@ -100,7 +78,7 @@ function poll() {
       const text = carry + chunk.subarray(0, bytesRead).toString('utf8');
       const lines = text.split(/\r?\n/u);
       carry = lines.pop() || '';
-      if (lines.some((line) => compilePattern.test(line))) syncRuntimeDist();
+      if (lines.some((line) => compilePattern.test(line))) await syncRuntimeDist();
     }
   } catch (error) {
     if (error?.code !== 'ENOENT') process.stderr.write(`runtime-dist sync monitor: ${error.message}\n`);

package/adapters/manifest.json

@@ -266,6 +266,14 @@
       "inputs": "resolve|prefill|seed-cdp; --target --cdp-port --fixture --state --profile --extension-dir --extension-id-file --out --source-out --fixture-script --summary; env RECIPE_WALLET_FIXTURE",
       "outputs": "fixture path on stdout (resolve), provenance/state/parity JSON files; exit 0/1/2"
     },
+    {
+      "id": "extension/build-handoff",
+      "entry": "adapters/extension/build-handoff.cjs",
+      "kind": "node",
+      "purpose": "Replace builds with the owned extension disabled, then refresh its worker and restore native panels without clearing profile storage.",
+      "inputs": "--target --runtime-dist [--dist] [--cdp-port]",
+      "outputs": "fresh worker and optional build copy; exit 0 / non-zero"
+    },
     {
       "id": "extension/launch-browser",
       "entry": "adapters/extension/launch-browser.cjs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.50.0",
+  "version": "0.50.1",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"