@broberg/lens-daemon 0.1.37 → 0.1.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@broberg/lens-daemon",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "description": "The Lens module of the cardmem daemon (flows, critic, coverage, capture sessions, the /lens/* routes and the cardmem-lens MCP) as a package. The daemon mounts createLensRouter(deps) + createLensMcpRouter(deps). Bun runtime.",
   "type": "module",
   "license": "MIT",

package/src/browser.ts

@@ -11,6 +11,8 @@
 // context + page are always closed in a finally, even on capture error.
 
 import { bindProfileChannel, claimProfile, killOwnBrowsersOn, profileDir, type ProfileChannel } from './profiles.ts';
+import { sweepChromeClones, trackChromeLaunch } from './chrome-clones.ts';
+import { launchWithRepair, type BrowserRepair } from './ensure-chromium.ts';
 import {
   chromium,
   webkit,
@@ -80,7 +82,15 @@ const CHROMIUM_ARGS = [
 
 async function launch(engine: LensEngine): Promise<Browser> {
   const args = engine === 'chromium' ? CHROMIUM_ARGS : [];
-  return ENGINES[engine].launch({ headless: true, args });
+  // F010.1 — a deleted browser is installed and the launch retried, not a fleet-wide outage.
+  return launchWithRepair(engine, () => ENGINES[engine].launch({ headless: true, args }), (r) => lastRepairs.push(r));
+}
+
+/** F010.1 — repairs made since the last read; a run reads (and clears) them into
+ *  its report. Read-and-clear, so one repair is reported once. */
+const lastRepairs: BrowserRepair[] = [];
+export function takeBrowserRepairs(): BrowserRepair[] {
+  return lastRepairs.splice(0, lastRepairs.length);
 }
 
 /** Get the warm browser for an engine, launching it on first use. Re-launches
@@ -353,7 +363,7 @@ async function launchWithExtension(
     if (profile) bindProfileChannel(profile, EXTENSION_CHANNEL);
     userDataDir = profile ? profileDir(profile) : await mkdtemp(join(tmpdir(), 'lens-ext-'));
     try {
-      context = await chromium.launchPersistentContext(userDataDir, {
+      context = await launchWithRepair('chromium', () => chromium.launchPersistentContext(userDataDir, {
         ...contextOptions(opts),
         headless: true,
         channel: EXTENSION_CHANNEL,
@@ -364,7 +374,7 @@ async function launchWithExtension(
           '--disable-dev-shm-usage',
           '--no-sandbox',
         ],
-      });
+      }), (r) => lastRepairs.push(r));
     } catch (err) {
       lastLaunchError = err instanceof Error ? err.message.split('\n')[0]! : String(err);
       if (!profile) await rm(userDataDir, { recursive: true, force: true }).catch(() => {});
@@ -421,12 +431,13 @@ function realUserAgent(channel: ProfileChannel): Promise<string> {
   let ua = headlessAgents.get(channel);
   if (!ua) {
     ua = (async () => {
-      const b = await chromium.launch({ channel, headless: true });
+      const b = await trackChromeLaunch(channel, () => chromium.launch({ channel, headless: true }));
       try {
         const page = await b.newPage();
         return (await page.evaluate(() => navigator.userAgent)).replace('HeadlessChrome/', 'Chrome/');
       } finally {
         await b.close().catch(() => {});
+        sweepChromeClones();
       }
     })();
     ua.catch(() => headlessAgents.delete(channel));
@@ -440,14 +451,15 @@ async function launchRunBrowser(opts: WithPageOptions, b: RunBrowser): Promise<{
   const userDataDir = b.profile ? profileDir(b.profile) : await mkdtemp(join(tmpdir(), 'lens-run-'));
   const userAgent = opts.userAgent ?? (b.visible ? undefined : await realUserAgent(b.channel));
   try {
-    const context = await chromium.launchPersistentContext(userDataDir, {
+    const context = await trackChromeLaunch(b.channel, () => chromium.launchPersistentContext(userDataDir, {
       ...contextOptions({ ...opts, ...(userAgent ? { userAgent } : {}) }),
       ...runBrowserLaunchOptions(b),
       timeout: EXTENSION_LAUNCH_TIMEOUT_MS,
-    });
+    }));
     return { context, userDataDir };
   } catch (err) {
-    killOwnBrowsersOn(userDataDir);
+    await killOwnBrowsersOn(userDataDir);
+    sweepChromeClones();
     if (!b.profile) await rm(userDataDir, { recursive: true, force: true }).catch(() => {});
     const msg = err instanceof Error ? err.message.split('\n')[0]! : String(err);
     throw new Error(`browser "${b.channel}" did not start: ${msg}${b.channel === 'chrome' ? ' — is Google Chrome installed on the daemon host?' : ''}`);
@@ -529,6 +541,7 @@ export async function withPage<T>(
       await withDeadline(context.close(), 5_000, 'browser context close').catch(() => {});
       if (!b.profile) await rm(userDataDir, { recursive: true, force: true }).catch(() => {});
       release();
+      sweepChromeClones();
     }
   }
 

package/src/capture-session.ts

@@ -19,6 +19,7 @@
 // file. The endpoint is loopback-only (127.0.0.1) behind the daemon's auth.
 
 import { bindProfileChannel, claimProfile, killOwnBrowsersOn, profileDir, type ProfileChannel } from './profiles.ts';
+import { sweepChromeClones, trackChromeLaunch } from './chrome-clones.ts';
 import { EXTENSION_CHANNEL } from './browser.ts';
 import { chromium, type Browser, type BrowserContext, type Page } from 'playwright';
 import { z } from 'zod';
@@ -86,7 +87,7 @@ async function launchHeaded(): Promise<{ browser: Browser; appName: string }> {
     // F240.10 — the macOS app NAME comes back with the browser. Playwright's
     // Browser handle exposes no process, so the name is the only handle we have
     // on the thing that has to come to the front — and it differs by channel.
-    return { browser: await chromium.launch({ ...opts, channel: 'chrome' }), appName: 'Google Chrome' };
+    return { browser: await trackChromeLaunch('chrome', () => chromium.launch({ ...opts, channel: 'chrome' })), appName: 'Google Chrome' };
   } catch {
     return { browser: await chromium.launch(opts), appName: 'Chromium' };
   }
@@ -419,9 +420,10 @@ export async function startCaptureSession(input: {
     const dir = profileDir(input.profile);
     releaseProfile = claimProfile(input.profile);
     try {
-      context = await chromium.launchPersistentContext(dir, profileLaunchOptions(channel));
+      context = await trackChromeLaunch(channel, () => chromium.launchPersistentContext(dir, profileLaunchOptions(channel)));
     } catch (err) {
-      killOwnBrowsersOn(dir);
+      await killOwnBrowsersOn(dir);
+      sweepChromeClones();
       releaseProfile();
       throw err;
     }
@@ -550,6 +552,7 @@ export async function finishCaptureSession(input: {
   } finally {
     reg.delete(input.sessionId);
     await s.browser.close().catch(() => {});
+    sweepChromeClones();
   }
 }
 
@@ -572,6 +575,7 @@ export async function cancelCaptureSession(
   clearTimeout(s.timer);
   reg.delete(sessionId);
   await s.browser.close().catch(() => {});
+  sweepChromeClones();
   return { ok: true, status: 'cancelled' };
 }
 

package/src/chrome-clones.ts

@@ -0,0 +1,159 @@
+// F010.7 — every start of Google Chrome.app makes a code-signing copy of the app in
+// /var/folders/<…>/X/com.google.Chrome.code_sign_clone/code_sign_clone.XXXXXX. Chrome
+// removes it on a normal exit; a killed Chrome leaves it (buddy, 25 Oct: 15 left, 10
+// of them from Lens runs). The owner runs his own Chrome on the same Mac, its copy in
+// the same folder, so Lens removes ONLY copies it caused.
+//
+// Measured 25 Oct: the copies are hard links of one another (one inode, link count 4),
+// so `lsof +D <copy>` reports every copy "in use" while any Chrome runs, and a Chrome
+// process never names its copy. The only link between a copy and a process is WHEN it
+// appeared. So: a copy that appeared while Lens launched Chrome, while no other Chrome
+// started, is ours — recorded with the pids of the Chrome we launched — and is removed
+// once none of those pids is a running Chrome. A launch window in which another Chrome
+// started records nothing: we cannot tell whose copy it is, so it is not ours to touch.
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+const CLONE = /^code_sign_clone\.[A-Za-z0-9]+$/;
+// The main process of an installed Chrome build (Chrome, Beta, Canary …): its own
+// binary, and no --type= (every helper carries one).
+const CHROME_MAIN = /\/Google Chrome[^/]*\.app\/Contents\/MacOS\/Google Chrome[^/]*(?: |$)/;
+
+export interface ChromeProc { pid: number; ppid: number; args: string }
+interface Probe { root: () => string | null; ledger: () => string; processes: () => ChromeProc[]; selfPid: () => number }
+
+function darwinCloneRoot(): string | null {
+  if (process.platform !== 'darwin') return null;
+  try {
+    const temp = execFileSync('getconf', ['DARWIN_USER_TEMP_DIR'], { encoding: 'utf8' }).trim();
+    return join(dirname(temp.replace(/\/$/, '')), 'X', 'com.google.Chrome.code_sign_clone');
+  } catch {
+    return null;
+  }
+}
+
+function listProcesses(): ChromeProc[] {
+  const out = execFileSync('ps', ['-eo', 'pid=,ppid=,args='], { encoding: 'utf8' });
+  const procs: ChromeProc[] = [];
+  for (const line of out.split('\n')) {
+    const m = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line);
+    if (m) procs.push({ pid: Number(m[1]), ppid: Number(m[2]), args: m[3]! });
+  }
+  return procs;
+}
+
+const defaultProbe: Probe = {
+  root: darwinCloneRoot,
+  ledger: () => process.env.LENS_CHROME_CLONE_LEDGER || join(homedir(), '.lens', 'chrome-clones.json'),
+  processes: listProcesses,
+  selfPid: () => process.pid,
+};
+let probe: Probe = defaultProbe;
+
+/** Test seam: a fake clone folder, ledger and process table. */
+export function setChromeCloneProbe(p: Partial<Probe> | null): void {
+  probe = p ? { ...defaultProbe, ...p } : defaultProbe;
+}
+
+interface Ledger { entries: Array<{ clone: string; pids: number[]; at: string }>; removed_total: number }
+
+function readLedger(): Ledger {
+  try {
+    const l = JSON.parse(readFileSync(probe.ledger(), 'utf8')) as Ledger;
+    if (Array.isArray(l.entries) && typeof l.removed_total === 'number') return l;
+  } catch {
+    // no ledger yet
+  }
+  return { entries: [], removed_total: 0 };
+}
+
+function writeLedger(l: Ledger): void {
+  const file = probe.ledger();
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(l), { mode: 0o600 });
+}
+
+function clonesNow(root: string): Set<string> {
+  try {
+    return new Set(readdirSync(root).filter((n) => CLONE.test(n)));
+  } catch {
+    return new Set();
+  }
+}
+
+function chromeMains(): ChromeProc[] {
+  try {
+    return probe.processes().filter((p) => CHROME_MAIN.test(p.args) && !p.args.includes(' --type='));
+  } catch {
+    return [];
+  }
+}
+
+/** Run a launch of the installed Google Chrome and record the code-sign copies it
+ *  made. Any other channel runs untouched (Playwright's Chromium makes no copy). */
+export async function trackChromeLaunch<T>(channel: string | undefined, launch: () => Promise<T>): Promise<T> {
+  const root = channel === 'chrome' ? probe.root() : null;
+  if (!root) return launch();
+  const clonesBefore = clonesNow(root);
+  const pidsBefore = new Set(chromeMains().map((p) => p.pid));
+  try {
+    return await launch();
+  } finally {
+    // Recorded on failure too: a launch that timed out may still have started Chrome.
+    const added = [...clonesNow(root)].filter((n) => !clonesBefore.has(n));
+    const started = chromeMains().filter((p) => !pidsBefore.has(p.pid));
+    const self = probe.selfPid();
+    const ours = started.filter((p) => p.ppid === self).map((p) => p.pid);
+    const foreign = started.some((p) => p.ppid !== self);
+    if (added.length > 0 && !foreign) {
+      const l = readLedger();
+      for (const name of added) l.entries.push({ clone: join(root, name), pids: ours, at: new Date().toISOString() });
+      writeLedger(l);
+    }
+  }
+}
+
+/** Remove the recorded copies whose Chrome is gone; keep the rest. Returns how many
+ *  were removed. Only ever a path in the ledger, and only a code_sign_clone.* entry
+ *  directly inside the clone folder. */
+export function sweepChromeClones(): number {
+  const root = probe.root();
+  if (!root) return 0;
+  const l = readLedger();
+  if (l.entries.length === 0) return 0;
+  const running = new Set(chromeMains().map((p) => p.pid));
+  let removed = 0;
+  l.entries = l.entries.filter((e) => {
+    if (dirname(e.clone) !== root || !CLONE.test(e.clone.slice(root.length + 1))) return false;
+    if (!existsSync(e.clone)) return false;
+    if (e.pids.some((pid) => running.has(pid))) return true;
+    try {
+      rmSync(e.clone, { recursive: true, force: true });
+    } catch (err) {
+      // Kept in the ledger, so the next sweep tries again; the reason is not hidden.
+      console.warn(`[lens] could not remove Chrome copy ${e.clone}: ${err instanceof Error ? err.message : String(err)}`);
+      return true;
+    }
+    removed++;
+    return false;
+  });
+  l.removed_total += removed;
+  writeLedger(l);
+  lastRemoved += removed;
+  return removed;
+}
+
+let lastRemoved = 0;
+/** Copies removed since the last read; a run reads (and clears) it into its report. */
+export function takeChromeClonesRemoved(): number {
+  const n = lastRemoved;
+  lastRemoved = 0;
+  return n;
+}
+
+export function chromeCloneStatus(): { ours_pending: number; removed_total: number } {
+  const l = readLedger();
+  return { ours_pending: l.entries.length, removed_total: l.removed_total };
+}

package/src/ensure-chromium.ts

@@ -14,7 +14,8 @@ import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
-import { chromium } from 'playwright';
+import { chromium, firefox, webkit } from 'playwright';
+import { sweepChromeClones } from './chrome-clones.ts';
 
 export interface ChromiumExpectation {
   installed: boolean;
@@ -81,6 +82,12 @@ export function ensureChromium(): Promise<{
   error?: string;
   alreadyInstalled?: boolean;
 }> {
+  // F010.7 — the boot is also where Chrome copies left by a previous daemon go.
+  try {
+    sweepChromeClones();
+  } catch (err) {
+    console.warn(`[lens] Chrome copy sweep failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
   const exp = chromiumExpectation();
   if (exp.installed) return Promise.resolve({ ok: true, alreadyInstalled: true });
   if (inFlight) return inFlight;
@@ -116,3 +123,115 @@ export function ensureChromium(): Promise<{
 
   return inFlight;
 }
+
+// ── F010.1 — repair at the moment of need, for every engine ────────────────────
+//
+// ensureChromium() runs once at daemon boot and installs the FULL Chromium only.
+// On 25 Oct the browsers were deleted while the daemon was running, and the warm
+// headless launch uses chromium-headless-shell, which boot never checked: every
+// run fleet-wide failed until a hand reinstalled. Now a launch that fails because
+// its binary is missing installs that engine's browsers (from the daemon's own
+// pinned Playwright, same as boot) and is retried once.
+
+export type BrowserEngine = 'chromium' | 'webkit' | 'firefox';
+
+/** What `playwright install` must fetch for an engine to launch in every mode Lens uses. */
+const INSTALL_NAMES: Record<BrowserEngine, string[]> = {
+  chromium: ['chromium', 'chromium-headless-shell', 'ffmpeg'],
+  webkit: ['webkit'],
+  firefox: ['firefox'],
+};
+
+export function isMissingBrowserError(err: unknown): boolean {
+  return /Executable doesn't exist/.test(err instanceof Error ? err.message : String(err));
+}
+
+type Installer = (names: string[]) => Promise<{ ok: boolean; error?: string }>;
+
+const spawnInstaller: Installer = (names) =>
+  new Promise((resolve) => {
+    let cliPath: string;
+    try {
+      cliPath = resolvePlaywrightCli();
+    } catch (err) {
+      resolve({ ok: false, error: `cannot resolve playwright CLI: ${err instanceof Error ? err.message : String(err)}` });
+      return;
+    }
+    console.log(`[lens] browser missing — installing ${names.join(', ')} via ${cliPath} …`);
+    const child = spawn(process.execPath, [cliPath, 'install', ...names], { stdio: 'inherit', env: process.env });
+    child.on('error', (err) => resolve({ ok: false, error: err.message }));
+    child.on('exit', (code) => resolve(code === 0 ? { ok: true } : { ok: false, error: `playwright install exited ${code}` }));
+  });
+
+let installer: Installer = spawnInstaller;
+/** Test seam: replace the installer (null restores the real one). */
+export function setBrowserInstaller(fn: Installer | null): void {
+  installer = fn ?? spawnInstaller;
+}
+
+// One install per engine at a time: two runs that hit the gap together share it.
+const engineInFlight = new Map<BrowserEngine, Promise<{ ok: boolean; error?: string }>>();
+
+export function installBrowsers(engine: BrowserEngine): Promise<{ ok: boolean; error?: string }> {
+  let p = engineInFlight.get(engine);
+  if (!p) {
+    p = installer(INSTALL_NAMES[engine]).finally(() => engineInFlight.delete(engine));
+    engineInFlight.set(engine, p);
+  }
+  return p;
+}
+
+export interface BrowserRepair {
+  engine: BrowserEngine;
+  ms: number;
+}
+
+/** Run a launch; if it fails ONLY because the browser binary is missing, install
+ *  that engine's browsers and retry once. Any other error propagates untouched. */
+export async function launchWithRepair<T>(
+  engine: BrowserEngine,
+  launch: () => Promise<T>,
+  onRepaired?: (r: BrowserRepair) => void,
+): Promise<T> {
+  try {
+    return await launch();
+  } catch (err) {
+    if (!isMissingBrowserError(err)) throw err;
+    const t0 = Date.now();
+    const inst = await installBrowsers(engine);
+    if (!inst.ok) {
+      throw new Error(`${engine} browser is missing and could not be installed: ${inst.error ?? 'unknown'} — original: ${(err as Error).message.split('\n')[0]}`);
+    }
+    const out = await launch();
+    onRepaired?.({ engine, ms: Date.now() - t0 });
+    return out;
+  }
+}
+
+/** For /health: does each engine's browser binary exist where this daemon looks?
+ *  chromium is reported for both the full build and the headless shell, because
+ *  the warm headless launch needs the shell (the 25 Oct gap boot never checked). */
+export function browsersPresent(): Record<string, boolean> {
+  const has = (f: () => string) => {
+    try {
+      return existsSync(f());
+    } catch {
+      return false;
+    }
+  };
+  const full = (() => {
+    try {
+      return chromium.executablePath();
+    } catch {
+      return '';
+    }
+  })();
+  const m = /^(.*[\\/])chromium-(\d+)[\\/]/.exec(full);
+  const shellDir = m ? join(m[1]!, `chromium_headless_shell-${m[2]}`) : '';
+  return {
+    chromium: has(() => full),
+    'chromium-headless-shell': shellDir ? existsSync(shellDir) : false,
+    webkit: has(() => webkit.executablePath()),
+    firefox: has(() => firefox.executablePath()),
+  };
+}

package/src/flow.ts

@@ -23,7 +23,8 @@ import {
   type AssertOutcome,
   type Target,
 } from '@broberg/lens-engine';
-import { withPage, type LensEngine, type RunBrowser } from './browser.ts';
+import { takeBrowserRepairs, withPage, type LensEngine, type RunBrowser } from './browser.ts';
+import { takeChromeClonesRemoved } from './chrome-clones.ts';
 import { collectNetworkShapes, type NetworkShapesOptions, type NetworkShapesReport } from './network-shapes.ts';
 import { deadline, defaultPopupOf, prepareExtension, seedExtensionStorage, SIMULATED_ACCESS_NOTE } from './extension-flow.ts';
 import { authPrepare, fetchMintJson, persistStorageState, persistTarget, type AuthConfig, type AuthEnv } from './auth/index.ts';
@@ -424,6 +425,10 @@ export interface FlowResult {
   /** F009.131 — set when auth.persist was asked for: whether the renewed login was
    *  written back to statePath, and why not when it was not. Never a value. */
   auth_persisted?: { ok: boolean; reason?: string };
+  /** F010.1 — browsers the daemon reinstalled because their binary was missing. */
+  browser_repaired?: Array<{ engine: string; ms: number }>;
+  /** F010.7 — Chrome code-sign copies Lens removed after this run's browser closed. */
+  chrome_clones_removed?: number;
   /** F009.137 — mails this run consumed for a code, and how many were removed
    *  after. Present only when a step read mail. Never a code or a body. */
   mail?: { consumed: number; cleaned: number; reason?: string };
@@ -3508,6 +3513,9 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
     reduced_motion: opts.reducedMotion ?? 'reduce',
     ...(authPersisted ? { auth_persisted: authPersisted } : {}),
     ...(mailReport ? { mail: mailReport } : {}),
+    // F010.1 — a missing browser this run had to reinstall, said out loud.
+    ...((() => { const r = takeBrowserRepairs(); return r.length ? { browser_repaired: r } : {}; })()),
+    ...((() => { const n = takeChromeClonesRemoved(); return n ? { chrome_clones_removed: n } : {}; })()),
     ...(extensionInfo ? { extension: extensionInfo } : {}),
     ...(networkShapesReport ? { network_shapes: networkShapesReport } : {}),
     downloads,

package/src/http.ts

@@ -5,6 +5,8 @@
 // all hit these. Artifact bytes are served here too, so an <img> in the
 // dashboard points straight at the daemon.
 
+import { browsersPresent } from './ensure-chromium.ts';
+import { chromeCloneStatus } from './chrome-clones.ts';
 import { Hono } from 'hono';
 import { setSandboxResolver } from './sandbox.ts';
 import { registerDaemonRoutes } from './daemon-routes.ts';
@@ -79,6 +81,8 @@ export function createLensRouter(deps: LensDeps): Hono {
 
   // F276.1/F276.4 — the upload queue: what it holds, and one drain pass.
   r.get('/uploads', (c) => c.json({ ok: true, ...uploadStats(deps.db) }));
+  // F010.1 — does each engine's browser binary exist where this daemon looks?
+  r.get('/browsers', (c) => c.json({ ok: true, browsers: browsersPresent(), chrome_clones: chromeCloneStatus() }));
   r.post('/uploads/drain', handle(async (body) => {
     const b = (body ?? {}) as { batch?: number };
     return drainUploads(deps.db, deps.storage, deps.cloud?.() ?? null, { batch: b.batch });

package/src/index.ts

@@ -16,7 +16,8 @@ export { durabilityOf, type EvidenceDurability } from './durability.ts';
 export { setSandboxResolver, type SandboxResolver } from './sandbox.ts';
 // Lifecycle the daemon owns: provision Chromium at boot, drain the evidence
 // upload queue on its timer, close the warm browser on shutdown.
-export { ensureChromium } from './ensure-chromium.ts';
+export { ensureChromium, browsersPresent } from './ensure-chromium.ts';
+export { sweepChromeClones, chromeCloneStatus } from './chrome-clones.ts';
 export { drainUploads } from './artifact-uploads.ts';
 export { closeBrowser } from './browser.ts';
 

package/src/profiles.ts

@@ -58,14 +58,17 @@ export function bindProfileChannel(name: string, channel: ProfileChannel): void
 // started running (measured twice on 25 Oct: a headless Chrome stayed up holding the
 // profile, so every retry hung on the lock it left). Kill only processes this
 // daemon started on this exact user-data dir.
-export function killOwnBrowsersOn(dir: string): number {
+// F010.7 — SIGTERM first: a Chrome that exits on its own removes its code-sign copy
+// of the app; a SIGKILLed one leaves it behind. SIGKILL only after graceMs.
+export async function killOwnBrowsersOn(dir: string, graceMs = 5_000): Promise<number> {
   let out = '';
   try {
     out = execFileSync('ps', ['-eo', 'pid=,ppid=,args='], { encoding: 'utf8' });
   } catch {
     return 0;
   }
-  let killed = 0;
+  const alive = (pid: number) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+  const targets: number[] = [];
   for (const line of out.split('\n')) {
     const m = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line);
     // The EXACT dir: a plain substring test matched profile "a" inside "a-b" (measured).
@@ -73,11 +76,20 @@ export function killOwnBrowsersOn(dir: string): number {
     const at = m ? (` ${m[3]!} `).indexOf(` ${flag} `) : -1;
     if (!m || Number(m[2]) !== process.pid || at < 0) continue;
     try {
-      process.kill(Number(m[1]), 'SIGKILL');
-      killed++;
+      process.kill(Number(m[1]), 'SIGTERM');
+      targets.push(Number(m[1]));
     } catch {
       // already gone
     }
   }
-  return killed;
+  const deadline = Date.now() + graceMs;
+  while (targets.some(alive) && Date.now() < deadline) await new Promise((r) => setTimeout(r, 100));
+  for (const pid of targets.filter(alive)) {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      // exited between the check and the kill
+    }
+  }
+  return targets.length;
 }