@monoes/monobrowse 1.0.24 → 1.0.26

package/package.json

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

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

@@ -5,16 +5,18 @@
  * launchBrowser would ever exec a browser binary, so these run fast and
  * don't depend on Chrome being installed in CI.
  *
- * Fixed port range (23470-23479) chosen to avoid colliding with real
- * services; each test binds/tears down its own listeners.
+ * Fixed port range (23460-23489) chosen to avoid colliding with real
+ * services and with reap-idle-browser.test.ts's 23490-23499, which runs in a
+ * parallel worker; each test binds/tears down its own listeners.
  */
 
-import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, 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 +34,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 +187,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 +201,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 +257,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/);
     });
@@ -180,25 +311,33 @@ describe.skipIf(process.platform === 'win32')(
 // port too — see cli/commands.ts's `port` option default). If the bind
 // fails (another process already has it), it exits the way real Chrome does
 // when a concurrent launch wins the same "free-looking" port: before its
-// CDP endpoint ever opens.
+// CDP endpoint ever opens. Like real Chrome on a fixed port, it writes no
+// DevToolsActivePort; it announces its browser websocket on stderr, with an
+// id unique to this process that /json/version reports too.
 const FAKE_CHROME_FIXED_PORT = `#!/usr/bin/env node
-const { createServer } = require('node:http');
+${FIXTURE_WATCHDOG}const { createServer } = require('node:http');
+const { randomUUID } = require('node:crypto');
 const { writeFileSync, mkdirSync } = require('node:fs');
 const { join } = require('node:path');
 const port = Number(
   process.argv.find((a) => a.startsWith('--remote-debugging-port=')).slice('--remote-debugging-port='.length),
 );
 const dir = process.argv.find((a) => a.startsWith('--user-data-dir=')).slice('--user-data-dir='.length);
+const ws = 'ws://127.0.0.1:' + port + '/devtools/browser/' + randomUUID();
 const server = createServer((req, res) => {
   res.writeHead(200, { 'Content-Type': 'application/json' });
-  res.end(req.url === '/json/version' ? JSON.stringify({ Browser: 'Chrome/999.0.0.0' }) : '[]');
+  res.end(
+    req.url === '/json/version'
+      ? JSON.stringify({ Browser: 'Chrome/999.0.0.0', webSocketDebuggerUrl: ws })
+      : '[]',
+  );
 });
 server.on('error', () => {
   process.exit(21);
 });
 server.listen(port, '127.0.0.1', () => {
   mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, 'DevToolsActivePort'), port + '\\n/devtools/browser/fake');
+  process.stderr.write('\\nDevTools listening on ' + ws + '\\n');
 });
 `;
 
@@ -206,7 +345,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 +355,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 +377,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
@@ -250,5 +394,68 @@ describe.skipIf(process.platform === 'win32')(
       expect(dirs[0]).toBeTruthy();
       expect(dirs[1]).toBeTruthy();
     }, 15000);
+
+    it('a launch whose Chrome is still booting does not adopt a concurrent launch that took the port', async () => {
+      // The loaded-machine shape of the race above, made deterministic: both
+      // launches probe the port as free, the "fast" Chrome binds it first,
+      // and the "slow" one is still starting when its poll finds a Chrome
+      // answering there. That Chrome is not the slow launch's own, so it
+      // must not be returned — nor may the slow launch record its own pid
+      // (about to exit on the lost bind) under the fast launch's port.
+      const dir = fixtureDir('monobrowse-adopt-');
+      const fast = join(dir, 'fast-chrome.cjs');
+      const slow = join(dir, 'slow-chrome.cjs');
+      writeFileSync(fast, fixedPortChrome(500));
+      writeFileSync(slow, fixedPortChrome(2500));
+      chmodSync(fast, 0o755);
+      chmodSync(slow, 0o755);
+      // Below BASE: this file's fixed ports, clear of the kernel's
+      // ephemeral range, where another test's listen(0) server can land on
+      // the candidate the slow launch scans on to.
+      const port = BASE - 10;
+
+      let results: PromiseSettledResult<number>[] = [];
+      try {
+        results = await Promise.allSettled([
+          launchBrowser({ port, executablePath: fast, launchTimeoutMs: 10_000 }),
+          launchBrowser({ port, executablePath: slow, launchTimeoutMs: 10_000 }),
+        ]);
+      } finally {
+        for (const r of results) {
+          const pid = r.status === 'fulfilled' ? getLaunchedPid(r.value) : undefined;
+          if (pid) {
+            try {
+              process.kill(pid, 'SIGKILL');
+            } catch {
+              /* already gone */
+            }
+          }
+        }
+      }
+
+      const [fastResult, slowResult] = results;
+      expect(fastResult).toEqual({ status: 'fulfilled', value: port });
+      if (slowResult.status === 'rejected') throw slowResult.reason;
+      expect(slowResult.value).not.toBe(port);
+      // The pid tracked for the port is the Chrome that actually serves it.
+      const fastDir = getLaunchedUserDataDir(port)!;
+      expect(fastDir).toBeTruthy();
+      expect(getLaunchedPid(port)).toBe(Number(readFileSync(join(fastDir, 'pid'), 'utf8')));
+    }, 20_000);
   },
 );
+
+/** FAKE_CHROME_FIXED_PORT that waits `delayMs` before binding, and records
+ *  its own pid in its profile dir. */
+function fixedPortChrome(delayMs: number): string {
+  return FAKE_CHROME_FIXED_PORT.replace(
+    'mkdirSync(dir, { recursive: true });',
+    `mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'pid'), String(process.pid));`,
+  )
+    .replace(
+      "server.listen(port, '127.0.0.1', () => {",
+      "setTimeout(() => server.listen(port, '127.0.0.1', () => {",
+    )
+    .replace(/\}\);\n$/, `}), ${delayMs});\n`);
+}

package/src/__tests__/launch-close-settle.test.ts

@@ -27,11 +27,18 @@
  *      manual repro. vi.useFakeTimers() (used throughout close-browser.test.ts)
  *      cannot catch this class of bug, because fake timers do not model real
  *      event-loop-drain semantics — hence a dedicated, real-timer test here.
+ *
+ * Ports come from the OS (listen on 0), never a fixed number (#351): these
+ * tests used 23495-23497, inside reap-idle-browser.test.ts's 23490-23499
+ * range, whose fake Chrome endpoints run in a parallel worker. A spawn that
+ * failed on 23495 while that file had 23495 bound looked like a lost launch
+ * race to launchBrowser, which moved on and reported port 23496 instead.
  */
 
 import { spawn } from 'node:child_process';
 import { chmodSync, writeFileSync } from 'node:fs';
 import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:net';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
@@ -88,6 +95,19 @@ afterEach(async () => {
   await rm(tempDir, { recursive: true, force: true });
 });
 
+/** A port nothing is listening on, picked by the kernel from its ephemeral
+ *  range — which the fixed-port fixtures of other test files stay below. */
+function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address() as { port: number };
+      server.close(() => resolve(port));
+    });
+  });
+}
+
 async function writePersistedPort(port: number, pid: number, savedAt: number): Promise<void> {
   const dir = join(tempDir, '.monomind', 'monobrowse');
   await mkdir(dir, { recursive: true });
@@ -118,21 +138,22 @@ describe('#314: launchBrowser settles instead of hanging when Chrome fails to st
     // "file not found" that launchBrowser would reject before ever exec'ing.
     writeFileSync(fake, 'not an executable\n');
     chmodSync(fake, 0o644);
+    const port = await freePort();
 
     const start = Date.now();
     await expect(
-      launchBrowser({ executablePath: fake, port: 23495, launchTimeoutMs: 3000 }),
-    ).rejects.toThrow(/Chrome failed to start on port 23495/);
+      launchBrowser({ executablePath: fake, port, launchTimeoutMs: 10_000 }),
+    ).rejects.toThrow(`Chrome failed to start on port ${port}: `);
     // Without a child 'error' listener, this used to depend entirely on
     // whether something outside this function happened to intercept the
     // resulting uncaught exception (a bare node:test process has nothing
     // that does — see the module doc comment); where it happened not to
     // crash the process outright, the promise still only ever settled by
     // burning the full launchTimeoutMs. The fix rejects as soon as the
-    // spawn error fires, so this must land in well under a second, not
-    // ride the 3000ms timeout out.
-    expect(Date.now() - start).toBeLessThan(1000);
-  }, 8000);
+    // spawn error fires, so this must land well inside the 10s timeout
+    // rather than ride it out — with room for a loaded machine.
+    expect(Date.now() - start).toBeLessThan(5000);
+  }, 20_000);
 
   it('rejects with a clear message when Chrome exits immediately instead of opening its CDP port', async () => {
     vi.resetModules();
@@ -140,18 +161,19 @@ describe('#314: launchBrowser settles instead of hanging when Chrome fails to st
     const fake = join(tempDir, 'chrome.sh');
     writeFileSync(fake, '#!/bin/sh\nexit 1\n');
     chmodSync(fake, 0o755);
+    const port = await freePort();
 
     await expect(
-      launchBrowser({ executablePath: fake, port: 23496, launchTimeoutMs: 3000 }),
-    ).rejects.toThrow(/Chrome exited before the CDP endpoint opened on port 23496/);
-  }, 8000);
+      launchBrowser({ executablePath: fake, port, launchTimeoutMs: 10_000 }),
+    ).rejects.toThrow(`Chrome exited before the CDP endpoint opened on port ${port} `);
+  }, 20_000);
 });
 
 describe('#314: closeBrowser settles under the real event loop, not fake timers', () => {
   it('resolves promptly when nothing else is pinning the event loop', async () => {
     vi.resetModules();
     const { closeBrowser } = await import('../browser/browser.js');
-    const port = 23497;
+    const port = await freePort();
 
     // A real, short-lived child — not Chrome, just something with a genuine,
     // observable exit so process.kill(pid, 0) behaves for real and there is

package/src/browser/browser.ts

@@ -1,4 +1,5 @@
 import { execSync, spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { connect } from 'node:net';
 import { tmpdir } from 'node:os';
@@ -92,18 +93,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';
   }
 }
 
@@ -249,19 +259,27 @@ function readDevToolsActivePort(file: string): number | null {
  * 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.
+ *
+ * A fixed port needs its own proof, since Chrome writes DevToolsActivePort
+ * only for port 0. Once listening, Chrome prints `DevTools listening on
+ * ws://…/devtools/browser/<id>` to stderr, and `<id>` is unique to that
+ * browser process, the same one `/json/version` reports. An endpoint is
+ * adopted only when it reports the id our own child printed. Without that
+ * check, a launch whose Chrome was still booting found a concurrent
+ * launch's Chrome on the shared port and returned it, recording its own
+ * doomed pid there. It also covers Chrome's [::1] fallback described above.
  */
 async function launchOnFreePort(config: BrowserConfig, port: number): Promise<number> {
   const chromePath = findChrome(config.executablePath);
-  // 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.
+  // Unique per launch, not just per port and 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) would
+  // otherwise share one profile directory (lock files, preferences, the
+  // DevToolsActivePort file itself) — including two launches from the same
+  // process, where a pid suffix alone is identical.
   const userDataDir =
-    config.userDataDir ?? join(tmpdir(), `monomind-browser-${port}-${process.pid}`);
+    config.userDataDir ??
+    join(tmpdir(), `monomind-browser-${port}-${process.pid}-${randomUUID().slice(0, 8)}`);
   const activePortFile = join(userDataDir, 'DevToolsActivePort');
   // A reused profile dir may hold a previous run's file naming a port some
   // other process now owns.
@@ -308,8 +326,26 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
   const args = [...defaultArgs, ...callerArgs];
   const child = spawn(chromePath, args, {
     detached: true,
-    stdio: 'ignore',
+    // stderr carries the fixed-port ownership proof (see above). The pipe is
+    // closed as soon as this launch settles, so a Chrome that outlives us
+    // never blocks writing to it.
+    stdio: port === 0 ? 'ignore' : ['ignore', 'ignore', 'pipe'],
   });
+  let announcedBrowserId: string | null = null;
+  if (child.stderr) {
+    let stderrTail = '';
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk: string) => {
+      if (announcedBrowserId) return;
+      stderrTail = (stderrTail + chunk).slice(-4096);
+      announcedBrowserId = browserIdOf(
+        /DevTools listening on (ws:\/\/\S+)\r?\n/.exec(stderrTail)?.[1],
+      );
+    });
+    child.stderr.on('error', () => {
+      /* closed under us — nothing to read */
+    });
+  }
 
   // Without this, a spawn failure (e.g. EACCES/ENOENT — chromePath exists per
   // findChrome()'s existsSync check but isn't actually executable, or is
@@ -353,51 +389,94 @@ 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.
 
+  // 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 */
+    }
+  };
+
+  // Our own Chrome, not just some Chrome, is serving `boundPort`. For port 0
+  // the port came from our own profile's DevToolsActivePort, so it is.
+  const isOwnEndpoint = async (boundPort: number): Promise<boolean> => {
+    if (port === 0) return true;
+    if (!announcedBrowserId) return false;
+    const wsUrl = await fetchBrowserWebSocketUrl(boundPort).catch(() => null);
+    return browserIdOf(wsUrl ?? undefined) === announcedBrowserId;
+  };
+
   const launchTimeout = config.launchTimeoutMs ?? LAUNCH_TIMEOUT;
   const deadline = Date.now() + launchTimeout;
-  while (Date.now() < deadline) {
-    if (earlyFailure) throw earlyFailure;
-    await sleep(POLL_INTERVAL);
-    if (earlyFailure) throw earlyFailure;
-    const boundPort = port === 0 ? readDevToolsActivePort(activePortFile) : port;
-    if (boundPort !== null && (await isPortOpen(boundPort))) {
-      if (await isChromeIdentity(boundPort)) {
-        track(boundPort);
-        return boundPort;
+  try {
+    while (Date.now() < deadline) {
+      if (earlyFailure) throw earlyFailure;
+      await sleep(POLL_INTERVAL);
+      if (earlyFailure) throw earlyFailure;
+      const boundPort = port === 0 ? readDevToolsActivePort(activePortFile) : port;
+      if (boundPort !== null && (await isPortOpen(boundPort))) {
+        const identity = await chromeIdentity(boundPort);
+        if (identity === 'chrome') {
+          if (await isOwnEndpoint(boundPort)) {
+            track(boundPort);
+            return boundPort;
+          }
+          // Some Chrome answers on the port, but not the one we started: a
+          // concurrent launch's, or ours before its stderr line arrived. Our
+          // child exiting (it lost the bind) or the deadline decides.
+          continue;
+        }
+        // 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;
+        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}.`,
+        );
       }
+    }
+
+    if (earlyFailure) throw earlyFailure;
+    killUntracked();
+
+    if (port === 0) {
       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}.`,
+        `Chrome did not report a CDP port in ${activePortFile} within ${launchTimeout}ms`,
       );
     }
-  }
 
-  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 */
+    // Timed out waiting for our Chrome to come up on the port. Distinguish
+    // "another Chrome holds it", "nothing is listening" (real launch failure)
+    // and "something non-CDP is squatting the port" (confusing generic
+    // timeout otherwise).
+    if (await isChromeIdentity(port)) {
+      throw new Error(
+        `Port ${port} is held by a Chrome/Chromium this launch did not start (a concurrent launch took it).`,
+      );
+    }
+    if (await isTcpPortOpen(port)) {
+      throw new Error(
+        `Port ${port} is occupied by a non-Chrome process (TCP connection succeeds but no CDP response within ${launchTimeout}ms). ` +
+          `Free the port or pass a different one.`,
+      );
     }
-    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.
-  if (await isTcpPortOpen(port)) {
-    throw new Error(
-      `Port ${port} is occupied by a non-Chrome process (TCP connection succeeds but no CDP response within ${launchTimeout}ms). ` +
-        `Free the port or pass a different one.`,
-    );
+    throw new Error(`Chrome failed to start on port ${port} within ${launchTimeout}ms`);
+  } finally {
+    child.stderr?.destroy();
   }
+}
 
-  throw new Error(`Chrome failed to start on port ${port} within ${launchTimeout}ms`);
+/** The per-process id in a browser-level CDP websocket URL
+ *  (`ws://host:port/devtools/browser/<id>`), or null. */
+function browserIdOf(wsUrl: string | undefined): string | null {
+  return wsUrl?.match(/\/devtools\/browser\/([^/?#\s]+)/)?.[1] ?? null;
 }
 
 export async function enableSessionDomains(client: CdpClient, sessionId: string): Promise<void> {