@monoes/monobrowse 1.0.3 → 1.0.5

package/src/__tests__/batch-eval-parsing.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import { parseBatchCommandLine } from '../cli/commands.js';
+
+describe('parseBatchCommandLine — eval expressions inside a batch command string', () => {
+  it('does not strip string-literal quotes from a raw JS expression passed to eval', () => {
+    // Regression: tokenizeBatchCommand's shell-style quote-stripping (correct for
+    // space-separated args like `fill @e1 "some value"`) previously ran on eval's
+    // expression too, silently deleting the expression's OWN string-literal quotes
+    // and turning `document.querySelector('a')` into `document.querySelector(a)` —
+    // a reference to an undefined identifier instead of a string literal.
+    const input = "eval document.querySelector('meta[name=mm-token]').content";
+    const { subName, subArgs } = parseBatchCommandLine(input);
+    expect(subName).toBe('eval');
+    expect(subArgs).toEqual(["document.querySelector('meta[name=mm-token]').content"]);
+  });
+
+  it('preserves double-quoted string literals in the expression too', () => {
+    const input = 'eval document.querySelector("body").tagName';
+    const { subName, subArgs } = parseBatchCommandLine(input);
+    expect(subName).toBe('eval');
+    expect(subArgs).toEqual(['document.querySelector("body").tagName']);
+  });
+
+  it('preserves an expression with multiple quoted segments and internal spaces', () => {
+    const input = "eval [...document.querySelectorAll('li')].map(x => x.textContent.trim())";
+    const { subName, subArgs } = parseBatchCommandLine(input);
+    expect(subName).toBe('eval');
+    expect(subArgs).toEqual(["[...document.querySelectorAll('li')].map(x => x.textContent.trim())"]);
+  });
+
+  it('still recognizes --json and --max-output flags placed before the expression', () => {
+    const input = "eval --json --max-output 100 document.querySelector('a').href";
+    const { subName, subArgs, flags } = parseBatchCommandLine(input);
+    expect(subName).toBe('eval');
+    expect(flags).toMatchObject({ json: true, 'max-output': 100 });
+    expect(subArgs).toEqual(["document.querySelector('a').href"]);
+  });
+
+  it('leaves non-eval commands tokenized exactly as before (no behavior change)', () => {
+    const input = 'fill @e1 "some value with spaces"';
+    const { subName, subArgs } = parseBatchCommandLine(input);
+    expect(subName).toBe('fill');
+    expect(subArgs).toEqual(['@e1', 'some value with spaces']);
+  });
+
+  it('leaves a simple multi-token command tokenized exactly as before', () => {
+    const input = 'open https://example.com --port 9333';
+    const { subName, subArgs } = parseBatchCommandLine(input);
+    expect(subName).toBe('open');
+    expect(subArgs).toEqual(['https://example.com', '--port', '9333']);
+  });
+});

package/src/__tests__/browser-launch.test.ts

@@ -0,0 +1,102 @@
+/**
+ * Unit tests for launchBrowser's port-scan/attach decisions (browser.ts).
+ * Deliberately scoped to branches reachable WITHOUT spawning a real Chrome —
+ * each scenario below resolves via attach or a thrown error before
+ * launchBrowser would ever exec a browser binary, so these run fast and
+ * don't depend on Chrome being installed in CI.
+ *
+ * Fixed port range (23470-23479) chosen to avoid colliding with real
+ * services; each test binds/tears down its own listeners.
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import { createServer as createTcpServer, type Server as TcpServer, type Socket } from 'net';
+import { createServer as createHttpServer, type Server as HttpServer } from 'http';
+import { launchBrowser } from '../browser/browser.js';
+
+const BASE = 23470;
+
+let servers: Array<TcpServer | HttpServer> = [];
+let sockets: Socket[] = [];
+
+afterEach(async () => {
+  // server.close() only stops accepting NEW connections — it waits for
+  // already-open ones (the fetches that hung until their AbortSignal fired)
+  // to close on their own, which can outlast the test. Destroy explicitly.
+  for (const sock of sockets) sock.destroy();
+  sockets = [];
+  await Promise.all(servers.map(s => new Promise<void>(resolve => s.close(() => resolve()))));
+  servers = [];
+}, 5000);
+
+/** Bind a bare TCP listener — accepts connections but speaks no HTTP/CDP. */
+function occupyNonChrome(port: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const s = createTcpServer(sock => { sockets.push(sock); /* accept and do nothing — no CDP response */ });
+    s.once('error', reject);
+    s.listen(port, '127.0.0.1', () => { servers.push(s); resolve(); });
+  });
+}
+
+/** Bind an HTTP server that answers /json/version like a real Chrome would. */
+function occupyChrome(port: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const s = createHttpServer((req, res) => {
+      if (req.url === '/json/version') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ Browser: 'Chrome/999.0.0.0' }));
+      } else {
+        res.writeHead(404); res.end();
+      }
+    });
+    s.on('connection', sock => sockets.push(sock));
+    s.once('error', reject);
+    s.listen(port, '127.0.0.1', () => { servers.push(s); resolve(); });
+  });
+}
+
+describe('launchBrowser — port scan/attach decisions', () => {
+  it('attaches immediately when the EXACT requested port already identifies as Chrome', async () => {
+    const port = BASE + 0;
+    await occupyChrome(port);
+    await expect(launchBrowser({ port })).resolves.toBe(port);
+  });
+
+  it('strictPort: throws immediately on an occupied non-Chrome requested port, never scans', async () => {
+    const port = BASE + 1;
+    await occupyNonChrome(port);
+    await occupyChrome(port + 1); // would succeed if scanning happened — must not be reached
+    await expect(launchBrowser({ port, strictPort: true }))
+      .rejects.toThrow(/does not identify as Chrome/);
+  });
+
+  it('strictPort: attaches on an occupied Chrome requested port (identical to non-strict)', async () => {
+    const port = BASE + 2;
+    await occupyChrome(port);
+    await expect(launchBrowser({ port, strictPort: true })).resolves.toBe(port);
+  });
+
+  it('all candidates occupied by non-Chrome processes: throws a clear range error', async () => {
+    const port = BASE + 3;
+    // Occupy the full 10-port scan window with non-Chrome listeners.
+    for (let i = 0; i < 10; i++) await occupyNonChrome(port + i);
+    await expect(launchBrowser({ port })).rejects.toThrow(
+      new RegExp(`Ports ${port}-${port + 9} are all occupied`)
+    );
+  }, 15000); // generous margin — 10 candidates, each a fast isTcpPortOpen check
+
+  it('a Chrome instance on a SCANNED (not the originally requested) port is skipped, not attached to', async () => {
+    // Security-relevant case: the attach-if-Chrome shortcut must apply only
+    // to the exact port the caller asked for. A Chrome instance sitting on a
+    // later candidate the caller never named must not be silently attached
+    // to — occupied candidates (Chrome or not) beyond the first are simply
+    // skipped, so if every candidate is occupied the call still fails even
+    // though one of them is an attachable Chrome.
+    const port = BASE + 4;
+    await occupyNonChrome(port);       // requested port: occupied, not Chrome
+    await occupyChrome(port + 1);      // scanned candidate: IS Chrome — must be skipped, not attached
+    for (let i = 2; i < 10; i++) await occupyNonChrome(port + i); // remaining candidates: occupied
+    await expect(launchBrowser({ port })).rejects.toThrow(
+      new RegExp(`Ports ${port}-${port + 9} are all occupied`)
+    );
+  }, 15000); // generous margin — 10 candidates, each a fast isTcpPortOpen check
+});

package/src/__tests__/ref-cache.test.ts

@@ -132,3 +132,44 @@ describe('ref-cache', () => {
     expect(loaded).toBeNull();
   });
 });
+
+describe('active-port persistence', () => {
+  it('round-trip: save then load returns the port; launched defaults true', async () => {
+    const mod = await importRefCache();
+    await mod.saveActivePort(9333);
+    expect(await mod.loadActivePort()).toBe(9333);
+    expect(await mod.loadActivePortInfo()).toEqual({ port: 9333, launched: true });
+  });
+
+  it('connect provenance: launched:false survives the round-trip', async () => {
+    const mod = await importRefCache();
+    await mod.saveActivePort(9229, { launched: false });
+    expect(await mod.loadActivePortInfo()).toEqual({ port: 9229, launched: false });
+  });
+
+  it('clear removes the file; load returns null afterwards', async () => {
+    const mod = await importRefCache();
+    await mod.saveActivePort(9333);
+    await mod.clearActivePort();
+    expect(await mod.loadActivePort()).toBeNull();
+    expect(await mod.loadActivePortInfo()).toBeNull();
+  });
+
+  it('clear with no file resolves without throwing', async () => {
+    const mod = await importRefCache();
+    await mod.clearActivePort();
+    await expect(mod.clearActivePort()).resolves.toBeUndefined();
+  });
+
+  it('rejects out-of-range or non-integer persisted ports', async () => {
+    const mod = await importRefCache();
+    const { writeFile, mkdir } = await import('fs/promises');
+    const dir = join(process.cwd(), '.monomind', 'monobrowse');
+    await mkdir(dir, { recursive: true });
+    for (const bad of [80, 70000, 1.5, '9222', null]) {
+      await writeFile(join(dir, 'active-port.json'), JSON.stringify({ port: bad }));
+      expect(await mod.loadActivePort()).toBeNull();
+      expect(await mod.loadActivePortInfo()).toBeNull();
+    }
+  });
+});

package/src/browser/actions.ts

@@ -496,12 +496,22 @@ export async function removeInitScript(client: CdpClient, sessionId: string, ide
   await client.send('Page.removeScriptToEvaluateOnNewDocument', { identifier }, sessionId);
 }
 
+// Default cap on how long an evaluateJs() call waits for Runtime.evaluate to
+// resolve. Because this always passes `awaitPromise: true`, an expression
+// like `new Promise(() => {})` never settles — the underlying CdpClient.send()
+// has no timeout of its own (the CDP_RESPONSE_SIZE_LIMIT in cdp.ts only guards
+// the HTTP /json/* endpoints, not WebSocket command responses), so without
+// this the caller (e.g. the `eval` CLI command) would hang forever with
+// nothing to kill it.
+const DEFAULT_EVAL_TIMEOUT_MS = 30_000;
+
 export async function evaluateJs(
   client: CdpClient,
   sessionId: string,
-  expression: string
+  expression: string,
+  timeoutMs: number = DEFAULT_EVAL_TIMEOUT_MS
 ): Promise<unknown> {
-  const result = await client.send<{
+  const evalPromise = client.send<{
     result: { value?: unknown; type: string; description?: string };
     exceptionDetails?: { text: string; exception?: { description?: string } };
   }>('Runtime.evaluate', {
@@ -510,6 +520,16 @@ export async function evaluateJs(
     awaitPromise: true,
   }, sessionId);
 
+  const result = await (timeoutMs > 0
+    ? Promise.race([
+        evalPromise,
+        new Promise<never>((_, reject) => {
+          const t = setTimeout(() => reject(new Error(`JS evaluation timed out after ${timeoutMs}ms`)), timeoutMs);
+          t.unref?.();
+        }),
+      ])
+    : evalPromise);
+
   if (result.exceptionDetails) {
     throw new Error(`JS evaluation error: ${result.exceptionDetails.exception?.description ?? result.exceptionDetails.text}`);
   }

package/src/browser/browser.ts

@@ -2,6 +2,7 @@ import { spawn, execSync } from 'child_process';
 import { existsSync } from 'fs';
 import { tmpdir } from 'os';
 import { join } from 'path';
+import { connect } from 'net';
 import { CdpClient, fetchTargets, fetchNewTarget } from './cdp.js';
 import type { BrowserConfig, CdpTarget } from './types.js';
 import { CHROME_EXECUTABLES } from './types.js';
@@ -11,6 +12,14 @@ import { setupDialogAutoHandling } from './dialog.js';
 const DEFAULT_PORT = 9222;
 const LAUNCH_TIMEOUT = 10_000;
 const POLL_INTERVAL = 200;
+const BROWSER_CLOSE_TIMEOUT_MS = 3000;
+
+// Tracks the PID of Chrome instances *we* spawned, keyed by CDP port, so
+// closeBrowser() has a kill fallback when the graceful `Browser.close` CDP
+// command fails or times out (e.g. a hung renderer). Ports we merely attached
+// to (already-running browser) are never recorded here — we only ever kill
+// processes we launched ourselves.
+const launchedPids = new Map<number, number>();
 
 function findChrome(executablePath?: string): string {
   if (executablePath) {
@@ -42,18 +51,105 @@ export async function isPortOpen(port: number): Promise<boolean> {
   }
 }
 
+/**
+ * Confirm the CDP endpoint on `port` actually identifies as Chrome/Chromium
+ * via `/json/version`'s `Browser` field, rather than assuming any CDP-speaking
+ * responder is "ours". Reduces (does not eliminate) the risk of silently
+ * attaching to an unrelated real browser that happens to be listening there.
+ */
+async function isChromeIdentity(port: number): Promise<boolean> {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/json/version`, { signal: AbortSignal.timeout(1000) });
+    if (!res.ok) return false;
+    const info = (await res.json()) as { Browser?: string };
+    return typeof info.Browser === 'string' && /chrom(e|ium)/i.test(info.Browser);
+  } catch {
+    return false;
+  }
+}
+
+/** Raw TCP connect probe — distinguishes "nothing listening" from "something listening that isn't CDP". */
+function isTcpPortOpen(port: number, timeoutMs = 1000): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = connect({ host: '127.0.0.1', port, timeout: timeoutMs });
+    const done = (result: boolean) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(result);
+    };
+    socket.once('connect', () => done(true));
+    socket.once('timeout', () => done(false));
+    socket.once('error', () => done(false));
+  });
+}
+
+/** Ports scanned when the requested one is occupied by a non-Chrome process
+ *  (e.g. another local tool that happens to reuse Chrome's conventional CDP
+ *  default, 9222 — mirrors the auto-increment convention this monorepo's own
+ *  dashboard server uses in bindServer/server.mjs). Only occupied-by-a-
+ *  DIFFERENT-process is worked around; an already-attachable Chrome on the
+ *  requested port is still returned as-is (existing "attach, don't relaunch"
+ *  behavior). */
+const LAUNCH_PORT_SCAN_TRIES = 10;
+
 export async function launchBrowser(config: BrowserConfig = {}): Promise<number> {
   const rawPort = config.port ?? DEFAULT_PORT;
   // Validate port is in a safe range for localhost CDP debugging
   if (!Number.isInteger(rawPort) || rawPort < 1024 || rawPort > 65535) {
     throw new Error(`Invalid port: ${rawPort}. Must be an integer between 1024 and 65535.`);
   }
-  const port = rawPort;
 
-  if (await isPortOpen(port)) {
-    return port;
+  // strictPort: fail fast on the exact requested port, matching the old
+  // behavior (Vite has the same escape hatch for the same reason) — for
+  // callers that treat the error as a signal ("this port is taken by
+  // something else, bail") rather than consuming the returned port.
+  if (config.strictPort) {
+    if (await isTcpPortOpen(rawPort)) {
+      if (await isChromeIdentity(rawPort)) return rawPort;
+      throw new Error(
+        `Port ${rawPort} is occupied by a process that does not identify as Chrome/Chromium. ` +
+        `Refusing to attach — pass a different port or free port ${rawPort}.`
+      );
+    }
+    return launchOnFreePort(config, rawPort);
+  }
+
+  const candidates: number[] = [];
+  for (let i = 0; i < LAUNCH_PORT_SCAN_TRIES && rawPort + i <= 65535; i++) candidates.push(rawPort + i);
+
+  // Attach-if-already-Chrome only applies to the EXACT requested port — the
+  // original, deliberate, single-port risk ("don't silently take over an
+  // unrelated real browser that happens to be on this port"). Scanning past
+  // an occupied default must not let that same shortcut attach to a
+  // DIFFERENT Chrome instance the caller never named; forward candidates are
+  // launch-only (skip if anything is there, Chrome or not).
+  if (await isTcpPortOpen(rawPort)) {
+    if (await isChromeIdentity(rawPort)) return rawPort;
+  } else {
+    return launchOnFreePort(config, rawPort);
+  }
+
+  for (const candidate of candidates.slice(1)) {
+    // TCP-level check for "is anything at all listening" — isPortOpen()
+    // does a full CDP /json fetch, which returns false BOTH for a genuinely
+    // free port and for one occupied by a non-CDP process (that ambiguity is
+    // exactly what the post-spawn isTcpPortOpen fallback below exists to
+    // resolve, the hard way, after a 10s launch timeout). Checking the raw
+    // socket first tells free and occupied apart up front, so the scan can
+    // skip an occupied candidate instead of trying to spawn Chrome on top of
+    // it and only discovering the conflict after a timeout.
+    if (!(await isTcpPortOpen(candidate))) return launchOnFreePort(config, candidate);
+    // Occupied (by anything — not just non-Chrome, per the note above) —
+    // try the next candidate instead of failing outright, same as a normal
+    // EADDRINUSE retry would.
   }
+  throw new Error(
+    `Ports ${candidates[0]}-${candidates[candidates.length - 1]} are all occupied and port ${candidates[0]} ` +
+    `isn't a Chrome/Chromium instance to attach to. Pass a different --port.`
+  );
+}
 
+async function launchOnFreePort(config: BrowserConfig, port: number): Promise<number> {
   const chromePath = findChrome(config.executablePath);
   const userDataDir = config.userDataDir ?? join(tmpdir(), `monomind-browser-${port}`);
 
@@ -89,11 +185,28 @@ export async function launchBrowser(config: BrowserConfig = {}): Promise<number>
     stdio: 'ignore',
   });
   child.unref();
+  if (child.pid) launchedPids.set(port, child.pid);
 
   const deadline = Date.now() + LAUNCH_TIMEOUT;
   while (Date.now() < deadline) {
     await sleep(POLL_INTERVAL);
-    if (await isPortOpen(port)) return port;
+    if (await isPortOpen(port)) {
+      if (await isChromeIdentity(port)) return port;
+      throw new Error(
+        `Port ${port} is occupied by a CDP-speaking process that does not identify as Chrome/Chromium. ` +
+        `Refusing to attach — pass a different port or free port ${port}.`
+      );
+    }
+  }
+
+  // Timed out waiting for our Chrome to come up on the port. Distinguish
+  // "nothing is listening" (real launch failure) from "something non-CDP is
+  // squatting the port" (confusing generic timeout otherwise) via a raw TCP probe.
+  if (await isTcpPortOpen(port)) {
+    throw new Error(
+      `Port ${port} is occupied by a non-Chrome process (TCP connection succeeds but no CDP response within ${LAUNCH_TIMEOUT}ms). ` +
+      `Free the port or pass a different one.`
+    );
   }
 
   throw new Error(`Chrome failed to start on port ${port} within ${LAUNCH_TIMEOUT}ms`);
@@ -140,6 +253,52 @@ export async function connectToTarget(port: number, targetId?: string): Promise<
   return { client, target, sessionId };
 }
 
+/**
+ * Cleanly terminate a Chrome/Chromium instance we launched on `port`.
+ * Sends the `Browser.close` CDP command (the correct graceful shutdown —
+ * closes all tabs and exits the process cleanly) over `client`'s connection.
+ * If that command fails, times out, or the connection is already gone,
+ * falls back to killing the tracked PID directly so a headed/interactive
+ * browser window (e.g. one spawned for a login/CAPTCHA flow) never lingers
+ * as a visible, authenticated, still-debuggable orphan process.
+ */
+export async function closeBrowser(client: CdpClient, port: number): Promise<void> {
+  let gracefullyClosed = false;
+  try {
+    await Promise.race([
+      client.send('Browser.close', {}),
+      new Promise<never>((_, reject) => {
+        const t = setTimeout(() => reject(new Error('Browser.close timed out')), BROWSER_CLOSE_TIMEOUT_MS);
+        t.unref?.();
+      }),
+    ]);
+    gracefullyClosed = true;
+  } catch {
+    // fall through to PID-kill fallback below
+  }
+
+  const pid = launchedPids.get(port);
+  if (pid === undefined) return; // not a process we launched — nothing to kill
+  launchedPids.delete(port);
+
+  if (!gracefullyClosed) {
+    try { process.kill(pid, 'SIGKILL'); } catch { /* already exited */ }
+    return;
+  }
+
+  // Browser.close was acknowledged — give the process a moment to exit on
+  // its own, then verify and force-kill as a safety net in case it hung.
+  const t = setTimeout(() => {
+    try {
+      process.kill(pid, 0); // throws if the process is already gone
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      /* already exited — expected path */
+    }
+  }, 1000);
+  t.unref?.();
+}
+
 export async function openUrl(client: CdpClient, sessionId: string, url: string): Promise<void> {
   // Cap to 2 MB to prevent OOM in CDP message serializer (e.g. data: URI attacks)
   if (url.length > 2_097_152) throw new Error('URL exceeds 2 MB limit');

package/src/browser/cdp.ts

@@ -151,7 +151,7 @@ export async function fetchTargets(port: number): Promise<CdpTarget[]> {
 
 export async function fetchNewTarget(port: number, url: string): Promise<CdpTarget> {
   // Chrome v92+ requires PUT for /json/new; GET returns 405. URL must be encoded.
-  const res = await fetch(`http://127.0.0.1:${port}/json/new?${url}`, { method: 'PUT' });
+  const res = await fetch(`http://127.0.0.1:${port}/json/new?${encodeURIComponent(url)}`, { method: 'PUT' });
   if (!res.ok) throw new Error(`Failed to create target: ${res.statusText}`);
   return readCdpJson(res) as Promise<CdpTarget>;
 }

package/src/browser/dashboard/server.ts

@@ -1,10 +1,11 @@
 import { createServer, IncomingMessage, ServerResponse } from 'node:http';
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'node:fs';
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
+import { randomBytes } from 'node:crypto';
 
 export interface StepEvent {
   type: string;
@@ -57,6 +58,21 @@ let instance: DashboardServer | null = null;
 export function startDashboard(port = DEFAULT_PORT): DashboardServer {
   if (instance) return instance;
 
+  // ── Security: per-process auth credential for mutating (non-GET) requests ──
+  // Generated once per server start and written to a well-known location so
+  // trusted local callers (CLI) can read it and pass it back via an auth
+  // header or query param on non-GET routes. Mirrors the pattern used by the
+  // main CLI dashboard (packages/@monomind/cli/src/ui/server.ts).
+  const dashboardAuthValue = randomBytes(24).toString('hex');
+  try {
+    const authFileDir = join(homedir(), '.monomind');
+    mkdirSync(authFileDir, { recursive: true });
+    writeFileSync(join(authFileDir, 'monobrowse-dashboard-token'), dashboardAuthValue, { mode: 0o600 });
+  } catch {
+    // best-effort: if we can't persist the token, mutating routes still
+    // enforce it in-memory — trusted callers just won't be able to read it.
+  }
+
   const runHistory: RunRecord[] = [];
   const stopRequests = new Set<string>();
   /** Map from client (WebSocket or SSE response) to the subscribed project dir,
@@ -79,6 +95,13 @@ export function startDashboard(port = DEFAULT_PORT): DashboardServer {
   } catch {
     uiHtml = `<!DOCTYPE html><html><head><title>monobrowse dashboard</title></head><body style="background:#0f0f1a;color:#ccc;font-family:system-ui;padding:20px"><h1>monobrowse dashboard</h1><p>Dashboard UI not found. Run the build to include ui.html.</p><script>let _retryDelay=1000;function connectSSE(){const es=new EventSource('/events');es.onmessage=e=>{console.log(JSON.parse(e.data));_retryDelay=1000;};es.onerror=()=>{es.close();setTimeout(connectSSE,Math.min(_retryDelay*=2,30000));};};connectSSE();</script></body></html>`;
   }
+  // Hand the per-process auth token to the served page so its own JS (e.g. the
+  // stop button) can pass it back on mutating requests. Injected once at
+  // startup — the loopback-only page is the sole reader.
+  const tokenScript = `<script>window.__MONOBROWSE_TOKEN__=${JSON.stringify(dashboardAuthValue)};</script>`;
+  uiHtml = uiHtml.includes('</head>')
+    ? uiHtml.replace('</head>', `${tokenScript}</head>`)
+    : tokenScript + uiHtml;
 
   const server = createServer(async (req, res) => {
     const url = req.url ?? '/';
@@ -100,8 +123,20 @@ export function startDashboard(port = DEFAULT_PORT): DashboardServer {
       return;
     }
 
+    // ── Security: require a matching auth token on all mutating routes ──────
+    // Binding to loopback only stops remote attackers, not a malicious page
+    // open in the user's own browser (DNS rebinding / same-origin fetch to
+    // 127.0.0.1). Require the per-process token via header or query param on
+    // every non-GET/HEAD route; GET/SSE reads stay open on the loopback baseline.
     if (url.startsWith('/stop/') && req.method === 'POST') {
-      const runId = url.slice(6);
+      const parsedAuth = new URL(url, 'http://localhost');
+      const suppliedAuth = req.headers['x-monobrowse-token'] || parsedAuth.searchParams.get('token') || '';
+      if (suppliedAuth !== dashboardAuthValue) {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Unauthorized: missing or invalid auth token' }));
+        return;
+      }
+      const runId = url.slice(6).split('?')[0];
       stopRequests.add(runId);
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ ok: true, runId }));

package/src/browser/dashboard/ui.html

@@ -678,7 +678,7 @@ function renderCards() {
     '</div>';
   }).join('');
 }
-function stopRun(id) { fetch('/stop/' + id, { method: 'POST' }).catch(function() {}); }
+function stopRun(id) { fetch('/stop/' + id, { method: 'POST', headers: { 'x-monobrowse-token': (window.__MONOBROWSE_TOKEN__ || '') } }).catch(function() {}); }
 
 // ═══════════════════════════════════════════════════════════════════
 // NODE PALETTE DEFINITIONS

package/src/browser/network.ts

@@ -6,6 +6,17 @@ export async function getCookies(client: CdpClient, sessionId: string): Promise<
   return result.cookies ?? [];
 }
 
+/**
+ * Get cookies scoped to specific page URLs via `Network.getCookies`, instead of
+ * `Network.getAllCookies` which returns cookies for every origin in the browser
+ * profile. Used for session save/export so we don't leak session tokens for
+ * unrelated domains the user happens to be logged into.
+ */
+export async function getCookiesForUrls(client: CdpClient, sessionId: string, urls: string[]): Promise<CdpCookie[]> {
+  const result = await client.send<{ cookies: CdpCookie[] }>('Network.getCookies', { urls }, sessionId);
+  return result.cookies ?? [];
+}
+
 export async function setCookies(client: CdpClient, sessionId: string, cookies: CdpCookie[]): Promise<void> {
   await client.send('Network.setCookies', { cookies }, sessionId);
 }

package/src/browser/record.ts

@@ -15,8 +15,20 @@ export interface RecordOptions {
 export interface RecordingState {
   frames: string[];
   offScreencast: (() => void) | null;
+  totalBytes: number;
+  autoStopped: boolean;
 }
 
+// Unlike har.ts's MAX_REQUESTS_PER_SESSION cap on the analogous network-request
+// buffer, the screencast frame buffer previously had no size or count cap at
+// all — recording for even a few minutes at normal frame rates can accumulate
+// hundreds of MB of base64-encoded JPEG data in memory, and stopRecording()'s
+// single JSON.stringify() of the whole frame array can exceed V8's max string
+// length and crash the process. Cap total accumulated base64 bytes (simpler to
+// check per-push than re-measuring the whole array) and auto-stop recording
+// once the budget is exhausted.
+const MAX_SCREENCAST_BYTES = 200 * 1024 * 1024; // ~200 MB of accumulated base64 frame data
+
 const _sessions = new Map<string, RecordingState>();
 
 export async function startRecording(
@@ -24,17 +36,38 @@ export async function startRecording(
   sessionId: string,
   options: RecordOptions = {}
 ): Promise<void> {
-  if (_sessions.has(sessionId)) {
+  const existing = _sessions.get(sessionId);
+  if (existing && !existing.autoStopped) {
     throw new Error('Recording already in progress for this session');
   }
+  if (existing) {
+    // Previous recording hit the buffer cap and auto-stopped but was never
+    // explicitly saved via stopRecording() — drop it so a fresh recording
+    // can start (its frames are lost; the auto-stop log already warned the
+    // caller to save via "record stop" before starting a new recording).
+    _sessions.delete(sessionId);
+  }
 
-  const state: RecordingState = { frames: [], offScreencast: null };
+  const state: RecordingState = { frames: [], offScreencast: null, totalBytes: 0, autoStopped: false };
   _sessions.set(sessionId, state);
 
   state.offScreencast = client.on('Page.screencastFrame', async (params, sid) => {
     if (sid !== sessionId) return;
     const { data, sessionId: frameSessionId } = params as { data: string; sessionId: number };
-    state.frames.push(data);
+    if (!state.autoStopped) {
+      state.frames.push(data);
+      state.totalBytes += data.length;
+      if (state.totalBytes >= MAX_SCREENCAST_BYTES) {
+        state.autoStopped = true;
+        state.offScreencast?.();
+        // eslint-disable-next-line no-console
+        console.error(
+          `[monobrowse] Screen recording auto-stopped: reached ${Math.round(MAX_SCREENCAST_BYTES / (1024 * 1024))}MB ` +
+          `of buffered frame data (${state.frames.length} frames). Call "record stop" to save what was captured.`
+        );
+        await client.send('Page.stopScreencast', {}, sessionId).catch(() => {});
+      }
+    }
     await client.send('Page.screencastFrameAck', { sessionId: frameSessionId }, sessionId).catch(() => {});
   });
 
@@ -62,7 +95,11 @@ export async function stopRecording(
   if (!state) throw new Error('No active recording for this session');
 
   try {
-    await client.send('Page.stopScreencast', {}, sessionId);
+    // If auto-stop already sent Page.stopScreencast and unsubscribed, don't
+    // send it again — Chrome errors on stopping an already-stopped screencast.
+    if (!state.autoStopped) {
+      await client.send('Page.stopScreencast', {}, sessionId);
+    }
   } finally {
     state.offScreencast?.();
     _sessions.delete(sessionId);
@@ -73,9 +110,9 @@ export async function stopRecording(
   return path;
 }
 
-export function getRecordingStatus(sessionId: string): { recording: boolean; frames: number } {
+export function getRecordingStatus(sessionId: string): { recording: boolean; frames: number; autoStopped: boolean } {
   const state = _sessions.get(sessionId);
-  return { recording: !!state, frames: state?.frames.length ?? 0 };
+  return { recording: !!state && !state.autoStopped, frames: state?.frames.length ?? 0, autoStopped: state?.autoStopped ?? false };
 }
 
 export async function saveFrameAsPng(