@monoes/monobrowse 1.0.22 → 1.0.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monobrowse",
-  "version": "1.0.22",
+  "version": "1.0.25",
   "description": "Native browser automation via Chrome DevTools Protocol — the engine powering monomind browse",
   "type": "module",
   "bin": {

package/src/__tests__/browse-concurrency.test.ts

@@ -18,7 +18,7 @@ import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { afterEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeAll, describe, expect, it } from 'vitest';
 import { CHROME_EXECUTABLES } from '../browser/types.js';
 
 const here = dirname(fileURLToPath(import.meta.url));
@@ -100,7 +100,51 @@ afterEach(async () => {
   }
 });
 
+/**
+ * Start Chrome once, outside any trial, and let it finish. A runner's first
+ * Chrome start pays for paging the binary and its libraries in and building
+ * the font cache; two of them at once in trial 1 took longer than `open`'s
+ * 10 s CDP wait on CI, while every later trial passed. `--dump-dom` exits on
+ * its own once the page loads, so this has no timeout of `open`'s to beat.
+ */
+async function warmUpChrome(): Promise<void> {
+  let found: string;
+  try {
+    found = execFileSync('which', ['google-chrome', 'chromium-browser', 'chromium'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch (err) {
+    // `which` exits non-zero when any one name is missing; the rest still print.
+    found = String((err as { stdout?: string }).stdout ?? '');
+  }
+  const chrome = CHROME_EXECUTABLES.find((p) => existsSync(p)) ?? found.split('\n')[0];
+  if (!chrome) return;
+  const profile = await mkdtemp(join(process.env.TMPDIR ?? tmpdir(), 'monobrowse-warmup-'));
+  try {
+    await new Promise<void>((resolve) => {
+      execFile(
+        chrome,
+        [
+          '--headless=new',
+          `--user-data-dir=${profile}`,
+          '--no-first-run',
+          ...(process.env.CI ? ['--no-sandbox', '--disable-dev-shm-usage'] : []),
+          '--dump-dom',
+          'about:blank',
+        ],
+        { timeout: 60_000 },
+        () => resolve(),
+      );
+    });
+  } finally {
+    await rm(profile, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
+  }
+}
+
 describe.skipIf(!runnable)('#318 concurrent browse sessions (real processes)', () => {
+  beforeAll(warmUpChrome, 90_000);
+
   for (const trial of [1, 2, 3, 4, 5]) {
     it(`trial ${trial}: two bare \`open\` calls each get their own browser, and each close kills only its own`, async () => {
       const root = await mkdtemp(join(process.env.TMPDIR ?? tmpdir(), 'monobrowse-318-'));
@@ -231,3 +275,64 @@ describe.skipIf(!runnable)('#318 adoption of a pre-#318 session (real processes)
     expect(await cdpAlive(legacyPort)).toBe(false);
   }, 90_000);
 });
+
+/**
+ * `--session <name>` is documented (browse-qa, browse-electron skills) as a
+ * way to drive several browsers side by side. It used to be a no-op outside
+ * `open`, where it only restored saved state and failed when none existed —
+ * AFTER launching a browser — so every later command silently acted on
+ * whichever session was newest. Real processes, because the bug is in what a
+ * later, separate CLI invocation resolves.
+ */
+describe.skipIf(!runnable)('--session named sessions (real processes)', () => {
+  beforeAll(warmUpChrome, 90_000);
+
+  it('two named sessions stay apart, a bare command never lands on them, and an unknown name fails', async () => {
+    const root = await mkdtemp(join(process.env.TMPDIR ?? tmpdir(), 'monobrowse-named-'));
+    dirs.push(root);
+    const pageA = join(root, 'a.html');
+    const pageB = join(root, 'b.html');
+    await writeFile(pageA, '<!doctype html><title>Page A</title><h1>a</h1>');
+    await writeFile(pageB, '<!doctype html><title>Page B</title><h1>b</h1>');
+
+    const openA = await runCli(['open', `file://${pageA}`, '--session', 'ref'], root, root);
+    expect(openA.code, `open ref failed: ${openA.stdout}${openA.stderr}`).toBe(0);
+    const openB = await runCli(['open', `file://${pageB}`, '--session', 'build'], root, root);
+    expect(openB.code, `open build failed: ${openB.stdout}${openB.stderr}`).toBe(0);
+    const portA = reportedPort(openA);
+    const portB = reportedPort(openB);
+    expect(portA).not.toBeNull();
+    expect(portA).not.toBe(portB);
+
+    // 'build' is the newest session, yet --session ref reaches 'ref'.
+    const titleA = await runCli(['get', 'title', '--session', 'ref'], root, root);
+    expect(titleA.code, `get title ref failed: ${titleA.stdout}${titleA.stderr}`).toBe(0);
+    expect(titleA.stdout).toContain('Page A');
+    const titleB = await runCli(['get', 'title', '--session', 'build'], root, root);
+    expect(titleB.stdout).toContain('Page B');
+
+    // Re-opening a name navigates that session's own browser.
+    const reopen = await runCli(['open', `file://${pageB}`, '--session', 'ref'], root, root);
+    expect(reopen.code, `re-open ref failed: ${reopen.stdout}${reopen.stderr}`).toBe(0);
+    expect(reportedPort(reopen)).toBe(portA);
+
+    // An unknown name is an error, not a silent fallback to the newest session.
+    const unknown = await runCli(['get', 'title', '--session', 'nope'], root, root);
+    expect(unknown.code).not.toBe(0);
+    expect(`${unknown.stdout}${unknown.stderr}`).toMatch(/No live browse session named "nope"/);
+
+    // A bare command starts its own browser instead of joining a named one.
+    const bare = await runCli(['get', 'title'], root, root);
+    expect(bare.code, `bare get title failed: ${bare.stdout}${bare.stderr}`).toBe(0);
+    expect(bare.stdout).not.toContain('Page');
+
+    // close --session ends exactly that session.
+    const closeA = await runCli(['close', '--session', 'ref'], root, root);
+    expect(closeA.code, `close ref failed: ${closeA.stdout}${closeA.stderr}`).toBe(0);
+    expect(await cdpAlive(portA!)).toBe(false);
+    expect(await cdpAlive(portB!)).toBe(true);
+    await runCli(['close', '--session', 'build'], root, root);
+    expect(await cdpAlive(portB!)).toBe(false);
+    await runCli(['close'], root, root);
+  }, 120_000);
+});

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

@@ -9,12 +9,13 @@
  * services; each test binds/tears down its own listeners.
  */
 
+import { execFileSync } from 'node:child_process';
 import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { createServer as createHttpServer, type Server as HttpServer } from 'node:http';
 import { createServer as createTcpServer, type Socket, type Server as TcpServer } from 'node:net';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { afterEach, describe, expect, it } from 'vitest';
+import { afterAll, afterEach, describe, expect, it } from 'vitest';
 import { getLaunchedPid, getLaunchedUserDataDir, launchBrowser } from '../browser/browser.js';
 
 const BASE = 23470;
@@ -32,6 +33,72 @@ afterEach(async () => {
   servers = [];
 }, 5000);
 
+// Every fake-chrome.cjs below is spawned by launchBrowser (detached, so a
+// test cannot reach it through a ChildProcess). Its temp dir is on its
+// command line, so each dir is recorded here and afterAll kills whatever is
+// still running out of one — a fixture must never outlive this file (one
+// that did kept 127.0.0.1:23480 bound and failed later runs with
+// EADDRINUSE).
+const fixtureDirs: string[] = [];
+
+function fixtureDir(prefix: string): string {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  fixtureDirs.push(dir);
+  return dir;
+}
+
+/** Pids of processes whose command line mentions `dir`. */
+function processesIn(dir: string): string[] {
+  try {
+    return execFileSync('pgrep', ['-f', dir], { encoding: 'utf8' })
+      .trim()
+      .split('\n')
+      .filter(Boolean);
+  } catch {
+    return []; // pgrep exits 1 when nothing matches
+  }
+}
+
+afterAll(async () => {
+  const leaked: string[] = [];
+  for (const dir of fixtureDirs.splice(0)) {
+    // A fixture a test just SIGKILLed can take a moment to disappear.
+    let pids = processesIn(dir);
+    for (let i = 0; i < 20 && pids.length > 0; i++) {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      pids = processesIn(dir);
+    }
+    leaked.push(...pids);
+    for (const pid of pids) {
+      try {
+        process.kill(Number(pid), 'SIGKILL');
+      } catch {
+        /* already gone */
+      }
+    }
+    rmSync(dir, { recursive: true, force: true });
+  }
+  // Swept above either way; failing here names a test whose own cleanup
+  // missed a fixture.
+  expect(leaked, 'fake-chrome fixtures outlived their test').toEqual([]);
+});
+
+// Prepended to every fake-chrome script: exit once the process that launched
+// it is gone (launchBrowser spawns detached, so a vitest worker that dies or
+// is killed mid-test would otherwise leave the fixture — and its port —
+// behind, reparented to init), and never live longer than a minute anyway.
+const FIXTURE_WATCHDOG = `const parent = process.ppid;
+setInterval(() => {
+  try {
+    if (process.ppid !== parent) process.exit(0);
+    process.kill(parent, 0);
+  } catch {
+    process.exit(0);
+  }
+}, 1000).unref();
+setTimeout(() => process.exit(0), 60000).unref();
+`;
+
 /** Bind a bare TCP listener — accepts connections but speaks no HTTP/CDP. */
 function occupyNonChrome(port: number): Promise<void> {
   return new Promise((resolve, reject) => {
@@ -119,7 +186,7 @@ describe('launchBrowser — port scan/attach decisions', () => {
 // --remote-debugging-port=0, it binds a kernel-assigned port and only then
 // writes that port to <user-data-dir>/DevToolsActivePort.
 const FAKE_CHROME = `#!/usr/bin/env node
-const { createServer } = require('node:http');
+${FIXTURE_WATCHDOG}const { createServer } = require('node:http');
 const { writeFileSync } = require('node:fs');
 const { join } = require('node:path');
 const dir = process.argv.find((a) => a.startsWith('--user-data-dir=')).slice('--user-data-dir='.length);
@@ -133,11 +200,32 @@ setTimeout(() => server.listen(0, '127.0.0.1', () => {
 }), 600);
 `;
 
+// Like FAKE_CHROME, but its first /json/version answer takes longer than
+// launchBrowser's 1 s identity timeout, while /json/list answers at once.
+const FAKE_CHROME_SLOW_IDENTITY = `#!/usr/bin/env node
+${FIXTURE_WATCHDOG}const { createServer } = require('node:http');
+const { writeFileSync } = require('node:fs');
+const { join } = require('node:path');
+const dir = process.argv.find((a) => a.startsWith('--user-data-dir=')).slice('--user-data-dir='.length);
+let versionCalls = 0;
+const server = createServer((req, res) => {
+  const send = () => {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(req.url === '/json/version' ? JSON.stringify({ Browser: 'Chrome/999.0.0.0' }) : '[]');
+  };
+  if (req.url === '/json/version' && versionCalls++ === 0) setTimeout(send, 1500);
+  else send();
+});
+server.listen(0, '127.0.0.1', () => {
+  writeFileSync(join(dir, 'DevToolsActivePort'), server.address().port + '\\n/devtools/browser/fake');
+});
+`;
+
 describe.skipIf(process.platform === 'win32')(
   'launchBrowser — port 0 (Chrome picks the port)',
   () => {
     it('returns the port its own Chrome reported, never another CDP endpoint', async () => {
-      const dir = mkdtempSync(join(tmpdir(), 'monobrowse-port0-'));
+      const dir = fixtureDir('monobrowse-port0-');
       const exe = join(dir, 'fake-chrome.cjs');
       writeFileSync(exe, FAKE_CHROME);
       chmodSync(exe, 0o755);
@@ -168,6 +256,48 @@ describe.skipIf(process.platform === 'win32')(
       }
     });
 
+    it('does not reject its own Chrome when /json/version answers slowly (loaded machine)', async () => {
+      // On a busy CI runner Chrome's DevTools server can take longer than the
+      // identity check's timeout to answer /json/version right after it
+      // starts listening, while /json/list (no timeout) got through. That
+      // timeout used to be read as "not Chrome" and failed the launch with
+      // "occupied by a CDP-speaking process that does not identify as
+      // Chrome/Chromium" — for the very Chrome it had just started.
+      const dir = fixtureDir('monobrowse-slowid-');
+      const exe = join(dir, 'fake-chrome.cjs');
+      writeFileSync(exe, FAKE_CHROME_SLOW_IDENTITY);
+      chmodSync(exe, 0o755);
+      const profile = join(dir, 'profile');
+      mkdirSync(profile);
+
+      let port: number | undefined;
+      try {
+        port = await launchBrowser({ port: 0, userDataDir: profile, executablePath: exe });
+        expect(port).toBeGreaterThan(0);
+        expect(getLaunchedPid(port)).toBeTypeOf('number');
+      } finally {
+        const pid = port === undefined ? undefined : getLaunchedPid(port);
+        if (pid) process.kill(pid, 'SIGKILL');
+      }
+    }, 15000);
+
+    it('still refuses a CDP endpoint that answers as a non-Chrome browser', async () => {
+      const dir = fixtureDir('monobrowse-notchrome-');
+      const exe = join(dir, 'fake-chrome.cjs');
+      writeFileSync(exe, FAKE_CHROME.replace('Chrome/999.0.0.0', 'Firefox/1.0'));
+      chmodSync(exe, 0o755);
+      const profile = join(dir, 'profile');
+      mkdirSync(profile);
+      await expect(
+        launchBrowser({ port: 0, userDataDir: profile, executablePath: exe }),
+      ).rejects.toThrow(/does not identify as Chrome/);
+      // Refused, so never tracked — launchBrowser must stop it itself.
+      for (let i = 0; i < 20 && processesIn(dir).length > 0; i++) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      }
+      expect(processesIn(dir)).toEqual([]);
+    }, 15000);
+
     it('refuses port 0 without a dedicated userDataDir', async () => {
       await expect(launchBrowser({ port: 0 })).rejects.toThrow(/requires a dedicated userDataDir/);
     });
@@ -182,7 +312,7 @@ describe.skipIf(process.platform === 'win32')(
 // when a concurrent launch wins the same "free-looking" port: before its
 // CDP endpoint ever opens.
 const FAKE_CHROME_FIXED_PORT = `#!/usr/bin/env node
-const { createServer } = require('node:http');
+${FIXTURE_WATCHDOG}const { createServer } = require('node:http');
 const { writeFileSync, mkdirSync } = require('node:fs');
 const { join } = require('node:path');
 const port = Number(
@@ -206,7 +336,7 @@ describe.skipIf(process.platform === 'win32')(
   'launchBrowser — concurrent launches with no explicit --port (TOCTOU race)',
   () => {
     it('two concurrent launches racing for the same default port both succeed, on different ports and profiles', async () => {
-      const dir = mkdtempSync(join(tmpdir(), 'monobrowse-concurrent-'));
+      const dir = fixtureDir('monobrowse-concurrent-');
       const exe = join(dir, 'fake-chrome.cjs');
       writeFileSync(exe, FAKE_CHROME_FIXED_PORT);
       chmodSync(exe, 0o755);
@@ -216,12 +346,17 @@ describe.skipIf(process.platform === 'win32')(
       // whether or not the user passed it (cli/commands.ts:288).
       const port = BASE + 10;
 
+      // allSettled, not all: when one launch rejects, the other's fixture is
+      // still running and must be killed too — Promise.all dropped its port
+      // and leaked it.
+      let results: PromiseSettledResult<number>[] = [];
       let ports: number[] = [];
       try {
-        ports = await Promise.all([
+        results = await Promise.allSettled([
           launchBrowser({ port, executablePath: exe, launchTimeoutMs: 5000 }),
           launchBrowser({ port, executablePath: exe, launchTimeoutMs: 5000 }),
         ]);
+        ports = results.flatMap((r) => (r.status === 'fulfilled' ? [r.value] : []));
       } finally {
         for (const p of ports) {
           const pid = getLaunchedPid(p);
@@ -233,9 +368,9 @@ describe.skipIf(process.platform === 'win32')(
             }
           }
         }
-        rmSync(dir, { recursive: true, force: true });
       }
 
+      for (const r of results) if (r.status === 'rejected') throw r.reason;
       expect(ports).toHaveLength(2);
       // The old probe-then-launch race let both calls observe the same
       // candidate as free and spawn Chrome on it — one bind wins, the

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

@@ -30,8 +30,14 @@ afterEach(async () => {
 async function load() {
   vi.resetModules();
   const store = await import('../browser/ref-cache.js');
-  const { resolveLiveSession, adoptLegacySession, pinnedPort, applySessionPortFlag, session } =
-    await import('../cli/session.js');
+  const {
+    resolveLiveSession,
+    adoptLegacySession,
+    pinnedPort,
+    applySessionPortFlag,
+    applySessionNameFlag,
+    session,
+  } = await import('../cli/session.js');
   // The slice of the browser namespace resolveLiveSession uses.
   const browser = {
     listSessionRecords: store.listSessionRecords,
@@ -49,6 +55,7 @@ async function load() {
     adoptLegacySession,
     pinnedPort,
     applySessionPortFlag,
+    applySessionNameFlag,
     session,
   };
 }
@@ -257,3 +264,106 @@ describe('#318 --port session selector', () => {
     expect(session.port).toBe(41111);
   });
 });
+
+describe('--session names a live session', () => {
+  /** Record sessions oldest → newest, so newest-first order is deterministic. */
+  async function recordInOrder(
+    store: Awaited<ReturnType<typeof load>>['store'],
+    ...records: Array<{ port: number; name?: string }>
+  ) {
+    const now = Date.now();
+    const clock = vi.spyOn(Date, 'now');
+    for (const [i, r] of records.entries()) {
+      clock.mockReturnValue(now - (records.length - i) * 1_000);
+      await store.saveSessionRecord(r.port, { pid: 10 + i, name: r.name });
+    }
+    clock.mockRestore();
+  }
+
+  it('the record keeps its name', async () => {
+    const { store } = await load();
+    await store.saveSessionRecord(41111, { pid: 11, name: 'ref' });
+    expect((await store.loadSessionRecord(41111))?.name).toBe('ref');
+  });
+
+  it('resolves the live session with that name, not the newest one', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    await recordInOrder(
+      store,
+      { port: 41111, name: 'ref' },
+      { port: 42222, name: 'build' },
+      { port: 43333 },
+    );
+    onlyLive(41111, 42222, 43333);
+
+    expect((await resolveLiveSession(browser, { name: 'ref' }))?.port).toBe(41111);
+    expect((await resolveLiveSession(browser, { name: 'build' }))?.port).toBe(42222);
+  });
+
+  it('an unknown name resolves to none instead of falling back to another session', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    await recordInOrder(store, { port: 41111 }, { port: 42222, name: 'build' });
+    onlyLive(41111, 42222);
+
+    expect(await resolveLiveSession(browser, { name: 'ref' })).toBeNull();
+  });
+
+  it('a command with no name never lands on a named session', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    await recordInOrder(store, { port: 41111 }, { port: 42222, name: 'ref' });
+    onlyLive(41111, 42222);
+
+    expect((await resolveLiveSession(browser))?.port).toBe(41111);
+  });
+
+  it('a dead named session is dropped, and the name resolves to none', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    await recordInOrder(store, { port: 41111, name: 'ref' });
+    onlyLive();
+
+    expect(await resolveLiveSession(browser, { name: 'ref' })).toBeNull();
+    expect(await store.loadSessionRecord(41111)).toBeNull();
+  });
+
+  // Regression: a command whose flags never set `session.name` (e.g.
+  // `snapshot -s <name>` — `-s` is `--selector` on snapshot, not
+  // `--session`, see withSessionSelector in cli/commands.ts) used to find
+  // NO live session at all once the only live session was named, so
+  // ensureConnected silently launched a brand-new, unrelated headless
+  // Chrome — its blank "New Tab" is what a following snapshot showed
+  // instead of the page the named session had actually opened. With only
+  // one live session, named or not, a nameless lookup must still resolve to
+  // it: there is nothing else it could mean.
+  it('a command with no name resolves the sole live session even if it is named', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    await recordInOrder(store, { port: 41111, name: 'ctrl' });
+    onlyLive(41111);
+
+    expect((await resolveLiveSession(browser))?.port).toBe(41111);
+  });
+
+  // But guessing between two DIFFERENT named sessions would reintroduce the
+  // exact cross-session bleed #318 fixed — refuse instead of picking one.
+  it('a command with no name refuses to guess between two live named sessions', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    await recordInOrder(store, { port: 41111, name: 'alpha' }, { port: 42222, name: 'beta' });
+    onlyLive(41111, 42222);
+
+    expect(await resolveLiveSession(browser)).toBeNull();
+  });
+
+  it('--session sets the process session name; a missing flag leaves it alone', async () => {
+    const { applySessionNameFlag, session } = await load();
+    applySessionNameFlag({ _: [], session: 'ref' });
+    expect(session.name).toBe('ref');
+    applySessionNameFlag({ _: [] });
+    expect(session.name).toBe('ref');
+  });
+
+  it('rejects a session name that is not a plain identifier', async () => {
+    const { applySessionNameFlag } = await load();
+    for (const bad of ['', '../x', 'a b', 'x'.repeat(65)]) {
+      expect(() => applySessionNameFlag({ _: [], session: bad })).toThrow(/Invalid session name/);
+    }
+  });
+});

package/src/browser/browser.ts

@@ -92,18 +92,27 @@ export async function isPortOpen(port: number): Promise<boolean> {
  * attaching to an unrelated real browser that happens to be listening there.
  */
 async function isChromeIdentity(port: number): Promise<boolean> {
+  return (await chromeIdentity(port)) === 'chrome';
+}
+
+/** isChromeIdentity, telling "answered as something else" apart from "did
+ *  not answer in time" ('unknown': a timeout, a refused or reset connection,
+ *  a non-OK status or an unparseable body). */
+async function chromeIdentity(port: number): Promise<'chrome' | 'other' | 'unknown'> {
   try {
     const res = await fetch(`http://127.0.0.1:${port}/json/version`, {
       signal: AbortSignal.timeout(1000),
     });
-    if (!res.ok) return false;
+    if (!res.ok) return 'unknown';
     const info = (await res.json()) as { Browser?: string };
     // Edge's Browser field is "Edg/<version>" with no "chrome"/"chromium"
     // substring, even though it's Chromium-based and CDP-compatible —
     // accept it alongside Chrome/Chromium rather than rejecting a valid target.
-    return typeof info.Browser === 'string' && /chrom(e|ium)|edg/i.test(info.Browser);
+    return typeof info.Browser === 'string' && /chrom(e|ium)|edg/i.test(info.Browser)
+      ? 'chrome'
+      : 'other';
   } catch {
-    return false;
+    return 'unknown';
   }
 }
 
@@ -353,6 +362,17 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
   // process's pid overwriting the real winner's, corrupting the very map
   // closeBrowser()'s kill fallback depends on.
 
+  // With port 0 a refused or timed-out launch is not tracked under any port,
+  // so no closeBrowser() could ever reach it — stop it rather than leave it
+  // running.
+  const killUntracked = () => {
+    try {
+      if (child.pid) process.kill(child.pid, 'SIGKILL');
+    } catch {
+      /* already gone */
+    }
+  };
+
   const launchTimeout = config.launchTimeoutMs ?? LAUNCH_TIMEOUT;
   const deadline = Date.now() + launchTimeout;
   while (Date.now() < deadline) {
@@ -361,10 +381,17 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
     if (earlyFailure) throw earlyFailure;
     const boundPort = port === 0 ? readDevToolsActivePort(activePortFile) : port;
     if (boundPort !== null && (await isPortOpen(boundPort))) {
-      if (await isChromeIdentity(boundPort)) {
+      const identity = await chromeIdentity(boundPort);
+      if (identity === 'chrome') {
         track(boundPort);
         return boundPort;
       }
+      // A Chrome that has only just opened its endpoint, on a loaded
+      // machine, can answer /json/list (no timeout) yet miss the identity
+      // check's 1 s timeout on /json/version. That says nothing about who is
+      // listening — keep polling rather than refuse our own Chrome.
+      if (identity === 'unknown') continue;
+      if (port === 0) killUntracked();
       throw new Error(
         `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}.`,
@@ -375,13 +402,7 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
   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 */
-    }
+    killUntracked();
     throw new Error(
       `Chrome did not report a CDP port in ${activePortFile} within ${launchTimeout}ms`,
     );

package/src/browser/ref-cache.ts

@@ -119,8 +119,14 @@ export interface SessionRecord {
   pid?: number;
   userDataDir?: string;
   savedAt?: number;
+  /** Set by `--session <name>`: only commands naming it resolve this session,
+   *  and commands naming none never land on it. */
+  name?: string;
 }
 
+/** A `--session` name: a plain identifier, safe as a label and in messages. */
+export const SESSION_NAME_RE = /^[A-Za-z0-9._-]{1,64}$/;
+
 /**
  * Record a browse session under its own port, so concurrent sessions in the
  * same working directory coexist instead of overwriting one shared handle.
@@ -132,7 +138,13 @@ export interface SessionRecord {
  */
 export async function saveSessionRecord(
   port: number,
-  opts?: { launched?: boolean; pid?: number; userDataDir?: string; savedAt?: number },
+  opts?: {
+    launched?: boolean;
+    pid?: number;
+    userDataDir?: string;
+    savedAt?: number;
+    name?: string;
+  },
 ): Promise<void> {
   try {
     await mkdir(SESSIONS_DIR, { recursive: true });
@@ -150,6 +162,7 @@ export async function saveSessionRecord(
         pid: opts?.pid,
         userDataDir: opts?.userDataDir,
         savedAt: opts?.savedAt ?? Date.now(),
+        name: opts?.name,
       }),
     );
   } catch {
@@ -235,6 +248,7 @@ function parseSessionRecord(raw: string): SessionRecord | null {
     pid?: unknown;
     userDataDir?: unknown;
     savedAt?: unknown;
+    name?: unknown;
   };
   if (
     typeof data.port !== 'number' ||
@@ -253,5 +267,6 @@ function parseSessionRecord(raw: string): SessionRecord | null {
         : undefined,
     userDataDir: typeof data.userDataDir === 'string' ? data.userDataDir : undefined,
     savedAt: typeof data.savedAt === 'number' ? data.savedAt : undefined,
+    name: typeof data.name === 'string' && SESSION_NAME_RE.test(data.name) ? data.name : undefined,
   };
 }