@amg555/frameforge-mcp 2.7.6 → 2.7.7

package/.agent/skills/gstack-browse/src/bun-polyfill.cjs

@@ -1,276 +0,0 @@
-/**
- * Bun API polyfill for Node.js — Windows compatibility layer.
- *
- * On Windows, Bun can't launch or connect to Playwright's Chromium
- * (oven-sh/bun#4253, #9911). The browse server falls back to running
- * under Node.js with this polyfill providing Bun API equivalents.
- *
- * Loaded via --require before the transpiled server bundle.
- */
-
-'use strict';
-
-const http = require('http');
-const { spawnSync: nodeSpawnSync, spawn: nodeSpawn } = require('child_process');
-// Node's spawn on Windows without shell:true only matches an EXACT
-// executable name — no PATHEXT resolution the way a real shell (or
-// Bun.spawn, which this file exists to polyfill) does. A bare command
-// name like 'bun' (no .exe/.cmd) then fails ENOENT even though `bun`
-// works fine typed at a prompt (confirmed live in #2461: this is what
-// produced "[browse] FATAL uncaught exception: spawn bun ENOENT" from
-// terminal-agent-control.ts's respawn path, once daemon output was
-// actually being captured to a file instead of silently discarded).
-//
-// Two things this is NOT fixed with, both tried and rejected in #2461:
-//
-// 1. shell:true + array args. This file is also reached (via server.ts →
-//    write-commands.ts/meta-commands.ts → cookie-import-browser.ts/
-//    browser-skill-commands.ts) by calls that pass genuinely variable
-//    content — browser-skill-commands.ts spreads `...opts.skillArgs`,
-//    sourced from `$B skill run <name> --arg k=v`'s passthrough CLI args,
-//    into the spawned argv. shell:true on Windows routes through cmd.exe,
-//    and Node's own array-arg handling for that combination does NOT
-//    neutralize cmd.exe metacharacters (& | ^ % < >) — verified in #2461 by
-//    directly spawning a resolved .cmd path with an arg containing
-//    `& echo INJECTED > proof.txt`: the file was created. Hand-rolled
-//    double-quote-only escaping doesn't close that either.
-//
-// 2. Resolve the .exe/.cmd path ourselves and spawn it with NO shell.
-//    Works for .exe targets, but Node refuses (EINVAL) to spawn a
-//    .cmd/.bat file without shell:true — deliberately, as part of Node's
-//    CVE-2024-27980 fix for implicit unsafe .cmd execution. bun's own
-//    Windows install (npm global) is exactly a .cmd shim, so this path is
-//    not optional to support.
-//
-// cross-spawn (previously a transitive dep, now direct) is the established
-// library for precisely this problem: PATHEXT resolution AND correct
-// Windows/cmd.exe argument escaping together. #2461 verified the injection
-// payload above reaches the child as a single literal argument while
-// normal resolution (`bun --version`) still works.
-const crossSpawn = require('cross-spawn');
-
-globalThis.Bun = {
-  serve(options) {
-    const { port, hostname = '127.0.0.1', fetch } = options;
-
-    const server = http.createServer(async (nodeReq, nodeRes) => {
-      try {
-        const url = `http://${hostname}:${port}${nodeReq.url}`;
-        const headers = new Headers();
-        for (const [key, val] of Object.entries(nodeReq.headers)) {
-          if (val) headers.set(key, Array.isArray(val) ? val[0] : val);
-        }
-
-        let body = null;
-        if (nodeReq.method !== 'GET' && nodeReq.method !== 'HEAD') {
-          body = await new Promise((resolve) => {
-            const chunks = [];
-            nodeReq.on('data', (chunk) => chunks.push(chunk));
-            nodeReq.on('end', () => resolve(Buffer.concat(chunks)));
-          });
-        }
-
-        const webReq = new Request(url, {
-          method: nodeReq.method,
-          headers,
-          body,
-        });
-
-        const webRes = await fetch(webReq);
-
-        nodeRes.statusCode = webRes.status;
-        webRes.headers.forEach((val, key) => {
-          nodeRes.setHeader(key, val);
-        });
-
-        const resBody = await webRes.arrayBuffer();
-        nodeRes.end(Buffer.from(resBody));
-      } catch (err) {
-        nodeRes.statusCode = 500;
-        nodeRes.end(JSON.stringify({ error: err.message }));
-      }
-    });
-
-    server.listen(port, hostname);
-
-    return {
-      stop() { server.close(); },
-      port,
-      hostname,
-    };
-  },
-
-  spawnSync(cmd, options = {}) {
-    const [command, ...args] = cmd;
-    const spawnSyncFn = process.platform === 'win32' ? crossSpawn.sync : nodeSpawnSync;
-    const result = spawnSyncFn(command, args, {
-      stdio: [
-        options.stdin || 'pipe',
-        options.stdout === 'pipe' ? 'pipe' : 'ignore',
-        options.stderr === 'pipe' ? 'pipe' : 'ignore',
-      ],
-      timeout: options.timeout,
-      env: options.env,
-      cwd: options.cwd,
-      // Node defaults windowsHide to false; Bun.spawn hides the console
-      // window. Without this the shim silently inverts the behavior on the
-      // one platform it exists to serve — every console child pops a window.
-      // Forwarded (not hardcoded) so an explicit windowsHide:false survives.
-      windowsHide: options.windowsHide !== false,
-    });
-
-    return {
-      exitCode: result.status,
-      stdout: result.stdout || Buffer.from(''),
-      stderr: result.stderr || Buffer.from(''),
-    };
-  },
-
-  spawn(cmd, options = {}) {
-    const [command, ...args] = cmd;
-    const stdio = options.stdio || ['pipe', 'pipe', 'pipe'];
-    const spawnFn = process.platform === 'win32' ? crossSpawn : nodeSpawn;
-    const proc = spawnFn(command, args, {
-      stdio,
-      env: options.env,
-      cwd: options.cwd,
-      // stdio:'ignore' silences a child's output but does not suppress its
-      // console window on Windows. The terminal-agent respawn (server.ts
-      // watchdog, 60s ticker) popped a visible bun.exe window on every
-      // respawn until this was forwarded. Forwarded, not hardcoded, so an
-      // explicit windowsHide:false survives.
-      windowsHide: options.windowsHide !== false,
-      // Without it a Windows child joins the parent's kill-on-close job and
-      // dies with the parent (#2637).
-      detached: options.detached === true,
-    });
-
-    // Drain stdout/stderr eagerly into in-memory buffers. Bun's spawn buffers
-    // these for the consumer; Node's Readables are pull-based, so if the caller
-    // awaits `proc.exited` before reading, anything past the OS pipe buffer
-    // (~16-64 KB) back-pressures the child until it blocks in write() and
-    // `exit` never fires. Eager draining keeps the pipes flowing regardless
-    // of read order; replay below is via fresh Web ReadableStreams.
-    //
-    // Cap the buffer so a runaway child can't OOM the server. 16 MB is
-    // generous: DPAPI outputs are tiny, tasklist is <1 KB, and the
-    // browser-skill consumer has its own 1 MB readCapped. Once the cap is
-    // reached we keep draining the pipe (so the child never blocks) but
-    // discard further bytes. Override via GSTACK_SPAWN_MAX_BUFFER (bytes).
-    const MAX_BUFFER = Math.max(
-      0,
-      parseInt(process.env.GSTACK_SPAWN_MAX_BUFFER || '', 10) || 16 * 1024 * 1024,
-    );
-    const drain = (stream) => {
-      if (!stream) return { done: Promise.resolve(), chunks: [], cancel() {} };
-      const state = { chunks: [], bytes: 0, truncated: false, cancelled: false, finished: false };
-      let finish;
-      const done = new Promise((resolve) => {
-        finish = () => {
-          if (state.finished) return;
-          state.finished = true;
-          resolve();
-        };
-        stream.on('data', (chunk) => {
-          if (state.cancelled) return;
-          if (state.bytes >= MAX_BUFFER) { state.truncated = true; return; }
-          if (state.bytes + chunk.length <= MAX_BUFFER) {
-            state.chunks.push(chunk);
-            state.bytes += chunk.length;
-          } else {
-            const remaining = MAX_BUFFER - state.bytes;
-            state.chunks.push(chunk.subarray(0, remaining));
-            state.bytes = MAX_BUFFER;
-            state.truncated = true;
-          }
-        });
-        // Any terminal event resolves: 'end' on normal close, 'error' on a
-        // stream-level error, 'close' as the belt-and-suspenders for spawn
-        // failures where Node fires 'close' but neither 'end' nor 'error'.
-        stream.once('end', finish);
-        stream.once('error', finish);
-        stream.once('close', finish);
-      });
-      return { done, chunks: state.chunks, cancel() {
-        if (state.cancelled) return;
-        state.cancelled = true;
-        state.chunks.length = 0;
-        state.bytes = 0;
-        finish();
-        stream.destroy();
-      } };
-    };
-    const stdoutDrain = drain(proc.stdout);
-    const stderrDrain = drain(proc.stderr);
-
-    // Bun's spawn exposes `proc.exited` as a Promise resolving to the exit
-    // code; several call sites — DPAPI decryption, isBrowserRunning,
-    // browser-skill-commands — `await proc.exited` directly or via
-    // Promise.race with a timeout. Without this, those awaits resolve to
-    // `undefined` immediately and the operation looks like a silent failure.
-    // Resolve only after both pipes have finished draining so consumers that
-    // read stdout AFTER awaiting exit see the full output, not a partial buffer.
-    const exited = new Promise((resolveExited) => {
-      let exitStatus;
-      proc.once('exit', (code, signal) => {
-        // Match Bun: exit code on normal exit; 128 + signal number on signal;
-        // 0 if neither was reported.
-        if (code !== null) exitStatus = code;
-        else if (signal) exitStatus = 128 + (require('os').constants.signals[signal] || 0);
-        else exitStatus = 0;
-      });
-      proc.once('error', () => {
-        if (exitStatus === undefined) exitStatus = 1;
-      });
-      // Wait for either 'exit' (normal child lifecycle) or 'error' (spawn
-      // failure — Node fires error without exit when the binary is missing).
-      // Either path resolves the lifecycle promise; without listening to both
-      // a spawn error hangs `await proc.exited` until the consumer's own
-      // timeout fires.
-      const lifecycle = new Promise((r) => {
-        proc.once('exit', r);
-        proc.once('error', r);
-      });
-      Promise.all([lifecycle, stdoutDrain.done, stderrDrain.done])
-        .then(() => resolveExited(exitStatus !== undefined ? exitStatus : 0));
-    });
-
-    // Replay buffered output as a fresh Web ReadableStream. `start()` observes
-    // the drain before enqueueing so `new Response(proc.stdout).text()` yields
-    // the complete output regardless of whether the consumer reads before or
-    // after awaiting `proc.exited`. Stream is single-shot (locked after one
-    // read), matching Bun's behavior.
-    const replay = (d) => {
-      let cancelled = false;
-      return new ReadableStream({
-        start(controller) {
-          d.done.then(() => {
-            if (cancelled) return;
-            for (const chunk of d.chunks) {
-              controller.enqueue(chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk));
-            }
-            controller.close();
-          });
-        },
-        cancel() {
-          cancelled = true;
-          d.cancel();
-        },
-      });
-    };
-
-    return {
-      pid: proc.pid,
-      stdout: replay(stdoutDrain),
-      stderr: replay(stderrDrain),
-      stdin: proc.stdin,
-      exited,
-      unref() { proc.unref(); },
-      kill(signal) { proc.kill(signal); },
-    };
-  },
-
-  sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-  },
-};

package/.agent/skills/gstack-browse/src/cdp-allowlist.ts

@@ -1,235 +0,0 @@
-/**
- * CDP method allow-list (T2: deny-default).
- *
- * Codex outside-voice T2: allow-default with a deny-list is backwards because
- * Target.*, Browser.*, Runtime.evaluate, Page.addScriptToEvaluateOnNewDocument,
- * Fetch.*, IO.read, etc. are all dangerous and easy to forget. Default-deny
- * inverts the failure mode: missing a method means it's blocked (annoying),
- * not exposed (silent compromise).
- *
- * Each entry has:
- *   - domain.method     unique CDP identifier
- *   - scope             "tab" | "browser" — controls T7 mutex tier
- *   - output            "trusted" | "untrusted" — wraps result if "untrusted"
- *   - justification     why this method is safe to allow
- *
- * Add entries via PR. CI lint (cdp-allowlist.test.ts) ensures every entry has all 4 fields.
- */
-
-export type CdpScope = 'tab' | 'browser';
-export type CdpOutput = 'trusted' | 'untrusted';
-
-export interface CdpAllowEntry {
-  domain: string;
-  method: string;
-  scope: CdpScope;
-  output: CdpOutput;
-  justification: string;
-}
-
-export const CDP_ALLOWLIST: ReadonlyArray<CdpAllowEntry> = Object.freeze([
-  // ─── Accessibility (read-only) ─────────────────────────────
-  {
-    domain: 'Accessibility',
-    method: 'getFullAXTree',
-    scope: 'tab',
-    output: 'untrusted',
-    justification: 'Read-only AX tree extraction. Output is third-party page content; wrap in UNTRUSTED.',
-  },
-  {
-    domain: 'Accessibility',
-    method: 'getPartialAXTree',
-    scope: 'tab',
-    output: 'untrusted',
-    justification: 'Read-only AX tree subtree by node. Output is third-party page content.',
-  },
-  {
-    domain: 'Accessibility',
-    method: 'getRootAXNode',
-    scope: 'tab',
-    output: 'untrusted',
-    justification: 'Read-only root AX node accessor.',
-  },
-  // ─── DOM (read-only inspection) ────────────────────────────
-  {
-    domain: 'DOM',
-    method: 'describeNode',
-    scope: 'tab',
-    output: 'untrusted',
-    justification: 'Inspect a DOM node by backend ID; pure read.',
-  },
-  {
-    domain: 'DOM',
-    method: 'getBoxModel',
-    scope: 'tab',
-    output: 'trusted',
-    justification: 'Pure geometric data (box dimensions). No page content leaks; safe trusted.',
-  },
-  {
-    domain: 'DOM',
-    method: 'getNodeForLocation',
-    scope: 'tab',
-    output: 'trusted',
-    justification: 'Pure coordinate→nodeId mapping; no content leak.',
-  },
-  // ─── CSS (read-only) ───────────────────────────────────────
-  {
-    domain: 'CSS',
-    method: 'getMatchedStylesForNode',
-    scope: 'tab',
-    output: 'untrusted',
-    justification: 'Read computed cascade for a node; output may contain attacker-controlled selectors.',
-  },
-  {
-    domain: 'CSS',
-    method: 'getComputedStyleForNode',
-    scope: 'tab',
-    output: 'trusted',
-    justification: 'Computed style values are bounded (CSS keywords/numbers); safe trusted.',
-  },
-  {
-    domain: 'CSS',
-    method: 'getInlineStylesForNode',
-    scope: 'tab',
-    output: 'untrusted',
-    justification: 'Inline style content may contain attacker-controlled custom-property values.',
-  },
-  // ─── Performance metrics ───────────────────────────────────
-  {
-    domain: 'Performance',
-    method: 'getMetrics',
-    scope: 'tab',
-    output: 'trusted',
-    justification: 'Pure numeric metrics (timing, layout count); safe.',
-  },
-  {
-    domain: 'Performance',
-    method: 'enable',
-    scope: 'tab',
-    output: 'trusted',
-    justification: 'Domain enable; no content; required prerequisite for getMetrics.',
-  },
-  {
-    domain: 'Performance',
-    method: 'disable',
-    scope: 'tab',
-    output: 'trusted',
-    justification: 'Domain disable; no content.',
-  },
-  // ─── Tracing (event capture) ───────────────────────────────
-  // NOTE: Tracing.start can capture cross-tab data depending on categories.
-  // We mark it browser-scoped to acquire the global lock when in use.
-  {
-    domain: 'Tracing',
-    method: 'start',
-    scope: 'browser',
-    output: 'trusted',
-    justification: 'Trace category capture. Browser-scoped to serialize against other CDP ops.',
-  },
-  {
-    domain: 'Tracing',
-    method: 'end',
-    scope: 'browser',
-    output: 'untrusted',
-    justification: 'Trace dump may contain URLs and page data; wrap.',
-  },
-  // ─── Emulation (viewport/device) ───────────────────────────
-  {
-    domain: 'Emulation',
-    method: 'setDeviceMetricsOverride',
-    scope: 'tab',
-    output: 'trusted',
-    justification: 'Viewport/scale override on the active tab.',
-  },
-  {
-    domain: 'Emulation',
-    method: 'clearDeviceMetricsOverride',
-    scope: 'tab',
-    output: 'trusted',
-    justification: 'Clear viewport override.',
-  },
-  {
-    domain: 'Emulation',
-    method: 'setUserAgentOverride',
-    scope: 'tab',
-    output: 'trusted',
-    justification: 'UA override on the active tab. NOTE: changes affect future requests; fine for tests.',
-  },
-  {
-    domain: 'Emulation',
-    method: 'setEmulatedMedia',
-    scope: 'tab',
-    output: 'trusted',
-    justification: 'Media type/feature override (prefers-color-scheme, prefers-reduced-motion, prefers-contrast, forced-colors) so a11y and dark-mode CSS branches are testable. Returns an empty result; no page content. NOTE: like setUserAgentOverride the override persists on the tab until cleared with an empty features array.',
-  },
-  {
-    domain: 'Emulation',
-    method: 'setCPUThrottlingRate',
-    scope: 'tab',
-    output: 'trusted',
-    justification: 'CPU slowdown multiplier on the active tab, for measuring performance on a realistic low-end client instead of the developer workstation. Same domain and mutating character as setDeviceMetricsOverride; affects only timing, reads nothing, exfiltrates nothing. NOTE: like setEmulatedMedia the override persists on the tab until cleared (rate: 1) — callers own restoration.',
-  },
-  {
-    domain: 'Network',
-    method: 'emulateNetworkConditions',
-    scope: 'tab',
-    output: 'trusted',
-    justification: 'Bandwidth/latency emulation on the active tab, for measuring page behaviour on a slow connection. Constrains traffic rather than reading it — no request bodies, headers or cookies are exposed. NOTE: like setEmulatedMedia the override persists on the tab until cleared (offline: false plus default throughput/latency) — callers own restoration.',
-  },
-  // ─── Page capture (output, not navigation) ─────────────────
-  {
-    domain: 'Page',
-    method: 'captureScreenshot',
-    scope: 'tab',
-    output: 'untrusted',
-    justification: 'Screenshot bytes; output is bounded image data (no marker injection vector).',
-  },
-  {
-    domain: 'Page',
-    method: 'printToPDF',
-    scope: 'tab',
-    output: 'untrusted',
-    justification: 'PDF bytes; bounded binary output.',
-  },
-  // NOTE: Page.navigate is INTENTIONALLY NOT on the allowlist (Codex T2 cat 4).
-  // Use $B goto for navigation; that path goes through the URL blocklist.
-  // ─── Network metadata (NOT bodies/cookies — those exfil data) ──
-  {
-    domain: 'Network',
-    method: 'enable',
-    scope: 'tab',
-    output: 'trusted',
-    justification: 'Domain enable; required prerequisite. Does not return data.',
-  },
-  {
-    domain: 'Network',
-    method: 'disable',
-    scope: 'tab',
-    output: 'trusted',
-    justification: 'Domain disable; mirrors Network.enable for cleanup symmetry.',
-  },
-  // NOTE: Network.getResponseBody, Network.getCookies, Network.replayXHR,
-  // Network.loadNetworkResource are INTENTIONALLY NOT allowed (Codex T2 cat 7).
-  // ─── Runtime (limited, NO evaluate/callFunctionOn) ──────────
-  // Runtime.evaluate/callFunctionOn/compileScript/runScript = RCE if exposed (Codex T2 cat 6).
-  // Only a tiny safe subset:
-  {
-    domain: 'Runtime',
-    method: 'getProperties',
-    scope: 'tab',
-    output: 'untrusted',
-    justification: 'Inspect properties of an existing remote object. Read-only; output may contain page data.',
-  },
-]);
-
-const CDP_ALLOWLIST_INDEX: Map<string, CdpAllowEntry> = new Map(
-  CDP_ALLOWLIST.map((e) => [`${e.domain}.${e.method}`, e]),
-);
-
-export function lookupCdpMethod(qualifiedName: string): CdpAllowEntry | null {
-  return CDP_ALLOWLIST_INDEX.get(qualifiedName) ?? null;
-}
-
-export function isCdpMethodAllowed(qualifiedName: string): boolean {
-  return CDP_ALLOWLIST_INDEX.has(qualifiedName);
-}

package/.agent/skills/gstack-browse/src/cdp-bridge.ts

@@ -1,180 +0,0 @@
-/**
- * CDP escape hatch — `$B cdp <Domain.method> [json-params]`.
- *
- * Path A from the spike: uses Playwright's newCDPSession() per page so we
- * piggyback Playwright's own CDP socket (no second WebSocket, no need for
- * --remote-debugging-port).
- *
- * Security posture (Codex T2):
- *   - DENY-DEFAULT. Methods must be explicitly listed in cdp-allowlist.ts.
- *   - Each entry is tagged scope (tab|browser) and output (trusted|untrusted).
- *
- * Concurrency posture (Codex T7):
- *   - Two-tier lock from browser-manager.ts.
- *   - tab-scoped methods take the per-tab mutex.
- *   - browser-scoped methods take the global lock that blocks all tab mutexes.
- *   - Hard 5s timeout on acquire → CDPMutexAcquireTimeout (no silent hangs).
- *   - Every lock-holder uses try { ... } finally { release() } so errors don't leak locks.
- */
-
-import type { Page } from 'playwright';
-import type { BrowserManager } from './browser-manager';
-import { lookupCdpMethod, type CdpAllowEntry } from './cdp-allowlist';
-import { logTelemetry } from './telemetry';
-
-const CDP_TIMEOUT_MS = 5000;
-const CDP_ACQUIRE_TIMEOUT_MS = 5000;
-
-// ─── CDP session lifecycle helpers ─────────────────────────────
-//
-// Every direct `newCDPSession(page)` call needs a matching `session.detach()`
-// to release the Chromium-side CDP target. Forgetting the detach leaves the
-// target attached until the underlying transport drops (often process exit),
-// which on a long-lived headed browser shows up as steadily-climbing
-// browser-process RSS. To make the leak class unforgettable, callers should
-// go through one of these two helpers and a static-grep test
-// (browse/test/cdp-session-cleanup.test.ts) fails CI if any source file
-// calls `newCDPSession(` outside this module.
-
-/**
- * Ephemeral CDP session with try/finally detach. Use for one-shot CDP work
- * where the caller doesn't need session reuse — e.g. archive snapshots,
- * `$B memory`, a single `Page.captureScreenshot`. The session is detached
- * in `finally` regardless of whether `fn` threw, so the Chromium target
- * doesn't leak on the error path.
- *
- * For repeated use of the same page (e.g. the `$B cdp` bridge or the
- * inspector), use `getOrCreateCdpSession` instead — it caches and detaches
- * on page close.
- */
-export async function withCdpSession<T>(
-  page: Page,
-  fn: (session: any) => Promise<T>,
-): Promise<T> {
-  const session = await page.context().newCDPSession(page);
-  try {
-    return await fn(session);
-  } finally {
-    try {
-      await session.detach();
-    } catch {
-      // Best-effort cleanup. Session may already be detached (target closed,
-      // context recreated, browser disconnect). Swallowing all errors is the
-      // correct cleanup posture per CLAUDE.md "best-effort cleanup paths".
-    }
-  }
-}
-
-/**
- * Cached long-lived CDP session keyed by Page. First call creates the
- * session and registers a `page.once('close', ...)` hook that removes the
- * cache entry AND calls `session.detach()`. Pre-helper code only removed
- * the cache entry, leaving the Chromium-side target attached.
- *
- * Pass a caller-owned WeakMap so this helper doesn't impose a single global
- * cache — the `$B cdp` bridge and the inspector each keep their own session
- * pool with different invariants (e.g. the inspector also detaches on
- * `framenavigated` because DOM/CSS domain state is tied to the document).
- */
-export async function getOrCreateCdpSession(
-  page: Page,
-  cache: WeakMap<Page, any>,
-): Promise<any> {
-  let session = cache.get(page);
-  if (session) return session;
-  session = await page.context().newCDPSession(page);
-  cache.set(page, session);
-  page.once('close', () => {
-    cache.delete(page);
-    session.detach().catch(() => {
-      // Best-effort cleanup — see withCdpSession finally block.
-    });
-  });
-  return session;
-}
-
-// ─── $B cdp bridge ─────────────────────────────────────────────
-
-// Per-page CDPSession cache. Lifecycle delegated to getOrCreateCdpSession
-// which registers a close hook that BOTH removes the cache entry AND calls
-// session.detach() — pre-helper code only did the former, leaving the
-// Chromium-side target attached.
-const sessionCache: WeakMap<Page, any> = new WeakMap();
-
-async function getCdpSession(page: Page): Promise<any> {
-  return getOrCreateCdpSession(page, sessionCache);
-}
-
-export interface CdpDispatchInput {
-  domain: string;
-  method: string;
-  params: Record<string, unknown>;
-  tabId: number;
-  bm: BrowserManager;
-}
-
-export interface CdpDispatchResult {
-  raw: unknown;
-  entry: CdpAllowEntry;
-}
-
-/**
- * Look up + acquire mutex + send + release. Throws structured errors on:
- *  - DENIED (method not on allowlist)
- *  - CDPMutexAcquireTimeout (lock contention exceeded budget)
- *  - CDPBridgeTimeout (CDP method itself didn't return in budget)
- *  - CDPSessionInvalidated (Playwright recreated context, session stale)
- */
-export async function dispatchCdpCall(input: CdpDispatchInput): Promise<CdpDispatchResult> {
-  const qualified = `${input.domain}.${input.method}`;
-  const entry = lookupCdpMethod(qualified);
-  if (!entry) {
-    // Surface the denial via telemetry — this is the data that drives the
-    // next allow-list expansion (DX D9: cdp_method_denied counter).
-    logTelemetry({ event: 'cdp_method_denied', domain: input.domain, method: input.method });
-    throw new Error(
-      `DENIED: ${qualified} is not on the CDP allowlist.\n` +
-        `Cause: deny-default posture; method has not been audited and added to cdp-allowlist.ts.\n` +
-        `Action: if this method is genuinely needed, open a PR adding it to CDP_ALLOWLIST with a one-line justification + scope (tab|browser) + output (trusted|untrusted).`
-    );
-  }
-  // Acquire the right tier of lock.
-  const acquireStart = Date.now();
-  const release =
-    entry.scope === 'browser'
-      ? await input.bm.acquireGlobalCdpLock(CDP_ACQUIRE_TIMEOUT_MS)
-      : await input.bm.acquireTabLock(input.tabId, CDP_ACQUIRE_TIMEOUT_MS);
-  const acquireMs = Date.now() - acquireStart;
-  logTelemetry({ event: 'cdp_method_lock_acquire_ms', domain: input.domain, method: input.method, ms: acquireMs });
-  logTelemetry({ event: 'cdp_method_called', domain: input.domain, method: input.method, allowed: true, scope: entry.scope });
-
-  try {
-    const page = input.bm.getPageForTab(input.tabId);
-    if (!page) {
-      throw new Error(
-        `Cannot dispatch: tab ${input.tabId} not found.\n` +
-          'Cause: tab was closed between command queue and dispatch.\n' +
-          'Action: $B tabs to list current tabs.'
-      );
-    }
-    let session;
-    try {
-      session = await getCdpSession(page);
-    } catch (e: any) {
-      throw new Error(
-        `CDPSessionInvalidated: ${e.message}\n` +
-          'Cause: Playwright context was recreated (e.g., viewport scale change) and the prior CDP session is stale.\n' +
-          'Action: retry the command; the bridge will create a fresh session.'
-      );
-    }
-    // Race the call against a hard timeout.
-    const callPromise = session.send(qualified, input.params);
-    const timeoutPromise = new Promise((_, reject) =>
-      setTimeout(() => reject(new Error(`CDPBridgeTimeout: ${qualified} did not return within ${CDP_TIMEOUT_MS}ms`)), CDP_TIMEOUT_MS),
-    );
-    const raw = await Promise.race([callPromise, timeoutPromise]);
-    return { raw, entry };
-  } finally {
-    release();
-  }
-}