@deeeed/metamask-harness 0.82.1 → 0.84.0

package/adapters/web-dapp/lib/cdp-client.mjs

@@ -1,84 +0,0 @@
-// Minimal browser-level Chrome DevTools Protocol client with flattened target
-// sessions, for the long-running web-dapp wallet host. Page-level UI actions use
-// @farmslot/recipe-runner/runtime/cdp instead.
-
-import WebSocket from 'ws';
-
-export async function browserWebSocketUrl(port, timeoutMs = 15000) {
-  const deadline = Date.now() + timeoutMs;
-  let lastError;
-  while (Date.now() < deadline) {
-    try {
-      const response = await fetch(`http://127.0.0.1:${port}/json/version`);
-      if (response.ok) return (await response.json()).webSocketDebuggerUrl;
-    } catch (error) {
-      lastError = error;
-    }
-    await new Promise((resolve) => setTimeout(resolve, 250));
-  }
-  throw new Error(`CDP on 127.0.0.1:${port} did not answer within ${timeoutMs}ms: ${lastError?.message ?? 'no response'}`);
-}
-
-export class CdpClient {
-  #ws;
-  #nextId = 1;
-  #pending = new Map();
-  #handlers = new Map();
-
-  static async connect(url) {
-    const client = new CdpClient();
-    client.#ws = new WebSocket(url, { perMessageDeflate: false, maxPayload: 256 * 1024 * 1024 });
-    await new Promise((resolve, reject) => {
-      client.#ws.once('open', resolve);
-      client.#ws.once('error', reject);
-    });
-    client.#ws.on('message', (data) => client.#dispatch(JSON.parse(String(data))));
-    client.#ws.on('close', () => {
-      for (const { reject } of client.#pending.values()) reject(new Error('CDP connection closed'));
-      client.#pending.clear();
-      client.#emit('close', {}, undefined);
-    });
-    return client;
-  }
-
-  #dispatch(message) {
-    if (message.id !== undefined) {
-      const pending = this.#pending.get(message.id);
-      if (!pending) return;
-      this.#pending.delete(message.id);
-      if (message.error) pending.reject(new Error(`${pending.method}: ${message.error.message}`));
-      else pending.resolve(message.result ?? {});
-      return;
-    }
-    this.#emit(message.method, message.params ?? {}, message.sessionId);
-  }
-
-  #emit(method, params, sessionId) {
-    for (const handler of this.#handlers.get(method) ?? []) {
-      try {
-        handler(params, sessionId);
-      } catch (error) {
-        process.stderr.write(`[cdp] handler for ${method} failed: ${error?.stack ?? error}\n`);
-      }
-    }
-  }
-
-  on(method, handler) {
-    if (!this.#handlers.has(method)) this.#handlers.set(method, new Set());
-    this.#handlers.get(method).add(handler);
-    return () => this.#handlers.get(method)?.delete(handler);
-  }
-
-  send(method, params = {}, sessionId = undefined) {
-    const id = this.#nextId++;
-    const payload = { id, method, params, ...(sessionId ? { sessionId } : {}) };
-    return new Promise((resolve, reject) => {
-      this.#pending.set(id, { resolve, reject, method });
-      this.#ws.send(JSON.stringify(payload));
-    });
-  }
-
-  close() {
-    this.#ws?.close();
-  }
-}

package/adapters/web-dapp/lib/display.mjs

@@ -1,115 +0,0 @@
-// How the slot browser is shown: headful (default) or headless, where its
-// window sits on screen, the page zoom that keeps the app's desktop layout
-// inside that window, and the optional slow-mo between UI actions.
-
-import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import path from 'node:path';
-
-const TRUE_VALUES = new Set(['1', 'true', 'yes', 'on']);
-const FALSE_VALUES = new Set(['0', 'false', 'no', 'off', '']);
-
-function envFlag(raw, label) {
-  if (raw == null) return undefined;
-  const value = String(raw).trim().toLowerCase();
-  if (TRUE_VALUES.has(value)) return true;
-  if (FALSE_VALUES.has(value)) return false;
-  throw new Error(`${label} must be 1/0 or true/false, got ${JSON.stringify(raw)}.`);
-}
-
-// Headless precedence: an explicit flag (--headless, or --headful as its
-// opposite) → the launch node (headless, or headful as its opposite) → env
-// TERMINAL_HEADLESS → headful.
-export function resolveHeadless({ headless, headful, nodeHeadless, nodeHeadful, env = process.env } = {}) {
-  if (headless === true && headful === true) throw new Error('--headless and --headful are mutually exclusive.');
-  if (headless === true) return true;
-  if (headful === true) return false;
-  if (typeof nodeHeadless === 'boolean') return nodeHeadless;
-  if (nodeHeadful === true) return false;
-  return envFlag(env.TERMINAL_HEADLESS, 'TERMINAL_HEADLESS') ?? false;
-}
-
-function slowMoValue(raw, label) {
-  if (raw == null || raw === '') return undefined;
-  const value = Number(raw);
-  if (!Number.isInteger(value) || value < 0 || value > 60000) {
-    throw new Error(`${label} must be whole milliseconds between 0 and 60000, got ${JSON.stringify(raw)}.`);
-  }
-  return value;
-}
-
-// Slow-mo precedence: --slow-mo → launch node slow_mo_ms → env TERMINAL_SLOW_MO → 0.
-export function resolveSlowMo({ flag, node, env = process.env } = {}) {
-  return slowMoValue(flag, '--slow-mo') ?? slowMoValue(node, 'slow_mo_ms') ?? slowMoValue(env.TERMINAL_SLOW_MO, 'TERMINAL_SLOW_MO') ?? 0;
-}
-
-// The order page switches layout at 800 and 1440 CSS px. Recipes were proven on
-// a 1600 CSS-px wide viewport, so a smaller window zooms out until the page
-// still lays out at least this wide.
-export const MIN_LAYOUT_WIDTH = 1460;
-export const MIN_ZOOM = 0.5;
-const FALLBACK_SCREEN = Object.freeze({ left: 0, top: 25, width: 1512, height: 920 });
-
-// The main screen's usable area in points (menu bar and Dock excluded).
-export function detectScreen(env = process.env) {
-  const explicit = /^(\d+)x(\d+)(?:\+(\d+)\+(\d+))?$/u.exec(String(env.TERMINAL_SCREEN ?? '').trim());
-  if (explicit) {
-    return { left: Number(explicit[3] ?? 0), top: Number(explicit[4] ?? 0), width: Number(explicit[1]), height: Number(explicit[2]), source: 'TERMINAL_SCREEN' };
-  }
-  if (process.platform === 'darwin') {
-    try {
-      const out = execFileSync('osascript', ['-l', 'JavaScript', '-e', [
-        'ObjC.import("AppKit");',
-        'const s = $.NSScreen.mainScreen; const f = s.frame; const v = s.visibleFrame;',
-        'JSON.stringify({ left: v.origin.x, top: f.size.height - v.origin.y - v.size.height, width: v.size.width, height: v.size.height })',
-      ].join(' ')], { encoding: 'utf8', timeout: 10000, stdio: ['ignore', 'pipe', 'ignore'] });
-      const screen = JSON.parse(out.trim());
-      if (screen.width > 0 && screen.height > 0) return { ...screen, source: 'main-screen' };
-    } catch {
-      // Fall through to a size that fits any current MacBook.
-    }
-  }
-  return { ...FALLBACK_SCREEN, source: 'fallback' };
-}
-
-// One window per slot, side by side: odd CDP ports (mmt-1: 9541) take the left
-// half of the main screen, even ports (mmt-2: 9542) the right half.
-// TERMINAL_WINDOW=x,y,width,height places the window explicitly.
-export function windowPlacement({ cdpPort, env = process.env, screen = null } = {}) {
-  const explicit = /^(-?\d+),(-?\d+),(\d+),(\d+)$/u.exec(String(env.TERMINAL_WINDOW ?? '').replace(/\s/gu, ''));
-  let bounds;
-  if (explicit) {
-    bounds = { x: Number(explicit[1]), y: Number(explicit[2]), width: Number(explicit[3]), height: Number(explicit[4]), source: 'TERMINAL_WINDOW' };
-  } else {
-    const area = screen ?? detectScreen(env);
-    const width = Math.floor(area.width / 2);
-    const column = Number(cdpPort) % 2 === 1 ? 0 : 1;
-    bounds = { x: Math.round(area.left) + column * width, y: Math.round(area.top), width, height: Math.floor(area.height), source: area.source ?? 'screen' };
-  }
-  const zoom = Math.max(MIN_ZOOM, Math.min(1, Math.floor((bounds.width / MIN_LAYOUT_WIDTH) * 100) / 100));
-  return { ...bounds, zoom };
-}
-
-// Chromium stores page zoom as a level: zoom = 1.2 ^ level. The profile's
-// default zoom applies to every page the slot browser opens.
-export function zoomLevel(zoom) {
-  return zoom === 1 ? 0 : Math.log(zoom) / Math.log(1.2);
-}
-
-export function writeProfileZoom(profile, zoom) {
-  const file = path.join(profile, 'Default', 'Preferences');
-  mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-  const prefs = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
-  prefs.partition ??= {};
-  prefs.partition.default_zoom_level = { ...(prefs.partition.default_zoom_level ?? {}), x: zoomLevel(zoom) };
-  const temporary = `${file}.${process.pid}.tmp`;
-  writeFileSync(temporary, JSON.stringify(prefs), { mode: 0o600 });
-  renameSync(temporary, file);
-}
-
-// Headless keeps the tall viewport the recipes were first proven on; headful
-// opens a placed window instead.
-export function browserDisplayArgs({ headless, placement }) {
-  if (headless) return ['--headless=new', '--window-size=1600,2400'];
-  return [`--window-position=${placement.x},${placement.y}`, `--window-size=${placement.width},${placement.height}`];
-}

package/adapters/web-dapp/lib/hud.mjs

@@ -1,148 +0,0 @@
-// Recipe HUD for the web-dapp app tab: state handling and the page expression
-// that draws it.
-//
-// The overlay is an <mm-harness-hud> element under <html> (outside <body>) with
-// a closed shadow root, aria-hidden and pointer-events:none: page text, test-id
-// selectors, elementFromPoint clicks and the accessibility tree never see it.
-// It sits over the chart's top-left corner, below the chart toolbar, away from
-// the nav bar, the order form, the order rows and the bottom-left dev badge.
-// State lives in <runtime>/hud.json so the wallet host can redraw it after
-// every navigation; the expression only draws on the app origin, never inside
-// MetaMask's extension pages.
-
-import { readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
-import path from 'node:path';
-
-export const HUD_ELEMENT = 'mm-harness-hud';
-export const HUD_FILE = 'hud.json';
-const MAX_TEXT = 180;
-
-function text(value, max = MAX_TEXT) {
-  if (typeof value !== 'string' && typeof value !== 'number') return '';
-  const flat = String(value).replace(/\s+/gu, ' ').trim();
-  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
-}
-
-function progressOf(raw) {
-  if (!raw || typeof raw !== 'object') return null;
-  const current = Number(raw.current);
-  const total = Number(raw.total);
-  if (!Number.isFinite(current) || !Number.isFinite(total) || total <= 0) return null;
-  return { current, total, complete: raw.complete === true };
-}
-
-// Fold one app.hud node into the previous state. A running node becomes the
-// current step; a pass/fail node also becomes the "last result" line, and the
-// recipe-complete node closes the run.
-export function nextHudState(prior, node = {}, nodeId = '') {
-  // A finished run's HUD stays up until the next run's first update replaces it.
-  const previous = prior?.finished ? { seq: prior.seq } : prior;
-  const status = ['running', 'pass', 'fail'].includes(node.status) ? node.status : 'running';
-  const progress = progressOf(node.progress);
-  const intent = text(node.intent ?? node.text ?? node.detail) || text(nodeId);
-  const id = text(node.node_id ?? node.nodeId ?? nodeId, 80);
-  const state = {
-    seq: (previous?.seq ?? 0) + 1,
-    title: text(node.title, 80) || previous?.title || 'Recipe run',
-    current: previous?.current ?? null,
-    last: previous?.last ?? null,
-    finished: null,
-  };
-  if (status === 'running') {
-    state.current = { nodeId: id, intent, progress: progress ?? previous?.current?.progress ?? null };
-    return state;
-  }
-  const error = status === 'fail' ? text(node.error) : '';
-  state.last = { nodeId: id, intent, status, ...(error ? { error } : {}) };
-  if (progress?.complete || id === 'recipe-complete') {
-    state.finished = status;
-    state.current = { nodeId: id, intent: status === 'pass' ? 'Recipe passed' : 'Recipe failed', progress };
-  } else if (progress) {
-    state.current = { ...(state.current ?? { nodeId: id, intent }), progress };
-  }
-  return state;
-}
-
-export function hudFile(runtimeDir) {
-  return path.join(runtimeDir, HUD_FILE);
-}
-
-export function readHudState(runtimeDir) {
-  try {
-    return JSON.parse(readFileSync(hudFile(runtimeDir), 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-export function writeHudState(runtimeDir, state) {
-  const file = hudFile(runtimeDir);
-  const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
-  writeFileSync(temporary, `${JSON.stringify(state)}\n`, { mode: 0o600 });
-  renameSync(temporary, file);
-}
-
-export function clearHudState(runtimeDir) {
-  rmSync(hudFile(runtimeDir), { force: true });
-}
-
-const STYLE = `
-:host { all: initial; }
-.hud { position: fixed; top: 220px; left: 12px; z-index: 2147483647; width: 360px; max-width: calc(50vw - 24px);
-  box-sizing: border-box; padding: 8px 10px; border-radius: 8px; border: 1px solid rgba(255,255,255,.18);
-  background: rgba(16,18,24,.82); color: #f2f4f7; font: 12px/1.35 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-  pointer-events: none; user-select: none; box-shadow: 0 4px 16px rgba(0,0,0,.35); }
-.row { display: flex; gap: 6px; align-items: baseline; }
-.title { font-weight: 600; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; flex: 1; }
-.step { color: #a9b1bd; font-variant-numeric: tabular-nums; }
-.intent { margin-top: 4px; }
-.badge { display: inline-block; padding: 0 5px; border-radius: 4px; font-size: 10px; font-weight: 700; letter-spacing: .03em; }
-.running { background: #2f6fed; color: #fff; }
-.pass { background: #1f9d55; color: #fff; }
-.fail { background: #d64545; color: #fff; }
-.last { margin-top: 4px; color: #c7cdd6; }
-.error { color: #ffb4b4; }
-`;
-
-// A self-contained page expression: draws (or clears, for null) the HUD when
-// the document is on the app origin, and skips the work when the same state
-// is already drawn.
-export function hudRenderExpression(state, appOrigin) {
-  return `(() => {
-    const state = ${JSON.stringify(state ?? null)};
-    if (location.origin !== ${JSON.stringify(String(appOrigin).replace(/\/$/u, ''))}) return { hud: false, reason: 'not-app-origin' };
-    const existing = document.documentElement.querySelector(':scope > ${HUD_ELEMENT}');
-    if (!state) { existing?.remove(); return { hud: false, cleared: true }; }
-    if (existing && existing.dataset.seq === String(state.seq)) return { hud: true, seq: state.seq, unchanged: true };
-    existing?.remove();
-    const host = document.createElement('${HUD_ELEMENT}');
-    host.dataset.seq = String(state.seq);
-    host.setAttribute('aria-hidden', 'true');
-    host.inert = true;
-    host.style.cssText = 'all: initial; position: fixed; inset: 0 auto auto 0; width: 0; height: 0; pointer-events: none; z-index: 2147483647;';
-    const root = host.attachShadow({ mode: 'closed' });
-    const el = (tag, cls, value) => { const node = document.createElement(tag); if (cls) node.className = cls; if (value != null) node.textContent = value; return node; };
-    const style = el('style', null, ${JSON.stringify(STYLE)});
-    const box = el('div', 'hud');
-    const head = el('div', 'row');
-    head.append(el('span', 'title', state.title));
-    const progress = state.current && state.current.progress;
-    if (progress) head.append(el('span', 'step', 'step ' + progress.current + '/' + progress.total));
-    box.append(head);
-    if (state.current) {
-      const line = el('div', 'intent');
-      const status = state.finished || 'running';
-      line.append(el('span', 'badge ' + status, status === 'running' ? 'RUN' : status.toUpperCase()), ' ', state.current.intent);
-      box.append(line);
-    }
-    if (state.last && !state.finished) {
-      const line = el('div', 'last');
-      line.append(el('span', 'badge ' + state.last.status, state.last.status.toUpperCase()), ' ', state.last.intent);
-      box.append(line);
-    }
-    if (state.last && state.last.error) box.append(el('div', 'last error', state.last.error));
-    root.append(style, box);
-    document.documentElement.append(host);
-    return { hud: true, seq: state.seq };
-  })()`;
-}

package/adapters/web-dapp/lib/policy.mjs

@@ -1,79 +0,0 @@
-// The venue policy of the adapter that extends web-dapp (e.g. the Terminal
-// plugin's plugins/terminal/policy.mjs): what web-dapp's launch, wallet host,
-// readiness and actions know about the app's venue. mm-harness sets its module
-// path in RECIPE_WEB_DAPP_POLICY when it binds such an adapter, so every
-// web-dapp leaf process and live action it starts reads the same policy.
-
-import { createRequire } from 'node:module';
-import path from 'node:path';
-
-export const POLICY_ENV = 'RECIPE_WEB_DAPP_POLICY';
-// The policy contract this web-dapp reads; a policy declares the version it was written for.
-export const POLICY_VERSION = 1;
-let loaded;
-
-// Every member web-dapp reads, checked once when the policy loads: a missing or mistyped
-// member fails here, naming the module, instead of deep in a launch or an assertion (a
-// missing signatureLog would silently drop the venue's L1 and mainnet rules).
-const MEMBERS = {
-  adapterId: 'string',
-  checkout: 'object',
-  venueHosts: 'function',
-  linkHosts: 'array',
-  probe: 'object',
-  startChain: 'number',
-  refuseTypedData: 'object',
-  signatureLog: 'object',
-  startPath: 'string',
-  pagePath: 'function',
-  dependencies: 'array',
-  testnetVariable: 'string',
-  module: 'string',
-};
-
-function checkPolicy(policy, file) {
-  const problems = [];
-  if (!policy || typeof policy !== 'object') problems.push('exports no policy object');
-  else {
-    if (policy.policyVersion !== POLICY_VERSION) problems.push(`policyVersion is ${policy.policyVersion ?? 'missing'}, this web-dapp reads ${POLICY_VERSION}`);
-    for (const [name, type] of Object.entries(MEMBERS)) {
-      const value = policy[name];
-      const ok = type === 'array' ? Array.isArray(value) : type === 'object' ? value !== null && typeof value === 'object' : typeof value === type;
-      if (!ok) problems.push(`${name} must be ${type === 'array' || type === 'object' ? `an ${type}` : `a ${type}`}`);
-    }
-    const { checkout, refuseTypedData, signatureLog } = policy;
-    if (checkout && typeof checkout.matches !== 'function') problems.push('checkout.matches must be a function');
-    for (const name of ['name', 'label', 'needs']) if (checkout && typeof checkout[name] !== 'string') problems.push(`checkout.${name} must be a string`);
-    if (refuseTypedData && typeof refuseTypedData.reason !== 'function') problems.push('refuseTypedData.reason must be a function');
-    for (const name of ['kind', 'message']) if (refuseTypedData && typeof refuseTypedData[name] !== 'string') problems.push(`refuseTypedData.${name} must be a string`);
-    // The venue's request-log rules: both maps are required (empty only on purpose), so a
-    // policy cannot drop its L1 or mainnet rules by omission.
-    for (const name of ['typedDataClasses', 'forbiddenEntries']) {
-      if (signatureLog && (signatureLog[name] === null || typeof signatureLog[name] !== 'object')) problems.push(`signatureLog.${name} must be an object`);
-    }
-  }
-  if (problems.length) {
-    throw new Error(`web-dapp venue policy ${file}: ${problems.join('; ')}.\nNext: update the library that declares the adapter to a revision written for this mm-harness.`);
-  }
-  return policy;
-}
-
-export function webDappPolicy(env = process.env) {
-  const file = env[POLICY_ENV];
-  if (!file) {
-    throw new Error(
-      'web-dapp needs a venue policy: select an adapter that extends it.\n' +
-      'Next: put the library that declares it on RECIPE_LIBRARY_PATH and pass its id, e.g. --adapter terminal.',
-    );
-  }
-  if (loaded?.file !== file) {
-    // The policy module uses node built-ins only and has no top-level await, so it loads synchronously.
-    loaded = { file, policy: checkPolicy(createRequire(import.meta.url)(path.resolve(file)).policy, file) };
-  }
-  return loaded.policy;
-}
-
-// The bound adapter's id, for names and paths; web-dapp's own when none is bound.
-export function webDappAdapterId(env = process.env) {
-  return env[POLICY_ENV] ? webDappPolicy(env).adapterId : 'web-dapp';
-}

package/adapters/web-dapp/lib/processes.mjs

@@ -1,187 +0,0 @@
-// Stop the web-dapp slot browser and wallet host by their pid files and prove
-// the slot CDP port is released. A pid is signalled only when its command line
-// carries this slot's owner marker for that process kind. A pid file naming a
-// dead process is removed; one naming a live process without the marker is
-// kept and reported, never signalled.
-
-import { execFileSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { existsSync, readFileSync, rmSync } from 'node:fs';
-import net from 'node:net';
-import path from 'node:path';
-
-import { webDappPolicy, webDappRuntimeDir } from '../../../library/actions/web-dapp/platform/runtime.mjs';
-
-export function pidAlive(pid) {
-  if (!Number.isInteger(Number(pid)) || Number(pid) <= 0) return false;
-  try {
-    process.kill(Number(pid), 0);
-    return true;
-  } catch (error) {
-    return error.code === 'EPERM';
-  }
-}
-
-function groupAlive(pgid) {
-  try {
-    process.kill(-pgid, 0);
-    return true;
-  } catch (error) {
-    return error.code === 'EPERM';
-  }
-}
-
-function readPid(file) {
-  if (!existsSync(file)) return null;
-  const pid = Number(readFileSync(file, 'utf8').trim());
-  return Number.isInteger(pid) && pid > 0 ? pid : null;
-}
-
-function psField(pid, field) {
-  try {
-    return execFileSync('ps', ['-ww', '-o', `${field}=`, '-p', String(pid)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-  } catch {
-    return '';
-  }
-}
-
-export function processCommand(pid) {
-  return pidAlive(pid) ? psField(pid, 'command') : '';
-}
-
-// Each process the slot starts carries `--mm-harness-owner=<kind>-<id>`, where
-// <id> is derived from the canonical runtime dir. Ownership is that exact
-// argument, compared as a whole whitespace-free token, so a runtime dir that
-// shares a prefix with this one (".../terminal backup", ".../terminal2")
-// never matches.
-export const OWNER_FLAG = '--mm-harness-owner';
-export const OWNER_KINDS = Object.freeze(['browser', 'wallet-host', 'console-collector']);
-
-export function ownerMarker(kind, runtimeDir) {
-  if (!OWNER_KINDS.includes(kind)) throw new Error(`unknown web-dapp process kind ${kind}`);
-  const id = createHash('sha256').update(path.resolve(runtimeDir)).digest('hex').slice(0, 32);
-  return `${OWNER_FLAG}=${kind}-${id}`;
-}
-
-export function ownsProcess(kind, pid, runtimeDir, command = processCommand(pid)) {
-  if (!command) return false;
-  return command.split(/\s+/u).includes(ownerMarker(kind, runtimeDir));
-}
-
-export function portFree(port) {
-  return new Promise((resolve) => {
-    const socket = net.connect({ host: '127.0.0.1', port }, () => {
-      socket.destroy();
-      resolve(false);
-    });
-    socket.on('error', () => resolve(true));
-  });
-}
-
-// Browsers and hosts are spawned detached, each leading its own process group.
-// When the pid leads its group the whole group is signalled and waited for,
-// so children that outlive the leader (renderers, a child ignoring SIGTERM)
-// are killed too; otherwise only the pid.
-export async function terminate(pid, graceMs = 8000) {
-  if (!pidAlive(pid)) return false;
-  const group = Number(psField(pid, 'pgid')) === pid;
-  const alive = () => (group ? groupAlive(pid) : pidAlive(pid));
-  const signal = (name) => {
-    try {
-      process.kill(group ? -pid : pid, name);
-    } catch {
-      // Already gone.
-    }
-  };
-  signal('SIGTERM');
-  const deadline = Date.now() + graceMs;
-  while (alive() && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 200));
-  if (alive()) {
-    signal('SIGKILL');
-    const killDeadline = Date.now() + 5000;
-    while (alive() && Date.now() < killDeadline) await new Promise((resolve) => setTimeout(resolve, 100));
-  }
-  return true;
-}
-
-// The console collector a run started (src/adapters/web-dapp/console-capture.ts)
-// outlives browser relaunches inside the run; stop and cleanup end it.
-export async function stopConsoleCollector(target, { log = () => {}, runtimeDir } = {}) {
-  const runtime = runtimeDir ?? webDappRuntimeDir(target);
-  const pidFile = path.join(runtime, 'console-tail.pid');
-  const pid = readPid(pidFile);
-  if (!pid) return { stopped: null };
-  if (ownsProcess('console-collector', pid, runtime)) {
-    await terminate(pid, 3000);
-    rmSync(pidFile, { force: true });
-    log(`stopped console collector pid ${pid}`);
-    return { stopped: pid };
-  }
-  if (pidAlive(pid)) {
-    log(`console collector pid ${pid} is alive but is not this slot's collector; left it alone`);
-    return { stopped: null, foreign: pid };
-  }
-  rmSync(pidFile, { force: true });
-  return { stopped: null, stale: pid };
-}
-
-// Every live process that proves it is a browser on this slot's profiles,
-// found by command line: a browser started through LaunchServices has no
-// child handle, and its pid is only known once it owns the CDP port.
-export function ownedBrowserPids(runtimeDir) {
-  const runtime = path.resolve(runtimeDir);
-  let lines = '';
-  try {
-    // `--` ends pgrep's options: the pattern itself starts with dashes.
-    lines = execFileSync('pgrep', ['-f', '--', ownerMarker('browser', runtime)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
-  } catch {
-    return [];
-  }
-  return lines.split('\n').map(Number).filter((pid) => pid > 0 && ownsProcess('browser', pid, runtime));
-}
-
-export function cdpListenerPids(port) {
-  try {
-    return execFileSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
-      .split('\n').map(Number).filter((pid) => pid > 0);
-  } catch {
-    return [];
-  }
-}
-
-export async function stopWebDappBrowser(target, { cdpPort, log = () => {}, runtimeDir } = {}) {
-  const runtime = runtimeDir ?? webDappRuntimeDir(target);
-  const stopped = [];
-  const stale = [];
-  const foreign = [];
-  for (const name of ['wallet-host', 'browser']) {
-    const pidFile = path.join(runtime, `${name}.pid`);
-    const pid = readPid(pidFile);
-    if (pid && ownsProcess(name, pid, runtime)) {
-      if (await terminate(pid)) {
-        stopped.push({ name, pid });
-        log(`stopped ${name} pid ${pid}`);
-      }
-      rmSync(pidFile, { force: true });
-    } else if (pid && pidAlive(pid)) {
-      foreign.push({ name, pid });
-      log(`${name} pid ${pid} is alive but is not this slot's ${name}; left it and its pid file alone`);
-    } else {
-      if (pid) stale.push({ name, pid });
-      rmSync(pidFile, { force: true });
-    }
-  }
-  rmSync(path.join(runtime, 'wallet-host.ready'), { force: true });
-  rmSync(path.join(runtime, 'browser.json'), { force: true });
-  let free = null;
-  if (cdpPort) {
-    const deadline = Date.now() + 10000;
-    free = await portFree(cdpPort);
-    while (!free && Date.now() < deadline) {
-      await new Promise((resolve) => setTimeout(resolve, 250));
-      free = await portFree(cdpPort);
-    }
-    if (!free) throw new Error(`CDP port ${cdpPort} is still in use after stopping the ${webDappPolicy().adapterId} browser; another process owns it.`);
-  }
-  return { stopped, stale, foreign, cdpPortFree: free };
-}