@monoes/monobrowse 1.0.3 → 1.0.4

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__/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,6 +51,38 @@ 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`);
+    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));
+  });
+}
+
 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
@@ -51,7 +92,16 @@ export async function launchBrowser(config: BrowserConfig = {}): Promise<number>
   const port = rawPort;
 
   if (await isPortOpen(port)) {
-    return port;
+    // Something CDP-speaking is already there — verify it's actually Chrome/Chromium
+    // before attaching, so we don't silently take over an unrelated real browser
+    // (e.g. the user's own personal Chrome) that happens to be on this 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}.`
+    );
   }
 
   const chromePath = findChrome(config.executablePath);
@@ -89,11 +139,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 +207,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(

package/src/browser/ref-cache.ts

@@ -16,6 +16,7 @@ import type { ElementRef } from './types.js';
 
 const CACHE_DIR = join(process.cwd(), '.monomind', 'monobrowse');
 const CACHE_FILE = join(CACHE_DIR, 'ax-snapshot.json');
+const PORT_FILE = join(CACHE_DIR, 'active-port.json');
 
 /** Snapshot older than this is flagged as possibly stale (page may have changed). */
 export const REF_CACHE_STALE_MS = 30_000;
@@ -88,3 +89,53 @@ export async function clearRefCache(): Promise<void> {
     // Nothing to clear, or not writable — non-fatal.
   }
 }
+
+/**
+ * Persist the "active" CDP port so a later CLI invocation (each command is a
+ * fresh process — see module header) can find the browser a prior `open
+ * --port N` attached to, instead of every subsequent command silently
+ * falling back to the hardcoded default port and launching/attaching to a
+ * second, unrelated Chrome instance.
+ */
+export async function saveActivePort(port: number, opts?: { launched?: boolean }): Promise<void> {
+  try {
+    await mkdir(CACHE_DIR, { recursive: true });
+    // `launched` records provenance: true = monobrowse spawned this Chrome
+    // (safe to Browser.close later); false = attached to a browser someone
+    // else owns (must never be killed). Absent (old files) reads as launched
+    // — matches pre-flag behavior where every persisted port came from open.
+    await writeFile(PORT_FILE, JSON.stringify({ port, launched: opts?.launched !== false, savedAt: Date.now() }));
+  } catch {
+    // Best-effort — persistence failure just means the next process falls
+    // back to the hardcoded default port, matching prior behavior.
+  }
+}
+
+/** Forget the persisted active port (session closed) so later invocations
+ *  fall back to the default instead of chasing a dead endpoint. */
+export async function clearActivePort(): Promise<void> {
+  try {
+    await rm(PORT_FILE, { force: true });
+  } catch {
+    // Best-effort — a stale port file only costs one failed probe later.
+  }
+}
+
+/** Load the persisted active port, or null if none was ever saved / it's unreadable. */
+export async function loadActivePort(): Promise<number | null> {
+  return (await loadActivePortInfo())?.port ?? null;
+}
+
+/** Load the persisted active port with its provenance flag. */
+export async function loadActivePortInfo(): Promise<{ port: number; launched: boolean } | null> {
+  try {
+    const raw = await readFile(PORT_FILE, 'utf8');
+    const data = JSON.parse(raw) as { port?: unknown; launched?: unknown };
+    if (typeof data.port === 'number' && Number.isInteger(data.port) && data.port >= 1024 && data.port <= 65535) {
+      return { port: data.port, launched: data.launched !== false };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/browser/session.ts

@@ -3,7 +3,13 @@ import { join, dirname } from 'path';
 import { homedir } from 'os';
 import type { SessionState, CdpCookie } from './types.js';
 import type { CdpClient } from './cdp.js';
-import { getCookies, setCookies, getLocalStorage, setLocalStorage, getSessionStorage, setSessionStorage } from './network.js';
+import { getCookiesForUrls, setCookies, getLocalStorage, setLocalStorage, getSessionStorage, setSessionStorage } from './network.js';
+
+// Session state files contain cookies/localStorage — treat as secrets:
+// owner-only read/write on the file (0600) and owner-only access on the
+// containing directory (0700) so other local users can't read session tokens.
+const SESSION_FILE_MODE = 0o600;
+const SESSION_DIR_MODE = 0o700;
 
 const SESSION_DIR = join(homedir(), '.monomind', 'browser-sessions');
 
@@ -31,15 +37,15 @@ export async function saveSession(
   title: string
 ): Promise<string> {
   validateSessionName(name);
-  await mkdir(SESSION_DIR, { recursive: true });
+  await mkdir(SESSION_DIR, { recursive: true, mode: SESSION_DIR_MODE });
 
-  const cookies = await getCookies(client, sessionId);
+  const cookies = await getCookiesForUrls(client, sessionId, [url]);
   const localStorage = await getLocalStorage(client, sessionId);
   const sessionStorage = await getSessionStorage(client, sessionId);
 
   const state: SessionState = { targetId, sessionId, url, title, cookies, localStorage, sessionStorage };
   const filePath = join(SESSION_DIR, `${name}.json`);
-  await writeFile(filePath, JSON.stringify(state, null, 2));
+  await writeFile(filePath, JSON.stringify(state, null, 2), { mode: SESSION_FILE_MODE });
   return filePath;
 }
 
@@ -79,12 +85,12 @@ export async function saveStateFile(
   title: string
 ): Promise<void> {
   validateFilePath(filePath);
-  await mkdir(dirname(filePath), { recursive: true });
-  const cookies = await getCookies(client, sessionId);
+  await mkdir(dirname(filePath), { recursive: true, mode: SESSION_DIR_MODE });
+  const cookies = await getCookiesForUrls(client, sessionId, [url]);
   const localStorage = await getLocalStorage(client, sessionId);
   const sessionStorage = await getSessionStorage(client, sessionId);
   const state: SessionState = { targetId, sessionId, url, title, cookies, localStorage, sessionStorage };
-  await writeFile(filePath, JSON.stringify(state, null, 2));
+  await writeFile(filePath, JSON.stringify(state, null, 2), { mode: SESSION_FILE_MODE });
 }
 
 export async function loadStateFile(