barebrowse 0.7.1 → 0.9.0

package/mcp-server.js

@@ -10,8 +10,47 @@
  */
 
 import { browse, connect } from './src/index.js';
-import { mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+// Read version from package.json so serverInfo.version doesn't drift behind
+// release bumps (pre-fix this was hardcoded 0.7.1 while package.json was 0.8.0).
+const _pkgPath = join(dirname(fileURLToPath(import.meta.url)), 'package.json');
+const PKG_VERSION = JSON.parse(readFileSync(_pkgPath, 'utf8')).version;
+
+/**
+ * Per-tool timeouts (ms). One blanket 30s was too short for SPA cold loads
+ * (goto regularly exceeded it on slow sites) and too long for instant ops
+ * like scroll. The split below is the H5 plan:
+ *   - navigation (goto/reload): 60s
+ *   - browser-history nav (back/forward): 30s
+ *   - interactive ops (click/type/press/scroll/hover/select/drag): 15s
+ *   - read-only ops (snapshot/tabs/eval/wait_for): 15s (wait_for has its own
+ *     internal deadline; this is the outer cap)
+ *   - heavy I/O (pdf/screenshot/upload): 45s
+ * Exported so tests can pin the contract.
+ */
+export const TIMEOUTS = {
+  goto: 60000,
+  reload: 60000,
+  back: 30000,
+  forward: 30000,
+  snapshot: 15000,
+  click: 15000,
+  type: 15000,
+  press: 15000,
+  scroll: 15000,
+  hover: 15000,
+  select: 15000,
+  drag: 15000,
+  tabs: 5000,
+  eval: 15000,
+  wait_for: 60000,
+  upload: 45000,
+  pdf: 45000,
+  screenshot: 45000,
+};
 
 // Optional: privacy assessment via wearehere
 let assessFn = null;
@@ -27,12 +66,17 @@ function isTransient(err) {
 }
 
 /**
- * Retry-once wrapper with per-attempt timeout.
- * On transient failure (CDP death OR timeout), resets session and retries once.
+ * Run fn with a per-attempt timeout. On transient failure (CDP death OR
+ * timeout), reset the session. If `retry` is true (default), retry once on
+ * a fresh page; if false, rethrow without retrying — required for
+ * non-idempotent ops (click/type/etc.) where a partial first attempt
+ * shouldn't be replayed against a blank fresh page.
  * @param {Function} fn - async function to execute
  * @param {number} timeoutMs - per-attempt timeout in ms
+ * @param {object} [opts]
+ * @param {boolean} [opts.retry=true] - whether to retry once on transient failure
  */
-async function withRetry(fn, timeoutMs) {
+async function withRetry(fn, timeoutMs, { retry = true } = {}) {
   async function attempt() {
     if (!timeoutMs) return await fn();
     let timer;
@@ -48,8 +92,9 @@ async function withRetry(fn, timeoutMs) {
     return await attempt();
   } catch (err) {
     if (!isTransient(err)) throw err;
-    // Transient failure — reset session and retry once
+    // Transient failure — reset session so the next request gets a fresh page.
     _page = null;
+    if (!retry) throw err;
     return await attempt();
   }
 }
@@ -96,10 +141,10 @@ function acquireAssessSlot() {
 }
 
 
-const TOOLS = [
+export const TOOLS = [
   {
     name: 'browse',
-    description: 'Browse a URL in a real browser. Use instead of web fetch when the page needs JavaScript, login cookies, consent dismissal, or bot detection. Returns a pruned ARIA snapshot with [ref=N] markers for interaction. Stateless — does not use the session page.',
+    description: 'One-shot headless browse — fetches a URL through a real browser (executes JS, injects cookies, dismisses consent, evades bot detection). Only when plain HTTP fetch can\'t render the page. Returns a pruned ARIA snapshot with [ref=N] markers. Stateless — for multi-step interaction use goto.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -112,7 +157,7 @@ const TOOLS = [
   },
   {
     name: 'goto',
-    description: 'Navigate the session page to a URL. Injects cookies from the user\'s browser for authenticated access. Returns ok — call snapshot to observe.',
+    description: 'Open URL in a persistent interactive browser session (pair with snapshot/click/type/press for multi-step flows). Use when the task needs clicking, typing, or form submission. Injects auth cookies. Returns ok — call snapshot to observe.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -221,8 +266,92 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: 'reload',
+    description: 'Reload the current page in the session. Returns ok — call snapshot to observe.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ignoreCache: { type: 'boolean', description: 'Bypass HTTP cache (hard reload). Default: false.' },
+      },
+    },
+  },
+  {
+    name: 'screenshot',
+    description: 'Capture a screenshot of the current page. Saves to .barebrowse/screenshot-*.png (or .jpeg/.webp) and returns the file path. Use the file with your image tools.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        format: { type: 'string', enum: ['png', 'jpeg', 'webp'], description: 'Image format (default: png)' },
+        quality: { type: 'number', description: 'JPEG/WebP quality 0-100 (default: 80, ignored for PNG)' },
+      },
+    },
+  },
+  {
+    name: 'wait_for',
+    description: 'Wait for visible text or a CSS selector to appear on the current page. Returns ok when found, throws on timeout.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'Substring that must appear in document.body.innerText' },
+        selector: { type: 'string', description: 'CSS selector that must match document.querySelector' },
+        timeout: { type: 'number', description: 'Timeout in ms (default: 30000)' },
+      },
+    },
+  },
+  {
+    name: 'tabs',
+    description: 'List open tabs in the session, or switch to one by index. Returns JSON array of { index, url, title } or "ok" after switch.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        switchTo: { type: 'number', description: 'Tab index to activate. Omit to just list tabs.' },
+      },
+    },
+  },
+  {
+    name: 'select',
+    description: 'Set the value of a <select> dropdown (or custom listbox) by ref. Returns ok.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ref: { type: 'string', description: 'Element ref from snapshot' },
+        value: { type: 'string', description: 'Option value or visible text to select' },
+      },
+      required: ['ref', 'value'],
+    },
+  },
+  {
+    name: 'hover',
+    description: 'Hover over an element by ref (triggers tooltips, hover menus). Returns ok.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ref: { type: 'string', description: 'Element ref from snapshot' },
+      },
+      required: ['ref'],
+    },
+  },
 ];
 
+// Powerful escape hatch — guarded behind an explicit env-var opt-in.
+// Runtime.evaluate in the user's authenticated session lets an agent read
+// cookies/localStorage, dispatch arbitrary events, hit any endpoint, etc.
+// Off by default; flip BAREBROWSE_MCP_EVAL=1 to enable.
+if (process.env.BAREBROWSE_MCP_EVAL === '1') {
+  TOOLS.push({
+    name: 'eval',
+    description: 'Run a JavaScript expression in the current page and return the result. POWERFUL: full access to the authenticated session — DOM, cookies, localStorage, fetch. Enabled because BAREBROWSE_MCP_EVAL=1 is set.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        expression: { type: 'string', description: 'JavaScript expression to evaluate' },
+      },
+      required: ['expression'],
+    },
+  });
+}
+
 // Add assess tool if wearehere is installed
 if (assessFn) {
   TOOLS.push({
@@ -261,7 +390,7 @@ async function handleToolCall(name, args) {
       try { await page.injectCookies(args.url); } catch {}
       await page.goto(args.url);
       return 'ok';
-    }, 30000);
+    }, TIMEOUTS.goto);
     case 'snapshot': return withRetry(async () => {
       const page = await getPage();
       const text = await page.snapshot();
@@ -271,22 +400,22 @@ async function handleToolCall(name, args) {
         return `Snapshot (${text.length} chars) saved to ${file}`;
       }
       return text;
-    }, 30000);
+    }, TIMEOUTS.snapshot);
     case 'click': return withRetry(async () => {
       const page = await getPage();
       await page.click(args.ref);
       return 'ok';
-    }, 30000);
+    }, TIMEOUTS.click, { retry: false });
     case 'type': return withRetry(async () => {
       const page = await getPage();
       await page.type(args.ref, args.text, { clear: args.clear });
       return 'ok';
-    }, 30000);
+    }, TIMEOUTS.type, { retry: false });
     case 'press': return withRetry(async () => {
       const page = await getPage();
       await page.press(args.key);
       return 'ok';
-    }, 30000);
+    }, TIMEOUTS.press, { retry: false });
     case 'scroll': return withRetry(async () => {
       const page = await getPage();
       let dy = args.deltaY;
@@ -298,31 +427,90 @@ async function handleToolCall(name, args) {
       }
       await page.scroll(dy);
       return 'ok';
-    }, 30000);
+    }, TIMEOUTS.scroll, { retry: false });
     case 'back': return withRetry(async () => {
       const page = await getPage();
       await page.goBack();
       return 'ok';
-    }, 30000);
+    }, TIMEOUTS.back, { retry: false });
     case 'forward': return withRetry(async () => {
       const page = await getPage();
       await page.goForward();
       return 'ok';
-    }, 30000);
+    }, TIMEOUTS.forward, { retry: false });
     case 'drag': return withRetry(async () => {
       const page = await getPage();
       await page.drag(args.fromRef, args.toRef);
       return 'ok';
-    }, 30000);
+    }, TIMEOUTS.drag, { retry: false });
     case 'upload': return withRetry(async () => {
       const page = await getPage();
       await page.upload(args.ref, args.files);
       return 'ok';
-    }, 30000);
+    }, TIMEOUTS.upload, { retry: false });
     case 'pdf': return withRetry(async () => {
       const page = await getPage();
       return await page.pdf({ landscape: args.landscape });
-    }, 30000);
+    }, TIMEOUTS.pdf);
+    case 'reload': return withRetry(async () => {
+      const page = await getPage();
+      await page.reload({ ignoreCache: !!args.ignoreCache });
+      return 'ok';
+    }, TIMEOUTS.reload);
+    case 'screenshot': return withRetry(async () => {
+      const page = await getPage();
+      const format = args.format || 'png';
+      const b64 = await page.screenshot({ format, quality: args.quality });
+      mkdirSync(OUTPUT_DIR, { recursive: true });
+      const ts = new Date().toISOString().replace(/[:.]/g, '-');
+      const file = join(OUTPUT_DIR, `screenshot-${ts}.${format}`);
+      writeFileSync(file, Buffer.from(b64, 'base64'));
+      return file;
+    }, TIMEOUTS.screenshot);
+    case 'wait_for': return withRetry(async () => {
+      const page = await getPage();
+      await page.waitFor({ text: args.text, selector: args.selector, timeout: args.timeout });
+      return 'ok';
+    }, TIMEOUTS.wait_for, { retry: false });
+    case 'tabs': return withRetry(async () => {
+      const page = await getPage();
+      if (typeof args.switchTo === 'number') {
+        await page.switchTab(args.switchTo);
+        return 'ok';
+      }
+      const list = await page.tabs();
+      return JSON.stringify(list, null, 2);
+    }, TIMEOUTS.tabs, { retry: false });
+    case 'select': return withRetry(async () => {
+      const page = await getPage();
+      await page.select(args.ref, args.value);
+      return 'ok';
+    }, TIMEOUTS.select, { retry: false });
+    case 'hover': return withRetry(async () => {
+      const page = await getPage();
+      await page.hover(args.ref);
+      return 'ok';
+    }, TIMEOUTS.hover, { retry: false });
+    case 'eval': {
+      // Only reachable when BAREBROWSE_MCP_EVAL=1 — the tool isn't registered
+      // otherwise, but this guard is the second line of defense in case the
+      // env var changes between tools/list and tools/call.
+      if (process.env.BAREBROWSE_MCP_EVAL !== '1') {
+        throw new Error('eval is disabled. Set BAREBROWSE_MCP_EVAL=1 to enable.');
+      }
+      return withRetry(async () => {
+        const page = await getPage();
+        const { result, exceptionDetails } = await page.cdp.send('Runtime.evaluate', {
+          expression: args.expression,
+          returnByValue: true,
+          awaitPromise: true,
+        });
+        if (exceptionDetails) {
+          throw new Error(exceptionDetails.text + (exceptionDetails.exception?.description ? `: ${exceptionDetails.exception.description}` : ''));
+        }
+        return result.value === undefined ? 'undefined' : JSON.stringify(result.value);
+      }, TIMEOUTS.eval, { retry: false });
+    }
     case 'assess': {
       if (!assessFn) throw new Error('wearehere is not installed. Run: npm install wearehere');
       const releaseSlot = await acquireAssessSlot();
@@ -391,7 +579,7 @@ async function handleMessage(msg) {
     return jsonrpcResponse(id, {
       protocolVersion: '2024-11-05',
       capabilities: { tools: {} },
-      serverInfo: { name: 'barebrowse', version: '0.7.1' },
+      serverInfo: { name: 'barebrowse', version: PKG_VERSION },
     });
   }
 
@@ -423,55 +611,71 @@ async function handleMessage(msg) {
 }
 
 // --- Stdio transport ---
+//
+// Exported as runStdio() so callers (notably cli.js) can explicitly start the
+// JSON-RPC loop. The previous "auto-start when isMain" guard broke the
+// `npx barebrowse mcp` path because cli.js launches the server via
+// `await import('./mcp-server.js')` — process.argv[1] is cli.js, not
+// mcp-server.js, so isMain was false and the loop never started. Both the
+// direct `node mcp-server.js` invocation and the cli.js path now call
+// runStdio() explicitly. Tests import TIMEOUTS/TOOLS without calling it.
+
+export function runStdio() {
+  // One-line startup banner to stderr (stderr because stdout is the JSON-RPC
+  // channel — must not contain non-JSON-RPC bytes). Captured by Claude Code's
+  // MCP log, makes "I added barebrowse twice and got the wrong one" issues
+  // diagnosable: the path here is the absolute file actually being served,
+  // so a scope conflict shows two different paths in two log files.
+  const _selfPath = fileURLToPath(import.meta.url);
+  process.stderr.write(`barebrowse mcp v${PKG_VERSION} | serving from ${_selfPath} | pid ${process.pid}\n`);
+
+  let buffer = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+
+    let newlineIdx;
+    while ((newlineIdx = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, newlineIdx).trim();
+      buffer = buffer.slice(newlineIdx + 1);
+      if (!line) continue;
 
-let buffer = '';
-
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', (chunk) => {
-  buffer += chunk;
-
-  let newlineIdx;
-  while ((newlineIdx = buffer.indexOf('\n')) !== -1) {
-    const line = buffer.slice(0, newlineIdx).trim();
-    buffer = buffer.slice(newlineIdx + 1);
-    if (!line) continue;
-
-    try {
-      const msg = JSON.parse(line);
-
-      handleMessage(msg).then((response) => {
-        if (response) {
+      try {
+        const msg = JSON.parse(line);
 
-          process.stdout.write(response + '\n');
+        handleMessage(msg).then((response) => {
+          if (response) {
+            process.stdout.write(response + '\n');
+          }
+        }).catch((err) => {
+          process.stdout.write(jsonrpcError(msg.id, -32700, `Error: ${err.message}`) + '\n');
+        });
+      } catch (err) {
+        process.stdout.write(jsonrpcError(null, -32700, `Parse error: ${err.message}`) + '\n');
+      }
+    }
+  });
 
-        }
-      }).catch((err) => {
+  // Prevent unhandled rejections and uncaught exceptions from crashing the server.
+  // Browser OOM/crash rejects all pending CDP promises — some may not be awaited.
+  process.on('unhandledRejection', () => { _page = null; });
+  process.on('uncaughtException', () => { _page = null; });
 
-        process.stdout.write(jsonrpcError(msg.id, -32700, `Error: ${err.message}`) + '\n');
-      });
-    } catch (err) {
+  // Clean up on exit
+  process.on('SIGINT', async () => {
+    if (_page) await _page.close().catch(() => {});
+    process.exit(0);
+  });
+  process.on('SIGTERM', async () => {
+    if (_page) await _page.close().catch(() => {});
+    process.exit(0);
+  });
+}
 
-      process.stdout.write(jsonrpcError(null, -32700, `Parse error: ${err.message}`) + '\n');
-    }
-  }
-});
-
-// Prevent unhandled rejections and uncaught exceptions from crashing the server.
-// Browser OOM/crash rejects all pending CDP promises — some may not be awaited.
-process.on('unhandledRejection', (err) => {
-  _page = null;
-});
-process.on('uncaughtException', (err) => {
-  _page = null;
-});
-
-// Clean up on exit
-process.on('SIGINT', async () => {
-  if (_page) await _page.close().catch(() => {});
-  process.exit(0);
-});
-
-process.on('SIGTERM', async () => {
-  if (_page) await _page.close().catch(() => {});
-  process.exit(0);
-});
+// Direct invocation (`node mcp-server.js`) still works without cli.js — auto-
+// start if this file IS process.argv[1]. The cli.js path imports + calls
+// runStdio() explicitly so we never depend on argv[1] matching.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runStdio();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barebrowse",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Authenticated web browsing for autonomous agents via CDP. URL in, pruned ARIA snapshot out.",
   "type": "module",
   "main": "src/index.js",
@@ -31,5 +31,5 @@
   "optionalDependencies": {
     "wearehere": "^1.0.0"
   },
-  "license": "MIT"
+  "license": "Apache-2.0"
 }

package/src/bareagent.js

@@ -244,6 +244,39 @@ export function createBrowseTools(opts = {}) {
         return await page.screenshot({ format });
       },
     },
+    {
+      name: 'reload',
+      description: 'Reload the current page. Returns the updated snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          ignoreCache: { type: 'boolean', description: 'Bypass HTTP cache (hard reload). Default: false.' },
+        },
+      },
+      execute: async ({ ignoreCache } = {}) => actionAndSnapshot((page) => page.reload({ ignoreCache })),
+    },
+    {
+      name: 'wait_for',
+      description: 'Wait for visible text or a CSS selector to appear on the current page. Returns the updated snapshot once found.',
+      parameters: {
+        type: 'object',
+        properties: {
+          text: { type: 'string', description: 'Substring that must appear in document.body.innerText' },
+          selector: { type: 'string', description: 'CSS selector that must match document.querySelector' },
+          timeout: { type: 'number', description: 'Timeout in ms (default: 30000)' },
+        },
+      },
+      execute: async ({ text, selector, timeout } = {}) => actionAndSnapshot((page) => page.waitFor({ text, selector, timeout })),
+    },
+    {
+      name: 'downloads',
+      description: 'List files captured via Content-Disposition: attachment downloads during this session. Returns JSON array of { url, suggestedFilename, savedPath, state, totalBytes, receivedBytes } per file.',
+      parameters: { type: 'object', properties: {} },
+      execute: async () => {
+        const page = await getPage();
+        return JSON.stringify(page.downloads.map((d) => ({ ...d })), null, 2);
+      },
+    },
   ];
 
   // Add assess tool if wearehere is installed

package/src/chromium.js

@@ -6,7 +6,47 @@
  */
 
 import { execSync, spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, rmSync } from 'node:fs';
+
+// Track launched browsers so we can clean them up if the parent crashes.
+// Registered exit handlers (one-time) iterate this set on shutdown.
+const activeBrowsers = new Set();
+let exitHandlersRegistered = false;
+
+function reapAllSync() {
+  const toReap = [...activeBrowsers];
+  activeBrowsers.clear();
+  // Send SIGKILL to everything first so the kernel reaps in parallel
+  for (const b of toReap) {
+    try { if (!b.process.killed) b.process.kill('SIGKILL'); } catch {}
+  }
+  // Then poll each for actual death before removing its profile dir —
+  // Chromium can hold file handles briefly even after SIGKILL, which would
+  // race rmSync. Cap the wait so a stuck process can't hang shutdown.
+  for (const b of toReap) {
+    for (let i = 0; i < 20; i++) {
+      try { process.kill(b.process.pid, 0); } catch { break; }
+      try { execSync('sleep 0.05'); } catch {}
+    }
+    if (b.ownedProfileDir) {
+      try { rmSync(b.ownedProfileDir, { recursive: true, force: true }); } catch {}
+    }
+  }
+}
+
+function registerExitHandlers() {
+  if (exitHandlersRegistered) return;
+  exitHandlersRegistered = true;
+  // 'exit' is sync-only — must use synchronous APIs (SIGKILL, rmSync)
+  process.once('exit', reapAllSync);
+  for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.once(sig, () => {
+      reapAllSync();
+      // Re-raise default behavior so the parent's exit code matches the signal
+      process.kill(process.pid, sig);
+    });
+  }
+}
 
 // Common Chromium binary paths by platform (Linux focus for POC)
 const CANDIDATES = [
@@ -75,6 +115,14 @@ export async function launch(opts = {}) {
     '--disable-sync',
     '--disable-translate',
     '--mute-audio',
+    // Force every iframe (same-origin included) into its own renderer so it
+    // gets a dedicated CDP session via Target.setAutoAttach. Without this,
+    // same-origin iframes stay in the parent process — getFullAXTree still
+    // works via frameId, but Input.dispatchMouseEvent on the parent session
+    // uses parent-viewport coords while DOM.getBoxModel for iframe-internal
+    // nodes returns frame-local coords, so clicks land off-target. The OOPIF
+    // path side-steps that: each frame has its own Input domain.
+    '--site-per-process',
     // Headless-only flags
     ...(!opts.headed ? ['--headless=new', '--hide-scrollbars'] : []),
     // Suppress permission prompts (location, notifications, camera, mic, etc.)
@@ -90,12 +138,14 @@ export async function launch(opts = {}) {
     args.push(`--proxy-server=${opts.proxy}`);
   }
 
+  // Track the temp profile dir only when we create one — caller-supplied dirs
+  // are the caller's to manage. ownedProfileDir gets rm'd in cleanupBrowser.
+  let ownedProfileDir = null;
   if (opts.userDataDir) {
     args.push(`--user-data-dir=${opts.userDataDir}`);
   } else {
-    // Use a unique temp profile so we don't lock the user's profile
-    // or conflict with parallel instances
-    args.push(`--user-data-dir=/tmp/barebrowse-${process.pid}-${Date.now()}`);
+    ownedProfileDir = `/tmp/barebrowse-${process.pid}-${Date.now()}`;
+    args.push(`--user-data-dir=${ownedProfileDir}`);
   }
 
   // about:blank as initial page
@@ -138,7 +188,52 @@ export async function launch(opts = {}) {
   // Extract port from wsUrl
   const actualPort = parseInt(new URL(wsUrl).port, 10);
 
-  return { wsUrl, process: child, port: actualPort };
+  const browser = { wsUrl, process: child, port: actualPort, ownedProfileDir };
+
+  // Register for parent-crash reaping. Auto-untrack on natural exit so
+  // a normally-exited browser doesn't leave a stale entry around.
+  registerExitHandlers();
+  activeBrowsers.add(browser);
+  child.once('exit', () => activeBrowsers.delete(browser));
+
+  return browser;
+}
+
+/**
+ * Kill a launched browser and remove its temp profile dir (if we created one).
+ * Waits up to 2s for the process to actually exit before unlinking the dir —
+ * Chromium can still hold files briefly after SIGTERM, which races rmSync.
+ * Safe to call on partially-failed launches or already-dead processes.
+ * @returns {Promise<void>}
+ */
+export async function cleanupBrowser(browser) {
+  if (!browser) return;
+  activeBrowsers.delete(browser);
+  if (browser.process && !browser.process.killed && browser.process.exitCode === null) {
+    const exited = new Promise((resolve) => {
+      const timer = setTimeout(resolve, 2000);
+      browser.process.once('exit', () => { clearTimeout(timer); resolve(); });
+    });
+    try { browser.process.kill(); } catch {}
+    await exited;
+  }
+  if (browser.ownedProfileDir) {
+    // Chromium can still flush files for ~hundreds of ms after exit; with
+    // --site-per-process (added in H2) every iframe is its own renderer
+    // process, each with its own pending file handles, so the old 10×100ms
+    // window (1s) wasn't always enough under parallel test load. Now
+    // 25×100ms (2.5s) plus a polling jitter to avoid every concurrent
+    // cleanup hammering at the same tick.
+    for (let i = 0; i < 25; i++) {
+      try {
+        rmSync(browser.ownedProfileDir, { recursive: true, force: true });
+        break;
+      } catch (err) {
+        if (err.code !== 'ENOTEMPTY' && err.code !== 'EBUSY') break;
+        await new Promise((r) => setTimeout(r, 100 + Math.floor(Math.random() * 50)));
+      }
+    }
+  }
 }
 
 /**
@@ -152,3 +247,18 @@ export async function getDebugUrl(port) {
   const data = await res.json();
   return data.webSocketDebuggerUrl;
 }
+
+/**
+ * Attach to a Chromium already running with --remote-debugging-port=<port>.
+ * Returns the same shape as launch() but with process: null and
+ * ownedProfileDir: null — cleanupBrowser() becomes a no-op so we never
+ * kill a browser we did not start or remove a profile we do not own.
+ * @param {object} opts
+ * @param {number} opts.port - The debug port the running browser is listening on
+ * @returns {Promise<{wsUrl: string, process: null, port: number, ownedProfileDir: null}>}
+ */
+export async function attach({ port }) {
+  if (!port) throw new Error('attach({ port }) requires a port number');
+  const wsUrl = await getDebugUrl(port);
+  return { wsUrl, process: null, port, ownedProfileDir: null };
+}

package/src/consent.js

@@ -290,14 +290,9 @@ function findAcceptButton(dialogId, nodes, nodeMap, parentMap) {
  * Only matches strong patterns (not single-word fallbacks) to avoid false positives.
  */
 function tryGlobalConsentButton(nodes, session) {
-  // Only use the specific multi-word patterns for global search
-  const strictPatterns = ACCEPT_PATTERNS.filter((p) => {
-    const src = p.source;
-    return src.includes('\\s') || src.includes('\\b.*\\b.*\\b');
-  });
-
-  // Actually, let's just use all non-single-word patterns
-  const safePatterns = ACCEPT_PATTERNS.slice(0, -3); // exclude ^accept$, ^agree$, ^ok$
+  // Multi-word patterns only — exclude the bare ^accept$/^agree$/^ok$ from
+  // ACCEPT_PATTERNS so we don't false-match unrelated buttons page-wide.
+  const safePatterns = ACCEPT_PATTERNS.slice(0, -3);
 
   for (const pattern of safePatterns) {
     for (const node of nodes) {