@rezkam/browser-tools 1.0.3 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,6 @@
1
1
  import { createHash, randomUUID } from 'node:crypto';
2
2
  import { spawn, spawnSync } from 'node:child_process';
3
+ import { createConnection } from 'node:net';
3
4
  import {
4
5
  accessSync,
5
6
  chmodSync,
@@ -16,13 +17,16 @@ import { homedir, tmpdir } from 'node:os';
16
17
  import { delimiter, dirname, join, resolve } from 'node:path';
17
18
  import { fileURLToPath } from 'node:url';
18
19
  import puppeteer from 'puppeteer-core';
20
+ import WebSocket from 'ws';
21
+ import { discoverChromeBinary, discoverChromeSourceDir, chromePlatformToken } from './browser-platform.mjs';
19
22
 
20
23
  export const DEFAULT_PORT = 9222;
21
24
  export const CONNECT_PROBE_TIMEOUT_MS = 3000;
25
+ export const PORT_OCCUPANCY_PROBE_TIMEOUT_MS = 250;
22
26
  export const CHROME_READY_TIMEOUT_MS = 15000;
23
27
  export const CHROME_READY_PROBE_TIMEOUT_MS = 250;
24
- export const DEFAULT_CHROME_BIN = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
25
- export const DEFAULT_CHROME_SRC = join(homedir(), 'Library', 'Application Support', 'Google', 'Chrome');
28
+ export const DEFAULT_CHROME_BIN = discoverChromeBinary() || (process.platform === 'linux' ? 'google-chrome' : '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome');
29
+ export const DEFAULT_CHROME_SRC = discoverChromeSourceDir({ chromeBin: DEFAULT_CHROME_BIN }) || join(homedir(), '.config', 'google-chrome');
26
30
  export const DEFAULT_CACHE_DIR = join(homedir(), '.cache', 'pi-browser-tools');
27
31
  export const DEFAULT_ARTIFACT_DIR = tmpdir();
28
32
 
@@ -49,7 +53,7 @@ export const MAX_BROWSERS_ENV = 'BROWSER_TOOLS_MAX_BROWSERS';
49
53
  // A managed browser older than this is almost certainly a leftover from a finished agent session.
50
54
  export const STALE_BROWSER_AGE_MS = 2 * 60 * 60 * 1000;
51
55
  export const PENDING_BROWSER_STATE_MAX_AGE_MS = 5000;
52
- export const REAP_HINT = 'Run scripts/stop.mjs --reap to sweep managed browsers that no lifecycle file accounts for.';
56
+ export const REAP_HINT = 'Run scripts/stop.mjs --reap to sweep reclaimable managed browsers whose lifecycle tracking or launcher lease has expired.';
53
57
 
54
58
  export function agentConfigRoot() {
55
59
  return process.env.AGENT_CONFIG_DIR || join(homedir(), '.agents');
@@ -82,11 +86,12 @@ export function expandHomePath(value) {
82
86
  export function browserToolsRuntimeConfig({ configDir = browserToolsConfigDir() } = {}) {
83
87
  const effectiveConfigDir = resolveBrowserToolsConfigDir(configDir);
84
88
  const config = safeReadJson(browserToolsConfigFile(effectiveConfigDir)) || {};
89
+ const chromeBin = expandHomePath(process.env.BROWSER_TOOLS_CHROME_BIN || config.browser?.chromeBin || config.chromeBin || discoverChromeBinary() || DEFAULT_CHROME_BIN);
85
90
  return {
86
91
  configDir: effectiveConfigDir,
87
92
  configFile: browserToolsConfigFile(effectiveConfigDir),
88
- chromeBin: expandHomePath(process.env.BROWSER_TOOLS_CHROME_BIN || config.browser?.chromeBin || config.chromeBin || DEFAULT_CHROME_BIN),
89
- chromeSourceDir: expandHomePath(process.env.BROWSER_TOOLS_CHROME_SOURCE_DIR || config.directories?.chromeSourceDir || config.sourceDir || DEFAULT_CHROME_SRC),
93
+ chromeBin,
94
+ chromeSourceDir: expandHomePath(process.env.BROWSER_TOOLS_CHROME_SOURCE_DIR || config.directories?.chromeSourceDir || config.sourceDir || discoverChromeSourceDir({ chromeBin }) || DEFAULT_CHROME_SRC),
90
95
  cacheDir: expandHomePath(process.env.BROWSER_TOOLS_CACHE_DIR || config.directories?.cacheDir || DEFAULT_CACHE_DIR),
91
96
  artifactDir: expandHomePath(process.env.BROWSER_TOOLS_ARTIFACT_DIR || config.directories?.artifactDir || DEFAULT_ARTIFACT_DIR),
92
97
  maxBrowsers: config.browser?.maxBrowsers ?? config.maxBrowsers ?? null,
@@ -377,7 +382,7 @@ export async function browserWSEndpoint(port = DEFAULT_PORT, timeoutMs = CONNECT
377
382
  const controller = new AbortController();
378
383
  const timer = setTimeout(() => controller.abort(), timeoutMs);
379
384
  try {
380
- const res = await fetch(`http://localhost:${normalizedPort}/json/version`, { signal: controller.signal });
385
+ const res = await fetch(`http://127.0.0.1:${normalizedPort}/json/version`, { signal: controller.signal });
381
386
  if (!res.ok) return null;
382
387
  const data = await res.json();
383
388
  return data.webSocketDebuggerUrl ?? null;
@@ -388,18 +393,114 @@ export async function browserWSEndpoint(port = DEFAULT_PORT, timeoutMs = CONNECT
388
393
  }
389
394
  }
390
395
 
391
- export async function waitForChromeReady(
396
+ /**
397
+ * Detect any local listener, not just a responsive CDP endpoint. A normal Chrome
398
+ * can occupy the preferred debugging port without exposing a usable
399
+ * /json/version response, and launching against that port otherwise fails only
400
+ * after the full readiness timeout. Unexpected probe errors are treated as
401
+ * occupied so an uncertain port is never handed to Chrome.
402
+ */
403
+ function tcpListenerOnHost(port, host, timeoutMs) {
404
+ return new Promise((resolvePromise) => {
405
+ const socket = createConnection({ host, port });
406
+ let settled = false;
407
+ const finish = (occupied) => {
408
+ if (settled) return;
409
+ settled = true;
410
+ socket.destroy();
411
+ resolvePromise(occupied);
412
+ };
413
+ socket.once('connect', () => finish(true));
414
+ socket.once('error', (error) => {
415
+ const code = error && typeof error === 'object' ? error.code : undefined;
416
+ finish(!['ECONNREFUSED', 'EHOSTUNREACH', 'ENETUNREACH', 'EADDRNOTAVAIL', 'EAFNOSUPPORT', 'EPROTONOSUPPORT', 'ENOTSUP'].includes(code));
417
+ });
418
+ socket.setTimeout(timeoutMs, () => finish(true));
419
+ });
420
+ }
421
+
422
+ export async function isPortOccupied(port = DEFAULT_PORT, timeoutMs = PORT_OCCUPANCY_PROBE_TIMEOUT_MS) {
423
+ const normalizedPort = normalizePort(port);
424
+ const [ipv4, ipv6] = await Promise.all([
425
+ tcpListenerOnHost(normalizedPort, '127.0.0.1', timeoutMs),
426
+ tcpListenerOnHost(normalizedPort, '::1', timeoutMs),
427
+ ]);
428
+ return ipv4 || ipv6;
429
+ }
430
+
431
+ export function devToolsActivePortMatches(userDataDir, endpoint) {
432
+ if (!userDataDir || !endpoint) return false;
433
+ try {
434
+ const url = new URL(endpoint);
435
+ const activePortFile = readFileSync(join(userDataDir, 'DevToolsActivePort'), 'utf8').trim().split(/\r?\n/);
436
+ const endpointPort = url.port || (url.protocol === 'ws:' ? '80' : url.protocol === 'wss:' ? '443' : '');
437
+ return activePortFile[0] === endpointPort && activePortFile[1] === url.pathname;
438
+ } catch {
439
+ return false;
440
+ }
441
+ }
442
+
443
+ // Fixed-port Chromium need not write DevToolsActivePort. A loopback URL alone is
444
+ // not ownership proof: ask the endpoint for its actual browser launch arguments.
445
+ export async function launchedEndpointMatches({ port, endpoint, state, timeoutMs = 3000 }) {
446
+ let url;
447
+ try { url = new URL(endpoint); } catch { return false; }
448
+ if (url.hash || url.username || url.password || url.protocol !== 'ws:' || !['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)
449
+ || Number(url.port) !== Number(port) || !url.pathname.startsWith('/devtools/browser/')) return false;
450
+ if (devToolsActivePortMatches(state?.userDataDir, endpoint)) return true;
451
+ if (!state?.managedToken || !state?.userDataDir) return false;
452
+ return new Promise((resolve) => {
453
+ let socket;
454
+ try { socket = new WebSocket(endpoint, { followRedirects: false, handshakeTimeout: timeoutMs, maxPayload: 1024 * 1024 }); }
455
+ catch { resolve(false); return; }
456
+ let settled = false;
457
+ const finish = (ok) => {
458
+ if (settled) return;
459
+ settled = true;
460
+ clearTimeout(timer);
461
+ socket.terminate();
462
+ resolve(ok);
463
+ };
464
+ const timer = setTimeout(() => finish(false), timeoutMs);
465
+ socket.on('error', () => finish(false));
466
+ socket.on('close', () => finish(false));
467
+ socket.on('open', () => socket.send(JSON.stringify({ id: 1, method: 'Browser.getBrowserCommandLine' })));
468
+ socket.on('message', (data) => {
469
+ try {
470
+ const message = JSON.parse(data.toString());
471
+ if (message.id !== 1) return;
472
+ const args = message.result?.arguments;
473
+ finish(Array.isArray(args) && [
474
+ '--enable-automation',
475
+ '--remote-debugging-port=' + port,
476
+ '--user-data-dir=' + state.userDataDir,
477
+ '--pi-browser-tools-managed=' + state.managedToken,
478
+ ].every(arg => args.includes(arg)));
479
+ } catch { finish(false); }
480
+ });
481
+ });
482
+ }
483
+
484
+ export async function waitForChromeEndpoint(
392
485
  port = DEFAULT_PORT,
393
486
  { timeoutMs = CHROME_READY_TIMEOUT_MS, intervalMs = 250, probeTimeoutMs = CHROME_READY_PROBE_TIMEOUT_MS } = {},
394
487
  ) {
395
488
  const deadline = Date.now() + timeoutMs;
396
489
  while (Date.now() < deadline) {
397
490
  const remainingMs = Math.max(1, deadline - Date.now());
398
- if (await browserWSEndpoint(port, Math.min(probeTimeoutMs, remainingMs))) return true;
491
+ const endpoint = await browserWSEndpoint(port, Math.min(probeTimeoutMs, remainingMs));
492
+ if (endpoint) return endpoint;
399
493
  const sleepMs = Math.min(intervalMs, Math.max(0, deadline - Date.now()));
400
494
  if (sleepMs > 0) await sleep(sleepMs);
401
495
  }
402
- return false;
496
+ return null;
497
+ }
498
+
499
+ export async function waitForChromeReady(
500
+ port = DEFAULT_PORT,
501
+ options = {},
502
+ ) {
503
+ return Boolean(await waitForChromeEndpoint(port, options));
403
504
  }
404
505
 
405
506
  export function profileCopyReady(profileName, profileDataDir = profileDataDirForPort()) {
@@ -764,6 +865,7 @@ export function syncChromeProfile(profileName, { force = false, port = DEFAULT_P
764
865
  const cachedMatches = cachedState
765
866
  && typeof cachedState.includeGoogle === 'boolean'
766
867
  && cachedState.includeGoogle === includeGoogle
868
+ && cachedState.sourceDir && resolve(cachedState.sourceDir) === resolve(sourceDir)
767
869
  && (includeGoogle || cachedState.googleStripOk === true);
768
870
  if (!force && cachedMatches && profileCopyReady(profileName, destDir)) {
769
871
  removeChromeProfileLocks(destDir);
@@ -773,11 +875,12 @@ export function syncChromeProfile(profileName, { force = false, port = DEFAULT_P
773
875
  const commands = profileSyncRsyncCommands(profileName, { sourceDir, destDir, checkExists: true });
774
876
 
775
877
  rmSync(destDir, { recursive: true, force: true });
776
- mkdirSync(destDir, { recursive: true });
878
+ mkdirSync(destDir, { recursive: true, mode: 0o700 });
879
+ chmodSync(destDir, 0o700);
777
880
  const results = [];
778
881
  const copiedItems = [];
779
882
  for (const command of commands) {
780
- mkdirSync(command.dest, { recursive: true });
883
+ mkdirSync(command.dest, { recursive: true, mode: 0o700 });
781
884
  const result = spawnSync('rsync', command.args, { stdio: 'inherit' });
782
885
  if (result.error) throw result.error;
783
886
  if (result.signal) throw new Error(`rsync failed for ${command.item}: terminated by signal ${result.signal}`);
@@ -911,6 +1014,8 @@ export function chromeLaunchArgs({ port = DEFAULT_PORT, profileName = null, mana
911
1014
  const args = [
912
1015
  `--remote-debugging-port=${normalizedPort}`,
913
1016
  `--user-data-dir=${launchUserDataDir}`,
1017
+ '--remote-debugging-address=127.0.0.1',
1018
+ '--enable-automation',
914
1019
  '--no-first-run',
915
1020
  '--no-default-browser-check',
916
1021
  '--disable-sync',
@@ -943,7 +1048,7 @@ export function detectChromeMajorVersion(chromeBin = browserToolsChromeBin()) {
943
1048
  // so this matches what a windowed macOS Chrome sends. It carries no machine-specific data.
944
1049
  export function chromeUserAgentForMajor(major) {
945
1050
  if (!Number.isInteger(major) || major < 1) return null;
946
- return `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${major}.0.0.0 Safari/537.36`;
1051
+ return `Mozilla/5.0 (${chromePlatformToken()}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${major}.0.0.0 Safari/537.36`;
947
1052
  }
948
1053
 
949
1054
  export function headlessUserAgent(chromeBin = browserToolsChromeBin()) {
@@ -1077,7 +1182,7 @@ export function managedBrowserIdentityMatches(expected, current) {
1077
1182
  export function verifyManagedChromePid(pid, { cacheDir = browserToolsCacheDir(), chromeBin = browserToolsChromeBin() } = {}) {
1078
1183
  const command = commandForPid(pid);
1079
1184
  if (!command) return null;
1080
- return managedChromeProcessFromCommand({ pid, command, cacheDir, chromeBin });
1185
+ return managedChromeProcessFromCommand({ pid, command: command.replaceAll('\0', ' ').trim(), cacheDir, chromeBin });
1081
1186
  }
1082
1187
 
1083
1188
  // The live inventory of managed browsers. This reads the process table rather than the lifecycle
@@ -1212,6 +1317,21 @@ export function staleManagedBrowsers(processes = listManagedChromeProcesses(), {
1212
1317
  return processes.filter((entry) => Number.isFinite(entry.ageMs) && entry.ageMs >= maxAgeMs);
1213
1318
  }
1214
1319
 
1320
+ function managedBrowserLauncherIsActive(state) {
1321
+ const launcherPid = Number(state?.launchedByPid);
1322
+ if (!Number.isInteger(launcherPid) || launcherPid < 1) return false;
1323
+ const recordedIdentity = typeof state?.launchedByProcessStartIdentity === 'string'
1324
+ ? state.launchedByProcessStartIdentity
1325
+ : null;
1326
+ if (!recordedIdentity) return processExists(launcherPid);
1327
+
1328
+ const currentIdentity = processStartIdentity(launcherPid);
1329
+ if (currentIdentity) return currentIdentity === recordedIdentity;
1330
+ // A transient process-table read failure must fail closed. Only consider the launcher gone when
1331
+ // the independent process existence check agrees that the PID no longer exists.
1332
+ return processExists(launcherPid);
1333
+ }
1334
+
1215
1335
  function readManagedPid(pidFile) {
1216
1336
  try {
1217
1337
  const pid = Number.parseInt(readFileSync(pidFile, 'utf-8').trim(), 10);
@@ -1221,8 +1341,8 @@ function readManagedPid(pidFile) {
1221
1341
  }
1222
1342
  }
1223
1343
 
1224
- // A managed browser whose lifecycle files no longer describe it. `stop --port N` cannot reach these,
1225
- // so they would otherwise accumulate forever.
1344
+ // Managed browsers the reaper may safely reclaim. This includes browsers whose lifecycle files no
1345
+ // longer describe them, unowned browsers, and old browsers whose recorded launcher has exited.
1226
1346
  export function orphanedManagedBrowsers(processes = listManagedChromeProcesses()) {
1227
1347
  return processes.filter((entry) => {
1228
1348
  // A concurrent start holds the port lock from before the spawn until the readiness probe passes,
@@ -1245,6 +1365,13 @@ export function orphanedManagedBrowsers(processes = listManagedChromeProcesses()
1245
1365
  // An unowned browser is tracked but unreachable: its owner token lives only in the caller that
1246
1366
  // started it, so once that process exits nothing can adopt or stop it. Reclaim it as garbage.
1247
1367
  if (!normalizeOwnerValue(state.ownerId)) return true;
1368
+ // Ownership cannot make a leaked browser immortal. Once the browser is old enough to be stale
1369
+ // and the process that launched it is gone, no live owner process remains to close it.
1370
+ if (
1371
+ Number.isFinite(entry.ageMs) &&
1372
+ entry.ageMs >= STALE_BROWSER_AGE_MS &&
1373
+ !managedBrowserLauncherIsActive(state)
1374
+ ) return true;
1248
1375
  return false;
1249
1376
  });
1250
1377
  }
@@ -1253,9 +1380,9 @@ export function forcedKillStatus(exited) {
1253
1380
  return exited ? 'killed' : 'failed';
1254
1381
  }
1255
1382
 
1256
- // Kill managed browsers that no lifecycle file accounts for, then drop their leftover clone dirs.
1257
- // Safe by construction: every target came from parseManagedChromeProcesses, so it carries our
1258
- // managed token and a user-data-dir inside our cache dir.
1383
+ // Kill reclaimable managed browsers. Safe by construction: every target came from
1384
+ // parseManagedChromeProcesses, so it carries our managed token and a user-data-dir inside our cache
1385
+ // dir. Old tracked browsers are eligible only after their launcher exits and the grace period ends.
1259
1386
  export function reapOrphanedChromes({ dryRun = false, processes = listManagedChromeProcesses() } = {}) {
1260
1387
  const orphans = orphanedManagedBrowsers(processes);
1261
1388
  const reaped = [];
@@ -1312,7 +1439,7 @@ function describeBrowserInventory(processes, { limit = 10, staleMaxAgeMs = STALE
1312
1439
  const lines = processes.slice(0, limit).map((entry) => {
1313
1440
  const stale = Number.isFinite(entry.ageMs) && entry.ageMs >= staleMaxAgeMs;
1314
1441
  const pid = Number.isInteger(Number(entry.pid)) ? `PID ${entry.pid}` : 'PID unknown';
1315
- return ` :${entry.port} ${pid} up ${formatBrowserAge(entry.ageMs)}${stale ? ' <- idle over 2h, likely a leftover' : ''}`;
1442
+ return ` :${entry.port} ${pid} up ${formatBrowserAge(entry.ageMs)}${stale ? ' <- running over 2h, likely a leftover' : ''}`;
1316
1443
  });
1317
1444
  if (processes.length > limit) lines.push(` ... and ${processes.length - limit} more`);
1318
1445
  return lines.join('\n');
@@ -1335,7 +1462,7 @@ export function assertManagedBrowserCapacity({ processes = listManagedChromeProc
1335
1462
  staleLine +
1336
1463
  `\n To continue, do one of these:\n` +
1337
1464
  ` scripts/stop.mjs --status see this list again at any time\n` +
1338
- ` scripts/stop.mjs --reap --dry-run preview browsers no lifecycle file tracks\n` +
1465
+ ` scripts/stop.mjs --reap --dry-run preview reclaimable leaked browsers\n` +
1339
1466
  ` scripts/stop.mjs --prune reap those, then drop their unused clones\n` +
1340
1467
  ` scripts/stop.mjs --port <n> --owner-token "$${OWNER_TOKEN_ENV}" stop one you own\n\n` +
1341
1468
  ` Best fix if these are yours: export ${OWNER_TOKEN_ENV} from the first start, and later\n` +
@@ -1366,7 +1493,8 @@ export function managedBrowserStartupWarnings({
1366
1493
  `${stale.length} managed browser${stale.length === 1 ? '' : 's'} ${stale.length === 1 ? 'has' : 'have'} been running over ${hours}h ` +
1367
1494
  `(${describePorts(stale)}), likely left over from a finished session. ` +
1368
1495
  `Stop a tracked browser with scripts/stop.mjs --port <n> --owner-token "$${OWNER_TOKEN_ENV}". ` +
1369
- `Use scripts/stop.mjs --reap --dry-run and scripts/stop.mjs --prune only for untracked browsers.`,
1496
+ `Old sessions whose launcher has exited are reclaimed automatically by the next start. ` +
1497
+ `Use scripts/stop.mjs --reap --dry-run to preview all reclaimable sessions.`,
1370
1498
  );
1371
1499
  }
1372
1500
  return warnings;
@@ -1397,6 +1525,7 @@ export function managedBrowserReuseDecision({
1397
1525
  // Adopting a browser built from a different profile (or a fresh, signed-out clone) would run the
1398
1526
  // caller's automation against the wrong account.
1399
1527
  if ((state?.profileName || null) !== (profileName || null)) return fail('profile-mismatch');
1528
+ if (profileName && (!state.profileSourceDir || resolve(state.profileSourceDir) !== resolve(browserToolsChromeSourceDir()))) return fail('profile-source-mismatch');
1400
1529
  // Headless is fixed at launch, so a windowed request cannot be served by a headless browser.
1401
1530
  if (Boolean(state?.headless) !== Boolean(headless)) return fail('headless-mismatch');
1402
1531
  return { ok: true, ownerId: ownership.ownerId, state };
@@ -1496,7 +1625,14 @@ export function launchChrome({ port = DEFAULT_PORT, profileName = null, userData
1496
1625
  const chromeBin = browserToolsChromeBin();
1497
1626
  const userAgent = headless ? headlessUserAgent(chromeBin) : null;
1498
1627
  const args = chromeLaunchArgs({ port: normalizedPort, profileName, managedToken, userDataDir: launchUserDataDir, headless, userAgent });
1628
+ // A stale marker must not make a later launch appear to own a competing endpoint.
1629
+ rmSync(join(launchUserDataDir, 'DevToolsActivePort'), { force: true });
1499
1630
  assertChromeBinaryLaunchable(chromeBin);
1631
+ if (process.platform === 'linux' && !headless && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) {
1632
+ throw new Error('No Linux display found. Pass --headless (API: headless: true), or provide a working DISPLAY/WAYLAND_DISPLAY.');
1633
+ }
1634
+ mkdirSync(launchUserDataDir, { recursive: true, mode: 0o700 });
1635
+ chmodSync(launchUserDataDir, 0o700);
1500
1636
  const pidFile = pidFileForPort(normalizedPort);
1501
1637
  const stateFile = stateFileForPort(normalizedPort);
1502
1638
  let proc = headless ? launchHeadlessChromeApp({ chromeBin, args }) : null;
@@ -1521,6 +1657,7 @@ export function launchChrome({ port = DEFAULT_PORT, profileName = null, userData
1521
1657
  pid: proc.pid,
1522
1658
  port: normalizedPort,
1523
1659
  profileName: profileName || null,
1660
+ profileSourceDir: profileName ? browserToolsChromeSourceDir() : null,
1524
1661
  userDataDir: launchUserDataDir,
1525
1662
  headless: Boolean(headless),
1526
1663
  includeGoogle: Boolean(includeGoogle),
@@ -1528,6 +1665,9 @@ export function launchChrome({ port = DEFAULT_PORT, profileName = null, userData
1528
1665
  ...buildOwnerState({ ownerToken: effectiveOwnerToken, ownerId }),
1529
1666
  // Who launched this browser, so a leaked one is attributable instead of anonymous.
1530
1667
  launchedByPid: process.pid,
1668
+ // The PID can be reused after the launcher exits. Record its start identity so a different
1669
+ // process inheriting the same number cannot keep an expired browser lease alive.
1670
+ launchedByProcessStartIdentity: processStartIdentity(process.pid),
1531
1671
  args,
1532
1672
  startedAt: new Date().toISOString(),
1533
1673
  }, null, 2));
@@ -1544,6 +1684,7 @@ export async function findAvailablePort(startPort = DEFAULT_PORT, { maxAttempts
1544
1684
  cleanupStaleManagedStateForPort(port);
1545
1685
  if (
1546
1686
  !(await browserWSEndpoint(port)) &&
1687
+ !(await isPortOccupied(port)) &&
1547
1688
  !existsSync(stateFileForPort(port)) &&
1548
1689
  !existsSync(pidFileForPort(port))
1549
1690
  ) return port;
@@ -1580,11 +1721,11 @@ export async function startChrome({
1580
1721
  const { requestedProfileName, resolvedProfileName } = resolveStartProfileName({ profileName, taskName, defaultProfileName });
1581
1722
  ensureCacheDir();
1582
1723
 
1583
- // Clean up before counting, so the cap reflects browsers that are actually reachable. Orphans are
1584
- // browsers no lifecycle file tracks: nothing can address or stop them, so they are pure garbage.
1724
+ // Clean up before counting, so the cap reflects browsers that are still actively owned. Untracked
1725
+ // browsers and old browsers whose launcher has exited are safe to reclaim before reserving a slot.
1585
1726
  const reaped = reapOrphanedChromes();
1586
1727
  if (reaped.reaped.length) {
1587
- console.error(`⟳ Reaped ${reaped.reaped.length} untracked managed browser${reaped.reaped.length === 1 ? '' : 's'} (${describePorts(reaped.reaped)})`);
1728
+ console.error(`⟳ Reaped ${reaped.reaped.length} reclaimable managed browser${reaped.reaped.length === 1 ? '' : 's'} (${describePorts(reaped.reaped)})`);
1588
1729
  try {
1589
1730
  pruneChromeClones({ keepPorts: [normalizedPort] });
1590
1731
  } catch {
@@ -1606,7 +1747,8 @@ export async function startChrome({
1606
1747
  ownerToken: providedOwnerToken, includeGoogle, processes: candidates,
1607
1748
  profileName: resolvedProfileName, headless, forceProfileSync,
1608
1749
  });
1609
- if (found && await browserWSEndpoint(found.port)) {
1750
+ const foundEndpoint = found ? await browserWSEndpoint(found.port) : null;
1751
+ if (found && foundEndpoint) {
1610
1752
  reusable = found;
1611
1753
  normalizedPort = found.port;
1612
1754
  }
@@ -1627,7 +1769,21 @@ export async function startChrome({
1627
1769
  try {
1628
1770
  cleanupStaleManagedStateForPort(normalizedPort);
1629
1771
 
1630
- if (await browserWSEndpoint(normalizedPort)) {
1772
+ const endpoint = await browserWSEndpoint(normalizedPort);
1773
+ const occupied = !endpoint && await isPortOccupied(normalizedPort);
1774
+ if (endpoint || occupied) {
1775
+ // A non-CDP listener is never an adoption candidate, even if stale
1776
+ // managed state happens to match this port and owner token.
1777
+ if (occupied) {
1778
+ if (!autoAllocatePort) {
1779
+ throw new Error(
1780
+ `Port :${normalizedPort} is already in use, but it is not a Browser Tools managed browser. Use a different --port or stop that listener manually.`,
1781
+ );
1782
+ }
1783
+ assertManagedBrowserCapacity();
1784
+ normalizedPort = await findAvailablePort(normalizedPort + 1);
1785
+ continue;
1786
+ }
1631
1787
  const safety = managedBrowserSafetyForPort(normalizedPort);
1632
1788
  const state = readManagedStateForPort(normalizedPort);
1633
1789
  const reuse = managedBrowserReuseDecision({
@@ -1660,6 +1816,9 @@ export async function startChrome({
1660
1816
  }
1661
1817
  // A configuration mismatch is not an ownership problem: the caller owns this browser, it
1662
1818
  // was just built differently. Say so, rather than sending them to look for a token.
1819
+ if (reuse.reason === 'profile-source-mismatch') {
1820
+ throw new Error('Managed Chrome profile source differs or was not recorded by this version. Stop it with the owner token and --clean, then restart for the requested source profile.');
1821
+ }
1663
1822
  if (reuse.reason === 'profile-mismatch') {
1664
1823
  throw new Error(
1665
1824
  `Chrome on :${normalizedPort} was started with profile ${state?.profileName ? `"${state.profileName}"` : '(fresh, no profile)'}, but this start requested ${resolvedProfileName ? `"${resolvedProfileName}"` : '(fresh, no profile)'}. Reusing it would run against the wrong account. Stop it with scripts/stop.mjs --clean and start again, or pick a different --port.`,
@@ -1812,10 +1971,18 @@ export async function startChrome({
1812
1971
  ownerTokenGenerated: false,
1813
1972
  };
1814
1973
  }
1815
- const ready = await waitForChromeReady(normalizedPort, { timeoutMs: CHROME_READY_TIMEOUT_MS });
1816
- if (!ready) {
1974
+ const launchedEndpoint = await waitForChromeEndpoint(normalizedPort, { timeoutMs: CHROME_READY_TIMEOUT_MS });
1975
+ if (!launchedEndpoint) {
1817
1976
  stopChrome({ port: normalizedPort, ownerToken: effectiveOwnerToken, ignorePortLock: true });
1818
- throw new Error(`Failed to connect to Chrome after ${Math.round(CHROME_READY_TIMEOUT_MS / 1000)}s`);
1977
+ throw new Error(`Failed to connect to Chrome after ${Math.round(CHROME_READY_TIMEOUT_MS / 1000)}s. Check the executable, Linux sandbox/user-namespace policy, display (or --headless), and profile permissions. Snap confinement may require BROWSER_TOOLS_CACHE_DIR and BROWSER_TOOLS_ARTIFACT_DIR inside its accessible directories. Browser Tools never disables the sandbox automatically.`);
1978
+ }
1979
+ const launchedState = readManagedStateForPort(normalizedPort);
1980
+ const launchedSafety = managedBrowserSafetyForPort(normalizedPort);
1981
+ if (!launchedSafety.ok || Number(launchedState?.pid) !== Number(proc?.pid) || !await launchedEndpointMatches({ port: normalizedPort, endpoint: launchedEndpoint, state: launchedState })) {
1982
+ stopChrome({ port: normalizedPort, ownerToken: effectiveOwnerToken, ignorePortLock: true });
1983
+ throw new Error(
1984
+ `Chrome reported ready on :${normalizedPort}, but the responding process was not verified as the managed launch (${launchedSafety.reason || 'pid-mismatch'}).`,
1985
+ );
1819
1986
  }
1820
1987
  return {
1821
1988
  status: 'started',
@@ -1878,7 +2045,7 @@ export function stopChrome({ port = DEFAULT_PORT, clean = false, dryRun = false,
1878
2045
  rmSync(paths.stateFile, { force: true });
1879
2046
  let cleaned = false;
1880
2047
  if (clean && isBrowserToolsUserDataDir(state?.userDataDir)) {
1881
- rmSync(state.userDataDir, { recursive: true, force: true });
2048
+ rmSync(state.userDataDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
1882
2049
  rmSync(profileSyncStateFileForPort(normalizedPort), { force: true });
1883
2050
  cleaned = true;
1884
2051
  }
@@ -1970,7 +2137,7 @@ export function stopChrome({ port = DEFAULT_PORT, clean = false, dryRun = false,
1970
2137
  rmSync(paths.stateFile, { force: true });
1971
2138
  let cleaned = false;
1972
2139
  if (clean && isBrowserToolsUserDataDir(state?.userDataDir)) {
1973
- rmSync(state.userDataDir, { recursive: true, force: true });
2140
+ rmSync(state.userDataDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
1974
2141
  rmSync(profileSyncStateFileForPort(normalizedPort), { force: true });
1975
2142
  cleaned = true;
1976
2143
  }
@@ -2056,6 +2223,19 @@ function readManagedState(stateFile) {
2056
2223
  }
2057
2224
 
2058
2225
  function commandForPid(pid) {
2226
+ if (process.platform === 'linux') {
2227
+ try {
2228
+ const command = readFileSync(`/proc/${pid}/cmdline`, 'utf8');
2229
+ // Chromium rewrites its process title into argv[0], leaving only trailing NULs.
2230
+ // Retain exact boundaries for ordinary argv; parse the rewritten title as ps does.
2231
+ if (command) return command.split('\0').filter(Boolean).length === 1 ? command.replaceAll('\0', '').trim() : command;
2232
+ if (!processExists(pid)) return null;
2233
+ throw new Error(`Cannot inspect live browser process ${pid}`);
2234
+ } catch (error) {
2235
+ if (error.code === 'ENOENT' || error.code === 'ESRCH') return null;
2236
+ throw error;
2237
+ }
2238
+ }
2059
2239
  const result = spawnSync('ps', ['-p', String(pid), '-o', 'command='], { encoding: 'utf-8' });
2060
2240
  if (result.error || result.status !== 0) return null;
2061
2241
  const command = result.stdout.trim();
@@ -2067,16 +2247,30 @@ function processStartIdentity(pid) {
2067
2247
  if (!Number.isInteger(normalizedPid) || normalizedPid < 1) return null;
2068
2248
  const result = spawnSync(
2069
2249
  'ps',
2070
- ['-p', String(normalizedPid), '-o', 'lstart=', '-o', 'command='],
2071
- { encoding: 'utf-8' },
2250
+ ['-p', String(normalizedPid), '-o', 'lstart='],
2251
+ {
2252
+ encoding: 'utf-8',
2253
+ // BSD ps formats lstart through the caller's locale and timezone. Canonicalize both so two
2254
+ // processes observing the same live launcher hash the same immutable start metadata.
2255
+ env: { ...process.env, LC_ALL: 'C', LANG: 'C', LC_TIME: 'C', TZ: 'UTC' },
2256
+ },
2072
2257
  );
2073
2258
  if (result.error || result.status !== 0) return null;
2074
- const identity = result.stdout.trim();
2075
- if (!identity) return null;
2259
+ const startedAt = result.stdout.trim();
2260
+ if (!startedAt) return null;
2261
+ // PID and kernel-reported start time stay fixed for the process lifetime. Command and argv do not:
2262
+ // process.title can rewrite them while the same live process continues owning the browser.
2263
+ const identity = `${normalizedPid}\n${startedAt}`;
2076
2264
  return createHash('sha256').update(identity, 'utf8').digest('hex');
2077
2265
  }
2078
2266
 
2079
2267
  function processIsZombie(pid) {
2268
+ if (process.platform === 'linux') {
2269
+ try {
2270
+ const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
2271
+ return stat.slice(stat.lastIndexOf(')') + 2).startsWith('Z');
2272
+ } catch { return false; }
2273
+ }
2080
2274
  const result = spawnSync('ps', ['-p', String(pid), '-o', 'state='], { encoding: 'utf-8' });
2081
2275
  if (result.error || result.status !== 0) return false;
2082
2276
  return result.stdout.trim().startsWith('Z');
@@ -2155,9 +2349,18 @@ export function managedChromeCommandSafety({ pid, port, state, command }) {
2155
2349
  const expectedToken = `--pi-browser-tools-managed=${state.managedToken}`;
2156
2350
  const expectedUserDataDir = `--user-data-dir=${state.userDataDir}`;
2157
2351
 
2158
- if (!command.includes(expectedDebugPort)) return { ok: false, reason: 'debug-port-mismatch', command };
2159
- if (!command.includes(expectedUserDataDir)) return { ok: false, reason: 'user-data-dir-mismatch', command };
2160
- if (!command.includes(expectedToken)) return { ok: false, reason: 'managed-token-mismatch', command };
2352
+ const argv = command.includes('\0') ? command.split('\0') : null;
2353
+ const hasArgument = (arg) => {
2354
+ if (argv) return argv.includes(arg);
2355
+ const start = command.indexOf(arg);
2356
+ if (start < 0) return false;
2357
+ const end = start + arg.length;
2358
+ return (start === 0 || /\s/.test(command[start - 1]))
2359
+ && (end === command.length || /\s/.test(command[end]));
2360
+ };
2361
+ if (!hasArgument(expectedDebugPort)) return { ok: false, reason: 'debug-port-mismatch', command };
2362
+ if (!hasArgument(expectedUserDataDir)) return { ok: false, reason: 'user-data-dir-mismatch', command };
2363
+ if (!hasArgument(expectedToken)) return { ok: false, reason: 'managed-token-mismatch', command };
2161
2364
 
2162
2365
  return { ok: true, command };
2163
2366
  }
@@ -2175,12 +2378,35 @@ export async function connectBrowser(port = DEFAULT_PORT, options = {}) {
2175
2378
  throw new Error(`Refusing to connect to Browser Tools Chrome on :${normalizedPort}: ${ownership.reason}`);
2176
2379
  }
2177
2380
  return puppeteer.connect({
2178
- browserURL: `http://localhost:${normalizedPort}`,
2381
+ browserURL: `http://127.0.0.1:${normalizedPort}`,
2179
2382
  defaultViewport: null,
2180
2383
  ...puppeteerOptions,
2181
2384
  });
2182
2385
  }
2183
2386
 
2387
+ /** Connects to a browser this process started itself, which needs no managed-browser ownership check. */
2388
+ export async function connectOwnBrowser(browserWSEndpoint, options = {}) {
2389
+ return puppeteer.connect({ browserWSEndpoint, defaultViewport: null, ...options });
2390
+ }
2391
+
2392
+ /** Connects to the one tab a tab broker leased (see tab-broker.mjs), seeing no other tab of the browser. */
2393
+ export async function connectLeasedTab({ cdpUrl, tabUrl }, options = {}) {
2394
+ if (typeof cdpUrl !== 'string' || !cdpUrl.startsWith('ws://')) throw new Error('cdpUrl must be a ws:// address');
2395
+ if (typeof tabUrl !== 'string' || !tabUrl.startsWith('about:blank#')) throw new Error('tabUrl must be a leased tab address');
2396
+ const browser = await puppeteer.connect({
2397
+ browserWSEndpoint: cdpUrl,
2398
+ defaultViewport: null,
2399
+ ...options,
2400
+ targetFilter: (target) => target.url() === tabUrl,
2401
+ });
2402
+ const [page] = await browser.pages();
2403
+ if (!page) {
2404
+ await browser.disconnect();
2405
+ throw new Error('The leased tab is gone');
2406
+ }
2407
+ return { browser, page };
2408
+ }
2409
+
2184
2410
  export async function withBrowser(port, callback, options = {}) {
2185
2411
  const browser = await connectBrowser(port, options);
2186
2412
  try {