toolroll 0.9.94 → 0.9.96

package/dist/protected-storage.js

@@ -15,14 +15,18 @@
  * OP_CONFIG_DIR, BITWARDENCLI_APPDATA_DIR, and the profiles Firefox's (and Zen's) profiles.ini places elsewhere.
  * Storage Toolroll doesn't know about (a browser started with its own --user-data-dir, a portable app) isn't covered.
  *
+ * Each launch's check is its own and finishes before the launch (prepareProtectedStorage): on a Mac it runs in a child
+ * process, so a privacy prompt never holds the thread that serves the console, and a check that can't finish refuses
+ * the launch in words that say which program macOS may need to allow. No earlier walk stands in for it.
+ *
  * The chat and vault variables (SLACK_*, TELEGRAM_*, DISCORD_*, TEAMS_*, OP_*, BW_*, BITWARDENCLI_*) are kept out of
  * every launch's environment (`withoutProtectedEnv`, exec.ts).
  */
-import { spawnSync } from "node:child_process";
-import { closeSync, existsSync, fstatSync, lstatSync, openSync, constants as fsConstants, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { closeSync, existsSync, fstatSync, lstatSync, openSync, constants as fsConstants, readSync, readdirSync, readlinkSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { configBase, namedFolder } from "./names.js";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 const AS = "Library/Application Support";
 const CONTAINERS = "Library/Containers";
 const GROUPS = "Library/Group Containers";
@@ -127,28 +131,38 @@ export function protectedStorageNames(home = homedir(), env = process.env, platf
             add(profile);
     return [...names].sort();
 }
-/** The absolute `Path=` entries of a profiles.ini in `root`, read only as the plain file it is, bounded. */
+/** The absolute `Path=` entries of a profiles.ini in `root`, read only as the plain file it is, bounded. On a Mac this
+ * runs only inside the storage check's child process (prepareProtectedStorage), where an open that waits on macOS
+ * holds up nothing else. */
 function profilesElsewhere(root) {
-    const file = join(root, "profiles.ini");
+    const text = profilesIniHere(join(root, "profiles.ini"));
+    return (text ?? "").split(/\r?\n/)
+        .map(line => /^\s*Path\s*=\s*(.+?)\s*$/i.exec(line)?.[1] ?? null)
+        .filter((path) => path !== null && isAbsolute(path));
+}
+function profilesIniHere(file) {
+    try {
+        lstatSync(file);
+    }
+    catch {
+        return null;
+    }
     let fd;
     try {
         fd = openSync(file, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
     }
     catch {
-        return [];
+        return null;
     }
     try {
         const held = fstatSync(fd);
         if (!held.isFile())
-            return [];
+            return null;
         const buffer = Buffer.alloc(Math.min(held.size, 64 * 1024));
-        const read = readSync(fd, buffer, 0, buffer.length, 0);
-        return buffer.subarray(0, read).toString("utf8").split(/\r?\n/)
-            .map(line => /^\s*Path\s*=\s*(.+?)\s*$/i.exec(line)?.[1] ?? null)
-            .filter((path) => path !== null && isAbsolute(path));
+        return buffer.subarray(0, readSync(fd, buffer, 0, buffer.length, 0)).toString("utf8");
     }
     catch {
-        return [];
+        return null;
     }
     finally {
         closeSync(fd);
@@ -156,26 +170,24 @@ function profilesElsewhere(root) {
 }
 const unwalkedSaid = new Set();
 /**
- * Every protected path one launch denies: each root by name and by real path, every link inside a present root that
- * leads outward (where it leads, by real path and as spelled), and the overrides. Resolved at each launch, never kept.
- * A link macOS makes in a sandboxed app's container to the same place under the home folder (its Desktop, Downloads,
- * Fonts…) is the system's own mirror of the person's folders, not the app's data, and isn't followed (systemMirror).
+ * The storage check, run right here: every root by name and by real path, every link inside a present root that leads
+ * outward (where it leads, by real path and as spelled), and the overrides. `unfinished` names each present root whose
+ * walk met an error other than "not there" or "not allowed": its links aren't all known. A link macOS makes in a
+ * sandboxed app's container to the same place under the home folder (its Desktop, Downloads, Fonts…) is the system's
+ * own mirror of the person's folders, not the app's data, and isn't followed (systemMirror).
  *
- * On a Mac, listing inside another app's container waits for the person to answer macOS's "access data from other apps"
- * prompt when the process asking has no answer yet (a plane run by launchd: every launch, and the console with it, hung
- * there in release check 3249). So the containers are walked only after a time-limited look in a child process
- * (`containers`, containersListable) shows they can be listed without waiting. A look that fails any other way refuses
- * the launch (it throws). When macOS is waiting on the person, the containers stay denied by name and real path, and
- * the outward links the last complete walk found (kept in the plane's own state folder, linkCacheFile) stay denied too;
- * with none kept, only the roots are denied, and that is said once.
+ * On a Mac a listing (or an open) inside another app's data can wait until a person answers a privacy prompt, so there
+ * this runs only in the check's own child process (prepareProtectedStorage), never on a thread that serves anything.
+ * `at` is told each root before its walk starts, so a check that runs out of time can name the app it was waiting on.
  */
-export function protectedStorageDenies(home = homedir(), env = process.env, platform = process.platform, say = line => process.stderr.write(`${line}\n`), containers = roots => containersListable(roots), list = path => readdirSync(path, { withFileTypes: true })) {
+export function protectedStorageHere(home = homedir(), env = process.env, platform = process.platform, say = () => { }, list = path => readdirSync(path, { withFileTypes: true }), at = () => { }) {
     const base = real(home);
+    const names = protectedStorageNames(base, env, platform);
     const out = new Set();
     const add = (path) => { if (!tooWide(path, base))
         out.add(path); };
-    const present = [];
-    for (const name of protectedStorageNames(base, env, platform)) {
+    const unfinished = [];
+    for (const name of names) {
         add(name);
         try {
             lstatSync(name);
@@ -185,36 +197,18 @@ export function protectedStorageDenies(home = homedir(), env = process.env, plat
         }
         const root = real(name);
         add(root);
-        present.push({ name, root });
-    }
-    const held = platform === "darwin" ? present.filter(one => inAppContainer(one.root, base)).map(one => one.root) : [];
-    // Throws when the look itself failed: the launch is refused, never fenced with less.
-    const listable = held.length === 0 || containers(held);
-    const cache = held.length === 0 ? null : linkCacheFile(base, env);
-    if (!listable) {
-        const kept = cache === null ? null : readLinkCache(cache, base);
-        for (const target of kept ?? [])
+        at(root);
+        const walked = { complete: true };
+        for (const target of outwardLinks(name, root, base, say, list, walked))
             add(target);
-        if (!unwalkedSaid.has(CONTAINERS_UNLISTED)) {
-            unwalkedSaid.add(CONTAINERS_UNLISTED);
-            say(`toolroll: fence: macOS didn't let Toolroll look inside other apps' containers without asking you; they stay denied, ${kept === null ? "but links inside them weren't checked" : "with the links found inside them when they were last checked"}. Allow Toolroll's service to access data from other apps (Privacy & Security) to check them now.`);
-        }
+        if (!walked.complete && !unfinished.includes(root))
+            unfinished.push(root);
     }
-    const walked = { complete: true }, inside = [];
-    for (const { name, root } of present) {
-        const container = held.includes(root);
-        if (container && !listable)
-            continue;
-        for (const target of outwardLinks(name, root, base, say, list, container ? walked : undefined)) {
-            add(target);
-            if (container)
-                inside.push(target);
-        }
-    }
-    // Only a walk of every container that met no error but "not there" or "not allowed" is kept for later.
-    if (listable && held.length > 0 && walked.complete && cache !== null)
-        writeLinkCache(cache, base, inside);
-    return [...out].sort();
+    return { names, denies: [...out].sort(), unfinished };
+}
+/** Every protected path, checked right here (protectedStorageHere), for a caller that has no prepared check. */
+export function protectedStorageDenies(home = homedir(), env = process.env, platform = process.platform, say, list) {
+    return protectedStorageHere(home, env, platform, say, list).denies;
 }
 /** Where the links inside a present root lead, when outside it: a walk that never follows a link, bounded. */
 function outwardLinks(name, root, home, say, list, walked) {
@@ -289,110 +283,165 @@ function systemMirror(link, root, target, home) {
     const known = CONTAINER_MIRRORS.has(named) || named === `Library/Application Scripts/${root.split(sep).at(-1)}`;
     return known && target === join(home, ...under);
 }
-/** The key `unwalkedSaid` keeps for "the containers couldn't be listed" (said once per process). */
-const CONTAINERS_UNLISTED = "\0containers";
-/** A root directly in the home folder's Library/Containers or Library/Group Containers: another app's container. */
-function inAppContainer(root, home) {
-    return dirname(root) === real(join(home, CONTAINERS)) || dirname(root) === real(join(home, GROUPS));
+/** The answers a walk takes as complete: the folder isn't there, or macOS refused it outright. */
+const ANSWERED = new Set(["ENOENT", "ENOTDIR", "EPERM", "EACCES"]);
+// ---- the check, off the thread ---------------------------------------------------------------------------------
+/** How long the storage check may take before the launch is refused (a slow Mac finishes well inside it). */
+export const STORAGE_LOOK_MS = 10_000;
+/** At most this much of the check's answer is read. */
+const LOOK_OUTPUT_MAX = 8 * 1024 * 1024;
+/** The plane's own variables the check reads (protectedStorageNames), handed to its child as they are here. */
+const STORAGE_ENV = ["XDG_CONFIG_HOME", "XDG_DATA_HOME", "OP_CONFIG_DIR", "BITWARDENCLI_APPDATA_DIR"];
+/** Why a launch didn't start: the storage check couldn't finish. Its words survive every catch (storageRefusalOf). */
+export class ProtectedStorageRefusal extends Error {
+    apps;
+    why;
+    code = "protected-storage";
+    constructor(apps, why, message) {
+        super(message);
+        this.apps = apps;
+        this.why = why;
+        this.name = "ProtectedStorageRefusal";
+    }
 }
-/** How long the look at other apps' containers may take before Toolroll takes it that macOS is waiting on the person. */
-export const CONTAINER_LOOK_MS = 3_000;
-/** How long a "can't list them" answer stands before the next launch looks again (the person may have allowed it since). */
-const CONTAINER_RELOOK_MS = 10 * 60_000;
-/** Each set of container roots' last answer: listable, or not and when that was seen. */
-const containerLooks = new Map();
-/** The look itself, in a child process: the same bounded walk `outwardLinks` makes, never following a link. */
-const CONTAINER_LOOK = `const fs=require("fs"),path=require("path");const [depth,limit,...roots]=process.argv.slice(1);
-for(const root of roots){let seen=0;const queue=[{p:root,d:0}];while(queue.length>0){const {p,d}=queue.shift();let entries;
-try{entries=fs.readdirSync(p,{withFileTypes:true});}catch{continue;}for(const e of entries){if(++seen>Number(limit)){queue.length=0;break;}
-if(!e.isSymbolicLink()&&e.isDirectory()&&d+1<Number(depth))queue.push({p:path.join(p,e.name),d:d+1});}}}`;
-/**
- * Whether this process can list inside these app containers without macOS stopping to ask the person: the walk run
- * first in a child process that is killed at CONTAINER_LOOK_MS. Finishing in time (listed, or refused outright) means
- * the walk can run here too; only running into that limit means macOS is waiting on the person (only the child waited).
- * A look that fails any other way is tried once more, then throws: the launch is refused rather than fenced with less.
- * A yes is kept (macOS keeps the person's answer); a no is looked at again after CONTAINER_RELOOK_MS.
- */
-export function containersListable(roots, look = lookInContainers, now = Date.now) {
-    const key = [...roots].sort().join("\0");
-    const last = containerLooks.get(key);
-    if (last !== undefined && (last.listable || now() - last.at < CONTAINER_RELOOK_MS))
-        return last.listable;
-    let answer = look(roots);
-    if (answer === "failed")
-        answer = look(roots);
-    if (answer === "failed")
-        throw new Error("Toolroll couldn't look inside other apps' containers to fence them (the look failed twice), so nothing was launched.");
-    const listable = answer === "listable";
-    containerLooks.set(key, { listable, at: now() });
-    return listable;
+/** The storage refusal inside a caught error, when it is one. */
+export function storageRefusalOf(error) {
+    return error instanceof ProtectedStorageRefusal ? error : null;
 }
-/** The child-process look (containersListable): node (or Electron as node) walks the roots, killed at its limit. */
-function lookInContainers(roots) {
-    const result = spawnSync(process.execPath, ["-e", CONTAINER_LOOK, String(PROTECTED_WALK.depth), String(PROTECTED_WALK.entries), ...roots], { stdio: "ignore", timeout: CONTAINER_LOOK_MS, killSignal: "SIGKILL", env: { ...process.env, ELECTRON_RUN_AS_NODE: "1" } });
-    return lookOutcome(result);
+/** The apps behind these roots, by name, for the words a person reads. */
+function appsOf(roots, home) {
+    const names = roots.map(root => PROTECTED_STORAGE.find(row => [...row.darwin, ...row.linux].some(one => real(join(home, one)) === root || join(home, one) === root))?.app ?? basename(root));
+    return [...new Set(names)];
 }
-/** A look's outcome from its child's result: only its own limit (ETIMEDOUT) is macOS waiting; any other error, signal
- * or exit code is a failed look. */
-export function lookOutcome(result) {
-    if (result.error?.code === "ETIMEDOUT")
-        return "waiting";
-    return result.error === undefined && result.signal === null && result.status === 0 ? "listable" : "failed";
+/** Which program macOS must allow: the one this plane runs as. A launchd service is its program itself; a plane started
+ * from a terminal asks as that terminal app. */
+export function storageAccessHolder(env = process.env, execPath = process.execPath, versions = process.versions) {
+    if (versions["electron"] !== undefined)
+        return "the Toolroll app";
+    const service = env["XPC_SERVICE_NAME"];
+    if (service !== undefined && service !== "" && service !== "0")
+        return `the program that keeps Toolroll running (${execPath})`;
+    const terminal = env["TERM_PROGRAM"];
+    if (terminal !== undefined && terminal !== "")
+        return `the terminal app Toolroll was started from (${terminal.replace(/\.app$/, "")})`;
+    return `the program Toolroll runs as (${execPath})`;
 }
-/** The answers a container walk takes as complete: the folder isn't there, or macOS refused it outright. */
-const ANSWERED = new Set(["ENOENT", "ENOTDIR", "EPERM", "EACCES"]);
-/** At most this much is ever read back from the link cache. */
-const LINK_CACHE_MAX = 256 * 1024;
-/** Where the outward links the last complete container walk found are kept: the plane's own state folder (fenced from
- * every build), one file per user. */
-export function linkCacheFile(home, env = process.env) {
-    return join(namedFolder(configBase({ ...env }, home)), "protected-links.json");
+/** Why nothing was launched, and what the person does about it. Never says macOS is asking: that isn't known. */
+export function storageRefusalWords(apps, why, holder) {
+    const named = apps.length === 0 ? "other apps" : apps.length === 1 ? apps[0] : `${apps.slice(0, -1).join(", ")} and ${apps.at(-1)}`;
+    const reason = why === "timed-out" ? ` (the check didn't finish within ${STORAGE_LOOK_MS / 1000} seconds)` : why === "unfinished" ? " (some of its folders couldn't be read)" : " (the check stopped with an error)";
+    return `Nothing was started: Toolroll couldn't finish checking ${apps.length === 0 ? "other apps'" : `${named}'s`} data for links to keep out of the build${reason}. `
+        + `macOS may need to let ${holder} read it: in System Settings → Privacy & Security → Full Disk Access, turn it on for ${holder}, then try again.`;
 }
-/** The kept links for this home: only a plain file of this user's (no link), at most LINK_CACHE_MAX, of exactly the
- * kept shape; anything else is no cache at all. */
-export function readLinkCache(file, home) {
-    let fd;
-    try {
-        const held = lstatSync(file);
-        if (!held.isFile() || held.size > LINK_CACHE_MAX || (process.getuid !== undefined && held.uid !== process.getuid()))
-            return null;
-        fd = openSync(file, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0));
-    }
-    catch {
-        return null;
+const inFlight = new Map();
+/**
+ * The storage check for one launch, awaited: what it denies, from a walk that finished just now. On a Mac the whole check
+ * (finding the roots, reading profiles.ini, every walk) runs in a child process, so a listing that waits on a privacy
+ * prompt holds up only that child; the thread that asked keeps serving. A check that doesn't finish within
+ * STORAGE_LOOK_MS, fails, or leaves a present root's walk unfinished refuses the launch (ProtectedStorageRefusal): no
+ * earlier walk stands in for it, since a link can move inside a root at any time. Checks asked for at once share one child.
+ */
+export async function prepareProtectedStorage(home = homedir(), env = process.env, platform = process.platform, look = lookInChild, holder = storageAccessHolder(env)) {
+    const base = real(home);
+    const request = { home: base, env: Object.fromEntries(STORAGE_ENV.flatMap(name => env[name] === undefined ? [] : [[name, env[name]]])), platform };
+    let answer;
+    if (platform !== "darwin") {
+        // No privacy prompt can hold a listing here: the check runs as it is.
+        const here = protectedStorageHere(base, env, platform, line => process.stderr.write(`${line}\n`));
+        answer = { kind: "done", storage: { names: here.names, denies: here.denies }, unfinished: here.unfinished };
     }
-    try {
-        const opened = fstatSync(fd);
-        if (!opened.isFile() || opened.size > LINK_CACHE_MAX || (process.getuid !== undefined && opened.uid !== process.getuid()))
-            return null;
-        const buffer = Buffer.alloc(opened.size);
-        const read = readSync(fd, buffer, 0, buffer.length, 0);
-        const value = JSON.parse(buffer.subarray(0, read).toString("utf8"));
-        if (value === null || typeof value !== "object" || Array.isArray(value))
-            return null;
-        const { version, home: kept, targets } = value;
-        if (version !== 1 || kept !== home || !Array.isArray(targets) || targets.some(one => typeof one !== "string" || !isAbsolute(one)))
-            return null;
-        return targets;
+    else {
+        const key = JSON.stringify(request);
+        let pending = inFlight.get(key);
+        if (pending === undefined) {
+            pending = look(request).finally(() => inFlight.delete(key));
+            inFlight.set(key, pending);
+        }
+        answer = await pending;
     }
-    catch {
-        return null;
+    if (answer.kind === "timed-out") {
+        const apps = answer.at === null ? [] : appsOf([answer.at], base);
+        throw new ProtectedStorageRefusal(apps, "timed-out", storageRefusalWords(apps, "timed-out", holder));
     }
-    finally {
-        closeSync(fd);
+    if (answer.kind === "failed")
+        throw new ProtectedStorageRefusal([], "failed", storageRefusalWords([], "failed", holder));
+    if (answer.unfinished.length > 0) {
+        const apps = appsOf(answer.unfinished, base);
+        throw new ProtectedStorageRefusal(apps, "unfinished", storageRefusalWords(apps, "unfinished", holder));
     }
+    return answer.storage;
+}
+/** Where the check's child script is: beside this module once built, else the built copy (a run from source). */
+export function storageLookScript() {
+    const beside = fileURLToPath(new URL("./protected-storage-look.js", import.meta.url));
+    return existsSync(beside) ? beside : fileURLToPath(new URL("../dist/protected-storage-look.js", import.meta.url));
+}
+/** The default check: node (or Electron as node) runs protected-storage-look.js, killed at STORAGE_LOOK_MS. */
+async function lookInChild(request) {
+    return readLook(await spawnLook(process.execPath, [storageLookScript(), JSON.stringify(request)], STORAGE_LOOK_MS));
 }
-/** Keep a complete walk's links: written aside (owner-only) and renamed into place, only into a state folder that is
- * already there. A failed write keeps whatever was kept before. */
-export function writeLinkCache(file, home, targets) {
-    if (!existsSync(dirname(file)))
-        return;
-    const aside = `${file}.${process.pid}.part`;
+/** A finished child's lines as the check's answer: `at\t<root>` before each walk, `done\t<answer>` once at the end. */
+export function readLook(ran) {
+    const lines = ran.stdout.split("\n");
+    const last = [...lines].reverse().find(line => line.startsWith("at\t"));
+    const at = last === undefined ? null : (() => { try {
+        const root = JSON.parse(last.slice(3));
+        return typeof root === "string" && isAbsolute(root) ? root : null;
+    }
+    catch {
+        return null;
+    } })();
+    if (ran.outcome === "timed-out")
+        return { kind: "timed-out", at };
+    if (ran.outcome === "failed")
+        return { kind: "failed", detail: ran.detail };
+    const done = lines.find(line => line.startsWith("done\t"));
+    if (done === undefined)
+        return { kind: "failed", detail: "the check gave no answer" };
     try {
-        writeFileSync(aside, JSON.stringify({ version: 1, home, targets: [...new Set(targets)].sort() }), { mode: 0o600, flag: "wx" });
-        renameSync(aside, file);
+        const value = JSON.parse(done.slice(5));
+        const paths = (one) => Array.isArray(one) && one.every(path => typeof path === "string" && isAbsolute(path)) ? one : null;
+        const names = paths(value["names"]), denies = paths(value["denies"]), unfinished = paths(value["unfinished"]);
+        if (names === null || denies === null || unfinished === null)
+            return { kind: "failed", detail: "the check's answer can't be read" };
+        return { kind: "done", storage: { names, denies }, unfinished };
     }
     catch {
-        rmSync(aside, { force: true });
+        return { kind: "failed", detail: "the check's answer can't be read" };
     }
 }
+/** Run a child without waiting on this thread: its output, bounded, and how it ended. Killed at `limitMs`. */
+export function spawnLook(command, args, limitMs) {
+    return new Promise(settle => {
+        let stdout = "", over = false, timedOut = false, settled = false;
+        const finish = (outcome, detail) => { if (settled)
+            return; settled = true; clearTimeout(timer); settle({ stdout, outcome, detail }); };
+        let child;
+        try {
+            child = spawn(command, [...args], { stdio: ["ignore", "pipe", "ignore"], env: { ...process.env, ELECTRON_RUN_AS_NODE: "1" } });
+        }
+        catch (error) {
+            settle({ stdout: "", outcome: "failed", detail: error instanceof Error ? error.message : String(error) });
+            return;
+        }
+        const timer = setTimeout(() => { timedOut = true; child.kill("SIGKILL"); }, limitMs);
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => { if (stdout.length + chunk.length > LOOK_OUTPUT_MAX) {
+            over = true;
+            child.kill("SIGKILL");
+        }
+        else
+            stdout += chunk; });
+        child.on("error", error => finish("failed", error.message));
+        child.on("close", (code, signal) => {
+            if (timedOut)
+                finish("timed-out", "");
+            else if (over)
+                finish("failed", "the check said too much");
+            else if (code === 0 && signal === null)
+                finish("done", "");
+            else
+                finish("failed", signal === null ? `the check exited with ${code}` : `the check was stopped (${signal})`);
+        });
+    });
+}

package/dist/provider-capture.d.ts

@@ -0,0 +1,34 @@
+import type { Store } from "./store.js";
+export declare const CAPTURE_TEXT_LIMIT = 4000;
+export type ProviderCapture = {
+    id: number;
+    run: number;
+    repo: string | null;
+    provider: string;
+    model: string | null;
+    authMode: string | null;
+    exitCode: number | null;
+    code: string | null;
+    text: string;
+    hint: boolean;
+    label: "exhausted" | "not-exhausted" | null;
+    labelledBy: string | null;
+    at: string;
+};
+/** Save one failed attempt's last words. Bookkeeping: it never costs the run anything. */
+export declare function captureProviderFailure(store: Store, input: {
+    run: number;
+    provider: string;
+    model: string | null;
+    authMode: string | null;
+    exitCode: number | null;
+    code: string | null;
+    texts: readonly (string | null | undefined)[];
+}, now: Date): void;
+/** Newest first, the ones mentioning limits at the top. */
+export declare function providerCaptures(store: Store, repos: readonly string[] | null, limit?: number): ProviderCapture[];
+export declare function providerCapture(store: Store, id: number): ProviderCapture | null;
+/** A person's reading of one capture. It marks it for keeping, and nothing routes on it. */
+export declare function labelProviderCapture(store: Store, id: number, label: "exhausted" | "not-exhausted", by: string): boolean;
+/** What goes in a fixture file: the provider's response and which version of what produced it. */
+export declare function captureFixture(capture: ProviderCapture): Record<string, unknown>;

package/dist/provider-capture.js

@@ -0,0 +1,53 @@
+/**
+ * What a provider said when an attempt failed, saved for a person (docs/plans/fleet-follow-through.md, part 5).
+ *
+ * Fallback between agents was removed in v115, and exhaustion.ts recognises only a dead sign-in. Telling a used-up
+ * subscription from any other failure needs a REAL response, so this saves them as they happen and nothing else. Nothing
+ * reads this table to route work: `hint` is a sort key for a person, never a recogniser, and a person's label decides
+ * nothing either. The text is the provider's, so it is data, scrubbed of secrets and bounded.
+ */
+import { readingFleet } from "./fleet-schema.js";
+import { cleanFindingText } from "./findings.js";
+export const CAPTURE_TEXT_LIMIT = 4_000;
+/** Kept per provider, newest first. A labelled capture is never pruned: it is the evidence a person kept. */
+const CAPTURES_KEPT = 40;
+/** Words worth a person's look. Only ever a sort key. */
+const LIMIT_WORDS = /\b(usage limit|rate limit|quota|credit|billing|exhaust|limit reached|too many requests|429|payment)/i;
+/** Save one failed attempt's last words. Bookkeeping: it never costs the run anything. */
+export function captureProviderFailure(store, input, now) {
+    try {
+        const text = cleanFindingText(input.texts.filter((one) => typeof one === "string" && one.trim() !== "").join("\n"), CAPTURE_TEXT_LIMIT);
+        if (text === "" && input.code === null)
+            return;
+        const run = store.getRun(input.run);
+        const repo = run === null ? null : store.refById(run.taskRef)?.repo ?? null;
+        store.handle.prepare(`INSERT INTO provider_capture (run, repo, provider, model, auth_mode, exit_code, code, text, hint, at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT (run) DO NOTHING`)
+            .run(input.run, repo, input.provider, input.model, input.authMode, input.exitCode, input.code === null ? null : cleanFindingText(input.code, 120), text, LIMIT_WORDS.test(`${input.code ?? ""} ${text}`) ? 1 : 0, now.toISOString());
+        store.handle.prepare(`DELETE FROM provider_capture WHERE provider = ? AND label IS NULL AND id NOT IN (SELECT id FROM provider_capture WHERE provider = ? ORDER BY id DESC LIMIT ?)`).run(input.provider, input.provider, CAPTURES_KEPT);
+    }
+    catch { /* a capture is never worth a run */ }
+}
+const captureOf = (row) => ({
+    id: Number(row["id"]), run: Number(row["run"]), repo: row["repo"] === null ? null : String(row["repo"]), provider: String(row["provider"]), model: row["model"] === null ? null : String(row["model"]),
+    authMode: row["auth_mode"] === null ? null : String(row["auth_mode"]), exitCode: row["exit_code"] === null ? null : Number(row["exit_code"]), code: row["code"] === null ? null : String(row["code"]),
+    text: String(row["text"]), hint: Number(row["hint"]) === 1, label: row["label"] === null ? null : String(row["label"]), labelledBy: row["labelled_by"] === null ? null : String(row["labelled_by"]), at: String(row["at"]),
+});
+/** Newest first, the ones mentioning limits at the top. */
+export function providerCaptures(store, repos, limit = 50) {
+    return readingFleet(() => store.handle.prepare("SELECT * FROM provider_capture ORDER BY hint DESC, id DESC LIMIT 500").all().map(captureOf)
+        .filter(one => repos === null || (one.repo !== null && repos.includes(one.repo))).slice(0, limit), []);
+}
+export function providerCapture(store, id) {
+    return readingFleet(() => {
+        const row = store.handle.prepare("SELECT * FROM provider_capture WHERE id = ?").get(id);
+        return row === undefined ? null : captureOf(row);
+    }, null);
+}
+/** A person's reading of one capture. It marks it for keeping, and nothing routes on it. */
+export function labelProviderCapture(store, id, label, by) {
+    return Number(store.handle.prepare("UPDATE provider_capture SET label = ?, labelled_by = ? WHERE id = ?").run(label, by, id).changes) === 1;
+}
+/** What goes in a fixture file: the provider's response and which version of what produced it. */
+export function captureFixture(capture) {
+    return { version: 1, provider: capture.provider, model: capture.model, authMode: capture.authMode, exitCode: capture.exitCode, code: capture.code, text: capture.text, label: capture.label, labelledBy: capture.labelledBy, capturedAt: capture.at };
+}

package/dist/release-carry.js

@@ -19,6 +19,7 @@
  * read only Toolroll's records and verified objects. (Coverage, in release-recheck.ts, trusts test code by Alex's
  * explicit decision; nothing here does.)
  */
+import { prepareProtectedStorage, storageRefusalOf } from "./protected-storage.js";
 import { createHash, randomUUID } from "node:crypto";
 import { closeSync, constants, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -304,11 +305,19 @@ export function fencedBuildRunner(store) {
         if (!macosFenceAvailable() && !linuxFenceAvailable()) {
             return { code: 1, stdout: "", stderr: "This machine can't confine the build (no macOS sandbox, no working bubblewrap), so it didn't run.\n", timedOut: false, notFound: false };
         }
+        // The storage check, awaited off this thread (protected-storage.ts); its words are the build's when it can't finish.
+        let storage;
+        try {
+            storage = await prepareProtectedStorage();
+        }
+        catch (error) {
+            return { code: 1, stdout: "", stderr: `${storageRefusalOf(error)?.message ?? "The build's fence could not be prepared, so it didn't run."}\n`, timedOut: false, notFound: false };
+        }
         const egress = await startEgressProxy({ hosts: [] });
         try {
             const network = { mode: "allowlist", proxyPort: egress.port, brokerPorts: [], loopback: "proxy-only", socketRoots: [...options.writable], token: egress.secret };
             const launch = fenceFor("check", {
-                databaseFile: store.databaseFile(), worktree: options.cwd, boundary: null, binding: null, runFolders: runFolders(null), poolRoots: [],
+                databaseFile: store.databaseFile(), worktree: options.cwd, boundary: null, binding: null, runFolders: runFolders(null), poolRoots: [], storage,
                 writes: { writes: { subpaths: [...options.writable], prefixes: [] }, readOnly: [] }, network,
             });
             return await run(file, args, { cwd: options.cwd, env: { ...options.env, ...proxyEnv(egress, "proxy-only") }, timeoutMs: options.timeoutMs, processGroup: true,

package/dist/release.js

@@ -93,6 +93,8 @@ export const ADVISORY_PR_CHECKS = {
     "youiyoux · UI drift": ".github/workflows/youiyoux.yml",
     "journeys · app (scripted)": ".github/workflows/journeys.yml",
     "journeys · flows (scripted)": ".github/workflows/journeys.yml",
+    "upgrade path · scope": ".github/workflows/upgrade-path.yml",
+    "upgrade path": ".github/workflows/upgrade-path.yml",
 };
 /** The checks a release's publication waits for on its tag (.github/workflows/publish.yml, docs/plans/test-matrix.md):
  * the release proof (the tagged tree passed every REQUIRED_PR_CHECKS check on its pull request, read from GitHub) and
@@ -249,6 +251,8 @@ export async function runRelease(options, adapters) {
     let step = "preflight";
     let freshApproval = false;
     let supersededTask = null;
+    /** The commit whose check stopped the release being set aside. The stop tells a person to approve it again with --new. */
+    let stoppedCheck = null;
     const save = () => { journal.updatedAt = adapters.now().toISOString(); writeJournal(file, journal); };
     /** Tell the progress record about a step (v146). Never throws and never waits: the release goes on whatever it says. */
     const mark = (at, state, detail = null) => {
@@ -322,6 +326,8 @@ export async function runRelease(options, adapters) {
             say(`Kept the earlier release journal at ${aside}.`);
             freshApproval = journal.needsApproval === true;
             supersededTask = journal.task.id;
+            if (journal.stopped?.reason === "check-failed")
+                stoppedCheck = journal.candidate.sha;
             journal = null;
         }
         if (journal?.step === "done") {
@@ -336,8 +342,10 @@ export async function runRelease(options, adapters) {
             journal = await begin(options, adapters, adapters.now());
             // The earlier attempt needs a person's fresh approval (a CI failure after its deploy): this one files a task of its
             // own for the same commit, so the old approval can't carry it.
+            // A check that stopped this same commit is the same: its task keeps that failure, so reusing it would only stop again
+            // (a passing run on it, run 3333, can't erase it). A new task reruns the check and asks a person, never the plane.
             // Only an id that has never existed, numbered after the superseded one: never a task whose approval still stands.
-            if (freshApproval) {
+            if (freshApproval || journal.candidate.sha === stoppedCheck) {
                 const base = journal.task.id;
                 const suffix = supersededTask === null ? null : supersededTask === base ? 1 : supersededTask.startsWith(`${base}-`) ? Number(supersededTask.slice(base.length + 1)) : null;
                 let picked = null;