@deeeed/metamask-harness 0.17.0 → 0.17.2

package/adapters/mobile/launch-console-forwarder.cjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const args = { port: '', out: '', err: '' };
+for (let i = 2; i < process.argv.length; i += 1) {
+  const key = process.argv[i];
+  if (key === '--port') args.port = process.argv[++i] || '';
+  else if (key === '--out') args.out = process.argv[++i] || '';
+  else if (key === '--err') args.err = process.argv[++i] || '';
+  else if (key === '--help' || key === '-h') {
+    process.stdout.write('Usage: launch-console-forwarder.cjs --port <port> --out <app-log> --err <error-log>\n');
+    process.exit(0);
+  } else {
+    process.stderr.write(`launch-console-forwarder: unknown arg: ${key}\n`);
+    process.exit(2);
+  }
+}
+
+if (!args.port || !args.out || !args.err) {
+  process.stderr.write('launch-console-forwarder: --port, --out, and --err are required\n');
+  process.exit(2);
+}
+
+const forwarder = path.join(__dirname, 'bridge-runtime', 'console-forwarder.cjs');
+const errFd = fs.openSync(args.err, 'a');
+try {
+  const child = spawn(process.execPath, [forwarder, '--port', args.port, '--out', args.out], {
+    detached: true,
+    stdio: ['ignore', errFd, errFd],
+  });
+  child.unref();
+  process.stdout.write(`${child.pid}\n`);
+} finally {
+  fs.closeSync(errFd);
+}

package/adapters/mobile/start-console-forwarder.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# Ensure one runner-owned CDP console forwarder is alive for this Mobile slot.
+set -uo pipefail
+
+TARGET="$PWD"
+PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
+QUIET=false
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target) TARGET="$2"; shift 2 ;;
+    --port)   PORT="$2"; shift 2 ;;
+    --quiet)  QUIET=true; shift ;;
+    -h|--help)
+      printf 'Usage: start-console-forwarder.sh [--target <dir>] [--port <port>] [--quiet]\n'
+      exit 0
+      ;;
+    *) printf 'start-console-forwarder: unknown arg: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+[ "${METAMASK_RECIPE_CONSOLE_FORWARD:-1}" != "0" ] || exit 0
+TARGET="$(cd "$TARGET" && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/../shared/harness-path.sh"
+LOG_DIR="$TARGET/$(recipe_runtime_dir)" || exit 1
+FORWARDER="$SCRIPT_DIR/bridge-runtime/console-forwarder.cjs"
+PID_FILE="$LOG_DIR/console-forwarder.pid"
+APP_LOG_FILE="$LOG_DIR/app-console.log"
+
+{ [ -f "$FORWARDER" ] && command -v node >/dev/null 2>&1; } || exit 0
+mkdir -p "$LOG_DIR"
+
+# One debugger owns a React Native page. Reap any collector for this Metro port,
+# including one left by an older globally installed harness.
+while read -r pid cmd; do
+  case "$cmd" in
+    *console-forwarder.cjs*" --port $PORT "*|*console-forwarder.cjs*" --port=$PORT "*)
+      kill "$pid" 2>/dev/null || true
+      ;;
+  esac
+done < <(ps -axo pid=,command= 2>/dev/null || true)
+
+if [ -f "$PID_FILE" ]; then
+  old_pid="$(cat "$PID_FILE" 2>/dev/null || true)"
+  if [ -n "$old_pid" ]; then
+    case "$(ps -p "$old_pid" -o command= 2>/dev/null)" in
+      *console-forwarder.cjs*) kill "$old_pid" 2>/dev/null || true ;;
+    esac
+  fi
+  rm -f "$PID_FILE"
+fi
+
+: > "$APP_LOG_FILE"
+pid="$(node "$SCRIPT_DIR/launch-console-forwarder.cjs" \
+  --port "$PORT" \
+  --out "$APP_LOG_FILE" \
+  --err "$LOG_DIR/console-forwarder.err")" || exit 1
+printf '%s\n' "$pid" > "$PID_FILE"
+
+# A successful launch must never claim capture when the collector died at boot.
+sleep 0.1
+if ! kill -0 "$pid" 2>/dev/null; then
+  rm -f "$PID_FILE"
+  printf 'start-console-forwarder: collector exited during startup; inspect %s\n' \
+    "$LOG_DIR/console-forwarder.err" >&2
+  exit 1
+fi
+[ "$QUIET" = true ] || printf 'Device console → app-console.log (CDP forwarder pid %s)\n' "$pid" >&2

package/adapters/mobile/start-metro.sh

@@ -77,45 +77,6 @@ default_metro_workers() {
 # shellcheck disable=SC1091
 . "$SCRIPT_DIR/lib/tmux-viewer.sh"
 
-# Bridgeless RN gates console→Metro forwarding on console._isPolyfilled, which is
-# false with the Hermes native console — device logs (incl. DevLogger) never reach
-# metro.log. The forwarder attaches over CDP and appends them back. Kill switch:
-# METAMASK_RECIPE_CONSOLE_FORWARD=0.
-start_console_forwarder() {
-  local forwarder="$SCRIPT_DIR/bridge-runtime/console-forwarder.cjs"
-  local fwd_pid_file="$LOG_DIR/console-forwarder.pid"
-  [ "${METAMASK_RECIPE_CONSOLE_FORWARD:-1}" != "0" ] || return 0
-  { [ -f "$forwarder" ] && command -v node >/dev/null 2>&1; } || return 0
-  # Only one debugger can own a React Native page. Reap any forwarder already
-  # attached to this Metro port, even if it was launched from another checkout or
-  # package install path and therefore does not own this runtime dir's pid file.
-  local pid cmd
-  while read -r pid cmd; do
-    case "$cmd" in
-      *console-forwarder.cjs*" --port $PORT "*|*console-forwarder.cjs*" --port=$PORT "*)
-        kill "$pid" 2>/dev/null || true
-        ;;
-    esac
-  done < <(ps -axo pid=,command= 2>/dev/null || true)
-  if [ -f "$fwd_pid_file" ]; then
-    local old_fwd
-    old_fwd="$(cat "$fwd_pid_file" 2>/dev/null || true)"
-    # A crash can leave a stale pid file and the OS can recycle the pid for an
-    # unrelated process — only kill when the command line is really ours.
-    if [ -n "$old_fwd" ]; then
-      case "$(ps -p "$old_fwd" -o command= 2>/dev/null)" in
-        *console-forwarder.cjs*) kill "$old_fwd" 2>/dev/null ;;
-      esac
-    fi
-    rm -f "$fwd_pid_file"
-  fi
-  nohup node "$forwarder" --port "$PORT" --out "$LOG_FILE" \
-    </dev/null >> "$LOG_DIR/console-forwarder.err" 2>&1 &
-  echo "$!" > "$fwd_pid_file"
-  disown 2>/dev/null || true
-  printf 'Device console → metro.log (CDP forwarder pid %s)\n' "$(cat "$fwd_pid_file")" >&2
-}
-
 write_metro_runner() {
   local runner="$1"
   local clear_flag=""
@@ -179,7 +140,6 @@ if metro_ready; then
     rm -f "$PID_FILE"
   elif metro_listener_valid; then
     printf 'Metro already running and valid on port %s\n' "$PORT" >&2
-    start_console_forwarder
     exit 0
   else
     stop_metro_listener || exit 1
@@ -269,7 +229,6 @@ if [ "$READY" = true ]; then
   first_ready_pid="${ready_pids%% *}"
   [ -z "$first_ready_pid" ] || printf '%s\n' "$first_ready_pid" > "$PID_FILE"
   printf 'Metro ready on port %s\n' "$PORT" >&2
-  start_console_forwarder
   printf '  Next: mm-harness logs  (tail Metro)\n' >&2
   exit 0
 fi

package/adapters/mobile/verify.sh

@@ -261,76 +261,19 @@ check_file "package.json"
 check_file "app/dev-tools/AgenticService/AgenticService.ts"
 
 if ! grep -q "AgenticService.install" "$TARGET/app/core/NavigationService/NavigationService.ts" 2>/dev/null; then
-  checks+=("{\"name\":\"NavigationService patch\",\"status\":\"fail\"}")
+  checks+=("{\"name\":\"NavigationService agentic bridge\",\"status\":\"fail\"}")
   status="fail"
 else
-  checks+=("{\"name\":\"NavigationService patch\",\"status\":\"pass\"}")
+  checks+=("{\"name\":\"NavigationService agentic bridge\",\"status\":\"pass\"}")
 fi
 
 if ! grep -q "AgentStepHud" "$TARGET/app/components/Nav/App/App.tsx" 2>/dev/null; then
-  checks+=("{\"name\":\"App AgentStepHud patch\",\"status\":\"fail\"}")
+  checks+=("{\"name\":\"App AgentStepHud\",\"status\":\"fail\"}")
   status="fail"
 else
-  checks+=("{\"name\":\"App AgentStepHud patch\",\"status\":\"pass\"}")
+  checks+=("{\"name\":\"App AgentStepHud\",\"status\":\"pass\"}")
 fi
 
-# Drift detection (read-only): compare the in-repo AgenticService/HUD against
-# the resolved runner overlay, not a runner-owned copy. The runner is the only
-# MetaMask-aware source of truth for Mobile injection.
-overlay_drift_check="$(
-  HARNESS_DIR_FOR_DRIFT="$HARNESS_DIR" TARGET_FOR_DRIFT="$TARGET" node <<'NODE'
-const fs = require('fs');
-const path = require('path');
-const name = 'agentic overlay matches runner (HUD freshness)';
-const harnessDir = process.env.HARNESS_DIR_FOR_DRIFT;
-const targetDir = path.join(process.env.TARGET_FOR_DRIFT, 'app', 'dev-tools', 'AgenticService');
-function readTrimmed(file) {
-  try { return fs.readFileSync(file, 'utf8').trim(); } catch { return ''; }
-}
-let runnerDir = readTrimmed(path.join(harnessDir, 'runner', '.runner-source'));
-if (!runnerDir) {
-  try {
-    const manifest = JSON.parse(fs.readFileSync(path.join(harnessDir, 'manifest.json'), 'utf8'));
-    runnerDir = manifest && manifest.source && manifest.source.runnerDir || '';
-  } catch {}
-}
-if (!runnerDir) {
-  process.stdout.write(JSON.stringify({ name, status: 'warn', detail: 'runner source unavailable; overlay freshness compare skipped' }));
-  process.exit(0);
-}
-const overlayDir = path.join(runnerDir, 'adapters', 'mobile', 'overlay', 'app', 'dev-tools', 'AgenticService');
-let checked = 0;
-const drifted = [];
-const missing = [];
-try {
-  for (const entry of fs.readdirSync(overlayDir)) {
-    if (!entry.endsWith('.patch')) continue;
-    if (/\.test\./u.test(entry)) continue;
-    const base = entry.slice(0, -'.patch'.length);
-    const targetFile = path.join(targetDir, base);
-    if (!fs.existsSync(targetFile)) { missing.push(base); continue; }
-    checked += 1;
-    if (fs.readFileSync(path.join(overlayDir, entry), 'utf8') !== fs.readFileSync(targetFile, 'utf8')) {
-      drifted.push(base);
-    }
-  }
-} catch (error) {
-  process.stdout.write(JSON.stringify({ name, status: 'warn', detail: 'runner overlay compare skipped: ' + String((error && error.message) || error) }));
-  process.exit(0);
-}
-if (drifted.length || missing.length) {
-  const parts = [];
-  if (drifted.length) parts.push('behind runner: ' + drifted.join(', '));
-  if (missing.length) parts.push('absent in repo: ' + missing.join(', '));
-  process.stdout.write(JSON.stringify({ name, status: 'warn', detail: parts.join('; ') + ' — rerun mm-harness install --force-overlay or mm-harness fixtures sync to refresh the in-repo HUD/AgenticService from the runner' }));
-} else if (checked === 0) {
-  process.stdout.write(JSON.stringify({ name, status: 'pass' }));
-} else {
-  process.stdout.write(JSON.stringify({ name, status: 'pass' }));
-}
-NODE
-)"
-checks+=("$overlay_drift_check")
 run_with_timeout() {
   local log_path="$1"
   local timeout_s="$2"

package/adapters/shared/open-debug.mjs

@@ -3,9 +3,10 @@
  * open-debug.mjs — open human-facing debugger UIs for recipe runtimes.
  *
  * Mobile: Metro /open-debugger or /open-dev-menu HTTP endpoints.
- * Extension: Chrome DevTools frontend for an extension page or service worker.
+ * Extension: DevTools in the slot-owned Chrome process, attached to the exact target.
  */
 import { spawnSync } from 'node:child_process';
+import WebSocket from 'ws';
 
 function usage() {
   console.error(`Usage:
@@ -96,8 +97,8 @@ async function fetchOk(url, init) {
   return response.ok;
 }
 
-async function fetchJson(url) {
-  const response = await fetch(url);
+async function fetchJson(url, init) {
+  const response = await fetch(url, init);
   if (!response.ok) {
     throw new Error(`HTTP ${response.status} for ${url}`);
   }
@@ -105,20 +106,46 @@ async function fetchJson(url) {
   return body;
 }
 
-function openUrl(url) {
-  if (process.platform === 'darwin') {
-    if (url.startsWith('devtools://') || url.startsWith('chrome://')) {
-      const chrome = spawnSync('open', ['-a', 'Google Chrome', url], { stdio: 'ignore' });
-      if (chrome.status === 0) return 'chrome';
-    }
-    spawnSync('open', [url], { stdio: 'ignore' });
-    return 'open';
-  }
-  if (process.platform === 'linux') {
-    spawnSync('xdg-open', [url], { stdio: 'ignore' });
-    return 'xdg-open';
+function sendBrowserCommand(webSocketDebuggerUrl, method, params) {
+  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,
+      }));
+    });
+    socket.on('message', (raw) => {
+      const message = JSON.parse(String(raw));
+      if (message.id !== 1) return;
+      finish(message);
+    });
+    socket.once('error', () => finish({ error: { message: `${method} WebSocket failed` } }));
+  });
+}
+
+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));
   }
-  return null;
+  throw new Error('Chrome opened DevTools but did not expose its native target');
 }
 
 // CDP-eval fallback: invoke DevSettings native module directly via the bridge
@@ -223,7 +250,8 @@ function pickExtensionTarget(targets, targetKind) {
 
   const pages = extensionTargets.filter((target) => target.type === 'page');
   return (
-    pages.find((target) => String(target.url || '').includes('/home.html'))
+    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('/popup-init.html'))
     || pages[0]
     || null
@@ -241,8 +269,9 @@ async function openExtensionDevtools(cdpPort, targetKind, shouldOpen) {
   const versionEndpoint = `http://127.0.0.1:${numericPort}/json/version`;
   const listEndpoint = `http://127.0.0.1:${numericPort}/json/list`;
 
+  let version;
   try {
-    await fetchJson(versionEndpoint);
+    version = await fetchJson(versionEndpoint);
   } catch (error) {
     return {
       ok: false,
@@ -291,48 +320,73 @@ async function openExtensionDevtools(cdpPort, targetKind, shouldOpen) {
   }
 
   const picked = pickExtensionTarget(targets, targetKind);
-  if (picked?.devtoolsFrontendUrl && shouldOpen) {
-    openUrl(picked.devtoolsFrontendUrl);
+  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),
+      };
+    }
     return {
       ok: true,
       adapter: 'extension',
       targetKind,
-      method: 'devtools-frontend',
-      endpoint: picked.devtoolsFrontendUrl,
+      method: 'native-devtools',
+      endpoint: devtoolsTarget.url,
       cdpPort: numericPort,
       target: {
         type: picked.type,
         url: picked.url,
         title: picked.title || null,
       },
-      devtoolsUrl: picked.devtoolsFrontendUrl,
-      inspectUrl,
-      configureHint,
+      debuggerTargetId: devtoolsTarget.id,
+      attached: true,
       opened: true,
     };
   }
 
-  if (shouldOpen) {
-    openUrl(inspectUrl);
-  }
+  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.',
+  };
 
   return {
     ok: true,
     adapter: 'extension',
     targetKind,
-    method: picked?.devtoolsFrontendUrl ? 'devtools-frontend' : 'chrome-inspect',
-    endpoint: picked?.devtoolsFrontendUrl || inspectUrl,
+    method: picked?.devtoolsFrontendUrl ? 'devtools-frontend' : 'target-list',
+    endpoint: picked?.devtoolsFrontendUrl || listEndpoint,
     cdpPort: numericPort,
     target: picked
       ? { type: picked.type, url: picked.url, title: picked.title || null }
       : null,
     devtoolsUrl: picked?.devtoolsFrontendUrl || null,
-    inspectUrl,
-    configureHint,
-    opened: shouldOpen,
-    hint: picked
-      ? 'Opened chrome://inspect because no devtools frontend URL was available for the selected target.'
-      : `No extension targets are registered yet. Open chrome://inspect and add ${configureHint}.`,
+    opened: false,
+    detail: 'Open action not invoked (--no-open).',
   };
 }
 

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

@@ -276,14 +276,8 @@ 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_runtime_context: resolveExtensionRuntimeContext,
   resolve_extension_slot_ports: (repo) => formatExtensionSlotPorts(repo) || null,

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

@@ -20,11 +20,6 @@ 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")"

package/adapters/shared/update-check-worker.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+
+const [cacheFile, timeoutText, endpointOverride] = process.argv.slice(2);
+const timeoutMs = Number.parseInt(timeoutText ?? '', 10);
+const endpoint = endpointOverride
+  ?? 'https://registry.npmjs.org/-/package/%40deeeed%2Fmetamask-harness/dist-tags';
+
+async function main() {
+  if (!cacheFile || !Number.isInteger(timeoutMs) || timeoutMs < 1) return;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(endpoint, { signal: controller.signal });
+    if (!response.ok) return;
+    const data = await response.json();
+    if (!data || typeof data.latest !== 'string' || data.latest.length === 0) return;
+    let lastCheck = Date.now();
+    try {
+      const cached = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+      if (typeof cached.lastCheck === 'number') lastCheck = cached.lastCheck;
+    } catch {
+      // The parent may have exited before creating the cache; recreate it below.
+    }
+    fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+    const temporary = `${cacheFile}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, JSON.stringify({ lastCheck, latest: data.latest }));
+    fs.renameSync(temporary, cacheFile);
+  } catch {
+    // Passive checks are intentionally silent; the explicit update command teaches failures.
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+await main();

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

@@ -0,0 +1,84 @@
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+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`);
+  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");
+  const collectorLog = recipeRuntimePath(target, "console-tail.log");
+  const pidFile = recipeRuntimePath(target, "console-tail.pid");
+  fs.mkdirSync(path.dirname(extensionLog), { recursive: true });
+  const existingPid = readPid(pidFile);
+  if (existingPid && collectorOwnsLog(existingPid, extensionLog)) return;
+  if (existingPid) {
+    try {
+      process.kill(existingPid, "SIGTERM");
+    } catch {
+    }
+  }
+  fs.rmSync(pidFile, { force: true });
+  fs.writeFileSync(extensionLog, "");
+  fs.writeFileSync(dappLog, "");
+  const script = path.join(runnerDir, "adapters", "extension", "console-tail.mjs");
+  const output = fs.openSync(collectorLog, "a");
+  let child;
+  try {
+    child = spawn(process.execPath, [
+      script,
+      "--cdp-port",
+      cdpPort,
+      "--extension-log",
+      extensionLog,
+      "--dapp-log",
+      dappLog
+    ], {
+      cwd: target,
+      detached: true,
+      stdio: ["ignore", output, output]
+    });
+  } finally {
+    fs.closeSync(output);
+  }
+  if (!child.pid) throw new Error("Extension console collector did not start.");
+  child.unref();
+  fs.writeFileSync(pidFile, `${child.pid}
+`);
+  for (let attempt = 0; attempt < 30; attempt += 1) {
+    if (collectorOwnsLog(child.pid, extensionLog) && containsAttachment(extensionLog, dappLog)) return;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error(`Extension console collector ${child.pid} did not attach to CDP ${cdpPort}.`);
+}
+function readPid(pidFile) {
+  try {
+    const pid = Number.parseInt(fs.readFileSync(pidFile, "utf8").trim(), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+function collectorOwnsLog(pid, extensionLog) {
+  try {
+    process.kill(pid, 0);
+  } catch {
+    return false;
+  }
+  const result = spawnSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8" });
+  return result.status === 0 && result.stdout.includes("console-tail.mjs") && result.stdout.includes(extensionLog);
+}
+function containsAttachment(...logs) {
+  return logs.some((log) => {
+    try {
+      return fs.readFileSync(log, "utf8").includes("[attached]");
+    } catch {
+      return false;
+    }
+  });
+}
+export {
+  ensureExtensionConsoleCapture
+};