flowviant 0.115.0 → 0.117.0

package/bin/lib/loginPath.mjs

@@ -11,17 +11,27 @@
  * measured "not installed" under the tray (2026-09-25).
  *
  * So the daemon asks the person's login shell for its PATH once, and keeps
- * every entry it already had FIRST (a terminal start is unchanged) with the
+ * every entry it already had FIRST (a terminal start keeps its order) with the
  * shell's additions after it; then the usual per-user bin directories that
  * exist. Best-effort and bounded: a shell that hangs or prints nothing costs a
- * few seconds once, and nothing is ever removed from PATH.
+ * few seconds once.
+ *
+ * ONLY ABSOLUTE ENTRIES ARE KEPT, from every input — the current PATH too
+ * (2026-10-10, F118). A relative entry (`node_modules/.bin`, `.`, and the empty
+ * entry, which also means "here") resolves against whatever directory a child
+ * is spawned in, and the daemon spawns `git`, `gh`, `cloudflared` and the CLIs
+ * by bare name with `cwd` set to an agent's worktree: a binary an agent plants
+ * there would run as the daemon, outside any sandbox, with its credentials. A
+ * common ~/.bashrc idiom is enough to open that. `FLOWVIANT_KEEP_PATH=1` is the
+ * operator's explicit opt-out and leaves PATH exactly as they set it.
  */
 
-import { execFileSync, spawn } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync } from 'node:fs';
 import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
 import { compareVersions } from './versionOrder.mjs';
+import { relaunchSelf, selfArgv } from './launchCommand.mjs';
 
 const MARK = '__FLOWVIANT_PATH__=';
 
@@ -60,12 +70,13 @@ export function userBinDirs({ home = homedir(), exists = existsSync, list = read
   return dirs.filter((d) => exists(d));
 }
 
-/** Current entries first, then any the others add. Order-preserving, deduped. */
+/** Current entries first, then any the others add. Order-preserving, deduped,
+ *  absolute only (see the header): an empty or relative entry is dropped. */
 export function mergePath(current, ...more) {
   const seen = new Set();
   const out = [];
   for (const part of [current, ...more].flatMap((p) => (Array.isArray(p) ? p : String(p ?? '').split(':')))) {
-    if (!part || seen.has(part)) continue;
+    if (!part || !part.startsWith('/') || seen.has(part)) continue;
     seen.add(part);
     out.push(part);
   }
@@ -91,24 +102,18 @@ export function adoptLoginPath({ shell = true, env = process.env, ...deps } = {}
  * processes are looked up and started with the environment the process
  * STARTED with unless a spawn passes `env` — a later `process.env.PATH = …` is
  * invisible to them (measured 2026-09-25: node found ~/.local/bin/claude after
- * the change, the compiled binary did not). So when the PATH grew, the
- * binary restarts itself once with it: a thin proxy, the same shape as the
- * self-update re-exec, stdio inherited, exit code and signals passed through.
- * Node needs none of that and adopts in place.
+ * the change, the compiled binary did not). So when the PATH changed, the
+ * binary restarts itself once with it through the one relaunch proxy
+ * (launchCommand.mjs `relaunchSelf`): stdio inherited, exit code and signals
+ * passed through. Node needs none of that and adopts in place.
  */
 export async function adoptLoginPathForProcess(opts = {}) {
   if (process.env.FLOWVIANT_PATH_ADOPTED === '1') return;
   const before = process.env.PATH;
   const after = adoptLoginPath(opts);
   if (!process.versions.bun || after === before) return;
-  const compiled = process.argv[1]?.startsWith('/$bunfs/');
-  const child = spawn(process.execPath, process.argv.slice(compiled ? 2 : 1), {
-    stdio: 'inherit',
+  await relaunchSelf({
+    argv: selfArgv(process.argv.slice(2)),
     env: { ...process.env, FLOWVIANT_PATH_ADOPTED: '1' },
   });
-  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
-    process.on(signal, () => { try { child.kill(signal); } catch { /* gone */ } });
-  }
-  const code = await new Promise((resolve) => child.on('exit', (status, signal) => resolve(status ?? (signal ? 1 : 0))));
-  process.exit(code);
 }

package/bin/lib/machineListing.mjs

@@ -92,11 +92,14 @@ const JUST_NOW = 'just now';
 /**
  * A coarse age. Never "0s": a box heard a moment ago reads as "just now",
  * because a daemon that polled four hundred milliseconds ago has not been
- * silent for no time at all — the same rule `agoLabel` keeps in holder.mjs and
- * `elapsed` keeps in the web.
+ * silent for no time at all — the same rule `elapsed` keeps in the web.
  *
  * NULL for anything unmeasurable, so the caller DROPS the clause rather than
- * printing a duration nobody took.
+ * printing a duration nobody took — the one rule this shares with holder.mjs's
+ * `agoLabel`. That one is a different formatter on purpose (2026-10-10, F084:
+ * this comment used to claim it kept the "never 0s" rule too): it prints a
+ * measured zero as "0s" and steps at 60s/60m/48h, and holder.test.mjs pins
+ * both.
  */
 export function agoFrom(iso, now = Date.now()) {
   const t = Date.parse(iso ?? '');

package/bin/lib/mcp-cli.mjs

@@ -17,13 +17,16 @@
  * never from a CLI credential sitting on a shared machine.
  */
 
-import { FLEET_TOKEN, USER_AGENT, MCP_URL, FLEET_URL } from './config.mjs';
+import { FLEET_TOKEN, MCP_URL, FLEET_URL } from './config.mjs';
 import { terminalCommand } from './launchCommand.mjs';
 import { fleetEndpoint } from './fleetWire.mjs';
+import { postFleetJson } from './fleetPost.mjs';
 
 const CLI_TOKEN_URL = fleetEndpoint('cli-token', FLEET_URL);
 
-export async function runMcpCommand(args = []) {
+/** `timeoutMs` is the request's ceiling — injectable only so a test can prove
+ *  a hung server is abandoned without waiting thirty seconds. */
+export async function runMcpCommand(args = [], { timeoutMs = 30_000 } = {}) {
   if (!FLEET_TOKEN) {
     console.error(
       `error: no credential resolves here. Run \`${terminalCommand('login')}\` first — or, with\n` +
@@ -33,16 +36,12 @@ export async function runMcpCommand(args = []) {
     process.exit(1);
   }
 
+  // BOUNDED (audit 2026-10-10, F102): this was the one fleet request with no
+  // timeout, so a hung server held the command forever. A timeout lands in
+  // the catch below and says so like any other unreachable server.
   let res;
   try {
-    res = await fetch(CLI_TOKEN_URL, {
-      method: 'POST',
-      headers: {
-        authorization: `Bearer ${FLEET_TOKEN}`,
-        'content-type': 'application/json',
-        'user-agent': USER_AGENT,
-      },
-    });
+    res = await postFleetJson(CLI_TOKEN_URL, undefined, { timeoutMs });
   } catch (err) {
     console.error(`error: could not reach Flowviant (${err?.message || err})`);
     process.exit(1);

package/bin/lib/noWindowEnv.mjs

@@ -41,9 +41,11 @@
  * purpose through WSL interop (`explorer.exe`, `cmd.exe /c start`); the kind
  * contracts ask it not to (artifactContracts.mjs, `NO_WINDOW`).
  */
-import { lstatSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { withoutMachineCredentials } from './machineEnv.mjs';
+import { ensureOwnDir } from './ownedDirs.mjs';
 
 /** Removed outright; WAYLAND_DISPLAY is kept but emptied (see above). */
 export const WINDOW_ENV_REMOVED = Object.freeze(['DISPLAY', 'WAYLAND_SOCKET']);
@@ -62,6 +64,24 @@ export function withoutWindows(env, browserHome = null) {
   return out;
 }
 
+/**
+ * EVERY CLI CHILD THE DAEMON SPAWNS UNATTENDED, ONE RULE (2026-10-10, the
+ * audit): no machine credential (machineEnv.mjs), and no way to a window
+ * unless a person at the keyboard asked for one (`display: true`, a Terminal
+ * tab's alone). It was composed by hand twice — a turn's `cliEnv`
+ * (runTurn.mjs) and the project check's `checkEnv` (workAgentCheck.mjs) — and
+ * skipped outright by the two spawns the daemon makes for its own purposes:
+ * the startup skills probe (runtimeCapabilities.mjs), whose `claude` started
+ * the person's stdio MCP servers and the checkout's SessionStart hooks with
+ * the machine credential in their environment, and the Codex offerings reads
+ * (runtimeOfferings.mjs), whose `codex mcp list` may start configured servers.
+ * Every one of them now asks here. Never mutates its input.
+ */
+export function unattendedEnv(env = process.env, { display = false, browserHome = null } = {}) {
+  const out = withoutMachineCredentials(env);
+  return display === true ? out : withoutWindows(out, browserHome);
+}
+
 /**
  * AN AGENT'S BROWSER HOME is kept beside its Codex home, in its worktree's
  * private git dir: never committed, the same profile turn after turn, and
@@ -82,8 +102,8 @@ export const agentBrowserHome = (sessionMetaPath, wt, agentId) =>
 export function openBrowserHome(kept) {
   if (kept) {
     try {
-      try { if (!lstatSync(kept).isDirectory()) rmSync(kept, { force: true }); } catch { /* absent */ }
-      mkdirSync(kept, { recursive: true, mode: 0o700 });
+      // ownedDirs.mjs (2026-10-10): the link goes, never its target.
+      ensureOwnDir(kept, { mode: 0o700 });
       return { dir: kept, cleanup: () => {} };
     } catch { /* fall through to a turn's own */ }
   }

package/bin/lib/ownedDirs.mjs

@@ -0,0 +1,99 @@
+/**
+ * DIRECTORIES THE DAEMON WRITES INTO THAT A REPOSITORY COULD HAVE PLANTED —
+ * one home for the rule "never follow a link a checkout carries under
+ * `.flowviant/`" (2026-10-10, the audit's F100 / F080).
+ *
+ * git commits symlinks. A checkout can arrive carrying `.flowviant -> ~/.ssh`,
+ * or `.flowviant/uploads -> ../../../../.ssh` (a worktree's depth under
+ * `~/.flowviant/worktrees` is deterministic), and any daemon write through
+ * either lands outside the place it was meant for, as the operator. The rule
+ * that stops it was hand-written in ten places in four shapes — a boolean, a
+ * true/null/false, a 'dir'/'none'/'other', a replace-then-mkdir — and the
+ * attachment lane, the one that writes a MEMBER'S bytes under a member's name,
+ * had none of them. Each new `.flowviant/<x>` writer had to rediscover it.
+ *
+ * TWO POLICIES, deliberately two doors:
+ *
+ *  - REFUSED, NEVER REPLACED (`ensureRealSubdir`): `.flowviant/` and the
+ *    directories under it a repository could hold — the artifacts directory,
+ *    the uploads directory. `.flowviant/` is not only ours (a repo declares
+ *    `check.json` and `deploy.json` there), so a link or a file at one of
+ *    these names is the repository's content: Flowviant deleting it would be
+ *    destroying what it did not create, and following it is the write outside
+ *    the worktree. Either answer is "no", and the caller says so in words.
+ *  - REPLACED, NEVER FOLLOWED (`ensureOwnDir`): a path that is wholly the
+ *    daemon's — the knowledge library under a parent its caller has already
+ *    checked, a kept browser home. A link or a file planted there is removed
+ *    (the link, never its target) and a real directory made in its place.
+ *
+ * Leaf: node:fs and node:path only.
+ */
+import { lstatSync, mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * What stands at `p`, by `lstat` and never followed: `'dir'` for a real
+ * directory, `'none'` for nothing at all, `'other'` for anything else — a
+ * symlink (to a directory or dangling), a regular file, or a path this cannot
+ * look at (a component that is a file, no permission). The unknown case is
+ * `'other'`, never `'none'`: an answer of "absent" invites a create.
+ */
+export function realDirState(p) {
+  try {
+    const st = lstatSync(p);
+    return st.isDirectory() && !st.isSymbolicLink() ? 'dir' : 'other';
+  } catch (e) {
+    return e?.code === 'ENOENT' ? 'none' : 'other';
+  }
+}
+
+/** `<placeDir>/.flowviant`, by the same three states. */
+export const flowviantParentState = (placeDir) => realDirState(join(placeDir, '.flowviant'));
+
+/**
+ * `<placeDir>/<rel>` as a real directory, every component of `rel` a real
+ * directory too — or FALSE, with nothing replaced.
+ *
+ * Each component must already be a real directory or be absent; any one that
+ * is a link or a non-directory refuses before anything is made. The missing
+ * ones are made, and then EVERY component is checked again: a link swapped in
+ * between the look and the make is caught here, and the caller writes
+ * nothing. `rel` is a relative path of plain names (`.flowviant/uploads`); a
+ * `..`, an empty or an absolute component refuses.
+ */
+export function ensureRealSubdir(placeDir, rel) {
+  const parts = String(rel).split('/');
+  if (parts.some((p) => p === '' || p === '.' || p === '..')) return false;
+  const paths = parts.map((_, i) => join(placeDir, ...parts.slice(0, i + 1)));
+  if (paths.some((p) => realDirState(p) === 'other')) return false;
+  try {
+    mkdirSync(paths[paths.length - 1], { recursive: true });
+  } catch {
+    return false;
+  }
+  return paths.every((p) => realDirState(p) === 'dir');
+}
+
+/**
+ * A directory that is wholly the daemon's, made real: anything at `path` that
+ * is not a real directory is removed — non-recursively, so a link goes and its
+ * target never does — and the directory made (`mode` for each directory this
+ * creates). Returns `path`; THROWS when a real directory cannot be had there,
+ * a link reappearing between the remove and the make included, so a caller
+ * never writes through one.
+ *
+ * Only for paths that are OURS. A path a repository may legitimately hold is
+ * `ensureRealSubdir`'s, which refuses rather than removes.
+ */
+export function ensureOwnDir(path, { mode } = {}) {
+  if (realDirState(path) !== 'dir') {
+    try {
+      rmSync(path, { force: true });
+    } catch {
+      /* the make below says why */
+    }
+  }
+  mkdirSync(path, mode === undefined ? { recursive: true } : { recursive: true, mode });
+  if (realDirState(path) !== 'dir') throw new Error(`${path} is not a real directory`);
+  return path;
+}

package/bin/lib/pinnedCapture.mjs

@@ -0,0 +1,383 @@
+/**
+ * A SCREENSHOT OF ONE PAGE, AND ONLY THAT PAGE (audit 2026-10-10, F657/F756).
+ *
+ * `captureScreenshot` (shot.mjs) photographs whatever document Chrome ends up
+ * on. For a page somebody else wrote that is the wrong question: the design
+ * preview used to load the model's HTML as a top-level `file://` document,
+ * and a `<meta http-equiv=refresh>` (or `location.replace`) to
+ * `file:///home/<you>/.flowviant/credentials.json` made the uploaded PNG a
+ * picture of every machine credential on the box — past the read fence the
+ * design posture exists for, and past the secret scrub, which reads text, not
+ * pixels. CSP has no working control over top-level navigation.
+ *
+ * This capture drives Chrome over its DevTools pipe (`--remote-debugging-pipe`
+ * — no port, nothing another local process can reach) and holds the page to
+ * the one URL it was given:
+ *
+ *  - EVERY network request is paused. The first Document request for `url` is
+ *    the page and goes through; any other Document request — a meta refresh,
+ *    a script navigation, a frame — is failed AND marks the capture as having
+ *    left the page. Subresources go through only when `allowSubresource` says
+ *    so (the page's own CSP hosts); the rest are failed quietly.
+ *  - A NEW PAGE (window.open, target=_blank) is paused before it runs, closed,
+ *    and marks the capture as having left the page.
+ *  - Downloads are denied.
+ *  - Before the PNG is kept, the committed document must still be `url`
+ *    (fragment aside) and must not be an error page.
+ *
+ * Any of those failing is `{ ok: false, reason: 'left-page' }`, and the caller
+ * (artifactPreview.mjs) reports `renderState: 'unavailable'` with no preview.
+ * Chrome itself refuses a navigation from an http page to `file://`, which is
+ * why the caller serves the page over loopback http rather than from disk.
+ *
+ * A Windows browser reached through WSL interop cannot be driven: interop
+ * bridges stdin/stdout/stderr and nothing else, so the DevTools pipe on fds 3
+ * and 4 never arrives. That path answers 'unavailable' rather than a
+ * screenshot nobody verified.
+ *
+ * The launch obeys shot.mjs's policy: sandboxed unless `sandboxOff`, one retry
+ * without it after a launch that measured a sandbox failure, and the machine
+ * credential stripped from Chrome's environment.
+ */
+
+import { spawn } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir, platform } from 'node:os';
+import { SANDBOX_FAILURE_RE, chromeEnv, chromeFlags, resolveBrowser, sandboxOff } from './shot.mjs';
+import { killGroup } from './processGroup.mjs';
+
+/** How long a closing browser gets to exit before it is killed. */
+const EXIT_GRACE_MS = 3_000;
+/** How long the page Chrome just made gets to be auto-attached. */
+const ATTACH_WAIT_MS = 2_000;
+
+/**
+ * A DevTools client over a pipe pair: JSON messages, each ended by a NUL.
+ * `send(method, params, sessionId)` resolves the result or rejects with the
+ * protocol's error; `on(fn)` receives every event; `close(reason)` rejects
+ * whatever is still waiting (the browser is gone).
+ */
+export function createCdpClient(writable, readable) {
+  let nextId = 0;
+  let closed = null;
+  const waiting = new Map();
+  const listeners = [];
+  let chunks = [];
+  readable.on('data', (d) => {
+    let start = 0;
+    for (let i = 0; i < d.length; i++) {
+      if (d[i] !== 0) continue;
+      chunks.push(d.subarray(start, i));
+      start = i + 1;
+      let msg;
+      try {
+        msg = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+      } catch {
+        msg = null;
+      }
+      chunks = [];
+      if (!msg) continue;
+      if (msg.id != null && waiting.has(msg.id)) {
+        const w = waiting.get(msg.id);
+        waiting.delete(msg.id);
+        if (msg.error) w.reject(new Error(msg.error.message || 'protocol error'));
+        else w.resolve(msg.result ?? {});
+      } else if (msg.method) {
+        for (const fn of listeners) fn(msg);
+      }
+    }
+    if (start < d.length) chunks.push(d.subarray(start));
+  });
+  return {
+    send(method, params = {}, sessionId) {
+      if (closed) return Promise.reject(new Error(closed));
+      const id = ++nextId;
+      const msg = { id, method, params, ...(sessionId ? { sessionId } : {}) };
+      return new Promise((resolve, reject) => {
+        waiting.set(id, { resolve, reject });
+        try {
+          writable.write(JSON.stringify(msg) + '\0');
+        } catch (e) {
+          waiting.delete(id);
+          reject(e);
+        }
+      });
+    },
+    on(fn) {
+      listeners.push(fn);
+    },
+    close(reason) {
+      if (closed) return;
+      closed = reason;
+      for (const w of waiting.values()) w.reject(new Error(reason));
+      waiting.clear();
+    },
+  };
+}
+
+/** `a` and `b` name the same document: equal once the fragment is dropped. */
+export function sameDocument(a, b) {
+  try {
+    const x = new URL(a);
+    const y = new URL(b);
+    x.hash = '';
+    y.hash = '';
+    return x.href === y.href;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * One launch, one page, one PNG. Resolves `{ ok: true }` with the PNG written
+ * to `out`, or `{ ok: false, reason, message, launchFailed?, sandboxFailed? }`.
+ * `launchFailed` means the browser never answered on the pipe — the only
+ * failure a different launch (classic headless, or no sandbox) can change.
+ */
+async function captureOnce(browser, { url, out, width, height, timeoutMs, budgetMs, allowSubresource, headlessFlag, noSandbox }, { spawnImpl, env }) {
+  const userDataDir = mkdtempSync(join(tmpdir(), 'flowviant-pin-'));
+  const args = [...chromeFlags({ headlessFlag, noSandbox, userDataDir, width, height }), '--remote-debugging-pipe', 'about:blank'];
+  let child;
+  try {
+    child = spawnImpl(browser.bin, args, {
+      stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'],
+      env: chromeEnv(env),
+      // Its own process group, so the kill below takes Chrome's helpers too.
+      detached: platform() !== 'win32',
+    });
+  } catch (e) {
+    rmSync(userDataDir, { recursive: true, force: true });
+    return { ok: false, reason: 'spawn', message: e.message, launchFailed: true };
+  }
+
+  if (!child.stdio?.[3] || !child.stdio?.[4]) {
+    try { child.kill('SIGKILL'); } catch { /* gone */ }
+    rmSync(userDataDir, { recursive: true, force: true });
+    return { ok: false, reason: 'spawn', message: 'no DevTools pipe to the browser.', launchFailed: true };
+  }
+
+  let err = '';
+  child.stderr?.on('data', (d) => { err = (err + d.toString()).slice(-4000); });
+  const exited = new Promise((resolve) => {
+    if (child.exitCode != null) return resolve();
+    child.once('exit', () => resolve());
+    child.once('error', () => resolve());
+  });
+  const cdp = createCdpClient(child.stdio[3], child.stdio[4]);
+  child.once('exit', (code) => cdp.close(`Chrome exited (code ${code}).`));
+  child.once('error', (e) => cdp.close(e.message));
+  child.stdio[3]?.on?.('error', () => {});
+  child.stdio[4]?.on?.('error', () => {});
+
+  // The browser's whole group (processGroup.mjs). On Windows it is not
+  // detached, the group signal throws there, and the child itself is killed.
+  const kill = () => killGroup(child, 'SIGKILL');
+  const shutdown = async () => {
+    cdp.send('Browser.close').catch(() => {});
+    let grace;
+    const gone = await Promise.race([exited.then(() => true), new Promise((r) => { grace = setTimeout(() => r(false), EXIT_GRACE_MS); })]);
+    clearTimeout(grace);
+    // A browser that closed took its helpers with it; one that did not is
+    // killed with its whole group.
+    if (!gone) kill();
+    cdp.close('closed');
+    for (const fd of [3, 4]) {
+      try { child.stdio[fd]?.destroy?.(); } catch { /* gone */ }
+    }
+    try { child.stderr?.destroy?.(); } catch { /* gone */ }
+    try { rmSync(userDataDir, { recursive: true, force: true }); } catch { /* a dying helper still writing */ }
+  };
+
+  let left = null; // the first sign the page was left, in words
+  const leave = (why) => { if (!left) left = why; };
+  let deadline;
+  const timedOut = new Promise((resolve) => {
+    deadline = setTimeout(() => resolve({ ok: false, reason: 'timeout', message: `the page did not finish within ${timeoutMs / 1000}s.` }), timeoutMs);
+  });
+
+  const run = async () => {
+    try {
+      await cdp.send('Browser.getVersion');
+    } catch (e) {
+      // Give a dying browser a moment to say why on stderr.
+      await Promise.race([exited, new Promise((r) => setTimeout(r, 200))]);
+      const tail = err.trim().split('\n').slice(-2).join(' ');
+      return {
+        ok: false,
+        reason: 'render',
+        message: `Chrome did not start (${e.message})${tail ? ' ' + tail : ''}`,
+        launchFailed: true,
+        sandboxFailed: !noSandbox && SANDBOX_FAILURE_RE.test(err),
+      };
+    }
+
+    let ours = null; // { targetId, sessionId }
+    let ourTargetId = null;
+    let documentSeen = false;
+    const attached = new Map(); // targetId -> { sessionId, waiting, type }
+    let ready;
+    const ourSession = new Promise((r) => { ready = r; });
+    let budgetDone;
+    const budget = new Promise((r) => { budgetDone = r; });
+
+    let navigating = false;
+    // Called only for a target that is paused before it runs. Once the page
+    // is navigating, a new page is one IT opened (a popup) and never runs;
+    // before that, it can only be the window Chrome starts with.
+    const settleForeign = (targetId, info) => {
+      if (info.type === 'page') {
+        if (navigating) leave('the page opened another window');
+        cdp.send('Target.closeTarget', { targetId }).catch(() => {});
+      } else {
+        cdp.send('Runtime.runIfWaitingForDebugger', {}, info.sessionId).catch(() => {});
+      }
+    };
+
+    cdp.on((msg) => {
+      const p = msg.params || {};
+      if (msg.method === 'Target.attachedToTarget' && !msg.sessionId) {
+        const info = { sessionId: p.sessionId, waiting: !!p.waitingForDebugger, type: p.targetInfo?.type };
+        const targetId = p.targetInfo?.targetId;
+        attached.set(targetId, info);
+        if (ourTargetId) {
+          if (targetId === ourTargetId) ready(info.sessionId);
+          else if (info.waiting) settleForeign(targetId, info);
+        }
+        return;
+      }
+      if (!ours || msg.sessionId !== ours.sessionId) return;
+      if (msg.method === 'Fetch.requestPaused') {
+        const requestId = p.requestId;
+        const reqUrl = p.request?.url ?? '';
+        if (p.resourceType === 'Document') {
+          if (!documentSeen && p.frameId === ours.targetId && reqUrl === url) {
+            documentSeen = true;
+            cdp.send('Fetch.continueRequest', { requestId }, ours.sessionId).catch(() => {});
+            return;
+          }
+          leave(`the page navigated to ${reqUrl.slice(0, 200)}`);
+          cdp.send('Fetch.failRequest', { requestId, errorReason: 'BlockedByClient' }, ours.sessionId).catch(() => {});
+          return;
+        }
+        let allowed = false;
+        try {
+          allowed = !!allowSubresource(reqUrl);
+        } catch {
+          allowed = false;
+        }
+        cdp.send(allowed ? 'Fetch.continueRequest' : 'Fetch.failRequest', allowed ? { requestId } : { requestId, errorReason: 'BlockedByClient' }, ours.sessionId).catch(() => {});
+        return;
+      }
+      if (msg.method === 'Emulation.virtualTimeBudgetExpired') budgetDone();
+    });
+
+    await cdp.send('Browser.setDownloadBehavior', { behavior: 'deny' }).catch(() => {});
+    await cdp.send('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: true, flatten: true });
+    const created = await cdp.send('Target.createTarget', { url: 'about:blank' });
+    ourTargetId = created.targetId;
+    for (const [targetId, info] of attached) {
+      if (targetId === ourTargetId) ready(info.sessionId);
+      else if (info.waiting) settleForeign(targetId, info);
+    }
+    // A Chrome that does not auto-attach the page it just made is attached
+    // to it by hand.
+    let attachWait;
+    const sessionId = await Promise.race([
+      ourSession,
+      new Promise((r) => { attachWait = setTimeout(r, ATTACH_WAIT_MS, null); }),
+    ]).then((id) => id ?? cdp.send('Target.attachToTarget', { targetId: ourTargetId, flatten: true }).then((a) => a.sessionId));
+    clearTimeout(attachWait);
+    ours = { targetId: ourTargetId, sessionId };
+
+    await cdp.send('Page.enable', {}, sessionId);
+    await cdp.send('Fetch.enable', { patterns: [{ urlPattern: '*', requestStage: 'Request' }] }, sessionId);
+    await cdp.send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false }, sessionId);
+    await cdp.send('Emulation.setVirtualTimePolicy', { policy: 'pause' }, sessionId);
+    await cdp.send('Runtime.runIfWaitingForDebugger', {}, sessionId).catch(() => {});
+    navigating = true;
+    const nav = await cdp.send('Page.navigate', { url }, sessionId);
+    if (nav.errorText) {
+      return { ok: false, reason: 'render', message: `the page did not load (${nav.errorText}).` };
+    }
+    // Let fonts and scripts settle, as `--virtual-time-budget` does.
+    await cdp.send('Emulation.setVirtualTimePolicy', { policy: 'pauseIfNetworkFetchesPending', budget: budgetMs }, sessionId);
+    // A Chrome that never reports the budget is captured on the wall clock,
+    // short of the deadline, rather than never.
+    let wall;
+    await Promise.race([budget, new Promise((r) => { wall = setTimeout(r, Math.max(budgetMs, timeoutMs - EXIT_GRACE_MS)); })]);
+    clearTimeout(wall);
+
+    const history = await cdp.send('Page.getNavigationHistory', {}, sessionId);
+    const current = history.entries?.[history.currentIndex]?.url ?? '';
+    const tree = await cdp.send('Page.getFrameTree', {}, sessionId);
+    const main = tree.frameTree?.frame ?? {};
+    if (!documentSeen) leave('the page was never requested');
+    if (!sameDocument(current, url) || !sameDocument(main.url ?? '', url) || main.unreachableUrl) {
+      leave(`the page ended on ${String(current || main.url || 'nothing').slice(0, 200)}`);
+    }
+    if (left) return { ok: false, reason: 'left-page', message: `${left}.` };
+
+    const shot = await cdp.send('Page.captureScreenshot', { format: 'png' }, sessionId);
+    // One last look: a navigation that landed during the capture.
+    if (left) return { ok: false, reason: 'left-page', message: `${left}.` };
+    writeFileSync(out, Buffer.from(shot.data ?? '', 'base64'));
+    return { ok: true, path: out };
+  };
+
+  try {
+    return await Promise.race([
+      run().catch((e) => ({ ok: false, reason: 'render', message: e?.message ?? String(e) })),
+      timedOut,
+    ]);
+  } finally {
+    clearTimeout(deadline);
+    await shutdown();
+  }
+}
+
+/**
+ * Capture `url` and nothing else to a PNG at `out` (see the header). Resolves
+ * `{ ok: true, path }` or `{ ok: false, reason, message }`; a reason of
+ * 'left-page' means the page tried to become something else.
+ *
+ * `browser`, `spawn`, `uid` and `env` are injectable for the tests; nothing in
+ * the daemon passes them.
+ */
+export async function capturePinnedPage({
+  url,
+  out,
+  width = 1440,
+  height = 900,
+  timeoutMs = 60_000,
+  budgetMs = 5_000,
+  allowSubresource = () => false,
+  browser = resolveBrowser(),
+  spawn: spawnImpl = spawn,
+  uid = process.getuid?.(),
+  env = process.env,
+}) {
+  if (!browser) {
+    return { ok: false, reason: 'no-browser', message: 'No Chrome/Chromium/Edge found.' };
+  }
+  if (browser.viaWindows) {
+    return { ok: false, reason: 'wsl', message: 'a Windows browser reached through WSL cannot be held to one page.' };
+  }
+  let noSandbox = sandboxOff({ uid, env });
+  let last = null;
+  for (const headlessFlag of ['--headless=new', '--headless']) {
+    const once = () =>
+      captureOnce(browser, { url, out, width, height, timeoutMs, budgetMs, allowSubresource, headlessFlag, noSandbox }, { spawnImpl, env });
+    let r = await once();
+    if (!r.ok && r.sandboxFailed) {
+      noSandbox = true; // sticky: the one retry this capture gets
+      r = await once();
+    }
+    const { launchFailed, sandboxFailed: _measured, ...result } = r;
+    // Only a browser that never answered is worth another launch; a page that
+    // left, timed out or failed to load answers the same under any flag.
+    if (result.ok || !launchFailed) return result;
+    last = result;
+  }
+  return last;
+}