@monoes/monobrowse 1.0.17 → 1.0.21

package/src/browser/browser.ts

@@ -1,12 +1,17 @@
 import { execSync, spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { connect } from 'node:net';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { CdpClient, fetchNewTarget, fetchTargets } from './cdp.js';
 import { enableConsoleCapture, setupConsoleCapture } from './console-log.js';
 import { setupDialogAutoHandling } from './dialog.js';
-import { clearActivePort, loadActivePortInfo } from './ref-cache.js';
+import {
+  listSessionRecords,
+  loadSessionRecord,
+  removeSessionRecord,
+  type SessionRecord,
+} from './ref-cache.js';
 import type { BrowserConfig, CdpTarget } from './types.js';
 import { CHROME_EXECUTABLES } from './types.js';
 
@@ -128,9 +133,17 @@ 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.`);
+  // Port 0 means "let Chrome bind a free port and tell us which" — see
+  // launchOnFreePort. Otherwise validate port is in a safe range for
+  // localhost CDP debugging.
+  if (rawPort === 0) {
+    if (!config.userDataDir) {
+      throw new Error(
+        'port 0 requires a dedicated userDataDir (Chrome reports the port it bound inside it).',
+      );
+    }
+  } else if (!Number.isInteger(rawPort) || rawPort < 1024 || rawPort > 65535) {
+    throw new Error(`Invalid port: ${rawPort}. Must be 0 or an integer between 1024 and 65535.`);
   }
 
   // Every launch/attach is this tool's only chance to notice that a previous
@@ -139,6 +152,8 @@ export async function launchBrowser(config: BrowserConfig = {}): Promise<number>
   // instance on the port we are about to use is freed before we probe it.
   await reapIdleLaunchedBrowser();
 
+  if (rawPort === 0) return launchOnFreePort(config, 0);
+
   // 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
@@ -158,19 +173,7 @@ export async function launchBrowser(config: BrowserConfig = {}): Promise<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)) {
+  for (const candidate of candidates) {
     // 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
@@ -179,10 +182,39 @@ export async function launchBrowser(config: BrowserConfig = {}): Promise<number>
     // 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.
+    if (await isTcpPortOpen(candidate)) {
+      // 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 (candidate === rawPort && (await isChromeIdentity(candidate))) return 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.
+      continue;
+    }
+    try {
+      return await launchOnFreePort(config, candidate);
+    } catch (err) {
+      const isLastCandidate = candidate === candidates[candidates.length - 1];
+      // isTcpPortOpen() above is a connect() probe, not an atomic claim: two
+      // concurrent launchBrowser() calls with no explicit --port can both
+      // observe the same candidate as free and both spawn Chrome on it
+      // before either binds. One wins; the other's Chrome exits before its
+      // CDP endpoint opens ("Chrome exited before the CDP endpoint opened
+      // ... code=21"). Something is listening on the candidate NOW that
+      // was not a moment ago — a losing race, not a broken Chrome install —
+      // so try the next candidate exactly like an already-occupied one,
+      // instead of failing the whole launch outright. A candidate that
+      // fails with nothing now listening (a real launch failure — bad
+      // executable, sandbox refusal, etc.) is not a race: retrying the
+      // next candidate would only fail the same way, so surface it as-is.
+      if (!isLastCandidate && (await isTcpPortOpen(candidate))) continue;
+      throw err;
+    }
   }
   throw new Error(
     `Ports ${candidates[0]}-${candidates[candidates.length - 1]} are all occupied and port ${candidates[0]} ` +
@@ -190,9 +222,50 @@ export async function launchBrowser(config: BrowserConfig = {}): Promise<number>
   );
 }
 
+/** The port Chrome wrote to `<userDataDir>/DevToolsActivePort` once its
+ *  DevTools server was listening, or null if it has not (yet). */
+function readDevToolsActivePort(file: string): number | null {
+  try {
+    const port = Number.parseInt(readFileSync(file, 'utf8').split('\n')[0], 10);
+    return Number.isInteger(port) && port > 0 && port <= 65535 ? port : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Spawn Chrome and wait for its CDP endpoint.
+ *
+ * With a fixed `port`, "our Chrome is up" is inferred from *some* Chrome
+ * answering on 127.0.0.1:<port> — which is not necessarily ours. When the port
+ * is already bound on 127.0.0.1 (a concurrent launch picked the same "free"
+ * port between its probe and Chrome's bind), Chrome does not fail: it logs
+ * `bind() failed: Address already in use` and listens on [::1]:<port>
+ * instead. The poll then accepts the OTHER launcher's browser, both callers
+ * drive one Chrome, and whichever closes first kills the other's connections
+ * ("CDP connection closed") while this launch's own Chrome is orphaned.
+ *
+ * `port: 0` removes the race instead of narrowing it: Chrome asks the kernel
+ * for a free port at bind time — atomic, nothing to collide on — and writes
+ * the port it got to DevToolsActivePort in its own (caller-dedicated) profile
+ * directory, which is proof the endpoint is the process we spawned.
+ */
 async function launchOnFreePort(config: BrowserConfig, port: number): Promise<number> {
   const chromePath = findChrome(config.executablePath);
-  const userDataDir = config.userDataDir ?? join(tmpdir(), `monomind-browser-${port}`);
+  // Suffixed with our own pid: two concurrent launches that both probe the
+  // same candidate port as free (the race this function exists to survive —
+  // see the retry-on-collision caller above) briefly run Chrome with
+  // *identical* --user-data-dir values if it were derived from the port
+  // alone, sharing a profile directory (lock files, preferences, the
+  // DevToolsActivePort file itself) between two unrelated Chrome processes
+  // for as long as the loser stays alive. Different processes always have
+  // different pids, so this can never collide even when the port does.
+  const userDataDir =
+    config.userDataDir ?? join(tmpdir(), `monomind-browser-${port}-${process.pid}`);
+  const activePortFile = join(userDataDir, 'DevToolsActivePort');
+  // A reused profile dir may hold a previous run's file naming a port some
+  // other process now owns.
+  if (port === 0) rmSync(activePortFile, { force: true });
 
   const defaultArgs = [
     `--remote-debugging-port=${port}`,
@@ -264,10 +337,21 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
   });
 
   child.unref();
-  if (child.pid) {
-    launchedPids.set(port, child.pid);
-    launchedUserDataDirs.set(port, userDataDir);
-  }
+  const track = (boundPort: number) => {
+    if (!child.pid) return;
+    launchedPids.set(boundPort, child.pid);
+    launchedUserDataDirs.set(boundPort, userDataDir);
+  };
+  // Tracked only once Chrome is CONFIRMED up on `boundPort`, not right after
+  // spawn(). For port !== 0 this used to track(port) unconditionally the
+  // moment the child was spawned, before knowing whether it would actually
+  // win the port — when a racing launchBrowser() call retries a candidate
+  // that a concurrent process also spawned Chrome on (see the retry loop in
+  // launchBrowser), BOTH child processes called track() for the SAME
+  // candidate, and whichever call's spawn happened to run last clobbered the
+  // map entry with its own pid — including the LOSING, about-to-exit
+  // process's pid overwriting the real winner's, corrupting the very map
+  // closeBrowser()'s kill fallback depends on.
 
   const launchTimeout = config.launchTimeoutMs ?? LAUNCH_TIMEOUT;
   const deadline = Date.now() + launchTimeout;
@@ -275,17 +359,34 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
     if (earlyFailure) throw earlyFailure;
     await sleep(POLL_INTERVAL);
     if (earlyFailure) throw earlyFailure;
-    if (await isPortOpen(port)) {
-      if (await isChromeIdentity(port)) return port;
+    const boundPort = port === 0 ? readDevToolsActivePort(activePortFile) : port;
+    if (boundPort !== null && (await isPortOpen(boundPort))) {
+      if (await isChromeIdentity(boundPort)) {
+        track(boundPort);
+        return boundPort;
+      }
       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}.`,
+        `Port ${boundPort} is occupied by a CDP-speaking process that does not identify as Chrome/Chromium. ` +
+          `Refusing to attach — pass a different port or free port ${boundPort}.`,
       );
     }
   }
 
   if (earlyFailure) throw earlyFailure;
 
+  if (port === 0) {
+    // Not tracked under any port yet, so no closeBrowser() could ever reach
+    // it — stop it here rather than leave it running.
+    try {
+      if (child.pid) process.kill(child.pid, 'SIGKILL');
+    } catch {
+      /* already gone */
+    }
+    throw new Error(
+      `Chrome did not report a CDP port in ${activePortFile} within ${launchTimeout}ms`,
+    );
+  }
+
   // 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.
@@ -394,13 +495,13 @@ export async function closeBrowser(client: CdpClient, port: number): Promise<voi
     // Fresh process (each CLI invocation is its own node process — see
     // module header) — launchedPids is per-process and empty here even
     // though a prior `open` in a DIFFERENT process launched this Chrome.
-    // Fall back to the PID that process persisted via saveActivePort().
+    // Fall back to the PID that process persisted via saveSessionRecord().
     try {
-      const persisted = await loadActivePortInfo();
-      if (persisted && persisted.port === port && persisted.launched && persisted.pid) {
+      const persisted = await loadSessionRecord(port);
+      if (persisted?.launched && persisted.pid) {
         // Bound how far we trust a cross-process PID: if the Chrome we
         // launched died outside this flow (OOM-killed, host slept, etc.)
-        // without active-port.json ever being cleared, the OS can recycle
+        // without its session record ever being cleared, the OS can recycle
         // that PID for an unrelated process. There is no cmdline/start-time
         // check available portably, so a coarse age bound is the practical
         // guard — a PID persisted more than a day ago is far more likely to
@@ -498,12 +599,21 @@ async function waitForProcessExit(pid: number): Promise<boolean> {
  * ever used for closeBrowser's own age-bounded force-kill.
  *
  * Never throws: a failed reap must not stop a launch. Returns the reaped
- * port, or null when there was nothing to reap.
+ * port, or null when there was nothing to reap. Sessions are per-port
+ * (#318), so every recorded one is considered, not just the newest.
  */
 export async function reapIdleLaunchedBrowser(): Promise<number | null> {
+  let reaped: number | null = null;
+  for (const session of await listSessionRecords().catch(() => [])) {
+    const port = await reapSession(session);
+    reaped ??= port;
+  }
+  return reaped;
+}
+
+async function reapSession(session: SessionRecord): Promise<number | null> {
   try {
-    const session = await loadActivePortInfo();
-    if (!session?.launched || session.savedAt === undefined) return null;
+    if (!session.launched || session.savedAt === undefined) return null;
     if (Date.now() - session.savedAt < IDLE_REAP_AFTER_MS) return null;
 
     const wsUrl = await fetchBrowserWebSocketUrl(session.port);
@@ -540,7 +650,7 @@ export async function reapIdleLaunchedBrowser(): Promise<number | null> {
     }
     launchedPids.delete(session.port);
     launchedUserDataDirs.delete(session.port);
-    await clearActivePort();
+    await removeSessionRecord(session.port);
     return session.port;
   } catch {
     return null;

package/src/browser/ref-cache.ts

@@ -1,5 +1,12 @@
 /**
- * AX-tree ref cache persistence.
+ * Per-session CLI state: the browse session index, and the AX-tree ref cache
+ * each session owns.
+ *
+ * Both are keyed by CDP port and scoped to the working directory: one file
+ * per browse session under `sessions/`, one ref cache per session beside it.
+ * A single shared `active-port.json` / `ax-snapshot.json` pair used to stand
+ * for "the" session, which is why two concurrent `open` invocations in one
+ * directory overwrote each other's handle (#318).
  *
  * `snapshot` and `find` are separate CLI invocations — each starts a fresh
  * node process, so the in-memory ElementRef Map built by captureSnapshot()
@@ -10,13 +17,19 @@
  * The full AX-tree text/dump is intentionally NOT persisted — only the
  * per-ref index, to keep the file small.
  */
-import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 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');
+const SESSIONS_DIR = join(CACHE_DIR, 'sessions');
+const refCacheFile = (port: number) => join(CACHE_DIR, `ax-snapshot-${port}.json`);
+const sessionFile = (port: number) => join(SESSIONS_DIR, `${port}.json`);
+// The pre-#318 layout: one session per directory, plus its one ref cache.
+// Still read (see loadLegacySessionRecord) so a session opened by an older
+// CLI is adopted rather than orphaned when monobrowse is upgraded under it.
+const LEGACY_SESSION_FILE = join(CACHE_DIR, 'active-port.json');
+const LEGACY_REF_CACHE_FILE = join(CACHE_DIR, 'ax-snapshot.json');
 
 /** Snapshot older than this is flagged as possibly stale (page may have changed). */
 export const REF_CACHE_STALE_MS = 30_000;
@@ -36,8 +49,11 @@ export interface RefCacheEntry {
   stale: boolean;
 }
 
-/** Persist the current ref index for a target so a later CLI process can read it back. */
+/** Persist the current ref index for a target so a later CLI process can read
+ *  it back. Scoped to the session's port so two sessions open in the same
+ *  directory keep their own refs instead of clobbering one file. */
 export async function saveRefCache(
+  port: number,
   targetId: string,
   url: string,
   refs: Map<string, ElementRef>,
@@ -50,7 +66,7 @@ export async function saveRefCache(
       savedAt: Date.now(),
       refs: [...refs.values()],
     };
-    await writeFile(CACHE_FILE, JSON.stringify(data));
+    await writeFile(refCacheFile(port), JSON.stringify(data));
   } catch {
     // Best-effort — persistence failure just means cross-process rehydration
     // won't work; in-process (same run) behavior is unaffected.
@@ -62,9 +78,9 @@ export async function saveRefCache(
  * different tab/target is ignored). Returns null if no usable cache exists —
  * callers fall back to an empty in-memory Map, matching prior behavior.
  */
-export async function loadRefCache(targetId: string): Promise<RefCacheEntry | null> {
+export async function loadRefCache(port: number, targetId: string): Promise<RefCacheEntry | null> {
   try {
-    const raw = await readFile(CACHE_FILE, 'utf8');
+    const raw = await readFile(refCacheFile(port), 'utf8');
     const data: RefCacheFile = JSON.parse(raw);
     if (!data || !Array.isArray(data.refs) || data.targetId !== targetId) return null;
 
@@ -82,104 +98,160 @@ export async function loadRefCache(targetId: string): Promise<RefCacheEntry | nu
 }
 
 /** Drop the persisted ref index — call whenever refs are invalidated (navigation, tab switch, close). */
-export async function clearRefCache(): Promise<void> {
+export async function clearRefCache(port: number): Promise<void> {
   try {
-    await rm(CACHE_FILE, { force: true });
+    await rm(refCacheFile(port), { force: true });
   } catch {
     // 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.
+ * A browse session: one Chrome instance, identified by the CDP port it
+ * listens on, recorded so a LATER CLI invocation (each command is its own
+ * node process — see module header) can find it again.
  */
-export async function saveActivePort(
+export interface SessionRecord {
+  port: number;
+  /** true = monobrowse launched this Chrome (safe to Browser.close later);
+   *  false = we attached to a browser someone else owns (never kill it). */
+  launched: boolean;
+  pid?: number;
+  userDataDir?: string;
+  savedAt?: number;
+}
+
+/**
+ * Record a browse session under its own port, so concurrent sessions in the
+ * same working directory coexist instead of overwriting one shared handle.
+ *
+ * `pid`/`userDataDir` are persisted so a later, fresh CLI process can still
+ * find and kill the Chrome this one launched. Without them, closeBrowser()'s
+ * PID-kill fallback can never fire outside the launching process, since the
+ * in-memory launchedPids Map (browser.ts) is empty there.
+ */
+export async function saveSessionRecord(
   port: number,
-  opts?: { launched?: boolean; pid?: number; userDataDir?: string },
+  opts?: { launched?: boolean; pid?: number; userDataDir?: string; savedAt?: number },
 ): 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 mkdir(SESSIONS_DIR, { recursive: true });
+    // `launched` absent (older files) reads as launched — matches the
+    // pre-flag behavior where every persisted port came from `open`.
     //
-    // `pid`/`userDataDir` are persisted so a LATER, fresh CLI process (each
-    // command is its own node process — see module header) can still find
-    // and kill the Chrome this one launched. Without this, closeBrowser()'s
-    // PID-kill fallback can never fire outside the launching process, since
-    // the in-memory launchedPids Map (browser.ts) is empty there.
+    // `savedAt` is passed only when re-recording a session that already
+    // existed (adopting a legacy record), so its real age — which is what
+    // the idle reaper and the newest-first ordering read — is preserved.
     await writeFile(
-      PORT_FILE,
+      sessionFile(port),
       JSON.stringify({
         port,
         launched: opts?.launched !== false,
         pid: opts?.pid,
         userDataDir: opts?.userDataDir,
-        savedAt: Date.now(),
+        savedAt: opts?.savedAt ?? Date.now(),
       }),
     );
   } catch {
-    // Best-effort — persistence failure just means the next process falls
-    // back to the hardcoded default port, matching prior behavior.
+    // Best-effort — persistence failure costs the next process the ability to
+    // find this session, not this command's own correctness.
   }
 }
 
-/** 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> {
+/** Forget one session (it was closed, or its browser is gone) so later
+ *  invocations don't chase a dead endpoint. */
+export async function removeSessionRecord(port: number): Promise<void> {
   try {
-    await rm(PORT_FILE, { force: true });
+    await rm(sessionFile(port), { force: true });
   } catch {
-    // Best-effort — a stale port file only costs one failed probe later.
+    // Best-effort — a stale record 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;
+/** The session recorded for `port`, or null if there is none / it's unreadable. */
+export async function loadSessionRecord(port: number): Promise<SessionRecord | null> {
+  try {
+    return parseSessionRecord(await readFile(sessionFile(port), 'utf8'));
+  } catch {
+    return null;
+  }
 }
 
-/** Load the persisted active port with its provenance flag, PID, user-data-dir, and save timestamp. */
-export async function loadActivePortInfo(): Promise<{
-  port: number;
-  launched: boolean;
-  pid?: number;
-  userDataDir?: string;
-  savedAt?: number;
-} | null> {
+/**
+ * The session a pre-#318 CLI left behind in this directory, if any.
+ *
+ * That layout held exactly one session in `active-port.json`. Upgrading
+ * monobrowse while such a session was open would otherwise strand its
+ * Chrome: nothing reads that file any more, so the new CLI could neither
+ * find nor close it. It is read here as one more candidate session and then
+ * either adopted (rewritten as `sessions/<port>.json`) or dropped — see
+ * adoptLegacySession() in cli/session.ts. Nothing ever writes it again.
+ */
+export async function loadLegacySessionRecord(): Promise<SessionRecord | null> {
   try {
-    const raw = await readFile(PORT_FILE, 'utf8');
-    const data = JSON.parse(raw) as {
-      port?: unknown;
-      launched?: unknown;
-      pid?: unknown;
-      userDataDir?: unknown;
-      savedAt?: unknown;
-    };
-    if (
-      typeof data.port === 'number' &&
-      Number.isInteger(data.port) &&
-      data.port >= 1024 &&
-      data.port <= 65535
-    ) {
-      return {
-        port: data.port,
-        launched: data.launched !== false,
-        pid:
-          typeof data.pid === 'number' && Number.isInteger(data.pid) && data.pid > 0
-            ? data.pid
-            : undefined,
-        userDataDir: typeof data.userDataDir === 'string' ? data.userDataDir : undefined,
-        savedAt: typeof data.savedAt === 'number' ? data.savedAt : undefined,
-      };
-    }
+    return parseSessionRecord(await readFile(LEGACY_SESSION_FILE, 'utf8'));
+  } catch {
     return null;
+  }
+}
+
+/** Drop the pre-#318 files, once their session has been adopted or found
+ *  dead. The single ref cache goes with them: it belonged to that one
+ *  session, and nothing reads it any more either. */
+export async function removeLegacySessionRecord(): Promise<void> {
+  try {
+    await rm(LEGACY_SESSION_FILE, { force: true });
+    await rm(LEGACY_REF_CACHE_FILE, { force: true });
   } catch {
+    // Best-effort — a leftover file is inert; it is only ever read again.
+  }
+}
+
+/** Every recorded session in this working directory, newest first. */
+export async function listSessionRecords(): Promise<SessionRecord[]> {
+  let entries: string[];
+  try {
+    entries = await readdir(SESSIONS_DIR);
+  } catch {
+    return [];
+  }
+  const records: SessionRecord[] = [];
+  for (const entry of entries) {
+    if (!entry.endsWith('.json')) continue;
+    try {
+      const record = parseSessionRecord(await readFile(join(SESSIONS_DIR, entry), 'utf8'));
+      if (record) records.push(record);
+    } catch {
+      // Unreadable file — skip it rather than failing the whole listing.
+    }
+  }
+  return records.sort((a, b) => (b.savedAt ?? 0) - (a.savedAt ?? 0));
+}
+
+function parseSessionRecord(raw: string): SessionRecord | null {
+  const data = JSON.parse(raw) as {
+    port?: unknown;
+    launched?: unknown;
+    pid?: unknown;
+    userDataDir?: unknown;
+    savedAt?: unknown;
+  };
+  if (
+    typeof data.port !== 'number' ||
+    !Number.isInteger(data.port) ||
+    data.port < 1024 ||
+    data.port > 65535
+  ) {
     return null;
   }
+  return {
+    port: data.port,
+    launched: data.launched !== false,
+    pid:
+      typeof data.pid === 'number' && Number.isInteger(data.pid) && data.pid > 0
+        ? data.pid
+        : undefined,
+    userDataDir: typeof data.userDataDir === 'string' ? data.userDataDir : undefined,
+    savedAt: typeof data.savedAt === 'number' ? data.savedAt : undefined,
+  };
 }

package/src/browser/types.ts

@@ -1,4 +1,6 @@
 export interface BrowserConfig {
+  /** CDP port. 0 lets Chrome bind a free one (requires `userDataDir`); the
+   *  port it bound is launchBrowser's return value. */
   port?: number;
   /** Fail fast if `port` is occupied by anything other than an attachable
    *  Chrome, instead of scanning forward to the next free port. Default false

package/src/cli/commands-context.ts

@@ -94,7 +94,7 @@ export const stateCommand: Command = {
         await browser.clearLocalStorage(c, sid);
         await browser.clearSessionStorage(c, sid);
         session.refs = new Map();
-        await browser.clearRefCache();
+        await browser.clearRefCache(session.port);
         output.printSuccess('Browser state cleared (cookies, localStorage, sessionStorage, refs)');
         return { success: true };
       }

package/src/cli/commands-navigate.ts

@@ -322,7 +322,7 @@ export const navigateCommand: Command = {
 
     // Refs captured before this navigation may now point at different content.
     session.refs = new Map();
-    await browser.clearRefCache();
+    await browser.clearRefCache(session.port);
 
     output.printSuccess(`Navigated: ${direction}`);
     return { success: true };
@@ -435,7 +435,7 @@ export const pushstateCommand: Command = {
     // SPA navigation changes what's on the page without a full page load —
     // refs captured before this pushState call may now resolve to different content.
     session.refs = new Map();
-    await browser.clearRefCache();
+    await browser.clearRefCache(session.port);
     output.printSuccess(`pushState: ${url}`);
     return { success: true };
   },

package/src/cli/commands-page.ts

@@ -71,7 +71,7 @@ export const snapshotCommand: Command = {
     });
 
     session.refs = result.refs;
-    await browser.saveRefCache(session.targetId, result.url, session.refs);
+    await browser.saveRefCache(session.port, session.targetId, result.url, session.refs);
 
     const applyOutputLimits = (text: string): string => {
       const maxOutput = ctx.flags['max-output'] as number | undefined;
@@ -375,7 +375,7 @@ export const diffCommand: Command = {
       });
 
       session.refs = snap2.refs;
-      await browser.saveRefCache(session.targetId, snap2.url, session.refs);
+      await browser.saveRefCache(session.port, session.targetId, snap2.url, session.refs);
 
       // Text diff
       const lines1 = snap1.text.split('\n');

package/src/cli/commands-report.ts

@@ -210,8 +210,8 @@ export const reportCommand: Command = {
       session.sessionId = '';
       session.targetId = '';
       session.refs = new Map();
-      await browser.clearActivePort();
-      await browser.clearRefCache();
+      await browser.removeSessionRecord(session.port);
+      await browser.clearRefCache(session.port);
     };
 
     let result: