@deeeed/metamask-harness 0.17.5 → 0.18.0

package/adapters/extension/launch-webpack.cjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const args = {};
+for (let index = 2; index < process.argv.length; index += 1) {
+  const key = process.argv[index];
+  if (key === '--help' || key === '-h') {
+    process.stdout.write('Usage: launch-webpack.cjs --target <path> --log <path> --pid-file <path> --sync-script <path> --sync-pid-file <path> --sync-log <path> --dist <path> --runtime-dist <path> [--port <port>] [--path-prefix <path>]\n');
+    process.exit(0);
+  }
+  if (!key.startsWith('--') || index + 1 >= process.argv.length) throw new Error(`invalid argument: ${key}`);
+  args[key.slice(2)] = process.argv[++index];
+}
+
+async function main() {
+  for (const required of ['target', 'log', 'pid-file', 'sync-script', 'sync-pid-file', 'sync-log', 'dist', 'runtime-dist']) {
+    if (!args[required]) throw new Error(`--${required} is required`);
+  }
+
+  const target = path.resolve(args.target);
+  const log = path.resolve(args.log);
+  const pidFile = path.resolve(args['pid-file']);
+  const syncScript = path.resolve(args['sync-script']);
+  const syncPidFile = path.resolve(args['sync-pid-file']);
+  const syncLog = path.resolve(args['sync-log']);
+  fs.mkdirSync(path.dirname(log), { recursive: true });
+  fs.mkdirSync(path.dirname(pidFile), { recursive: true });
+  fs.mkdirSync(path.dirname(syncLog), { recursive: true });
+  if (!fs.existsSync(syncScript)) throw new Error(`sync script not found: ${syncScript}`);
+  const logFd = fs.openSync(log, 'a');
+  const syncLogFd = fs.openSync(syncLog, 'a');
+  const env = { ...process.env };
+  if (args.port) env.PORT = String(args.port);
+  if (args['path-prefix']) env.PATH = `${args['path-prefix']}${env.PATH || ''}`;
+
+  try {
+    const child = spawn('yarn', ['start'], {
+      cwd: target,
+      detached: true,
+      env,
+      stdio: ['ignore', logFd, logFd],
+    });
+    await new Promise((resolve, reject) => {
+      child.once('spawn', resolve);
+      child.once('error', reject);
+    });
+    fs.writeFileSync(pidFile, `${child.pid}\n`);
+    const syncChild = spawn(process.execPath, [
+      syncScript,
+      '--watcher-pid', String(child.pid),
+      '--watch-log', log,
+      '--target', target,
+      '--dist', path.resolve(args.dist),
+      '--runtime-dist', path.resolve(args['runtime-dist']),
+      '--pid-file', syncPidFile,
+    ], {
+      cwd: target,
+      detached: true,
+      env,
+      stdio: ['ignore', syncLogFd, syncLogFd],
+    });
+    await new Promise((resolve, reject) => {
+      syncChild.once('spawn', resolve);
+      syncChild.once('error', reject);
+    });
+    fs.writeFileSync(syncPidFile, `${syncChild.pid}\n`);
+    process.stdout.write(`${child.pid}\n`);
+    syncChild.unref();
+    child.unref();
+  } finally {
+    fs.closeSync(logFd);
+    fs.closeSync(syncLogFd);
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`launch-webpack: ${error.message}\n`);
+  process.exit(1);
+});

package/adapters/extension/launch.sh

@@ -114,24 +114,21 @@ else
   status="fail"
 fi
 
-# Live extension-console viewer tab (default-on): tail the running extension's
-# service worker + UI-page console in a tmux window, mirroring the Metro/webpack
-# tabs. Skipped silently when there is no tmux session or CDP (headless/CI), so
-# it never affects the launch result.
+# The public CLI owns console collection after every successful launch path.
+# This leaf only adds an optional viewer when an explicitly run-owned tmux
+# session exists; the viewer tails the file and never owns the collector.
 if [ "$status" = "pass" ] && [ -n "$CDP_PORT" ] && command -v tmux >/dev/null 2>&1; then
+  console_runtime="$TARGET/$( (cd "$TARGET" && recipe_runtime_dir) 2>/dev/null || echo temp/recipe/runtime)"
+  mkdir -p "$console_runtime"
+  console_log="$console_runtime/extension-console.log"
   for _tv_src in "$SCRIPT_DIR/lib/tmux-viewer.sh" "$SCRIPT_DIR/../shared/tmux-viewer.sh"; do
     # shellcheck disable=SC1091
     [ -f "$_tv_src" ] && { . "$_tv_src"; break; }
   done
   unset _tv_src
-  console_tail="$SCRIPT_DIR/console-tail.mjs"
-  if command -v tmux_viewer_open >/dev/null 2>&1 && [ -f "$console_tail" ]; then
-    console_runtime="$TARGET/$( (cd "$TARGET" && recipe_runtime_dir) 2>/dev/null || echo temp/recipe/runtime)"
-    mkdir -p "$console_runtime"
-    console_log="$console_runtime/extension-console.log"
-    : > "$console_log"
+  if command -v tmux_viewer_open >/dev/null 2>&1; then
     tmux_viewer_open "console" "$CDP_PORT" "$console_log" "$console_runtime" "$console_runtime/console.tmux" \
-      "exec node $(printf '%q' "$console_tail") --cdp-port ${CDP_PORT} --log $(printf '%q' "$console_log")"
+      "exec tail -n +1 -F $(printf '%q' "$console_log")"
   fi
 fi
 

package/adapters/extension/lib/chrome-args.cjs

@@ -21,4 +21,11 @@ function remoteDebuggingArgs(cdpPort) {
   ];
 }
 
-module.exports = { remoteDebuggingArgs };
+// An isolated automation profile must never ask for or write credentials in the
+// operator's macOS login keychain. Chromium's mock keychain keeps profile-local
+// encryption deterministic and prevents modal prompts from blocking startup.
+function isolatedProfileArgs(platform = process.platform) {
+  return platform === 'darwin' ? ['--use-mock-keychain'] : [];
+}
+
+module.exports = { isolatedProfileArgs, remoteDebuggingArgs };

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

@@ -0,0 +1,32 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+
+function captureMacFrontmostProcess() {
+  if (process.platform !== 'darwin') return null;
+  try {
+    const value = execFileSync('osascript', [
+      '-e',
+      'tell application "System Events" to get unix id of first application process whose frontmost is true',
+    ], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    const pid = Number.parseInt(value, 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function restoreMacFrontmostProcess(pid) {
+  if (process.platform !== 'darwin' || !Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    execFileSync('osascript', [
+      '-e',
+      `tell application "System Events" to set frontmost of first application process whose unix id is ${pid} to true`,
+    ], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { captureMacFrontmostProcess, restoreMacFrontmostProcess };

package/adapters/extension/live.sh

@@ -32,6 +32,7 @@
 set -euo pipefail
 
 TARGET="$PWD"
+INVOCATION_DIR="$PWD"
 CDP_PORT=""
 ARTIFACTS=""
 OUT=""
@@ -39,7 +40,7 @@ PREPARE_CMD="${RECIPE_HARNESS_EXTENSION_LAUNCH_CMD:-}"
 LAUNCH_EXISTING_DIST=false
 START_WATCH=false
 DIST_DIR="dist/chrome"
-CHROME_USER_DATA_DIR=""
+CHROME_USER_DATA_DIR="${CHROME_USER_DATA_DIR:-}"
 REMOTE_FLAGS=""
 REMOTE_FLAGS_APPLIED=false
 while [ "$#" -gt 0 ]; do
@@ -60,6 +61,11 @@ while [ "$#" -gt 0 ]; do
   esac
 done
 
+case "$CHROME_USER_DATA_DIR" in
+  ""|/*) ;;
+  *) CHROME_USER_DATA_DIR="$INVOCATION_DIR/$CHROME_USER_DATA_DIR" ;;
+esac
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
 for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../shared/harness-path.sh"; do
@@ -100,7 +106,6 @@ if [ -z "$VERIFY_SH" ]; then
   echo "mm-harness: extension verify.sh not found next to $SCRIPT_DIR; reinstall the runner." >&2
   exit 1
 fi
-TARGET="$(cd "$TARGET" && pwd)"
 RUNTIME_DIR="$(recipe_runtime_dir)"
 RUNTIME_DIST_DIR="${RECIPE_RUNTIME_DIST_DIR:-runtime-dist}"
 CHROME_PROFILE_NAME="${RECIPE_CHROME_PROFILE_NAME:-chrome-profile}"
@@ -163,6 +168,7 @@ NODE
   quoted_seed_fixture="$(printf '%q' "$SCRIPT_DIR/seed-fixture.sh")"
   quoted_start_watch="$(printf '%q' "$SCRIPT_DIR/start-watch.sh")"
   quoted_snapshot_dist="$(printf '%q' "$SCRIPT_DIR/snapshot-dist.sh")"
+  quoted_stamp_title="$(printf '%q' "$SCRIPT_DIR/stamp-runtime-title.cjs")"
   quoted_chrome_launcher="$(printf '%q' "$SCRIPT_DIR/launch-browser.cjs")"
   quoted_fixture_state="$(printf '%q' "$FIXTURE_STATE_ABS")"
   quoted_fixture_validation="$(printf '%q' "$FIXTURE_VALIDATION_ABS")"
@@ -211,11 +217,11 @@ try {
   executable = chromium.executablePath();
 } catch (error) {
   const message = error && error.message ? error.message : String(error);
-  console.error(`[recipe-harness] Could not resolve Playwright Chromium executable: ${message}. Manual approval required before installing the Playwright Chromium browser cache (no package.json changes); ask the user before running yarn exec playwright install chromium.`);
+  console.error(`[recipe-harness] Could not resolve Playwright Chromium executable: ${message}. Manual approval required before installing the Playwright Chromium browser cache (no package.json changes); ask the user before running yarn playwright install chromium.`);
   process.exit(1);
 }
 if (!fs.existsSync(executable)) {
-  console.error(`[recipe-harness] Playwright Chromium is not installed at ${executable}. Manual approval required before installing the Playwright Chromium browser cache (no package.json changes). Ask the user for approval; if they agree, run: cd ${shellQuote(process.cwd())} && yarn exec playwright install chromium`);
+  console.error(`[recipe-harness] Playwright Chromium is not installed at ${executable}. Manual approval required before installing the Playwright Chromium browser cache (no package.json changes). Ask the user for approval; if they agree, run: cd ${shellQuote(process.cwd())} && yarn playwright install chromium`);
   console.error('[recipe-harness] To use a browser that is already installed, set RECIPE_HARNESS_CHROME_BIN=/path/to/chrome explicitly.');
   process.exit(1);
 }
@@ -227,25 +233,9 @@ NODE
     rm -f "$_chrome_probe"
   fi
 
-  if [ -z "${CHROME_BIN:-}" ]; then
-    for candidate in \
-      "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
-      "/Applications/Chromium.app/Contents/MacOS/Chromium" \
-      "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary" \
-      "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"; do
-      if [ -x "$candidate" ]; then
-        CHROME_BIN="$candidate"
-        break
-      fi
-    done
-    if [ -n "${CHROME_BIN:-}" ]; then
-      echo "[recipe-harness] WARN: Playwright Chromium unavailable; falling back to system browser: $CHROME_BIN" >&2
-    fi
-  fi
-
   if [ -z "${CHROME_BIN:-}" ]; then
     [ -n "${CHROME_PROBE_LOG:-}" ] && cat "$CHROME_PROBE_LOG" >&2 2>/dev/null || true
-    echo "[recipe-harness] No approved Chromium binary selected; stopping before live Extension launch." >&2
+    echo "[recipe-harness] No compatible Chromium binary selected; stopping before build or live Extension launch." >&2
     exit 1
   fi
   quoted_chrome="$(printf '%q' "$CHROME_BIN")"
@@ -257,6 +247,7 @@ NODE
   fi
   prepare_parts+=("node ${quoted_chrome_launcher} --stop-only 1 --reset-profile 1 --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}")
   prepare_parts+=("bash ${quoted_snapshot_dist} --dist ${quoted_dist} --runtime-dist ${quoted_runtime_dist}")
+  prepare_parts+=("node ${quoted_stamp_title} --target ${quoted_target} --runtime-dist ${quoted_runtime_dist} --runtime-dir ${quoted_runtime_dir}")
   # Optional A/B feature-flag pinning: patch the ephemeral snapshot manifest so
   # manifest._flags wins over the fetched ClientConfigApi value. No-op unless
   # --remote-flag was passed; the snapshot is re-created each run, so no revert.

package/adapters/extension/reattach.sh

@@ -103,6 +103,7 @@ 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/stamp-runtime-title.cjs" --target "$TARGET" --runtime-dist "$RUNTIME_DIST_ABS" --runtime-dir "$RUNTIME_DIR" >&2
 fi
 
 # Resolve the extension id: explicit flag, then the recorded id file, else CDP.

package/adapters/extension/seed-fixture.sh

@@ -4,15 +4,13 @@
 #
 # Purpose:
 #   Resolves which wallet fixture a slot run should use (env override then
-#   runtime-dir/legacy/port-scoped candidates) and drives the recipe-tree
+#   the checkout's canonical runtime fixture) and drives the recipe-tree
 #   wallet-fixture-state.cjs phases around the browser launch.
 #
 # Subcommands (flags):
 #   resolve   --target <repo> --cdp-port <port> [--source-out <file>]
 #             Prints the fixture path (empty if none). Chain:
-#             RECIPE_WALLET_FIXTURE env > <runtime-dir>/wallet-fixture.json >
-#             temp/runtime/ > temp/.recipe-validation-<port>/ >
-#             temp/.agent-validation/.
+#             RECIPE_WALLET_FIXTURE env > <runtime-dir>/wallet-fixture.json.
 #   prefill   --fixture <json> --target <repo> --state <file> --profile <dir>
 #             --extension-dir <dist> --extension-id-file <file>
 #             Runs fixture-state generate then prefill-profile (pre-launch).
@@ -131,14 +129,8 @@ if [ "$SUBCOMMAND" = resolve ]; then
     fi
     resolved="$RECIPE_WALLET_FIXTURE"
   else
-    for candidate in \
-      ${RUNTIME_DIR:+"$TARGET/$RUNTIME_DIR/wallet-fixture.json"} \
-      "$TARGET/temp/runtime/wallet-fixture.json" \
-      ${CDP_PORT:+"$TARGET/temp/.recipe-validation-${CDP_PORT}/wallet-fixture.json"} \
-      "$TARGET/temp/.agent-validation/wallet-fixture.json"
-    do
-      [ -f "$candidate" ] && { resolved="$candidate"; break; }
-    done
+    candidate="${RUNTIME_DIR:+$TARGET/$RUNTIME_DIR/wallet-fixture.json}"
+    [ -n "$candidate" ] && [ -f "$candidate" ] && resolved="$candidate"
   fi
   [ -n "$resolved" ] || resolve_status=missing
   if [ -n "$SOURCE_OUT" ]; then

package/adapters/extension/sidepanel-toggle.sh

@@ -289,7 +289,10 @@ const { chromium } = require('playwright');
     return { windowId: currentWindow.id };
   });
 
-  await page.locator('#__recipe_open_sidepanel__').click({ timeout: 5000 });
+  // This harness-owned button exists only to provide Chrome's trusted user
+  // gesture. Its visual layout is irrelevant and can be occluded by the app's
+  // full-screen loading surface, so do not wait on Playwright actionability.
+  await page.locator('#__recipe_open_sidepanel__').click({ timeout: 5000, force: true });
   const clickResult = await page
     .locator('#__recipe_open_sidepanel__')
     .evaluate((button) => button.dataset.result || '');

package/adapters/extension/stamp-runtime-title.cjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { readSlotId } = require('./lib/slot-title.cjs');
+
+function stampRuntimeTitles({ target, runtimeDist, runtimeDir = process.env.RECIPE_RUNTIME_DIR || 'temp/recipe/runtime' }) {
+  const slotId = readSlotId(target, runtimeDir);
+  if (!slotId) return { slotId: '', stamped: [] };
+  const stamped = [];
+  for (const name of ['home.html', 'sidepanel.html']) {
+    const file = path.join(runtimeDist, name);
+    let fd;
+    try {
+      fd = fs.openSync(file, 'r+');
+      const source = fs.readFileSync(fd, 'utf8');
+      const next = source.replace(/<title>([^<]*)<\/title>/iu, (_match, title) => {
+        const base = String(title || 'MetaMask').replace(/^.+?\s+[—–-]\s+/u, '') || 'MetaMask';
+        return `<title>${slotId} — ${base}</title>`;
+      });
+      if (next === source) continue;
+      const bytes = Buffer.from(next, 'utf8');
+      fs.writeSync(fd, bytes, 0, bytes.length, 0);
+      fs.ftruncateSync(fd, bytes.length);
+      stamped.push(name);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    } finally {
+      if (fd !== undefined) fs.closeSync(fd);
+    }
+  }
+  return { slotId, stamped };
+}
+
+if (require.main === module) {
+  const args = {};
+  for (let index = 2; index < process.argv.length; index += 1) {
+    const key = process.argv[index];
+    if (key === '--help' || key === '-h') {
+      process.stdout.write('Usage: stamp-runtime-title.cjs --target <path> --runtime-dist <path> [--runtime-dir <path>]\n');
+      process.exit(0);
+    }
+    if (!key.startsWith('--') || index + 1 >= process.argv.length) throw new Error(`invalid argument: ${key}`);
+    args[key.slice(2)] = process.argv[++index];
+  }
+  if (!args.target) throw new Error('--target is required');
+  if (!args['runtime-dist']) throw new Error('--runtime-dist is required');
+  const result = stampRuntimeTitles({
+    target: path.resolve(args.target),
+    runtimeDist: path.resolve(args['runtime-dist']),
+    runtimeDir: args['runtime-dir'],
+  });
+  if (result.stamped.length > 0) process.stdout.write(`slot title ${result.slotId}: ${result.stamped.join(', ')}\n`);
+}
+
+module.exports = { stampRuntimeTitles };

package/adapters/extension/start-watch.sh

@@ -182,9 +182,15 @@ rm -rf node_modules/.cache/webpack
 killed_harness_pid=""
 if [ -f "$RUNTIME_DIR/recipe-harness-webpack.pid" ]; then
   killed_harness_pid="$(cat "$RUNTIME_DIR/recipe-harness-webpack.pid" 2>/dev/null || true)"
+  [ -z "$killed_harness_pid" ] || kill -- "-$killed_harness_pid" >/dev/null 2>&1 || true
   [ -z "$killed_harness_pid" ] || kill "$killed_harness_pid" >/dev/null 2>&1 || true
   rm -f "$RUNTIME_DIR/recipe-harness-webpack.pid"
 fi
+if [ -f "$RUNTIME_DIR/recipe-harness-webpack-sync.pid" ]; then
+  sync_pid="$(cat "$RUNTIME_DIR/recipe-harness-webpack-sync.pid" 2>/dev/null || true)"
+  [ -z "$sync_pid" ] || kill "$sync_pid" >/dev/null 2>&1 || true
+  rm -f "$RUNTIME_DIR/recipe-harness-webpack-sync.pid"
+fi
 
 # Do not start a second writer for dist/chrome. Slot-owned watches use
 # webpack.pid; harness-owned watches use recipe-harness-webpack.pid.
@@ -219,6 +225,8 @@ fi
 # unrelated repo and leave this target validating stale dist/chrome output.
 watch_pid_file="$RUNTIME_DIR/recipe-harness-webpack.pid"
 watch_log="$RUNTIME_DIR/recipe-harness-webpack.log"
+sync_pid_file="$RUNTIME_DIR/recipe-harness-webpack-sync.pid"
+sync_log="$RUNTIME_DIR/recipe-harness-webpack-sync.log"
 rm -f "$watch_pid_file"
 : > "$watch_log"
 LIB_DIR=""
@@ -229,11 +237,16 @@ unset _lib
 echo "[recipe-harness] Starting yarn start (watcher-port=${WATCHER_PORT:-default})"
 echo "[recipe-harness] compact build view - full log: $watch_log (mm-harness logs --full)"
 started_pid=""
-# Launch the watcher detached writing to the log; the tmux window is a read-only tail viewer.
 path_prefix="${REPO_NODE_PATH_PREFIX:-}"
-nohup env -u BUNDLED_DEBUGPY_PATH ${path_prefix:+PATH="${path_prefix}${PATH}"} ${WATCHER_PORT:+PORT="$WATCHER_PORT"} yarn start > "$watch_log" 2>&1 &
-started_pid=$!
-printf '%s\n' "$started_pid" > "$watch_pid_file"
+launcher="$SCRIPT_DIR/launch-webpack.cjs"
+[ -f "$launcher" ] || { echo "launch-webpack.cjs missing from harness; run: mm-harness install" >&2; exit 1; }
+sync_script="$SCRIPT_DIR/sync-webpack-dist.cjs"
+[ -f "$sync_script" ] || { echo "sync-webpack-dist.cjs missing from harness; run: mm-harness install" >&2; exit 1; }
+launch_args=(--target "$PWD" --log "$watch_log" --pid-file "$watch_pid_file" --sync-script "$sync_script" --sync-pid-file "$sync_pid_file" --sync-log "$sync_log" --dist "$PWD/dist/chrome" --runtime-dist "$PWD/$RUNTIME_DIR/${RECIPE_RUNTIME_DIST_DIR:-runtime-dist}")
+[ -z "$WATCHER_PORT" ] || launch_args+=(--port "$WATCHER_PORT")
+[ -z "$path_prefix" ] || launch_args+=(--path-prefix "$path_prefix")
+env -u BUNDLED_DEBUGPY_PATH node "$launcher" "${launch_args[@]}" >/dev/null
+started_pid="$(cat "$watch_pid_file")"
 # The orchestrator names the session; the harness only populates windows. Resolve
 # via the run-owned ladder (RECIPE_TMUX_SESSION → agentic-runtime.json session) —
 # no current-session fallback or slot-number derivation.

package/adapters/extension/stop-viewers.sh

@@ -52,5 +52,5 @@ ps -axo pid=,command= 2>/dev/null | while read -r pid command; do
   esac
 done
 
-rm -f "$runtime_dir/console.tmux" "$runtime_dir/webpack.tmux"
+rm -f "$runtime_dir/console.tmux" "$runtime_dir/webpack.tmux" "$runtime_dir/console-tail.pid"
 exit 0

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

@@ -0,0 +1,107 @@
+#!/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 args = {};
+for (let index = 2; index < process.argv.length; index += 1) {
+  const key = process.argv[index];
+  if (key === '--help' || key === '-h') {
+    process.stdout.write('Usage: sync-webpack-dist.cjs --watcher-pid <pid> --watch-log <path> --target <path> --dist <path> --runtime-dist <path> --pid-file <path>\n');
+    process.exit(0);
+  }
+  if (!key.startsWith('--') || index + 1 >= process.argv.length) throw new Error(`invalid argument: ${key}`);
+  args[key.slice(2)] = process.argv[++index];
+}
+for (const required of ['watcher-pid', 'watch-log', 'target', 'dist', 'runtime-dist', 'pid-file']) {
+  if (!args[required]) throw new Error(`--${required} is required`);
+}
+
+const watcherPid = Number(args['watcher-pid']);
+if (!Number.isInteger(watcherPid) || watcherPid <= 0) throw new Error('--watcher-pid must be a positive integer');
+
+const watchLog = path.resolve(args['watch-log']);
+const dist = path.resolve(args.dist);
+const runtimeDist = path.resolve(args['runtime-dist']);
+const pidFile = path.resolve(args['pid-file']);
+const compilePattern = /compiled successfully|compiled with \d+ warning|MetaMask .* compiled|Bundle end: service worker|Bundle end:.*app-init/u;
+let offset = 0;
+let carry = '';
+let timer;
+
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function removeOwnPidFile() {
+  try {
+    if (fs.readFileSync(pidFile, 'utf8').trim() === String(process.pid)) fs.rmSync(pidFile, { force: true });
+  } catch {
+    // The launcher may have already removed or replaced it.
+  }
+}
+
+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;
+  }
+  stampRuntimeTitles({ target: path.resolve(args.target), runtimeDist });
+  process.stdout.write(`runtime-dist updated after webpack compile (${new Date().toISOString()})\n`);
+}
+
+function poll() {
+  if (!processAlive(watcherPid)) {
+    removeOwnPidFile();
+    process.exit(0);
+  }
+  let fd;
+  try {
+    fd = fs.openSync(watchLog, 'r');
+    const size = fs.fstatSync(fd).size;
+    if (size < offset) {
+      offset = 0;
+      carry = '';
+    }
+    if (size > offset) {
+      const length = size - offset;
+      const chunk = Buffer.alloc(length);
+      const bytesRead = fs.readSync(fd, chunk, 0, length, offset);
+      offset += bytesRead;
+      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();
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') process.stderr.write(`runtime-dist sync monitor: ${error.message}\n`);
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+  timer = setTimeout(poll, 250);
+}
+
+fs.mkdirSync(path.dirname(pidFile), { recursive: true });
+process.on('SIGTERM', () => {
+  clearTimeout(timer);
+  removeOwnPidFile();
+  process.exit(0);
+});
+process.on('SIGINT', () => {
+  clearTimeout(timer);
+  removeOwnPidFile();
+  process.exit(0);
+});
+poll();

package/adapters/extension/verify.sh

@@ -58,7 +58,7 @@ if ! command -v harness_root >/dev/null 2>&1; then
   exit 1
 fi
 
-# Safe task-local --out resolution (kept from the legacy extension path.sh).
+# Safe task-local --out resolution.
 resolve_harness_out() {
   local target="$1"
   local out="$2"