@monoes/monobrowse 1.0.19 → 1.0.21

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/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:

package/src/cli/commands-session.ts

@@ -10,10 +10,13 @@
 
 import { output } from './output.js';
 import {
+  adoptLegacySession,
   detectAttentionNeeded,
   ensureConnected,
-  ensureSignalCleanupHandlers,
   getBrowser,
+  launchSessionBrowser,
+  pinnedPort,
+  resolveLiveSession,
   session,
   switchToHeaded,
 } from './session.js';
@@ -23,7 +26,13 @@ export const openCommand: Command = {
   name: 'open',
   description: 'Open a URL in the browser. Usage: monomind browse open <url>',
   options: [
-    { name: 'port', short: 'p', type: 'number', description: 'CDP port', default: 9222 },
+    {
+      name: 'port',
+      short: 'p',
+      type: 'number',
+      description:
+        'Attach to (or launch on) this CDP port. Default: a free port of this session’s own',
+    },
     {
       name: 'headed',
       type: 'boolean',
@@ -37,7 +46,10 @@ export const openCommand: Command = {
     const url = ctx.args[0] as string;
     if (!url) throw new Error('URL required. Usage: monomind browse open <url>');
 
-    const port = (ctx.flags.port as number) ?? 9222;
+    // No --port means "start a session of my own on a free port" (#318) —
+    // never "join whatever is on 9222", which is what made two uncoordinated
+    // `open` calls race for one browser and one profile directory.
+    const port = pinnedPort(ctx.flags);
     const forceHeaded = ctx.flags.headed as boolean;
     const browser = await getBrowser();
 
@@ -77,38 +89,9 @@ export const openCommand: Command = {
       session.refs = new Map();
     }
 
-    session.port = await browser.launchBrowser({ port, headless: !forceHeaded });
-    // Persist the active port so subsequent CLI invocations (each a fresh
-    // process) default to attaching here instead of hardcoded 9222. Also
-    // persist the launched PID/userDataDir so a later process's closeBrowser
-    // can still kill this Chrome even though launchedPids (browser.ts) is
-    // per-process and empty there.
-    //
-    // launchBrowser() can either LAUNCH a fresh Chrome or ATTACH to one
-    // already listening on the requested port (see its own "attach if
-    // already Chrome" comment) — it returns only a port number, with no
-    // signal telling this caller which happened. getLaunchedPid(session.port) is
-    // undefined on the attach path (this process never spawned anything).
-    // Bug fixed here: unconditionally saving {pid: undefined, ...} on
-    // attach used to CLOBBER a real PID a previous `open` had already
-    // persisted for this exact port, destroying the only way a later
-    // process's closeBrowser() PID-kill fallback could ever find it.
-    const freshPid = browser.getLaunchedPid(session.port);
-    const freshUserDataDir = browser.getLaunchedUserDataDir(session.port);
-    if (freshPid !== undefined) {
-      await browser.saveActivePort(session.port, { pid: freshPid, userDataDir: freshUserDataDir });
-    } else {
-      // Attach path: preserve whatever PID/userDataDir was already on file
-      // for this port (most likely from the process that originally
-      // launched it) instead of overwriting with undefined.
-      const existing = await browser.loadActivePortInfo();
-      const preserved = existing && existing.port === session.port ? existing : undefined;
-      await browser.saveActivePort(session.port, {
-        pid: preserved?.pid,
-        userDataDir: preserved?.userDataDir,
-      });
-    }
-    ensureSignalCleanupHandlers();
+    // Starts this session's own browser (and records it) unless --port named
+    // one to attach to — see the session rule in session.ts.
+    session.port = await launchSessionBrowser(browser, { port, headless: !forceHeaded });
     const conn = await browser.connectToTarget(session.port);
     session.client = conn.client;
     session.sessionId = conn.sessionId;
@@ -117,7 +100,7 @@ export const openCommand: Command = {
     // A snapshot taken before this navigation is no longer valid for the new
     // page — drop the persisted ref cache so a stale process's weak
     // time-based check can't resurrect it before the next explicit snapshot.
-    await browser.clearRefCache();
+    await browser.clearRefCache(session.port);
 
     if (ctx.flags.state && ctx.flags.session) {
       output.printWarning('Both --state and --session provided; --state takes precedence');
@@ -142,7 +125,7 @@ export const openCommand: Command = {
         output.printWarning(
           `${attentionType === 'captcha' ? 'CAPTCHA' : 'Login'} detected — switching to headed mode`,
         );
-        await switchToHeaded(currentUrl, port);
+        await switchToHeaded(currentUrl, session.port);
         await browser.openUrl(session.client!, session.sessionId, currentUrl);
         output.printSuccess(
           `Resumed headless after ${attentionType === 'captcha' ? 'CAPTCHA' : 'login'}`,
@@ -153,15 +136,27 @@ export const openCommand: Command = {
     const finalUrl = await browser.getCurrentUrl(session.client!, session.sessionId);
     const title = await browser.getCurrentTitle(session.client!, session.sessionId);
 
-    output.printSuccess(`Opened: ${title} (${finalUrl})`);
-    return { success: true, data: { url: finalUrl, title } };
+    // The port is part of the result, not decoration: it is this session's
+    // handle, and the only way a concurrent caller can pin it from another
+    // process (`--port N`) instead of resolving "the newest live session".
+    output.printSuccess(`Opened: ${title} (${finalUrl}) [port ${session.port}]`);
+    return { success: true, data: { url: finalUrl, title, port: session.port } };
   },
 };
 
 export const closeCommand: Command = {
   name: 'close',
-  description: 'Close the active browser session',
-  action: async (_ctx: CommandContext): Promise<CommandResult> => {
+  description:
+    'Close a browser session. Usage: monomind browse close [--port <port>] (default: the newest live session here)',
+  options: [
+    {
+      name: 'port',
+      short: 'p',
+      type: 'number',
+      description: 'Close the session on this CDP port instead of the newest live one',
+    },
+  ],
+  action: async (ctx: CommandContext): Promise<CommandResult> => {
     if (session.client) {
       const browser = await getBrowser();
       const sid = session.sessionId;
@@ -192,26 +187,48 @@ export const closeCommand: Command = {
       browser.stopRequestCapture(sid);
       browser.teardownDialogHandling(sid);
       browser.teardownConsoleCapture(sid);
+      // Terminate the browser this process launched, not just our socket to
+      // it: with a session of its own on a free port (#318), a Chrome left
+      // behind here is one nothing else knows how to find. A browser we
+      // merely attached to (`connect`) is the user's — never killed.
+      const record = await browser.loadSessionRecord(session.port);
+      if (record?.launched !== false) {
+        try {
+          await browser.closeBrowser(client, session.port);
+        } catch {
+          /* best-effort — the record cleanup below still runs */
+        }
+      }
       client.close();
       session.client = null;
       session.sessionId = '';
       session.parentSessionId = '';
       session.targetId = '';
       session.refs = new Map();
-      // Session is gone — forget the persisted port and stale refs so later
+      // This session is gone — forget its record and stale refs so later
       // invocations don't chase a dead endpoint (or the wrong elements).
-      await browser.clearActivePort();
-      await browser.clearRefCache();
-      output.printSuccess('Browser session closed');
+      // Other sessions' records are left alone.
+      await browser.removeSessionRecord(session.port);
+      await browser.clearRefCache(session.port);
+      output.printSuccess(`Browser session closed (port ${session.port})`);
     } else {
       // Each CLI invocation is a fresh process, so `close` almost always
-      // lands here. The persisted port file is the real session handle:
-      // if monobrowse LAUNCHED that browser (open), gracefully Browser.close
+      // lands here. The session record is the real handle: `--port` names
+      // one, otherwise it is the newest session whose browser still answers
+      // (strict:false — a dead one is cleaned up, not raised as an error).
+      // If monobrowse LAUNCHED that browser (open), gracefully Browser.close
       // it — otherwise every open→close cycle leaks a headless Chrome. If we
       // merely ATTACHED to it (connect, launched:false), never kill it: it's
-      // the user's own browser. Either way, forget the port and refs.
+      // the user's own browser. Either way, forget that one session.
       const browser = await getBrowser();
-      const persisted = await browser.loadActivePortInfo();
+      const pinned = pinnedPort(ctx.flags);
+      const persisted = pinned
+        ? ((await browser.loadSessionRecord(pinned)) ??
+          (await adoptLegacySession(browser, { port: pinned })) ?? {
+            port: pinned,
+            launched: true,
+          })
+        : await resolveLiveSession(browser, { strict: false });
       if (persisted?.launched) {
         try {
           const conn = await browser.connectToTarget(persisted.port);
@@ -257,8 +274,10 @@ export const closeCommand: Command = {
             : 'No active browser session',
         );
       }
-      await browser.clearActivePort();
-      await browser.clearRefCache();
+      if (persisted) {
+        await browser.removeSessionRecord(persisted.port);
+        await browser.clearRefCache(persisted.port);
+      }
     }
     return { success: true };
   },
@@ -346,12 +365,12 @@ export const connectCommand: Command = {
     session.targetId = conn.target.id;
     session.port = port;
     session.refs = new Map();
-    // Persist the port like `open` does — without this, the NEXT CLI process
-    // (each command is a fresh process) resolves the hardcoded default and
-    // tries to launch its own Chrome on 9222 instead of reusing this session.
+    // Record the session like `open` does — without this, the NEXT CLI
+    // process (each command is a fresh process) has nothing to resolve and
+    // launches a browser of its own instead of reusing this session.
     // launched:false marks this browser as someone else's — close must never
     // kill it, and a dead endpoint must not be silently relaunched.
-    await browser.saveActivePort(port, { launched: false });
+    await browser.saveSessionRecord(port, { launched: false });
     const url = await browser.getCurrentUrl(session.client, session.sessionId);
     const title = await browser.getCurrentTitle(session.client, session.sessionId);
     output.printSuccess(`Connected: ${title} (${url})`);