@monoes/monobrowse 1.0.19 → 1.0.21

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

@@ -41,8 +41,8 @@ describe('ref-cache', () => {
     const mod = await importRefCache();
     const refs = makeRefs(2);
 
-    await mod.saveRefCache('target-1', 'https://example.com', refs as any);
-    const loaded = await mod.loadRefCache('target-1');
+    await mod.saveRefCache(9222, 'target-1', 'https://example.com', refs as any);
+    const loaded = await mod.loadRefCache(9222, 'target-1');
 
     expect(loaded).not.toBeNull();
     expect(loaded!.url).toBe('https://example.com');
@@ -57,8 +57,8 @@ describe('ref-cache', () => {
     const mod = await importRefCache();
     const refs = makeRefs(1);
 
-    await mod.saveRefCache('target-A', 'https://a.com', refs as any);
-    const loaded = await mod.loadRefCache('target-B');
+    await mod.saveRefCache(9222, 'target-A', 'https://a.com', refs as any);
+    const loaded = await mod.loadRefCache(9222, 'target-B');
 
     expect(loaded).toBeNull();
   });
@@ -66,27 +66,27 @@ describe('ref-cache', () => {
   it('corrupt JSON file returns null', async () => {
     const mod = await importRefCache();
     // First save a valid cache to create the directory structure
-    await mod.saveRefCache('t', 'https://x.com', makeRefs(1) as any);
+    await mod.saveRefCache(9222, 't', 'https://x.com', makeRefs(1) as any);
 
     // Now overwrite the file with invalid JSON
-    const cacheFile = join(tempDir, '.monomind', 'monobrowse', 'ax-snapshot.json');
+    const cacheFile = join(tempDir, '.monomind', 'monobrowse', 'ax-snapshot-9222.json');
     const { writeFile: wf } = await import('node:fs/promises');
     await wf(cacheFile, '{{{not valid json!!!');
 
-    const loaded = await mod.loadRefCache('t');
+    const loaded = await mod.loadRefCache(9222, 't');
     expect(loaded).toBeNull();
   });
 
   it('clearRefCache removes the cache file', async () => {
     const mod = await importRefCache();
-    await mod.saveRefCache('t1', 'https://x.com', makeRefs(1) as any);
+    await mod.saveRefCache(9222, 't1', 'https://x.com', makeRefs(1) as any);
 
-    const cacheFile = join(tempDir, '.monomind', 'monobrowse', 'ax-snapshot.json');
+    const cacheFile = join(tempDir, '.monomind', 'monobrowse', 'ax-snapshot-9222.json');
     // Verify file exists
     const before = await stat(cacheFile).catch(() => null);
     expect(before).not.toBeNull();
 
-    await mod.clearRefCache();
+    await mod.clearRefCache(9222);
 
     const after = await stat(cacheFile).catch(() => null);
     expect(after).toBeNull();
@@ -94,18 +94,18 @@ describe('ref-cache', () => {
 
   it('load after clear returns null', async () => {
     const mod = await importRefCache();
-    await mod.saveRefCache('t1', 'https://x.com', makeRefs(1) as any);
-    await mod.clearRefCache();
+    await mod.saveRefCache(9222, 't1', 'https://x.com', makeRefs(1) as any);
+    await mod.clearRefCache(9222);
 
-    const loaded = await mod.loadRefCache('t1');
+    const loaded = await mod.loadRefCache(9222, 't1');
     expect(loaded).toBeNull();
   });
 
   it('freshly saved cache is not stale', async () => {
     const mod = await importRefCache();
-    await mod.saveRefCache('t1', 'https://x.com', makeRefs(1) as any);
+    await mod.saveRefCache(9222, 't1', 'https://x.com', makeRefs(1) as any);
 
-    const loaded = await mod.loadRefCache('t1');
+    const loaded = await mod.loadRefCache(9222, 't1');
     expect(loaded).not.toBeNull();
     expect(loaded!.stale).toBe(false);
     expect(loaded!.ageMs).toBeLessThan(mod.REF_CACHE_STALE_MS);
@@ -113,16 +113,16 @@ describe('ref-cache', () => {
 
   it('cache older than REF_CACHE_STALE_MS is flagged stale', async () => {
     const mod = await importRefCache();
-    await mod.saveRefCache('t1', 'https://x.com', makeRefs(1) as any);
+    await mod.saveRefCache(9222, 't1', 'https://x.com', makeRefs(1) as any);
 
     // Manually backdate the savedAt timestamp
-    const cacheFile = join(tempDir, '.monomind', 'monobrowse', 'ax-snapshot.json');
+    const cacheFile = join(tempDir, '.monomind', 'monobrowse', 'ax-snapshot-9222.json');
     const raw = JSON.parse(await readFile(cacheFile, 'utf8'));
     raw.savedAt = Date.now() - mod.REF_CACHE_STALE_MS - 5000;
     const { writeFile: wf } = await import('node:fs/promises');
     await wf(cacheFile, JSON.stringify(raw));
 
-    const loaded = await mod.loadRefCache('t1');
+    const loaded = await mod.loadRefCache(9222, 't1');
     expect(loaded).not.toBeNull();
     expect(loaded!.stale).toBe(true);
     expect(loaded!.ageMs).toBeGreaterThan(mod.REF_CACHE_STALE_MS);
@@ -130,76 +130,117 @@ describe('ref-cache', () => {
 
   it('loading with no cache file returns null (no crash)', async () => {
     const mod = await importRefCache();
-    const loaded = await mod.loadRefCache('nonexistent');
+    const loaded = await mod.loadRefCache(9222, 'nonexistent');
     expect(loaded).toBeNull();
   });
+
+  it('#318: each session keeps its own ref cache', async () => {
+    const mod = await importRefCache();
+    await mod.saveRefCache(41111, 'target-A', 'https://a.com', makeRefs(1) as any);
+    await mod.saveRefCache(42222, 'target-B', 'https://b.com', makeRefs(2) as any);
+
+    expect((await mod.loadRefCache(41111, 'target-A'))!.url).toBe('https://a.com');
+    expect((await mod.loadRefCache(42222, 'target-B'))!.refs.size).toBe(2);
+
+    await mod.clearRefCache(41111);
+    expect(await mod.loadRefCache(41111, 'target-A')).toBeNull();
+    expect(await mod.loadRefCache(42222, 'target-B')).not.toBeNull();
+  });
 });
 
-describe('active-port persistence', () => {
-  it('round-trip: save then load returns the port; launched defaults true', async () => {
+describe('#318 session store (one record per port)', () => {
+  it('round-trip: save then load returns the session; launched defaults true', async () => {
     const mod = await importRefCache();
-    await mod.saveActivePort(9333);
-    expect(await mod.loadActivePort()).toBe(9333);
-    expect(await mod.loadActivePortInfo()).toEqual({
+    await mod.saveSessionRecord(9333);
+    expect(await mod.loadSessionRecord(9333)).toEqual({
       port: 9333,
       launched: true,
       savedAt: expect.any(Number),
     });
   });
 
-  it('connect provenance: launched:false survives the round-trip', async () => {
+  it('two concurrent sessions coexist — neither overwrites the other', async () => {
     const mod = await importRefCache();
-    await mod.saveActivePort(9229, { launched: false });
-    expect(await mod.loadActivePortInfo()).toEqual({
-      port: 9229,
-      launched: false,
-      savedAt: expect.any(Number),
-    });
+    await mod.saveSessionRecord(41111, { pid: 11 });
+    await mod.saveSessionRecord(42222, { pid: 22 });
+
+    expect((await mod.listSessionRecords()).map((r) => r.port).sort()).toEqual([41111, 42222]);
+    expect((await mod.loadSessionRecord(41111))!.pid).toBe(11);
+    expect((await mod.loadSessionRecord(42222))!.pid).toBe(22);
+  });
+
+  it('lists newest first — the discovery order for a command with no --port', async () => {
+    const mod = await importRefCache();
+    const now = Date.now();
+    const clock = vi.spyOn(Date, 'now').mockReturnValue(now - 5_000);
+    await mod.saveSessionRecord(41111);
+    clock.mockReturnValue(now);
+    await mod.saveSessionRecord(42222);
+    clock.mockRestore();
+
+    expect((await mod.listSessionRecords()).map((r) => r.port)).toEqual([42222, 41111]);
+  });
+
+  it('removing one session leaves the others alone', async () => {
+    const mod = await importRefCache();
+    await mod.saveSessionRecord(41111);
+    await mod.saveSessionRecord(42222);
+
+    await mod.removeSessionRecord(41111);
+
+    expect(await mod.loadSessionRecord(41111)).toBeNull();
+    expect((await mod.listSessionRecords()).map((r) => r.port)).toEqual([42222]);
   });
 
-  it('clear removes the file; load returns null afterwards', async () => {
+  it('removing a session that was never recorded resolves without throwing', async () => {
     const mod = await importRefCache();
-    await mod.saveActivePort(9333);
-    await mod.clearActivePort();
-    expect(await mod.loadActivePort()).toBeNull();
-    expect(await mod.loadActivePortInfo()).toBeNull();
+    await expect(mod.removeSessionRecord(41111)).resolves.toBeUndefined();
   });
 
-  it('clear with no file resolves without throwing', async () => {
+  it('listing with no sessions directory returns an empty list (no crash)', async () => {
     const mod = await importRefCache();
-    await mod.clearActivePort();
-    await expect(mod.clearActivePort()).resolves.toBeUndefined();
+    expect(await mod.listSessionRecords()).toEqual([]);
   });
 
-  it('#115: pid and userDataDir persist and round-trip so a later process can kill an orphaned launch', async () => {
+  it('connect provenance: launched:false survives the round-trip', async () => {
     const mod = await importRefCache();
-    await mod.saveActivePort(9333, { pid: 54321, userDataDir: '/tmp/monomind-browser-9333' });
-    expect(await mod.loadActivePortInfo()).toEqual({
+    await mod.saveSessionRecord(9229, { launched: false });
+    expect(await mod.loadSessionRecord(9229)).toEqual({
+      port: 9229,
+      launched: false,
+      savedAt: expect.any(Number),
+    });
+  });
+
+  it('#115: pid and userDataDir persist so a later process can kill an orphaned launch', async () => {
+    const mod = await importRefCache();
+    await mod.saveSessionRecord(9333, { pid: 54321, userDataDir: '/tmp/monomind-browse-9333' });
+    expect(await mod.loadSessionRecord(9333)).toEqual({
       port: 9333,
       launched: true,
       pid: 54321,
-      userDataDir: '/tmp/monomind-browser-9333',
+      userDataDir: '/tmp/monomind-browse-9333',
       savedAt: expect.any(Number),
     });
   });
 
   it('#115: an attached (launched:false) session with no pid argument persists none', async () => {
     const mod = await importRefCache();
-    await mod.saveActivePort(9229, { launched: false });
-    const info = await mod.loadActivePortInfo();
+    await mod.saveSessionRecord(9229, { launched: false });
+    const info = await mod.loadSessionRecord(9229);
     expect(info!.launched).toBe(false);
     expect(info!.pid).toBeUndefined();
   });
 
-  it('#124-review: saveActivePort does NOT strip pid when launched:false — callers must not pass one for an attach', async () => {
+  it('#124-review: saveSessionRecord does NOT strip pid when launched:false — callers must not pass one for an attach', async () => {
     // The property above (attach sessions have no pid) is caller discipline,
     // not something this function enforces — the one production caller
-    // (commands.ts's `connect` action) simply never passes a pid alongside
-    // launched:false. This test documents that explicitly so it can't be
-    // mistaken for an invariant the code itself guarantees.
+    // (`connect`) simply never passes a pid alongside launched:false. This
+    // test documents that explicitly so it can't be mistaken for an
+    // invariant the code itself guarantees.
     const mod = await importRefCache();
-    await mod.saveActivePort(9229, { launched: false, pid: 4242 });
-    const info = await mod.loadActivePortInfo();
+    await mod.saveSessionRecord(9229, { launched: false, pid: 4242 });
+    const info = await mod.loadSessionRecord(9229);
     expect(info!.launched).toBe(false);
     expect(info!.pid).toBe(4242);
   });
@@ -207,27 +248,39 @@ describe('active-port persistence', () => {
   it('#115: a non-numeric or non-positive persisted pid is dropped, not trusted', async () => {
     const mod = await importRefCache();
     const { writeFile, mkdir } = await import('node:fs/promises');
-    const dir = join(process.cwd(), '.monomind', 'monobrowse');
+    const dir = join(process.cwd(), '.monomind', 'monobrowse', 'sessions');
     await mkdir(dir, { recursive: true });
     for (const badPid of ['54321', -1, 0, 1.5, null]) {
       await writeFile(
-        join(dir, 'active-port.json'),
+        join(dir, '9333.json'),
         JSON.stringify({ port: 9333, launched: true, pid: badPid }),
       );
-      const info = await mod.loadActivePortInfo();
+      const info = await mod.loadSessionRecord(9333);
       expect(info!.pid).toBeUndefined();
     }
   });
 
-  it('rejects out-of-range or non-integer persisted ports', async () => {
+  it('rejects out-of-range or non-integer persisted ports, and skips them when listing', async () => {
     const mod = await importRefCache();
     const { writeFile, mkdir } = await import('node:fs/promises');
-    const dir = join(process.cwd(), '.monomind', 'monobrowse');
+    const dir = join(process.cwd(), '.monomind', 'monobrowse', 'sessions');
     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();
+      await writeFile(join(dir, '9333.json'), JSON.stringify({ port: bad }));
+      expect(await mod.loadSessionRecord(9333)).toBeNull();
+      expect(await mod.listSessionRecords()).toEqual([]);
     }
   });
+
+  it('a corrupt record is skipped, not fatal for the rest of the listing', async () => {
+    const mod = await importRefCache();
+    await mod.saveSessionRecord(42222);
+    const { writeFile } = await import('node:fs/promises');
+    await writeFile(
+      join(process.cwd(), '.monomind', 'monobrowse', 'sessions', '41111.json'),
+      '{{{not valid json!!!',
+    );
+
+    expect((await mod.listSessionRecords()).map((r) => r.port)).toEqual([42222]);
+  });
 });

package/src/__tests__/report-exit-code.test.ts

@@ -91,7 +91,7 @@ export async function getBrowser() {
     stopRequestCapture: () => {},
     teardownConsoleCapture: () => {},
     ${close}
-    clearActivePort: async () => {},
+    removeSessionRecord: async () => {},
     clearRefCache: async () => {},
   };
 }

package/src/__tests__/session-discovery.test.ts

@@ -0,0 +1,259 @@
+/**
+ * #318: how a CLI command with no `--port` finds "its" session, and what it
+ * does when it finds none — the discovery half of the per-session-browser
+ * fix. The allocation half (Chrome binding a free port in a profile of its
+ * own) is covered by browser-launch.test.ts and, end to end, by
+ * browse-concurrency.test.ts.
+ *
+ * resolveLiveSession() takes the browser namespace as a parameter, so the
+ * real session store (with process.cwd() pointed at a temp dir) can be used
+ * while only the CDP liveness probe is faked.
+ */
+
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), 'monobrowse-session-'));
+  vi.spyOn(process, 'cwd').mockReturnValue(tempDir);
+});
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+async function load() {
+  vi.resetModules();
+  const store = await import('../browser/ref-cache.js');
+  const { resolveLiveSession, adoptLegacySession, pinnedPort, applySessionPortFlag, session } =
+    await import('../cli/session.js');
+  // The slice of the browser namespace resolveLiveSession uses.
+  const browser = {
+    listSessionRecords: store.listSessionRecords,
+    removeSessionRecord: store.removeSessionRecord,
+    clearRefCache: store.clearRefCache,
+    loadSessionRecord: store.loadSessionRecord,
+    saveSessionRecord: store.saveSessionRecord,
+    loadLegacySessionRecord: store.loadLegacySessionRecord,
+    removeLegacySessionRecord: store.removeLegacySessionRecord,
+  } as unknown as Parameters<typeof resolveLiveSession>[0];
+  return {
+    store,
+    browser,
+    resolveLiveSession,
+    adoptLegacySession,
+    pinnedPort,
+    applySessionPortFlag,
+    session,
+  };
+}
+
+/** Write the session file a pre-#318 CLI left behind in this directory. */
+async function writeLegacyRecord(record: Record<string, unknown>) {
+  const { mkdir, writeFile } = await import('node:fs/promises');
+  const dir = join(process.cwd(), '.monomind', 'monobrowse');
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, 'active-port.json'), JSON.stringify(record));
+}
+
+async function legacyFileExists(): Promise<boolean> {
+  const { readFile } = await import('node:fs/promises');
+  return readFile(join(process.cwd(), '.monomind', 'monobrowse', 'active-port.json')).then(
+    () => true,
+    () => false,
+  );
+}
+
+/** Fake the CDP `/json/version` probe: only `live` ports answer. */
+function onlyLive(...live: number[]) {
+  vi.stubGlobal('fetch', async (input: string | URL) => {
+    const port = Number(new URL(String(input)).port);
+    if (live.includes(port)) return new Response('{}', { status: 200 });
+    throw new Error('connection refused');
+  });
+}
+
+describe('#318 session discovery', () => {
+  it('with no sessions recorded, resolves to none — the caller starts its own', async () => {
+    const { browser, resolveLiveSession } = await load();
+    onlyLive();
+    expect(await resolveLiveSession(browser)).toBeNull();
+  });
+
+  it('resolves the newest live session', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    const now = Date.now();
+    const clock = vi.spyOn(Date, 'now').mockReturnValue(now - 5_000);
+    await store.saveSessionRecord(41111, { pid: 11 });
+    clock.mockReturnValue(now);
+    await store.saveSessionRecord(42222, { pid: 22 });
+    clock.mockRestore();
+    onlyLive(41111, 42222);
+
+    expect((await resolveLiveSession(browser))?.port).toBe(42222);
+  });
+
+  it('skips a session whose browser died and resolves the older live one', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    const now = Date.now();
+    const clock = vi.spyOn(Date, 'now').mockReturnValue(now - 5_000);
+    await store.saveSessionRecord(41111);
+    clock.mockReturnValue(now);
+    await store.saveSessionRecord(42222);
+    clock.mockRestore();
+    onlyLive(41111);
+
+    expect((await resolveLiveSession(browser))?.port).toBe(41111);
+  });
+
+  it('self-heals: a dead session is dropped from the store, not left to wedge later commands', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    await store.saveSessionRecord(42222);
+    onlyLive();
+
+    expect(await resolveLiveSession(browser)).toBeNull();
+    expect(await store.loadSessionRecord(42222)).toBeNull();
+  });
+
+  it('a dead connect-origin session fails loudly instead of being relaunched under the user', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    await store.saveSessionRecord(9229, { launched: false });
+    onlyLive();
+
+    await expect(resolveLiveSession(browser)).rejects.toThrow(/Connected browser on port 9229/);
+    expect(await store.loadSessionRecord(9229)).toBeNull();
+  });
+
+  it('close (strict:false) cleans a dead connect-origin session up instead of throwing', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    await store.saveSessionRecord(9229, { launched: false });
+    onlyLive();
+
+    expect(await resolveLiveSession(browser, { strict: false })).toBeNull();
+    expect(await store.loadSessionRecord(9229)).toBeNull();
+  });
+});
+
+describe('#318 adoption of a pre-#318 session record', () => {
+  it('adopts a live legacy session: the record is rewritten per port and the old file is gone', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    const savedAt = Date.now() - 60_000;
+    await writeLegacyRecord({ port: 41111, launched: true, pid: 4242, savedAt });
+    onlyLive(41111);
+
+    expect((await resolveLiveSession(browser))?.port).toBe(41111);
+
+    expect(await store.loadSessionRecord(41111)).toEqual({
+      port: 41111,
+      launched: true,
+      pid: 4242,
+      // Preserved, not reset — the session's real age is what the idle
+      // reaper and the newest-first ordering read.
+      savedAt,
+    });
+    expect(await legacyFileExists()).toBe(false);
+  });
+
+  it('adoption keeps connect provenance, so close still never kills the user’s browser', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    await writeLegacyRecord({ port: 9229, launched: false });
+    onlyLive(9229);
+
+    expect((await resolveLiveSession(browser))?.launched).toBe(false);
+    expect((await store.loadSessionRecord(9229))!.launched).toBe(false);
+  });
+
+  it('a legacy session whose browser is gone is removed, without throwing', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    await writeLegacyRecord({ port: 41111, launched: true, pid: 4242 });
+    onlyLive();
+
+    expect(await resolveLiveSession(browser)).toBeNull();
+    expect(await legacyFileExists()).toBe(false);
+    expect(await store.loadSessionRecord(41111)).toBeNull();
+  });
+
+  it('a dead legacy connect-origin session is cleaned up too, not raised as an error', async () => {
+    const { browser, resolveLiveSession } = await load();
+    await writeLegacyRecord({ port: 9229, launched: false });
+    onlyLive();
+
+    expect(await resolveLiveSession(browser)).toBeNull();
+    expect(await legacyFileExists()).toBe(false);
+  });
+
+  it('a live native session wins; the superseded legacy file is dropped', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    await store.saveSessionRecord(42222, { pid: 22 });
+    await writeLegacyRecord({ port: 41111, launched: true });
+    onlyLive(41111, 42222);
+
+    expect((await resolveLiveSession(browser))?.port).toBe(42222);
+    // Not adopted while a native session is live — it is the older candidate.
+    expect(await legacyFileExists()).toBe(true);
+  });
+
+  it('a legacy record for a port that already has a native record is dropped, not adopted twice', async () => {
+    const { store, browser, adoptLegacySession } = await load();
+    await store.saveSessionRecord(41111, { launched: false });
+    await writeLegacyRecord({ port: 41111, launched: true, pid: 4242 });
+    onlyLive(41111);
+
+    expect(await adoptLegacySession(browser)).toBeNull();
+    expect(await legacyFileExists()).toBe(false);
+    expect((await store.loadSessionRecord(41111))!.launched).toBe(false);
+  });
+
+  it('adoption restricted to a named port leaves another port’s legacy record alone', async () => {
+    const { browser, adoptLegacySession } = await load();
+    await writeLegacyRecord({ port: 41111, launched: true });
+    onlyLive(41111);
+
+    expect(await adoptLegacySession(browser, { port: 42222 })).toBeNull();
+    expect(await legacyFileExists()).toBe(true);
+    expect((await adoptLegacySession(browser, { port: 41111 }))?.port).toBe(41111);
+    expect(await legacyFileExists()).toBe(false);
+  });
+
+  it('with no legacy file at all, adoption is a no-op', async () => {
+    const { browser, adoptLegacySession } = await load();
+    onlyLive();
+    expect(await adoptLegacySession(browser)).toBeNull();
+  });
+});
+
+describe('#318 --port session selector', () => {
+  it('reads a usable port from the flags, in either the number or string form', async () => {
+    const { pinnedPort } = await load();
+    expect(pinnedPort({ _: [], port: 9333 })).toBe(9333);
+    expect(pinnedPort({ _: [], port: '9333' })).toBe(9333);
+  });
+
+  it('treats absent, out-of-range and unparseable ports as "no selector"', async () => {
+    const { pinnedPort } = await load();
+    expect(pinnedPort({ _: [] })).toBeUndefined();
+    expect(pinnedPort({ _: [], port: 80 })).toBeUndefined();
+    expect(pinnedPort({ _: [], port: 70000 })).toBeUndefined();
+    expect(pinnedPort({ _: [], port: 1.5 })).toBeUndefined();
+    expect(pinnedPort({ _: [], port: 'nope' })).toBeUndefined();
+    expect(pinnedPort({ _: [], port: true })).toBeUndefined();
+  });
+
+  it('pins the process to the named session', async () => {
+    const { applySessionPortFlag, session } = await load();
+    applySessionPortFlag({ _: [], port: 9333 });
+    expect(session.port).toBe(9333);
+  });
+
+  it('a command with no --port leaves an established session alone (batch open → snapshot)', async () => {
+    const { applySessionPortFlag, session } = await load();
+    session.port = 41111; // as `open` set it earlier in this process
+    applySessionPortFlag({ _: [] });
+    expect(session.port).toBe(41111);
+  });
+});

package/src/browser/browser.ts

@@ -6,7 +6,12 @@ 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';
 
@@ -490,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
@@ -594,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);
@@ -636,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;