@ctrl-spc/cs 0.5.0 → 0.7.0

package/dist/agents.js

@@ -1,6 +1,6 @@
-import { accessSync, constants } from 'node:fs';
+import { accessSync, constants, readdirSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { delimiter, join } from 'node:path';
+import { delimiter, join, win32 } from 'node:path';
 const AGENTS = ['claude', 'codex'];
 /** Well-known install locations Claude/Codex land in but that a plain
  *  Terminal's PATH often misses (notably the Codex CLI inside ChatGPT.app). */
@@ -9,13 +9,38 @@ function fallbackPaths(agent) {
         return [join(homedir(), '.local/bin/claude'), '/opt/homebrew/bin/claude', '/usr/local/bin/claude'];
     }
     return [
-        process.env.CODEX_CLI_PATH ?? '',
         '/Applications/ChatGPT.app/Contents/Resources/codex',
         join(homedir(), '.local/bin/codex'),
         '/opt/homebrew/bin/codex',
         '/usr/local/bin/codex',
     ].filter(Boolean);
 }
+/** Explicit and app-managed installs that must beat PATH. On Windows the
+ *  Desktop app's current runtime and the global npm CLI can be different
+ *  builds; the app-managed binary is the one paired with the machine's current
+ *  sandbox helpers. */
+function preferredPaths(agent, platform = process.platform, env = process.env, home = homedir()) {
+    const explicit = agent === 'codex' ? (env.CODEX_CLI_PATH ?? '').trim() : '';
+    const windowsAppRoot = agent === 'codex' && platform === 'win32'
+        ? win32.join(env.LOCALAPPDATA ?? win32.join(home, 'AppData', 'Local'), 'OpenAI', 'Codex', 'bin')
+        : '';
+    let bundled = [];
+    if (windowsAppRoot) {
+        try {
+            bundled = readdirSync(windowsAppRoot, { withFileTypes: true })
+                .filter((entry) => entry.isDirectory())
+                .map((entry) => win32.join(windowsAppRoot, entry.name, 'codex.exe'))
+                .filter(isExecutable)
+                .sort((left, right) => statSync(right).mtimeMs - statSync(left).mtimeMs);
+        }
+        catch {
+            bundled = [];
+        }
+    }
+    const windowsAppFallback = windowsAppRoot ? win32.join(windowsAppRoot, 'codex.exe') : '';
+    return [explicit, ...bundled, windowsAppFallback].filter(Boolean);
+}
+export const preferredPathsForTest = preferredPaths;
 function isExecutable(path) {
     try {
         accessSync(path, constants.X_OK);
@@ -25,11 +50,51 @@ function isExecutable(path) {
         return false;
     }
 }
+/** The extensions a launcher can carry on this platform, in the order Windows
+ *  itself prefers them.
+ *
+ *  WINDOWS DOES NOT EXECUTE AN EXTENSIONLESS FILE. npm installs BOTH a shell
+ *  script named `claude` and a `claude.cmd`; the extensionless one satisfies
+ *  `accessSync(X_OK)`, so resolution used to "succeed" and hand `spawn` a path
+ *  it could not run — every dispatch died with ENOENT. Verified on the Windows
+ *  box: the bare path gives ENOENT, `claude.cmd --version` prints the version.
+ *
+ *  The empty string comes first so a genuine extensionless binary (every POSIX
+ *  install, and any real .exe found by name) still wins where it exists. */
+function candidateNames(agent, platform = process.platform, pathext = process.env.PATHEXT) {
+    if (platform !== 'win32')
+        return [agent];
+    const exts = (pathext ?? '.COM;.EXE;.BAT;.CMD')
+        .split(';')
+        .map(e => e.trim().toLowerCase())
+        .filter(Boolean);
+    /* EXTENSIONS FIRST ON WINDOWS, bare name LAST. npm ships both `claude` (a sh
+       script, unrunnable here) and `claude.cmd` in the SAME directory, and
+       `accessSync(X_OK)` cannot tell them apart — it is satisfied by any readable
+       file. Putting the bare name first therefore resolved to the unrunnable one
+       and every dispatch still ENOENTed, which is what the box showed after the
+       first attempt at this fix. The bare name is kept as a last resort so a real
+       extensionless executable is still found. */
+    return [...exts.map(ext => `${agent}${ext}`), agent];
+}
+/** Exported for the cross-platform test: `process.platform` cannot be faked, so
+ *  the Windows behaviour has to be reachable from a Mac test run. */
+export const candidateNamesForTest = candidateNames;
 function resolve(agent) {
+    const preferred = preferredPaths(agent).find(isExecutable);
+    if (preferred)
+        return preferred;
     const dirs = (process.env.PATH ?? '').split(delimiter).filter(Boolean);
+    const names = candidateNames(agent);
     for (const dir of dirs) {
-        if (isExecutable(join(dir, agent)))
-            return join(dir, agent);
+        for (const name of names) {
+            const candidate = join(dir, name);
+            /* On Windows `accessSync(X_OK)` is satisfied by any readable file, so it
+               cannot tell a runnable launcher from the extensionless shell script.
+               The extension list is what does the discriminating there. */
+            if (isExecutable(candidate))
+                return candidate;
+        }
     }
     return fallbackPaths(agent).find(isExecutable) ?? null;
 }

package/dist/autostart.js

@@ -88,6 +88,20 @@ function macOn() {
     const uid = process.getuid?.() ?? 0;
     const node = process.execPath;
     const entry = entryPath();
+    /* ═══ `USER` IS LOAD-BEARING, AND ITS ABSENCE IS SILENT. ═══
+       launchd starts an agent with almost no environment: PATH was set here
+       because the daemon could not otherwise FIND `claude`, and `USER` is the
+       same class of bug one layer down. The agents the daemon spawns inherit
+       `process.env`, and the Claude Code CLI resolves its stored credential by
+       the current user's name — with `USER` unset it reports "Not logged in ·
+       Please run /login" while the very same binary, run from a shell one second
+       earlier, authenticates fine.
+       THE COST OF MISSING IT: every claude-designated request fails with "Claude
+       is not signed in on this machine", which reads as an expired token and
+       sends you to re-authenticate something that was never broken. Reproduced
+       by hand: `env -i HOME=… PATH=… claude -p` fails, and adding USER alone
+       fixes it. HOME is set for the same reason, though launchd does supply it. */
+    const userName = process.env.USER ?? process.env.LOGNAME ?? '';
     const logDir = join(homedir(), '.config', 'ctrl-spc-v2');
     mkdirSync(logDir, { recursive: true });
     mkdirSync(dirname(plistPath()), { recursive: true });
@@ -102,7 +116,7 @@ function macOn() {
   <key>KeepAlive</key><true/>
   <key>StandardOutPath</key><string>${join(logDir, 'daemon.log')}</string>
   <key>StandardErrorPath</key><string>${join(logDir, 'daemon.log')}</string>
-  <key>EnvironmentVariables</key><dict><key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string></dict>
+  <key>EnvironmentVariables</key><dict><key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string><key>USER</key><string>${userName}</string><key>HOME</key><string>${homedir()}</string></dict>
 </dict></plist>
 `;
     writeFileSync(plistPath(), plist);

package/dist/browser.js

@@ -1,4 +1,13 @@
 import { spawn } from 'node:child_process';
+import { mkdtemp, rm, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/* 18c Slice 7, gate round 2: the tree kill this repo already proved is the only
+   one that works. `child.kill()` ends ONE process, and headless Chrome is a
+   parent with six to ten helpers — see `captureUrlScreenshot` for the
+   measurement, and win-shell.ts:98 for the Windows case that established it. */
+import { killTree } from './win-shell.js';
 /** Opens `url` in the default browser. Never fatal — callers print the URL too. */
 export function openBrowser(url) {
     const { command, args } = process.platform === 'darwin' ? { command: 'open', args: [url] }
@@ -11,3 +20,380 @@ export function openBrowser(url) {
     }
     catch { /* missing opener is non-fatal */ }
 }
+/* ═══ 18c SLICE 7, CORRECTED — THE PRODUCT TAKES THE PICTURE, NOT THE AGENT. ═══
+
+   WHAT THE WALK FOUND, on both platforms, in two independent sittings. Story 4's
+   scenario ("show me what the recruiter search screen looks like at
+   http://localhost:8000/", the word screenshot never typed) finished `done` every
+   time with ZERO rows in `cliv2_screenshots` and no `attach_screenshot` on the
+   wire. Slice 7's prompt change works — the agent knows the tool is there and
+   says so — and the agent still cannot use it.
+
+   THE REAL CAUSE, and it is NOT the allow list. `--allowedTools` was suspected,
+   and measuring it cleared it: on claude 2.1.226 that flag adds permission RULES
+   and does not remove built-ins (`--tools ""` is the flag that would), so `Bash`
+   is present in the worker's tool list and a read-only command runs fine. What
+   fails is the APPROVAL. `--permission-mode acceptEdits` auto-approves file
+   edits and nothing else, so any command outside the CLI's built-in read-only
+   classifier comes back `This command requires approval` — and a headless worker
+   has no human to approve it, so the denial is permanent. Reproduced exactly
+   against the product's own argv: `echo` succeeds, `curl` returns
+   `permission_denials: [{tool_name: "Bash"}]`. Every capture command is in the
+   second class, so the agent could not produce the tool's input.
+
+   WHY THIS IS THE FIX RATHER THAN A WIDER ALLOW LIST. `attach_screenshot` demands
+   an absolute path to an EXISTING PNG, and its own description told the agent
+   "Playwright or Maestro captures the file first" — neither of which is installed,
+   and both of which would need a shell to drive. So the product was asking the
+   agent for an input it had no reachable way to make. Handing it a scoped
+   `Bash(...)` rule would have made the capability depend on the agent guessing a
+   browser binary, a flag set and a temp path correctly on two operating systems,
+   failing silently wherever that guess was wrong, and it would have bought codex
+   nothing at all: codex's isolation is a seeded `$CODEX_HOME` with no argv
+   equivalent, so a claude-only argv change would leave half the product broken.
+   Capturing here fixes both agents at once, through the one channel a worker is
+   guaranteed to reach — an MCP tool call.
+
+   AND IT WEAKENS NOTHING. No permission flag changes. `--allowedTools
+   mcp__ctrl-spc__*`, `--strict-mcp-config`, `--setting-sources ''`,
+   `--permission-mode acceptEdits` and the whole codex branch Slice 8 hardened are
+   all untouched, so a worker still cannot run an arbitrary command. The browser
+   is launched by THIS process, the daemon the user installed, with a fixed argv
+   the agent cannot influence beyond the URL. That is strictly less authority than
+   letting the worker run a shell command of its own composition.
+
+   HEADLESS CHROME BECAUSE IT IS ALREADY THERE. No dependency is added: this
+   product ships no browser engine, and adding Playwright would put a ~300 MB
+   download in front of a capability that has to work on a user's machine today.
+   Chrome's `--headless --screenshot` writes a standard non-interlaced PNG, which
+   is exactly the shape `readPngScreenshot` already validates. */
+/** Where Chrome (or a Chromium build) usually lives, per platform.
+ *
+ *  A LIST RATHER THAN ONE PATH because "installed" is not one location: Edge is
+ *  Chromium and is present on essentially every Windows box, and a Mac may have
+ *  Chromium or Brave and no Chrome. Probed in order and the first that exists
+ *  wins, so the common case costs one `existsSync`.
+ *
+ *  `CTRL_SPC_V2_BROWSER` overrides the whole list. It is here for the user whose
+ *  browser is somewhere else entirely, and for a test that needs a known binary,
+ *  and it is read from the DAEMON's environment — never from anything an agent
+ *  can set, which is the property that keeps this from becoming a way to make
+ *  the product run an arbitrary executable. */
+export function browserCandidates(platform = process.platform) {
+    const override = process.env.CTRL_SPC_V2_BROWSER?.trim();
+    if (override)
+        return [override];
+    if (platform === 'darwin') {
+        return [
+            '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+            '/Applications/Chromium.app/Contents/MacOS/Chromium',
+            '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+            '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+        ];
+    }
+    if (platform === 'win32') {
+        const programFiles = process.env['ProgramFiles'] ?? 'C:\\Program Files';
+        const programFilesX86 = process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)';
+        const localAppData = process.env['LOCALAPPDATA'] ?? '';
+        return [
+            `${programFiles}\\Google\\Chrome\\Application\\chrome.exe`,
+            `${programFilesX86}\\Google\\Chrome\\Application\\chrome.exe`,
+            ...(localAppData ? [`${localAppData}\\Google\\Chrome\\Application\\chrome.exe`] : []),
+            `${programFiles}\\Microsoft\\Edge\\Application\\msedge.exe`,
+            `${programFilesX86}\\Microsoft\\Edge\\Application\\msedge.exe`,
+        ];
+    }
+    return [
+        '/usr/bin/google-chrome',
+        '/usr/bin/chromium',
+        '/usr/bin/chromium-browser',
+        '/usr/bin/microsoft-edge',
+    ];
+}
+/** The first candidate that exists, or null when this machine has no Chromium. */
+export function findBrowser(platform = process.platform, exists = existsSync) {
+    return browserCandidates(platform).find(exists) ?? null;
+}
+/** Only http(s), and that is a security boundary rather than tidiness.
+ *
+ *  The URL is the ONE part of the capture the agent controls, so it is the one
+ *  part that has to be constrained. `file://` would turn a screenshot request
+ *  into "render any file on this disk and upload it to the cloud", which is an
+ *  exfiltration route out of a machine whose absolute paths this product is
+ *  otherwise careful never to publish (AGENTS.md's path-privacy invariant).
+ *  `javascript:` and `data:` are refused for the same reason. An allow list, not
+ *  a deny list, so a scheme nobody thought of is refused by default.
+ *
+ *  ═══ LOOPBACK AND PRIVATE ADDRESSES ARE DELIBERATELY ALLOWED. DO NOT "FIX"
+ *      THIS. ═══
+ *
+ *  Read as a generic web fetcher this looks like a textbook SSRF hole: an agent
+ *  can name `http://localhost:*`, `http://127.0.0.1:*` or a LAN address and the
+ *  product will render it. Blocking those is the reflex, and it would delete the
+ *  entire feature. THE WHOLE CAPABILITY IS ABOUT LOCALHOST: story 4's scenario
+ *  is "show me what the recruiter search screen looks like at
+ *  http://localhost:8000/", the walk's fixture is a `python3 -m http.server` on
+ *  the tester's own machine, and a user asking to see their work in progress
+ *  means the dev server they are running right now. A loopback blocklist turns
+ *  the answer to every real request into a refusal.
+ *
+ *  WHAT KEEPS THAT ACCEPTABLE, and it is not that the risk is imaginary. The
+ *  agent already runs ON this machine with the user's own file access, so a
+ *  localhost HTTP GET grants it nothing it could not already do more directly —
+ *  this is not a server-side fetcher reaching into a trusted network from
+ *  outside, which is the shape SSRF advice is written for. The two local
+ *  services this product itself runs are both token-gated (the MCP tools server
+ *  checks `mcpToken()`, the companion checks its own token), so an agent
+ *  pointing a capture at either gets an error page rather than credentials;
+ *  that was checked rather than assumed. And the scheme allow list above still
+ *  holds, so the cloud-metadata style of attack that needs a non-HTTP scheme, or
+ *  a redirect to one, is refused — Chrome itself blocks an http->file redirect
+ *  with ERR_UNSAFE_REDIRECT, which was measured too.
+ *
+ *  If a future reader wants to narrow this, the thing to narrow is WHO may ask
+ *  for a capture, not which addresses are reachable from the user's own box. */
+export function isCapturableUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+}
+/** The bound on a capture, and after gate round 2 it is a REAL bound again
+ *  rather than the normal exit path. See `captureUrlScreenshot`. */
+export const CAPTURE_TIMEOUT_MS = 45_000;
+/** How often the PNG is checked for. 100ms costs nothing against a capture that
+ *  takes one to three seconds, and it is what turns a 45-second wait into a
+ *  ~1-second one. */
+const CAPTURE_POLL_MS = 100;
+/** The PNG must hold the SAME SIZE across two consecutive polls before it is
+ *  called finished. Chrome writes the file progressively, so a single
+ *  `existsSync` can catch a half-written image whose IDAT stream is truncated —
+ *  which `readPngScreenshot` would then reject as a corrupt PNG, turning a good
+ *  capture into a mysterious validation failure. One quiet interval is enough
+ *  because the write is a single streamed pass, not a series of edits. */
+const CAPTURE_SETTLE_POLLS = 2;
+/**
+ * Render `url` in headless Chrome and write a PNG this process owns.
+ *
+ * THE FILE IS THIS PROCESS'S, IN A PRIVATE TEMP DIRECTORY, AND IS DELETED. The
+ * agent never learns the path and never needed to: it names a URL, the bytes
+ * reach `cliv2_screenshots`, and nothing about this machine's filesystem is
+ * recorded anywhere. That is the same rule the `path` argument already obeys
+ * ("The local path is never uploaded or stored"), kept while removing the reason
+ * the agent had to know a path at all.
+ *
+ * `--disable-gpu` and `--hide-scrollbars` are the two flags that make the output
+ * deterministic enough to be worth comparing between runs; the rest of Chrome's
+ * defaults are left alone deliberately, because a screenshot the user recognises
+ * is the point and a heavily-flagged browser stops looking like their browser.
+ *
+ * ═══ GATE ROUND 2 — WHY THIS WAITS FOR THE FILE AND NOT FOR THE PROCESS. ═══
+ *
+ * THE FIRST BUILD USED `execFile` AND WAS WRONG IN TWO WAYS AT ONCE, both
+ * measured on this machine against Chrome 151 rather than reasoned about.
+ *
+ * ONE: CHROME 112+ NEW-HEADLESS DOES NOT EXIT AFTER `--screenshot`. The PNG was
+ * complete and byte-stable at about 2.5 seconds and the browser was still alive
+ * at three minutes. So every capture ran to `CAPTURE_TIMEOUT_MS` and returned in
+ * 45024, 45038, 45039 and 45042 ms — the timeout was not a safety net, it was
+ * the normal exit path, and a user asking for one screenshot waited 45 seconds
+ * for an image that had been ready for 42 of them.
+ *
+ * TWO: AND THE KILL DID NOT KILL IT. `execFile`'s `timeout` sends SIGTERM to the
+ * DIRECT CHILD ONLY, and headless Chrome is a parent with six to ten helper
+ * processes. Measured: after a capture "finished", the Chrome parent and its
+ * helpers were still alive and orphaned, holding open handles inside the temp
+ * directory this function had just tried to delete. Ten screenshots left ten
+ * resident browsers.
+ *
+ * THIS REPO ALREADY LITIGATED THAT SECOND POINT AND I MISSED IT. `win-shell.ts`
+ * exists to say that a single-process kill does not end a process tree: it
+ * records the Windows measurement (the descendant survived in `tasklist`) and
+ * ships `killTree`, whose `taskkill /T` walks downward and takes every
+ * descendant. On Windows the consequence is worse than a stray process, because
+ * an open handle BLOCKS directory deletion outright, so `rm(dir)` fails and the
+ * `.catch(() => {})` on the cleanup swallows it — the temp-profile leak would
+ * have been silent and the Windows walk could not have passed.
+ *
+ * SO THE COMPLETION SIGNAL IS THE ARTEFACT, NOT THE EXIT. Poll for the PNG,
+ * require its size to hold steady across two polls so a half-written file is
+ * never handed on, then `killTree` immediately. The process exiting on its own
+ * is still honoured (`--headless=old` and non-Chrome Chromium builds do exit),
+ * and either way the tree is killed before returning, so nothing is left behind
+ * on any platform.
+ */
+export async function captureUrlScreenshot(url, { width = 1280, height = 900, timeoutMs = CAPTURE_TIMEOUT_MS, browserPath = findBrowser(), 
+/** Injected by the suite. Real captures use `spawn` — see the note in
+ *  screenshot-capture.test.mjs about what a stubbed browser cannot prove. */
+spawnBrowser = spawn, pollMs = CAPTURE_POLL_MS, } = {}) {
+    if (!isCapturableUrl(url)) {
+        throw new Error(`url must be an http:// or https:// address, and "${url}" is not`);
+    }
+    if (!browserPath) {
+        throw new Error('no Chrome, Chromium or Edge was found on this machine, so CTRL+SPC could not take the ' +
+            'screenshot. Install one, or set CTRL_SPC_V2_BROWSER to the browser executable.');
+    }
+    const dir = await mkdtemp(join(tmpdir(), 'ctrl-spc-shot-'));
+    const path = join(dir, 'screenshot.png');
+    const cleanup = () => rm(dir, { recursive: true, force: true }).catch(() => { });
+    /* A THROWAWAY PROFILE, because the alternative is worse in both directions.
+       Sharing the user's real profile would put their logged-in cookies into a
+       picture the agent asked for, and Chrome refuses to start headless against a
+       profile an interactive window already holds — so the capability would fail
+       precisely when the user has their browser open, which is always. */
+    const profileDir = join(dir, 'profile');
+    let child;
+    try {
+        child = spawnBrowser(browserPath, [
+            '--headless',
+            '--disable-gpu',
+            '--hide-scrollbars',
+            `--user-data-dir=${profileDir}`,
+            `--window-size=${width},${height}`,
+            `--screenshot=${path}`,
+            url,
+        ], {
+            // The repo-wide invariant for ANY child process (MEMORY: "Windows silence
+            // decision"): a user must never see a console window flash.
+            windowsHide: true,
+            stdio: 'ignore',
+            /* ITS OWN PROCESS GROUP, ON POSIX, AND THIS IS LOad-BEARING — see `stop`
+               below. `detached` here does NOT mean "outlive us": the process is never
+               `unref`ed, and `stop` always runs before this function returns. It means
+               "become a group leader", which is the only way to signal Chrome's
+               helpers as a unit on Mac and Linux. */
+            detached: process.platform !== 'win32',
+        });
+    }
+    catch (err) {
+        await cleanup();
+        throw new Error(`the browser could not open ${url}: ${err.message}`);
+    }
+    /* A browser that could not be launched at all (a bad CTRL_SPC_V2_BROWSER, a
+       binary that vanished between the existence check and here) raises `error`
+       rather than exiting, and with `stdio: 'ignore'` there is no stderr to read.
+       Recorded rather than thrown, because throwing from an event handler escapes
+       this promise entirely. */
+    const launchState = { error: null, exited: false };
+    child.on('error', (err) => { launchState.error = err; });
+    child.on('exit', () => { launchState.exited = true; });
+    /* ═══ THE TREE, NOT THE HANDLE — AND ON POSIX THAT MEANS THE PROCESS GROUP.
+           ═══
+  
+       `killTree` is `win-shell.ts`'s and it is exactly right on Windows, where it
+       is `taskkill /T`. But its POSIX branch is a plain `child.kill('SIGKILL')`,
+       which is correct for what that file was written for (a `cmd.exe` wrapper
+       around one agent) and NOT enough for Chrome. Measured here rather than
+       assumed: a headless Chrome spawned with a temp profile had 6 direct children
+       and 8 processes total holding the directory; after a single-process SIGKILL
+       one survivor was still alive, and that survivor is what recreated the temp
+       directory AFTER `cleanup()` had deleted it. It showed up as one stray
+       `ctrl-spc-shot-*` directory per full-suite run and nowhere else, because it
+       needs a loaded machine to lose the race.
+  
+       So on Mac and Linux the signal goes to the GROUP (`-pid`), which the
+       `detached: true` above created. That reaches every helper in one call, which
+       is the same guarantee `taskkill /T` gives on Windows, by the mechanism each
+       platform actually offers. `killTree` is still used for the Windows path and
+       as the fallback, so nothing about the case that file litigated changes.
+  
+       Safe to call when the process has already gone: ESRCH is swallowed, because
+       a caller that wanted it dead is not wrong when it already is. */
+    const stop = () => {
+        if (process.platform !== 'win32' && typeof child.pid === 'number') {
+            try {
+                process.kill(-child.pid, 'SIGKILL');
+                return;
+            }
+            catch {
+                /* No group (the child died before `setsid`, or this platform declined
+                   it). Fall through to the single-process kill, which is still better
+                   than nothing. */
+            }
+        }
+        try {
+            killTree(child);
+        }
+        catch { /* already gone */ }
+    };
+    const started = Date.now();
+    let lastSize = -1;
+    let stableFor = 0;
+    try {
+        for (;;) {
+            let size = -1;
+            try {
+                const info = await stat(path);
+                if (info.isFile())
+                    size = info.size;
+            }
+            catch { /* not written yet */ }
+            /* Size 0 is Chrome having created the file but not yet filled it, which is
+               not a finished capture. */
+            if (size > 0 && size === lastSize) {
+                stableFor += 1;
+                if (stableFor >= CAPTURE_SETTLE_POLLS - 1)
+                    break;
+            }
+            else {
+                stableFor = 0;
+            }
+            lastSize = size;
+            if (launchState.error) {
+                throw new Error(`the browser could not open ${url}: ${launchState.error.message}`);
+            }
+            /* THE PROCESS EXITING IS STILL A VALID END, for `--headless=old` and for
+               Chromium builds that do quit. One more look at the file settles whether
+               it produced anything, and then the loop is over either way. */
+            if (launchState.exited) {
+                let finalSize = -1;
+                try {
+                    const info = await stat(path);
+                    if (info.isFile())
+                        finalSize = info.size;
+                }
+                catch { /* nothing was written */ }
+                if (finalSize > 0)
+                    break;
+                throw new Error(`the browser opened ${url} but produced no image`);
+            }
+            /* ═══ A REAL TIMEOUT IS NOW DISTINGUISHABLE FROM SUCCESS (gate round 2,
+                   BLOCKER 2). ═══
+               While the timeout WAS the normal exit path, "timed out but a file
+               exists" had to be treated as success, so a page that painted a spinner
+               and hung produced a screenshot of the spinner after 45 seconds with
+               nothing saying it was truncated. Now that a finished capture returns in
+               about a second, reaching here means the page genuinely never settled,
+               and the honest answer is to say so and produce NOTHING. A picture of a
+               half-loaded page presented as the screen is worse than an error,
+               because the user cannot tell. */
+            if (Date.now() - started >= timeoutMs) {
+                throw new Error(`the browser opened ${url} but the page had not finished rendering after ` +
+                    `${Math.round(timeoutMs / 1000)}s, so no screenshot was taken. The page may be waiting ` +
+                    'on a request that never returns.');
+            }
+            await new Promise(resolve => setTimeout(resolve, pollMs));
+        }
+    }
+    catch (err) {
+        stop();
+        await cleanup();
+        throw err;
+    }
+    /* THE BROWSER GOES BEFORE THIS RETURNS, always. The caller gets a path to a
+       file nothing is still holding, which is what makes `cleanup()` able to
+       succeed on Windows. */
+    stop();
+    /* Belt and braces against a `stat` that raced the write: the caller is about
+       to hand this to the PNG validator, and "no image was produced" is a far
+       better message than "not found at <path>". */
+    if (!existsSync(path)) {
+        await cleanup();
+        throw new Error(`the browser opened ${url} but produced no image`);
+    }
+    return { path, cleanup };
+}

package/dist/codebases.js

@@ -32,6 +32,21 @@ export async function listCodebases(client, projectId) {
         name: row.name,
     }));
 }
+/** Path-free availability rows for the signed-in user's machines. */
+export async function listCodebaseLocations(client, gitRemoteUrls) {
+    if (gitRemoteUrls.length === 0)
+        return [];
+    const { data, error } = await client
+        .from('cliv2_codebase_locations')
+        .select('machine_id, git_remote_url')
+        .in('git_remote_url', gitRemoteUrls);
+    if (error)
+        throw new Error(error.message);
+    return (data ?? []).map((row) => ({
+        machineId: row.machine_id,
+        gitRemoteUrl: row.git_remote_url,
+    }));
+}
 /**
  * A display name from a canonical `host/path` remote: its last `/` segment.
  * E.g. `github.com/acme/web` → `web`. Throws rather than ever returning an