@deeeed/metamask-harness 0.17.4 → 0.18.0

package/adapters/shared/open-debug.mjs

@@ -3,10 +3,11 @@
  * open-debug.mjs — open human-facing debugger UIs for recipe runtimes.
  *
  * Mobile: Metro /open-debugger or /open-dev-menu HTTP endpoints.
- * Extension: DevTools in the slot-owned Chrome process, attached to the exact target.
+ * Extension: Chrome DevTools frontend for an extension page or service worker.
  */
 import { spawnSync } from 'node:child_process';
-import WebSocket from 'ws';
+import http from 'node:http';
+import { createRequire } from 'node:module';
 
 function usage() {
   console.error(`Usage:
@@ -97,8 +98,8 @@ async function fetchOk(url, init) {
   return response.ok;
 }
 
-async function fetchJson(url, init) {
-  const response = await fetch(url, init);
+async function fetchJson(url) {
+  const response = await fetch(url);
   if (!response.ok) {
     throw new Error(`HTTP ${response.status} for ${url}`);
   }
@@ -106,52 +107,109 @@ async function fetchJson(url, init) {
   return body;
 }
 
-function sendBrowserCommand(webSocketDebuggerUrl, method, params) {
+// Probe whether the debug server will accept a browser DevTools frontend
+// WebSocket for `targetId` under `origin`. Chrome 403s every browser Origin
+// unless the slot launched with --remote-allow-origins for it; a slot launched
+// before that flag existed fails here, so we can tell the user to relaunch
+// instead of opening a window that shows "Debugging connection was closed".
+// Transient: the socket is destroyed the instant the handshake resolves.
+function probeAttach(port, targetId, origin) {
   return new Promise((resolve) => {
-    const socket = new WebSocket(webSocketDebuggerUrl);
-    const timer = setTimeout(() => finish({ error: { message: `${method} timed out` } }), 5000);
-    const finish = (result) => {
-      clearTimeout(timer);
-      socket.close();
-      resolve(result);
-    };
-    socket.once('open', () => {
-      socket.send(JSON.stringify({
-        id: 1,
-        method,
-        params,
-      }));
+    const req = http.request({
+      host: '127.0.0.1',
+      port,
+      path: `/devtools/page/${targetId}`,
+      headers: {
+        Connection: 'Upgrade',
+        Upgrade: 'websocket',
+        'Sec-WebSocket-Version': '13',
+        'Sec-WebSocket-Key': 'dGhlIHNhbXBsZSBub25jZQ==',
+        Origin: origin,
+      },
     });
-    socket.on('message', (raw) => {
-      let message;
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
       try {
-        message = JSON.parse(String(raw));
+        req.destroy();
       } catch {
-        finish({ error: { message: `${method} returned a non-JSON WebSocket frame` } });
-        return;
+        // Best-effort teardown of the probe socket.
       }
-      if (message.id !== 1) return;
-      finish(message);
-    });
-    socket.once('error', () => finish({ error: { message: `${method} WebSocket failed` } }));
+      resolve(value);
+    };
+    req.on('upgrade', () => finish({ ok: true }));
+    req.on('response', (res) => finish({ ok: false, status: res.statusCode }));
+    req.on('error', (err) => finish({ ok: false, error: err.message }));
+    req.setTimeout(3000, () => finish({ ok: false, error: 'timeout' }));
+    req.end();
   });
 }
 
-async function openNativeDevtools(cdpPort, browserWebSocketUrl, target) {
-  const response = await sendBrowserCommand(browserWebSocketUrl, 'Target.openDevTools', {
-    targetId: target.id,
-    panelId: 'console',
-  });
-  if (response.error) throw new Error(response.error.message);
-  const devtoolsId = response.result?.targetId;
-  if (!devtoolsId) throw new Error('Chrome did not return a native DevTools target');
-  for (let attempt = 0; attempt < 20; attempt += 1) {
-    const targets = await fetchJson(`http://127.0.0.1:${cdpPort}/json/list`);
-    const devtools = targets.find((candidate) => candidate.id === devtoolsId);
-    if (devtools && String(devtools.url || '').startsWith('devtools://devtools/')) return devtools;
-    await new Promise((resolve) => setTimeout(resolve, 100));
+function resolveWebSocketImpl() {
+  if (typeof WebSocket === 'function') return WebSocket;
+  try {
+    const require = createRequire(import.meta.url);
+    return require(require.resolve('ws', { paths: [process.cwd()] }));
+  } catch {
+    return null;
   }
-  throw new Error('Chrome opened DevTools but did not expose its native target');
+}
+
+// Open the locally-served bundled DevTools frontend as its own window inside the
+// slot's own Chromium, via a browser-level CDP call (the Node client sends no
+// Origin header, so it is never origin-rejected). Returns the new target id.
+async function openDevtoolsWindow(browserWsUrl, url) {
+  const WebSocketImpl = resolveWebSocketImpl();
+  if (!WebSocketImpl) throw new Error('WebSocket unavailable in this Node runtime to open the DevTools window');
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocketImpl(browserWsUrl);
+    const timer = setTimeout(() => {
+      try {
+        ws.close();
+      } catch {
+        // Best-effort cleanup on timeout.
+      }
+      reject(new Error('timeout creating the DevTools window over CDP'));
+    }, 8000);
+    const onOpen = () => {
+      ws.send(JSON.stringify({
+        id: 1,
+        method: 'Target.createTarget',
+        params: { url, newWindow: true, width: 1200, height: 800 },
+      }));
+    };
+    const onMessage = (event) => {
+      const raw = event?.data ?? event;
+      let msg;
+      try {
+        msg = JSON.parse(Buffer.isBuffer(raw) ? raw.toString('utf8') : String(raw));
+      } catch {
+        return;
+      }
+      if (msg.id !== 1) return;
+      clearTimeout(timer);
+      ws.close();
+      if (msg.error) {
+        reject(new Error(msg.error.message || 'Target.createTarget failed'));
+        return;
+      }
+      resolve(msg.result?.targetId || null);
+    };
+    const onError = (err) => {
+      clearTimeout(timer);
+      reject(new Error(`browser CDP websocket error while opening DevTools: ${err?.message || err || 'unknown'}`));
+    };
+    if (typeof ws.on === 'function') {
+      ws.on('open', onOpen);
+      ws.on('message', onMessage);
+      ws.on('error', onError);
+    } else {
+      ws.addEventListener('open', onOpen);
+      ws.addEventListener('message', onMessage);
+      ws.addEventListener('error', onError);
+    }
+  });
 }
 
 // CDP-eval fallback: invoke DevSettings native module directly via the bridge
@@ -256,8 +314,7 @@ function pickExtensionTarget(targets, targetKind) {
 
   const pages = extensionTargets.filter((target) => target.type === 'page');
   return (
-    pages.find((target) => String(target.url || '').includes('/sidepanel.html'))
-    || pages.find((target) => String(target.url || '').includes('/home.html'))
+    pages.find((target) => String(target.url || '').includes('/home.html'))
     || pages.find((target) => !String(target.url || '').includes('/popup-init.html'))
     || pages[0]
     || null
@@ -270,7 +327,6 @@ async function openExtensionDevtools(cdpPort, targetKind, shouldOpen) {
     return { ok: false, adapter: 'extension', error: 'invalid-cdp-port', cdpPort };
   }
 
-  const inspectUrl = 'chrome://inspect/#devices';
   const configureHint = `127.0.0.1:${numericPort}`;
   const versionEndpoint = `http://127.0.0.1:${numericPort}/json/version`;
   const listEndpoint = `http://127.0.0.1:${numericPort}/json/list`;
@@ -286,9 +342,8 @@ async function openExtensionDevtools(cdpPort, targetKind, shouldOpen) {
       cdpPort: numericPort,
       error: 'cdp-unreachable',
       endpoint: versionEndpoint,
-      inspectUrl,
       configureHint,
-      hint: `Start the extension runtime first (mm-harness launch). Then open chrome://inspect and add ${configureHint}.`,
+      hint: 'Start the extension runtime first (mm-harness launch).',
       detail: error instanceof Error ? error.message : String(error),
     };
   }
@@ -304,9 +359,8 @@ async function openExtensionDevtools(cdpPort, targetKind, shouldOpen) {
       cdpPort: numericPort,
       error: 'cdp-list-failed',
       endpoint: listEndpoint,
-      inspectUrl,
       configureHint,
-      hint: `CDP is up but /json/list failed. Open chrome://inspect and add ${configureHint}.`,
+      hint: 'CDP is up but /json/list failed. Relaunch the runtime (mm-harness launch).',
       detail: error instanceof Error ? error.message : String(error),
     };
   }
@@ -319,80 +373,107 @@ async function openExtensionDevtools(cdpPort, targetKind, shouldOpen) {
       cdpPort: numericPort,
       error: 'cdp-list-invalid',
       endpoint: listEndpoint,
-      inspectUrl,
       configureHint,
-      hint: `Open chrome://inspect and add ${configureHint}.`,
+      hint: 'Relaunch the runtime (mm-harness launch).',
     };
   }
 
   const picked = pickExtensionTarget(targets, targetKind);
-  if (picked?.id && shouldOpen) {
-    let devtoolsTarget;
-    try {
-      if (!version.webSocketDebuggerUrl) throw new Error('Chrome did not expose its browser debugger endpoint');
-      devtoolsTarget = await openNativeDevtools(numericPort, version.webSocketDebuggerUrl, picked);
-    } catch (error) {
-      return {
-        ok: false,
-        adapter: 'extension',
-        targetKind,
-        cdpPort: numericPort,
-        error: 'debugger-open-failed',
-        endpoint: listEndpoint,
-        target: { type: picked.type, url: picked.url, title: picked.title || null },
-        hint: 'The extension target is healthy, but its debugger window could not be opened. Run mm-harness debug --no-open --json to inspect the resolved target.',
-        detail: error instanceof Error ? error.message : String(error),
-      };
-    }
+  if (!picked) {
+    return {
+      ok: false,
+      adapter: 'extension',
+      targetKind,
+      cdpPort: numericPort,
+      error: 'no-target',
+      endpoint: listEndpoint,
+      configureHint,
+      hint: 'No extension targets are registered yet. Start the runtime (mm-harness launch).',
+    };
+  }
+
+  // Locally-served bundled DevTools frontend (offline, same host:port as the ws
+  // target so its Origin is allowed). Built from the target id — Chrome omits
+  // webSocketDebuggerUrl for already-attached targets, but the id is always present.
+  const wsRef = `127.0.0.1:${numericPort}/devtools/page/${picked.id}`;
+  const devtoolsUrl = `http://127.0.0.1:${numericPort}/devtools/inspector.html?ws=${wsRef}`;
+  const targetInfo = { type: picked.type, url: picked.url, title: picked.title || null };
+
+  if (!shouldOpen) {
     return {
       ok: true,
       adapter: 'extension',
       targetKind,
-      method: 'native-devtools',
-      endpoint: devtoolsTarget.url,
+      method: 'devtools-window',
+      endpoint: devtoolsUrl,
       cdpPort: numericPort,
-      target: {
-        type: picked.type,
-        url: picked.url,
-        title: picked.title || null,
-      },
-      debuggerTargetId: devtoolsTarget.id,
-      attached: true,
-      opened: true,
+      target: targetInfo,
+      devtoolsUrl,
+      opened: false,
+      detail: 'Open action not invoked (--no-open).',
     };
   }
 
-  if (shouldOpen) return {
-    ok: false,
-    adapter: 'extension',
-    targetKind,
-    error: picked ? 'devtools-url-unavailable' : 'extension-target-unavailable',
-    endpoint: listEndpoint,
-    cdpPort: numericPort,
-    target: picked
-      ? { type: picked.type, url: picked.url, title: picked.title || null }
-      : null,
-    inspectUrl,
-    configureHint,
-    opened: false,
-    hint: picked
-      ? 'The selected extension target did not expose a DevTools URL. Relaunch it with mm-harness launch.'
-      : 'No extension target is ready. Launch it with mm-harness launch, then retry mm-harness debug.',
-  };
+  // Honest gate: confirm the debug server will accept a browser DevTools Origin
+  // before opening a window. A slot launched before --remote-allow-origins support
+  // 403s here; tell the user to relaunch rather than open a dead console.
+  const probe = await probeAttach(numericPort, picked.id, `http://127.0.0.1:${numericPort}`);
+  if (!probe.ok) {
+    return {
+      ok: false,
+      adapter: 'extension',
+      targetKind,
+      cdpPort: numericPort,
+      error: 'origin-rejected',
+      endpoint: devtoolsUrl,
+      target: targetInfo,
+      hint: 'This slot was launched before debugger support (Chrome rejects the DevTools WebSocket origin). Relaunch it: mm-harness launch',
+      detail: probe.status ? `HTTP ${probe.status}` : probe.error || 'handshake rejected',
+    };
+  }
+
+  const browserWsUrl = version?.webSocketDebuggerUrl;
+  if (!browserWsUrl) {
+    return {
+      ok: false,
+      adapter: 'extension',
+      targetKind,
+      cdpPort: numericPort,
+      error: 'no-browser-ws',
+      endpoint: devtoolsUrl,
+      target: targetInfo,
+      hint: 'CDP /json/version did not expose a browser websocket. Relaunch the runtime (mm-harness launch).',
+    };
+  }
+
+  let createdTargetId;
+  try {
+    createdTargetId = await openDevtoolsWindow(browserWsUrl, devtoolsUrl);
+  } catch (error) {
+    return {
+      ok: false,
+      adapter: 'extension',
+      targetKind,
+      cdpPort: numericPort,
+      error: 'devtools-window-failed',
+      endpoint: devtoolsUrl,
+      target: targetInfo,
+      hint: 'Could not open the DevTools window over CDP. Relaunch the runtime (mm-harness launch).',
+      detail: error instanceof Error ? error.message : String(error),
+    };
+  }
 
   return {
     ok: true,
     adapter: 'extension',
     targetKind,
-    method: picked?.devtoolsFrontendUrl ? 'devtools-frontend' : 'target-list',
-    endpoint: picked?.devtoolsFrontendUrl || listEndpoint,
+    method: 'devtools-window',
+    endpoint: devtoolsUrl,
     cdpPort: numericPort,
-    target: picked
-      ? { type: picked.type, url: picked.url, title: picked.title || null }
-      : null,
-    devtoolsUrl: picked?.devtoolsFrontendUrl || null,
-    opened: false,
-    detail: 'Open action not invoked (--no-open).',
+    target: targetInfo,
+    devtoolsUrl,
+    createdTargetId,
+    opened: true,
   };
 }
 

package/adapters/shared/resolve-slot-ports-core.mjs

@@ -172,10 +172,10 @@ function extensionRuntimeContextPath(repo) {
   const repoRoot = path.resolve(repo);
   const envCtx = process.env.RECIPE_RUNTIME_CONTEXT;
   if (envCtx) {
-    const resolved = path.resolve(envCtx);
-    if (resolved === repoRoot || resolved.startsWith(`${repoRoot}${path.sep}`)) {
-      return resolved;
-    }
+    // Farmslot may manage runtime context outside the checkout. Treat the
+    // explicit environment override as authoritative; containment is not a
+    // security boundary and silently dropping it selects the wrong port.
+    return path.resolve(envCtx);
   }
   return path.join(repoRoot, recipeRuntimeDir(), 'agentic-runtime.json');
 }
@@ -198,12 +198,22 @@ export function resolveExtensionRuntimeContext(repo) {
   }
 }
 
-// Checkout-scoped extension ports: runtime context (authoritative) → pool → suffix formula.
-export function formatExtensionSlotPorts(repo) {
+// Context and pool describe checkout identity and therefore replace stale
+// inherited env values. The suffix formula is only a fallback and is applied
+// separately by callers so an explicitly supplied env port can still win.
+export function formatExtensionIdentityPorts(repo) {
   const realRepo = path.resolve(repo);
   return mergeKvLayers(
     { source: resolveExtensionRuntimeContext(realRepo), overwrite: true },
     { source: resolveSlotPortsByRepo(realRepo), overwrite: false },
+  );
+}
+
+// Checkout-scoped extension ports: runtime context (authoritative) → pool → suffix formula.
+export function formatExtensionSlotPorts(repo) {
+  const realRepo = path.resolve(repo);
+  return mergeKvLayers(
+    { source: formatExtensionIdentityPorts(realRepo), overwrite: true },
     { source: resolveDefaultExtensionPorts(realRepo), overwrite: false },
   );
 }
@@ -276,9 +286,16 @@ export function resolveMobileRuntimePorts(repo) {
   );
 }
 
+// Back-compat: the previous name for resolveSlotPortsByRepo, kept as an alias for
+// one release so existing importers keep resolving.
+export const resolveFarmslotPortsByRepo = resolveSlotPortsByRepo;
+
 export const cliFns = {
   resolve_slot_ports_by_repo: resolveSlotPortsByRepo,
+  // Back-compat cli key for one release.
+  resolve_farmslot_ports_by_repo: resolveSlotPortsByRepo,
   resolve_default_extension_ports: resolveDefaultExtensionPorts,
+  resolve_extension_identity_ports: (repo) => formatExtensionIdentityPorts(repo) || null,
   resolve_extension_runtime_context: resolveExtensionRuntimeContext,
   resolve_extension_slot_ports: (repo) => formatExtensionSlotPorts(repo) || null,
   resolve_extension_runtime_ports: (repo) => resolveExtensionRuntimePorts(repo) || null,

package/adapters/shared/resolve-slot-ports.sh

@@ -20,6 +20,11 @@ resolve_slot_ports_by_repo() {
   _resolve_ports_cli resolve_slot_ports_by_repo "$1"
 }
 
+# Back-compat alias for the previous function name (one release).
+resolve_farmslot_ports_by_repo() {
+  resolve_slot_ports_by_repo "$1"
+}
+
 infer_extension_slot_suffix() {
   local repo="$1" base
   base="$(basename "$repo")"
@@ -47,12 +52,13 @@ apply_extension_slot_ports() {
   local repo="${1:-.}" line key val resolved="" ctx_file="" runtime_rel="${RECIPE_RUNTIME_DIR:-temp/recipe/runtime}"
   repo="$(cd "$repo" && pwd)"
   ctx_file="$repo/$runtime_rel/agentic-runtime.json"
-  if [ -f "$ctx_file" ]; then
-    export RECIPE_RUNTIME_CONTEXT="$ctx_file"
-  else
-    unset RECIPE_RUNTIME_CONTEXT
+  if [ -z "${RECIPE_RUNTIME_CONTEXT:-}" ] && [ -f "$ctx_file" ]; then
+    RECIPE_RUNTIME_CONTEXT="$ctx_file"
   fi
-  resolved="$(_resolve_ports_cli resolve_extension_slot_ports "$repo" 2>/dev/null)" || return 0
+  export RECIPE_RUNTIME_CONTEXT
+  # Context/pool are authoritative checkout identity. Formula ports are only
+  # fallback values and must not replace explicitly supplied env ports.
+  resolved="$(_resolve_ports_cli resolve_extension_identity_ports "$repo" 2>/dev/null)" || resolved=""
   while IFS= read -r line; do
     [ -n "$line" ] || continue
     key="${line%%=*}"
@@ -63,6 +69,17 @@ apply_extension_slot_ports() {
       SLOT_ID) RECIPE_SLOT_ID="$val" ;;
     esac
   done <<< "$resolved"
+  resolved="$(_resolve_ports_cli resolve_default_extension_ports "$repo" 2>/dev/null)" || return 0
+  while IFS= read -r line; do
+    [ -n "$line" ] || continue
+    key="${line%%=*}"
+    val="${line#*=}"
+    case "$key" in
+      CDP_PORT) [ -n "${CDP_PORT:-}" ] || CDP_PORT="$val" ;;
+      WATCHER_PORT) [ -n "${WATCHER_PORT:-}" ] || WATCHER_PORT="$val" ;;
+      SLOT_ID) [ -n "${RECIPE_SLOT_ID:-}" ] || RECIPE_SLOT_ID="$val" ;;
+    esac
+  done <<< "$resolved"
 }
 
 apply_resolved_extension_ports() {

package/bin/mm-harness

@@ -5,6 +5,17 @@
 # end-state surface; it resolves node/tsx/dist the same way whether the package is
 # installed as a dependency or run from a source checkout.
 set -euo pipefail
+INVOKED_AS="$0"
+if [[ "$INVOKED_AS" == */* ]]; then
+  INVOKED_AS="$(cd "$(dirname "$INVOKED_AS")" && pwd -L)/${INVOKED_AS##*/}"
+else
+  RESOLVED_INVOKED_AS="$(command -v "$INVOKED_AS" 2>/dev/null || true)"
+  if [[ -z "$RESOLVED_INVOKED_AS" ]]; then
+    echo "ERROR: Cannot resolve the invoked mm-harness executable: $INVOKED_AS" >&2
+    exit 1
+  fi
+  INVOKED_AS="$RESOLVED_INVOKED_AS"
+fi
 SOURCE="${BASH_SOURCE[0]}"
 while [ -L "$SOURCE" ]; do
   SOURCE_DIR="$(cd "$(dirname "$SOURCE")" && pwd -P)"
@@ -26,7 +37,7 @@ RUNNER_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 # already points at this script — including via a symlink (both sides are resolved
 # to their real paths before comparing).
 if [ -n "${MM_HARNESS_BIN:-}" ]; then
-  self_real="$SCRIPT_DIR/$(basename "$SOURCE")"
+  self_real="$SCRIPT_DIR/${SOURCE##*/}"
   # Resolve MM_HARNESS_BIN through any symlink chain so a symlink-to-self is caught.
   mm_bin_src="$MM_HARNESS_BIN"
   while [ -L "$mm_bin_src" ]; do
@@ -39,7 +50,7 @@ if [ -n "${MM_HARNESS_BIN:-}" ]; then
     fi
   done
   bin_real_dir="$(cd "$(dirname "$mm_bin_src")" 2>/dev/null && pwd -P || true)"
-  bin_real="${bin_real_dir:+$bin_real_dir/$(basename "$mm_bin_src")}"
+  bin_real="${bin_real_dir:+$bin_real_dir/${mm_bin_src##*/}}"
   if [ "$bin_real" != "$self_real" ]; then
     if [ ! -x "$MM_HARNESS_BIN" ]; then
       echo "mm-harness: MM_HARNESS_BIN is not an executable: $MM_HARNESS_BIN" >&2
@@ -55,7 +66,8 @@ fi
 # mm-harness is not on PATH (task-local installs). Set AFTER the MM_HARNESS_BIN
 # delegation above so the final executable entered always overwrites any
 # inherited/stale value with its own resolved self path.
-export MM_HARNESS_EXECUTABLE="$SCRIPT_DIR/$(basename "$SOURCE")"
+export MM_HARNESS_EXECUTABLE="$SCRIPT_DIR/${SOURCE##*/}"
+export MM_HARNESS_INVOKED_AS="$INVOKED_AS"
 
 ENTRY_TS="$RUNNER_DIR/src/mm-harness-cli.ts"
 ENTRY_DIST="$RUNNER_DIR/dist/mm-harness-cli.js"

package/dist/adapters/core/surface.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { depsCheck } from "@farmslot/recipe-harness/runtime/deps-readiness";
+import { shellQuote } from "../../commands/parse-args.js";
 const coreSurface = {
   adapter: "core",
   headless: true,
@@ -14,6 +15,7 @@ const coreSurface = {
       reasons: [
         ready ? "Core is headless; dependencies are installed. Run recipes with mm-harness run." : "Core is headless; dependencies are not fully installed."
       ],
+      nextAction: ready ? void 0 : `cd ${shellQuote(path.resolve(target))} && yarn install --immutable`,
       deps: deps.status
     };
   },
@@ -49,7 +51,8 @@ const coreSurface = {
   },
   hints: {
     launch: "mm-harness run <recipe>   # run recipes against the headless core",
-    relaunch: "mm-harness verify"
+    relaunch: "mm-harness verify",
+    runtimeProbeRecovery: (target) => `mm-harness verify --adapter core --target ${shellQuote(path.resolve(target))}`
   }
 };
 export {

package/dist/adapters/extension/console-capture.js

@@ -5,7 +5,9 @@ import { recipeRuntimePath, runnerDir } from "../../paths.js";
 async function ensureExtensionConsoleCapture(target) {
   const cdpPort = process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
   if (!cdpPort) throw new Error("Extension console capture requires a resolved CDP port.");
-  const response = await fetch(`http://127.0.0.1:${cdpPort}/json/version`);
+  const response = await fetch(`http://127.0.0.1:${cdpPort}/json/version`, {
+    signal: AbortSignal.timeout(3e3)
+  });
   if (!response.ok) throw new Error(`Extension CDP ${cdpPort} is not ready for console capture.`);
   const extensionLog = recipeRuntimePath(target, "extension-console.log");
   const dappLog = recipeRuntimePath(target, "dapp-console.log");

package/dist/adapters/extension/harness-freshness.js

@@ -0,0 +1,39 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { recipeHarnessPath, runnerDir } from "../../paths.js";
+async function ensureExtensionHarnessFresh(target) {
+  if (!fs.existsSync(path.join(target, "package.json"))) return;
+  let current;
+  try {
+    const mod = await import(pathToFileURL(path.join(runnerDir, "adapters/shared/harness-source-fingerprint.mjs")).href);
+    current = mod.harnessSourceFingerprint(runnerDir);
+  } catch {
+    return;
+  }
+  const manifestPath = recipeHarnessPath(target, "extension", "manifest.json");
+  const installed = readInstalledFingerprint(manifestPath);
+  if (installed === current) return;
+  const reason = installed === null ? "harness not installed" : "runner changed";
+  try {
+    execFileSync(process.execPath, [path.join(runnerDir, "adapters/extension/inject.mjs"), "--target", target], {
+      stdio: ["ignore", "ignore", "inherit"]
+    });
+    console.error(`\u2192 refreshed extension harness overlay (${reason})`);
+  } catch (error) {
+    const detail = error instanceof Error ? `: ${error.message}` : "";
+    throw new Error(`could not refresh the extension harness overlay (${reason})${detail}`);
+  }
+}
+function readInstalledFingerprint(manifestPath) {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    return typeof manifest.sourceFingerprint === "string" ? manifest.sourceFingerprint : null;
+  } catch {
+    return null;
+  }
+}
+export {
+  ensureExtensionHarnessFresh
+};