toolroll 0.9.104 → 0.9.105

package/dist/protected-storage.js

@@ -1,27 +1,3 @@
-/**
- * Protected storage (docs/plans/chat-management.md §1.1): where the person's chat apps, browser profiles and password
- * managers keep their sessions, denied to every launch Toolroll fences, read and write, under both fence policies and
- * on every backend. A linked chat account is not proof of a person: whatever holds the Slack desktop's token, Telegram
- * Desktop's `tdata` or a browser's cookies can press the bot's buttons as them. So no build, check, flow or tool server
- * may read those, whatever its project's settings say.
- *
- * The list is outside HOME_CONFIGURATION (agent-fence.ts), which only version-1 fences read: `agentFence` adds these to
- * every fence it makes, as paths no grant can reopen, and `taskBoundary` names them for both policies.
- *
- * Each root is denied by its name, present or not (a build can't make the folder now and swap in a link later), and by
- * its real path (a root that is itself a link to a relocated folder). Inside each present root a bounded walk that
- * never follows a link finds links leading outward and denies where they lead. The overrides Toolroll can know are read
- * from the plane's own environment at each launch, never from a checkout: XDG_CONFIG_HOME and XDG_DATA_HOME (Linux),
- * 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 { 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";
@@ -30,17 +6,12 @@ import { fileURLToPath } from "node:url";
 const AS = "Library/Application Support";
 const CONTAINERS = "Library/Containers";
 const GROUPS = "Library/Group Containers";
-/**
- * Every listed root. Checked against a real Mac (2026-10-25): existence only, never a file's contents. The 1Password
- * containers and the extra Chrome, Edge and other browsers' folders below were found there and added.
- */
 export const PROTECTED_STORAGE = [
     { app: "Slack", darwin: [`${AS}/Slack`, `${CONTAINERS}/com.tinyspeck.slackmacgap`], linux: [".config/Slack", "snap/slack", ".var/app/com.slack.Slack"] },
     { app: "Telegram", darwin: [`${AS}/Telegram Desktop`, `${CONTAINERS}/org.telegram.desktop`, `${GROUPS}/6N38VWS5BX.ru.keepcoder.Telegram`, `${CONTAINERS}/ru.keepcoder.Telegram`],
         linux: [".local/share/TelegramDesktop", "snap/telegram-desktop", ".var/app/org.telegram.desktop"] },
     { app: "Discord", darwin: [`${AS}/discord`, `${AS}/discordptb`, `${AS}/discordcanary`],
         linux: [".config/discord", ".config/discordptb", ".config/discordcanary", "snap/discord", ".var/app/com.discordapp.Discord"] },
-    // New Teams keeps its sign-in in Microsoft's shared sign-in cache (OneAuth) too.
     { app: "Teams", darwin: [`${CONTAINERS}/com.microsoft.teams2`, `${GROUPS}/UBF8T346G9.com.microsoft.teams`, `${AS}/Microsoft/Teams`, `${GROUPS}/UBF8T346G9.com.microsoft.oneauth`],
         linux: [".config/Microsoft/Microsoft Teams", ".config/teams-for-linux"] },
     { app: "WhatsApp", darwin: [`${CONTAINERS}/net.whatsapp.WhatsApp`, `${GROUPS}/group.net.whatsapp.WhatsApp.shared`, `${GROUPS}/group.net.whatsapp.WhatsApp.private`, `${GROUPS}/group.net.whatsapp.family`], linux: [] },
@@ -51,7 +22,6 @@ export const PROTECTED_STORAGE = [
         linux: [".config/1Password", "snap/1password", ".var/app/com.onepassword.OnePassword", ".config/op", ".op"] },
     { app: "Bitwarden", darwin: [`${AS}/Bitwarden`, `${CONTAINERS}/com.bitwarden.desktop`, `${GROUPS}/LTZ2PFU5D6.com.bitwarden.desktop`, `${AS}/Bitwarden CLI`],
         linux: [".config/Bitwarden", "snap/bitwarden", ".var/app/com.bitwarden.desktop", ".config/Bitwarden CLI"] },
-    // The browser extensions of both password managers live inside the browser profiles below.
     { app: "Chrome", darwin: [`${AS}/Google/Chrome`, `${AS}/Google/Chrome Beta`, `${AS}/Google/Chrome Canary`, `${AS}/Google/Chrome Dev`],
         linux: [".config/google-chrome", ".config/google-chrome-beta", ".config/google-chrome-unstable", ".var/app/com.google.Chrome"] },
     { app: "Chromium", darwin: [`${AS}/Chromium`], linux: [".config/chromium", "snap/chromium", ".var/app/org.chromium.Chromium"] },
@@ -66,18 +36,15 @@ export const PROTECTED_STORAGE = [
     { app: "Orion", darwin: [`${AS}/Orion`], linux: [] },
     { app: "Safari", darwin: ["Library/Safari", `${CONTAINERS}/com.apple.Safari`, `${CONTAINERS}/com.apple.Safari.WebApp`, "Library/Cookies", "Library/HTTPStorages", "Library/WebKit"], linux: [] },
 ];
-/** The roots whose profiles.ini may place a profile anywhere (Firefox and its forks). */
 const PROFILE_INDEXES = {
     darwin: [`${AS}/Firefox`, `${AS}/zen`],
     linux: [".mozilla/firefox", "snap/firefox/common/.mozilla/firefox", ".var/app/org.mozilla.firefox/.mozilla/firefox", ".zen"],
 };
-/** The chat and vault variables no launch gets. */
 export const PROTECTED_ENV_PREFIXES = ["SLACK_", "TELEGRAM_", "DISCORD_", "TEAMS_", "OP_", "BW_", "BITWARDENCLI_"];
 export function isProtectedEnvName(name) {
     const upper = name.toUpperCase();
     return PROTECTED_ENV_PREFIXES.some(prefix => upper.startsWith(prefix));
 }
-/** `env` without a chat or vault variable. */
 export function withoutProtectedEnv(env) {
     const out = { ...env };
     for (const name of Object.keys(out))
@@ -85,7 +52,6 @@ export function withoutProtectedEnv(env) {
             delete out[name];
     return out;
 }
-/** How far the link walk goes in each present root. */
 export const PROTECTED_WALK = { depth: 4, entries: 5_000 };
 const real = (path) => { try {
     return realpathSync(path);
@@ -95,11 +61,9 @@ catch {
 } };
 const within = (child, parent) => { const rel = relative(parent, child); return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel); };
 const platformOf = (platform) => platform === "darwin" ? "darwin" : platform === "linux" ? "linux" : null;
-/** A path the fence can't deny without denying the machine: `/`, the home folder or a folder above it. */
 function tooWide(path, home) {
     return !isAbsolute(path) || path === dirname(path) || path === home || within(home, path);
 }
-/** The roots by name, under the (real) home folder and the overrides the plane's environment names. */
 export function protectedStorageNames(home = homedir(), env = process.env, platform = process.platform) {
     const os = platformOf(platform);
     if (os === null)
@@ -131,9 +95,6 @@ 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. 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 text = profilesIniHere(join(root, "profiles.ini"));
     return (text ?? "").split(/\r?\n/)
@@ -169,17 +130,6 @@ function profilesIniHere(file) {
     }
 }
 const unwalkedSaid = new Set();
-/**
- * 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 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 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);
@@ -193,7 +143,7 @@ export function protectedStorageHere(home = homedir(), env = process.env, platfo
             lstatSync(name);
         }
         catch {
-            continue; /* denied by name only */
+            continue;
         }
         const root = real(name);
         add(root);
@@ -206,11 +156,9 @@ export function protectedStorageHere(home = homedir(), env = process.env, platfo
     }
     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) {
     const found = [];
     let seen = 0;
@@ -258,19 +206,11 @@ function outwardLinks(name, root, home, say, list, walked) {
     }
     return found;
 }
-/** The links macOS makes in every sandboxed app's container (`Data/X` → `~/X`), as found on a real Mac (2026-10-26). */
 const CONTAINER_MIRRORS = new Set([".CFUserTextEncoding", "Desktop", "Downloads", "Movies", "Music", "Pictures",
     ...["Audio", "Calendars", "ColorPickers", "ColorSync", "Colors", "Components", "Compositions", "Dictionaries", "Favorites", "Filters", "FontCollections", "Fonts",
         "Input Methods", "KeyBindings", "Keyboard Layouts", "Keychains", "Mail", "PDF Services", "QuickLook", "Sounds", "Spelling", "Images/People",
         "Application Support/AddressBook", "Application Support/iCloud", "Application Support/SyncServices",
         "Preferences/com.apple.security.plist", "Preferences/com.apple.security_common.plist"].map(one => `Library/${one}`)]);
-/**
- * The system's own redirect in a sandboxed app's container, and nothing else: the root is an app container (its links
- * under `Data/`) or a group container, directly in the home folder's Library, and the link is one macOS makes there
- * (CONTAINER_MIRRORS, or the app's own Application Scripts folder) leading to the same place under the home folder.
- * Any other outward link — in a browser profile, a password manager's folder, or an unknown name in a container — is
- * where that app's data was moved, and is denied.
- */
 function systemMirror(link, root, target, home) {
     const app = dirname(root) === real(join(home, CONTAINERS)), group = dirname(root) === real(join(home, GROUPS));
     if (!app && !group)
@@ -283,16 +223,10 @@ 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 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;
@@ -304,17 +238,13 @@ export class ProtectedStorageRefusal extends Error {
         this.name = "ProtectedStorageRefusal";
     }
 }
-/** The storage refusal inside a caught error, when it is one. */
 export function storageRefusalOf(error) {
     return error instanceof ProtectedStorageRefusal ? error : null;
 }
-/** 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)];
 }
-/** 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";
@@ -326,7 +256,6 @@ export function storageAccessHolder(env = process.env, execPath = process.execPa
         return `the terminal app Toolroll was started from (${terminal.replace(/\.app$/, "")})`;
     return `the program Toolroll runs as (${execPath})`;
 }
-/** 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)";
@@ -334,19 +263,11 @@ export function storageRefusalWords(apps, why, holder) {
         + `macOS may need to let ${holder} read it: in System Settings → Privacy & Security → Full Disk Access, turn it on for ${holder}, then try again.`;
 }
 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 };
     }
@@ -371,16 +292,13 @@ export async function prepareProtectedStorage(home = homedir(), env = process.en
     }
     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));
 }
-/** 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"));
@@ -410,7 +328,6 @@ export function readLook(ran) {
         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;

package/dist/provider-auth.js

@@ -1,8 +1,5 @@
 import { PROVIDER_IDS } from "./provider.js";
 import { withAcp } from "./acp-agents.js";
-/** Every sign-in message's dedupe key starts here: `signin:<kind>:<provider>:<ordinal>:<person>`.
- * Not a lifecycle (`life:`) key: those are progress chatter, and an undelivered
- * one stays out of the attention list — this one needs a person. */
 export const SIGN_IN_KEY_PREFIX = "signin:";
 export const PROVIDER_AUTH_SCHEMA = `
 CREATE TABLE IF NOT EXISTS provider_auth_pause (
@@ -33,23 +30,17 @@ const SIGN_IN = withAcp({ claude: "claude /login", codex: "codex login", gemini:
 export function providerName(provider) {
     return PROVIDER_IDS.includes(provider) ? NAMES[provider] : provider;
 }
-/** The plain reason: "Claude needs you to sign in again". */
 export function signInReason(pause) {
     const name = providerName(pause.provider);
     return pause.authMode === "api-key" ? `${name} needs a working API key` : `${name} needs you to sign in again`;
 }
-/** What to run, as a command. */
 export function signInCommand(pause) {
     return pause.authMode === "api-key" && pause.provider !== "openrouter" ? `toolroll keys set ${pause.provider}` : SIGN_IN[pause.provider];
 }
-/** The same command for a chat message: the phone scrub hides anything shaped
- * like a path (`/login` included), so a message names Claude's equivalent
- * `claude auth login`. */
 export function messageCommand(pause) {
     const command = signInCommand(pause);
     return command === "claude /login" ? "claude auth login" : command;
 }
-/** One line for status, ready and the console. */
 export function signInWords(pause) {
     return `${signInReason(pause)}. Run \`${signInCommand(pause)}\` on this computer; its tasks start again on their own once it works (or \`toolroll providers resume ${pause.provider}\`).`;
 }
@@ -65,19 +56,10 @@ function readPause(row) {
         runs: Number(row["runs"]),
     };
 }
-/** The open pause for a provider, or null. */
 export function authPauseOf(store, provider) {
     const row = store.handle.prepare("SELECT * FROM provider_auth_pause WHERE provider = ? AND lifted_at IS NULL").get(provider);
     return row === undefined ? null : readPause(row);
 }
-/**
- * SQL: whether the pause `pause` (a provider_auth_pause alias) is on one of
- * the task_ref `taskRef`'s current providers — its pins, its working profile,
- * and route legs — so a task re-routed to another provider
- * stops saying it waits on the old one. A task that names none yet (an
- * unpinned planner, whose agent comes from configuration) keeps what the gate
- * found.
- */
 export function pauseOnTaskProviders(pause, taskRef) {
     const providers = `SELECT r.agent_provider provider FROM task_ref r WHERE r.id = ${taskRef}
     UNION ALL SELECT r.plan_provider FROM task_ref r WHERE r.id = ${taskRef}
@@ -88,22 +70,14 @@ export function pauseOnTaskProviders(pause, taskRef) {
     return `(${pause}.provider IN (SELECT provider FROM (${providers}) WHERE provider IS NOT NULL)
     OR NOT EXISTS (SELECT 1 FROM (${providers}) WHERE provider IS NOT NULL))`;
 }
-/** The open pause the dispatch gate last left this task waiting on, while it
- * is still on one of the task's providers; or null. */
 export function authWaitOf(store, taskRef) {
     const row = store.handle.prepare(`SELECT p.* FROM task_ref r JOIN provider_auth_pause p ON p.id = r.auth_wait_pause
     WHERE r.id = ? AND p.lifted_at IS NULL AND ${pauseOnTaskProviders("p", "r.id")}`).get(taskRef);
     return row === undefined ? null : readPause(row);
 }
-/** Every open pause, oldest first. */
 export function openAuthPauses(store) {
     return store.handle.prepare("SELECT * FROM provider_auth_pause WHERE lifted_at IS NULL ORDER BY id").all().map(readPause);
 }
-/**
- * Record an auth-expired run against its provider's pause, opening the
- * incident (and its one notification) when none is open. Called inside the
- * run's own failure transaction. Returns whether this run opened it.
- */
 export function pauseForAuth(store, args) {
     return store.transact(() => {
         const db = store.handle;
@@ -124,12 +98,6 @@ export function pauseForAuth(store, args) {
         return { opened: true, pause };
     });
 }
-/**
- * One message per instance operator, addressed to them: only someone at this
- * computer can sign an agent back in, and a personal notification reaches that
- * person on every channel they paired (Telegram, Slack, Discord, Teams) and in
- * the console, whichever projects those channels follow.
- */
 function notifyOperators(store, key, message, now) {
     const operators = store.accountFacts().map(one => one.name).filter(name => store.isInstanceOperator(name));
     for (const recipient of operators) {
@@ -145,15 +113,7 @@ function notifyOperators(store, key, message, now) {
         }, now);
     }
 }
-/**
- * Lift a provider's open pause — a run or probe on it succeeded, or a person
- * resumed it — and send the one short "signed in again" message. Returns the
- * number of tasks its incident sent back to the queue, or null when nothing
- * was paused.
- */
-export function liftAuthPause(store, provider, how, by, now, 
-/** For a run: when it started. A run that began before the pause opened proves nothing about the sign-in now. */
-runStartedAt) {
+export function liftAuthPause(store, provider, how, by, now, runStartedAt) {
     return store.transact(() => {
         const pause = authPauseOf(store, provider);
         if (pause === null)
@@ -178,12 +138,6 @@ runStartedAt) {
         return { resumed, pause };
     });
 }
-/**
- * What a non-spending sign-in probe said. A probe lifts the pause only after
- * one during the same pause saw the provider signed out: a CLI that reports
- * "logged in" while its session cannot refresh must not lift and re-open the
- * pause over and over.
- */
 export function noteSignInProbe(store, provider, state, now) {
     const pause = authPauseOf(store, provider);
     if (pause === null)
@@ -200,14 +154,7 @@ export function noteSignInProbe(store, provider, state, now) {
     const lifted = liftAuthPause(store, provider, "probe", "sign-in check", now);
     return lifted === null ? null : { resumed: lifted.resumed };
 }
-/** How often a paused provider lets one task through as a trial. */
 export const AUTH_TRIAL_MS = 10 * 60_000;
-/**
- * Whether this task may go ahead as the paused provider's trial: at most one
- * every AUTH_TRIAL_MS. A trial that works lifts the pause (its run proves the
- * sign-in); one that fails the same way only counts against the open
- * incident, so nobody is told twice. Null when no trial is due.
- */
 export function claimAuthTrial(store, pause, now) {
     return store.transact(() => {
         const due = new Date(now.getTime() - AUTH_TRIAL_MS).toISOString();
@@ -219,19 +166,10 @@ export function claimAuthTrial(store, pause, now) {
         return Number(claimed.changes) === 1 ? { pauseId: pause.id, takenAt, previous } : null;
     });
 }
-/** Give a trial back when its task never started (its claim failed), so the next pass may take it. */
 export function giveBackAuthTrial(store, trial) {
     store.handle.prepare("UPDATE provider_auth_pause SET last_trial_at = ? WHERE id = ? AND last_trial_at = ? AND lifted_at IS NULL")
         .run(trial.previous, trial.pauseId, trial.takenAt);
 }
-/**
- * The sign-in gate every road that starts an agent asks before it claims
- * anything: the tick's queue and the roads beside it.
- * Waits when a provider is paused,
- * unless this is the pause's one trial. A waiting task is noted on its
- * task_ref, so the work index says exactly what the gate decided; a task let
- * through is un-noted. A road whose claim fails after a trial calls giveBack.
- */
 export function signInGate(store, providers, now, taskRef) {
     const pause = [...new Set(providers)].map(one => authPauseOf(store, one)).find(one => one !== null) ?? null;
     const trial = pause === null ? null : claimAuthTrial(store, pause, now);
@@ -250,9 +188,6 @@ export function signInGate(store, providers, now, taskRef) {
         },
     };
 }
-/** The loop beside the console: every two minutes, probe each paused
- * provider's sign-in (no model, nothing spent) and lift the pause when it
- * works again. Nothing is probed while nothing is paused. */
 export function startSignInProbes(store, check, everyMs = 120_000) {
     let stopped = false;
     let running = false;
@@ -265,10 +200,10 @@ export function startSignInProbes(store, check, everyMs = 120_000) {
                 try {
                     noteSignInProbe(store, pause.provider, (await check(pause.provider, true)).state, new Date());
                 }
-                catch { /* the next pass asks again */ }
+                catch { }
             }
         }
-        catch { /* the next pass asks again */ }
+        catch { }
         finally {
             running = false;
         }
@@ -277,7 +212,6 @@ export function startSignInProbes(store, check, everyMs = 120_000) {
     timer.unref?.();
     return () => { stopped = true; clearInterval(timer); };
 }
-/** The console's view of every open pause: title, command, one action. */
 export function signInNotices(store) {
     return openAuthPauses(store).map(pause => ({
         provider: pause.provider,

package/dist/provider-capture.js

@@ -1,19 +1,8 @@
-/**
- * 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);
@@ -25,14 +14,13 @@ export function captureProviderFailure(store, input, now) {
             .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 */ }
+    catch { }
 }
 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), []);
@@ -43,11 +31,9 @@ export function providerCapture(store, 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/provider-connection.js

@@ -1,4 +1,3 @@
-/** Non-spending account checks. Only normalized facts leave this module. */
 import { homedir } from "node:os";
 import { run } from "./exec.js";
 import { ALL_CREDENTIAL_ENV, inspectionOf } from "./provider.js";
@@ -47,8 +46,6 @@ export function createConnectionChecker(options = {}) {
     const cache = new Map();
     const pending = new Map();
     return async (provider, fresh = false) => {
-        // An ACP agent is never run to ask how it is signed in (nothing executes it outside the gateway): what is known
-        // of it is its conformance check, read elsewhere. Here it is simply unverified.
         if (isAcpProvider(provider))
             return { state: "unverified", mode: "agent-login", checkedAt: clock().toISOString() };
         const mode = readAuthMode(provider, home);
@@ -64,7 +61,6 @@ export function createConnectionChecker(options = {}) {
             return inFlight;
         const check = (async () => {
             if (mode === "api-key") {
-                // A saved key is tested only when asked (Check again, or just after it is saved): one small request to the provider, never a model.
                 const stored = fresh && keyFacts.set ? readProviderKey(provider, home) : null;
                 if (stored === null)
                     return { state: keyFacts.set || ambient ? "key-present" : "missing-key", mode, checkedAt: now.toISOString() };
@@ -76,8 +72,6 @@ export function createConnectionChecker(options = {}) {
             if (identityProbe === null)
                 return { state: "unverified", mode, checkedAt: now.toISOString() };
             try {
-                // Same subscription credential stripping as provider invocations.
-                // No model prompt, repository scripts, or stored API keys are used.
                 const result = await probe(facts.binary, [...identityProbe], { cwd: home, timeoutMs: 5000, maxBuffer: 32 * 1024, omitEnv: ALL_CREDENTIAL_ENV });
                 return signInFacts(provider, result, clock());
             }
@@ -88,8 +82,6 @@ export function createConnectionChecker(options = {}) {
         pending.set(key, check);
         try {
             const value = await check;
-            // Only cache against the same credential mode that began this check.
-            // A slow subscription probe must not overwrite a newer API-key result.
             const currentKeyFacts = keyStatus(provider, home);
             const currentKey = JSON.stringify([provider, readAuthMode(provider, home), currentKeyFacts.set, currentKeyFacts.updatedAt, !!(options.env ?? process.env)[PROVIDER_KEY_ENV[provider]]]);
             if (currentKey === key)

package/dist/provider-home.js

@@ -1,19 +1,3 @@
-/**
- * What a build keeps of the provider's own home, and nothing more.
- *
- * A build loads none of the operator's Claude settings or Codex config
- * (provider.ts), so two things from them are carried explicitly:
- *
- * - A build routed with no model runs as the operator's own CLI would: the
- *   model they chose (Claude's settings.json `model`, Codex's config.toml
- *   `model`), Claude's `alwaysThinkingEnabled` and Codex's reasoning effort.
- *   Nothing else of either file (hooks, plugins, MCP servers) is read.
- * - A Codex build gets its own CODEX_HOME for the launch: links to the
- *   operator's `auth.json` and `sessions/` (so it signs in, and a repair
- *   resumes the same thread), and no skills, AGENTS.md or anything else from
- *   theirs. Links, never copies: a refreshed sign-in lands in the real file.
- *   The folder is fenced from the agent's commands and removed after the run.
- */
 import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
@@ -25,7 +9,6 @@ export function claudeConfigDir(env = process.env, home = homedir()) {
 export function codexHomeDir(env = process.env, home = homedir()) {
     return env["CODEX_HOME"] || join(home, ".codex");
 }
-/** Claude's user settings: its `model` and `alwaysThinkingEnabled`, when valid. */
 export function claudeDefaults(configDir) {
     let settings;
     try {
@@ -42,7 +25,6 @@ export function claudeDefaults(configDir) {
         ...(typeof alwaysThinkingEnabled === "boolean" ? { alwaysThinking: alwaysThinkingEnabled } : {}),
     };
 }
-/** Codex's config.toml: its top-level `model` and `model_reasoning_effort`, or the selected profile's. */
 export function codexDefaults(codexHome) {
     let text;
     try {
@@ -75,12 +57,6 @@ export function codexDefaults(codexHome) {
         ...(effort !== undefined && EFFORT.test(effort) ? { effort } : {}),
     };
 }
-/**
- * One Codex launch's CODEX_HOME: a private folder linking the operator's
- * sign-in and sessions. A missing `auth.json` stays missing (an API-key
- * build needs none); a missing `sessions/` is made where Codex would make
- * it, so a resumed build finds the thread its first launch wrote.
- */
 export function isolatedCodexHome(source, root = tmpdir()) {
     const dir = mkdtempSync(join(root, "so-codex-"));
     try {
@@ -94,6 +70,5 @@ export function isolatedCodexHome(source, root = tmpdir()) {
         rmSync(dir, { recursive: true, force: true });
         throw error;
     }
-    // rm removes the links themselves, never what they point to.
     return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
 }

package/dist/provider-limits.js

@@ -3,15 +3,11 @@ const WINDOW_NAME = /^[a-z][a-z0-9_]{0,39}$/;
 const CLAUDE_MINUTES = { five_hour: 300, seven_day: 10_080, seven_day_opus: 10_080, seven_day_sonnet: 10_080 };
 const finite = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
 const percent = (value) => Math.max(0, Math.min(100, Math.round(value * 10) / 10));
-/** An epoch (seconds) as an ISO time, or null when it isn't a plausible one. */
 const epoch = (value) => {
     const seconds = finite(value);
     return seconds === null || seconds < 1_000_000_000 || seconds > 10_000_000_000 ? null : new Date(seconds * 1000).toISOString();
 };
 export const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
-/** A Claude stream event's limits, or null when it isn't the session's own `rate_limit_event` or says nothing usable.
- * A subagent's (parent_tool_use_id set) is never read: the session reports its own windows each turn, and a
- * subagent-tagged reading can't be told apart from one shaped by the subagent's own traffic (stream-scope.ts). */
 export function claudeLimitsOf(event) {
     const body = record(event);
     if (body === null || body["type"] !== "rate_limit_event" || !topLevelEvent(body))
@@ -31,22 +27,17 @@ export function claudeLimitsOf(event) {
         windows.push({ window: name, usedPercent: percent(used * 100), windowMinutes: Object.hasOwn(CLAUDE_MINUTES, name) ? CLAUDE_MINUTES[name] : null, resetsAt: epoch(one["resetsAt"]), reached: rejected && name === current });
     }
     if (windows.length === 0 && current !== null && WINDOW_NAME.test(current)) {
-        // An older CLI names only the window it's in; its use is known only when it's spent.
         const used = finite(info["utilization"]);
         if (used !== null || rejected)
             windows.push({ window: current, usedPercent: rejected ? 100 : percent(used * 100), windowMinutes: Object.hasOwn(CLAUDE_MINUTES, current) ? CLAUDE_MINUTES[current] : null, resetsAt: epoch(info["resetsAt"]), reached: rejected });
-        // Only this window is known: the others keep their last reading.
         return windows.length === 0 ? null : { provider: "claude", plan: null, windows, partial: true, billing: "subscription" };
     }
-    // A plan's windows are a plan's: this turn ran on the sign-in.
     return windows.length === 0 ? null : { provider: "claude", plan: null, windows, billing: "subscription" };
 }
-/** Codex's `account/rateLimits/read` answer as a reading, or null. */
 export function codexLimitsOf(result) {
     const limits = record(record(result)?.["rateLimits"]);
     if (limits === null)
         return null;
-    // Codex names why it stopped ("rate_limit_reached", "…usage_limit_reached"), not which window: the fullest one.
     const reachedType = typeof limits["rateLimitReachedType"] === "string" ? limits["rateLimitReachedType"] : null;
     const windows = [];
     for (const slot of ["primary", "secondary"]) {
@@ -63,15 +54,12 @@ export function codexLimitsOf(result) {
     const plan = typeof limits["planType"] === "string" && /^[a-z0-9_-]{1,40}$/i.test(limits["planType"]) ? limits["planType"] : null;
     return windows.length === 0 ? null : { provider: "codex", plan, windows };
 }
-/** Where readings go: the store, in any process that runs Claude. The latest one set wins; one that's done removes
- * only itself, so a command that ends inside a longer one leaves the longer one's in place. Unset, readings drop. */
 const sinks = [];
 export function pushLimitSink(next) {
     sinks.push(next);
     return () => { const at = sinks.lastIndexOf(next); if (at !== -1)
         sinks.splice(at, 1); };
 }
-/** A reading from a stream; never throws into the run that carried it. */
 export function noteLimits(reading) {
     const sink = sinks[sinks.length - 1];
     if (reading === null || sink === undefined)
@@ -80,10 +68,8 @@ export function noteLimits(reading) {
         sink(reading);
     }
     catch {
-        // A reading that can't be kept must not touch the turn.
     }
 }
-/** A window in words: "5-hour", "Weekly", "Weekly (Opus)". */
 export function windowLabel(window, minutes) {
     if (window === "five_hour")
         return "5-hour";