@broberg/lens-daemon 0.1.38 → 0.1.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@broberg/lens-daemon",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "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",
@@ -15,8 +15,8 @@
     "sharp": "^0.35.5",
     "turndown": "^7.2.4",
     "zod": "^3.23.8",
-    "@broberg/lens-svg": "0.1.1",
-    "@broberg/lens-engine": "0.14.1"
+    "@broberg/lens-engine": "0.14.1",
+    "@broberg/lens-svg": "0.1.1"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.10.6",

package/src/browser.ts

@@ -11,7 +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 { launchWithRepair, type BrowserRepair } from './ensure-chromium.ts';
+import { sweepChromeClones, trackChromeLaunch } from './chrome-clones.ts';
+import { launchWithRepair, repairInFlight, type BrowserRepair } from './ensure-chromium.ts';
 import {
   chromium,
   webkit,
@@ -118,6 +119,20 @@ export async function getBrowser(engine: LensEngine = 'chromium'): Promise<Brows
 // deadline; on timeout, discard the wedged browser and retry once fresh.
 const WEDGE_TIMEOUT_MS = 20_000;
 
+/** F010.1 — the wedge deadline on a warm launch, except while that engine's
+ *  browser is being reinstalled: then the repair is waited for (it has its own
+ *  bound) and the deadline applies again after it. Exported for test. */
+export async function launchDeadline<T>(p: Promise<T>, engine: LensEngine, ms: number): Promise<T> {
+  try {
+    return await withDeadline(p, ms, 'browser launch');
+  } catch (err) {
+    const repair = repairInFlight(engine);
+    if (!repair || !(err instanceof Error && err.message.includes('lens browser wedged'))) throw err;
+    await repair;
+    return withDeadline(p, ms, 'browser launch');
+  }
+}
+
 function withDeadline<T>(p: Promise<T>, ms: number, what: string): Promise<T> {
   return new Promise<T>((resolve, reject) => {
     const t = setTimeout(
@@ -430,12 +445,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));
@@ -449,14 +465,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?' : ''}`);
@@ -538,11 +555,12 @@ 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();
     }
   }
 
   const makeContext = async (): Promise<BrowserContext> => {
-    const browser = await withDeadline(getBrowser(engine), WEDGE_TIMEOUT_MS, 'browser launch');
+    const browser = await launchDeadline(getBrowser(engine), engine, WEDGE_TIMEOUT_MS);
     return withDeadline(
       browser.newContext(contextOptions(opts)),
       WEDGE_TIMEOUT_MS,

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

@@ -15,6 +15,7 @@ import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 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;
@@ -141,6 +148,8 @@ export function isMissingBrowserError(err: unknown): boolean {
 
 type Installer = (names: string[]) => Promise<{ ok: boolean; error?: string }>;
 
+const INSTALL_TIMEOUT_MS = 10 * 60_000;
+
 const spawnInstaller: Installer = (names) =>
   new Promise((resolve) => {
     let cliPath: string;
@@ -152,8 +161,13 @@ const spawnInstaller: Installer = (names) =>
     }
     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}` }));
+    // A download that stalls must not hold every run waiting on it forever.
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      resolve({ ok: false, error: `playwright install did not finish within ${INSTALL_TIMEOUT_MS / 60_000} min` });
+    }, INSTALL_TIMEOUT_MS);
+    child.on('error', (err) => { clearTimeout(timer); resolve({ ok: false, error: err.message }); });
+    child.on('exit', (code) => { clearTimeout(timer); resolve(code === 0 ? { ok: true } : { ok: false, error: `playwright install exited ${code}` }); });
   });
 
 let installer: Installer = spawnInstaller;
@@ -191,16 +205,31 @@ export async function launchWithRepair<T>(
   } 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;
+    const repair = (async () => {
+      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;
+    })();
+    const settled = repair.then(() => {}, () => {});
+    repairsInFlight.set(engine, settled);
+    void settled.then(() => { if (repairsInFlight.get(engine) === settled) repairsInFlight.delete(engine); });
+    return repair;
   }
 }
 
+// F010.1 — measured live 25 Oct: the warm launch sits under a 20 s "wedged"
+// deadline, and a firefox download takes longer, so the run failed while the
+// repair was still installing. A caller's deadline asks this first: a repair in
+// flight (install, bounded by INSTALL_TIMEOUT_MS, then one relaunch) is waited for.
+const repairsInFlight = new Map<BrowserEngine, Promise<void>>();
+export function repairInFlight(engine: BrowserEngine): Promise<void> | undefined {
+  return repairsInFlight.get(engine);
+}
+
 /** 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). */

package/src/flow.ts

@@ -24,6 +24,7 @@ import {
   type Target,
 } from '@broberg/lens-engine';
 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';
@@ -426,6 +427,8 @@ export interface FlowResult {
   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 };
@@ -3512,6 +3515,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
     ...(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

@@ -6,6 +6,7 @@
 // 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';
@@ -81,7 +82,7 @@ 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() }));
+  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

@@ -17,6 +17,7 @@ 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, 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;
 }