toolroll 0.9.103 → 0.9.105

package/dist/tidy.js

@@ -1,19 +1,8 @@
-/**
- * Put away old tasks (docs/plans/task-tidy.md). Tidy finds tasks nobody needs to see any more, says why for each, and
- * puts them away (v145 `task_archive`): old routine runs a newer run replaces, release tasks for versions already
- * published or replaced, and "Checks failed" notices main has since fixed. A person can also put away finished tasks
- * older than N days from the same preview. Deterministic and explainable: the same records give the same list, every
- * item carries its rule and one plain reason, and the preview's digest binds exactly what a person saw.
- *
- * Never touched: a task with a live attempt, a task asked of a named person (`task ask`), a task with feedback or a
- * steering note still pending, a task already Complete, and (automatically) a task a person filed or restored.
- */
 import { createHash } from "node:crypto";
 import { closeSync, fstatSync, lstatSync, openSync, readdirSync, readSync, constants } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
 import { archiveTaskFamily } from "./store.js";
 import { workTidyRows } from "./work-index.js";
-/** The preview's groups, in order. "finished" is a person's own choice only; tidy never applies it on its own. */
 export const TIDY_GROUPS = [
     { rule: "release", label: "Old releases" },
     { rule: "routine", label: "Old routine runs" },
@@ -21,15 +10,11 @@ export const TIDY_GROUPS = [
     { rule: "finished", label: "Finished more than {days} days ago" },
 ];
 export const TIDY_DEFAULT_DAYS = 14;
-/** At most this many tasks are put away automatically per pass. */
 export const TIDY_PASS_LIMIT = 25;
 const MAX_JOURNALS = 2000;
 const MAX_JOURNAL_BYTES = 1 << 20;
 const TASK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
 const VERSION = /^\d{1,6}\.\d{1,6}\.\d{1,6}(?:-[0-9A-Za-z.-]{1,64})?$/;
-/** Reads `releases/*.json` under the plane's state folder (the database's folder), written only by `toolroll release`.
- * A symlink, a non-file, an oversized or unreadable journal makes the whole answer untrusted (`problem`), so the
- * release rule then puts nothing away: a journal it can't read might be the one that says a release is in flight. */
 export function readReleaseFacts(stateDir) {
     const dir = join(stateDir, "releases");
     let names;
@@ -67,12 +52,9 @@ export function readReleaseFacts(stateDir) {
     }
     return { facts, problem: null };
 }
-/** The release journals beside this database (its folder is the plane's state folder). An in-memory or relative
- * database has no state folder, so the release rule stays off rather than reading whatever folder it runs in. */
 export function releaseFactsFor(databaseFile) {
     return isAbsolute(databaseFile) ? readReleaseFacts(dirname(databaseFile)) : { facts: [], problem: "this database has no state folder" };
 }
-/** One journal's JSON, never through a symlink, bounded; null when it can't be read. */
 function readJournalFile(file) {
     let fd = null;
     try {
@@ -101,9 +83,6 @@ function readJournalFile(file) {
             closeSync(fd);
     }
 }
-/** A journal's task is the release task Toolroll filed for it: its id is the gate id for that version and commit
- * (release.ts gateTaskId, maybe with a fresh-approval suffix), the task exists, and its scope's candidate, when it has
- * one, is the journal's commit. */
 function releaseTaskMatches(store, fact) {
     const base = `release-${fact.version.replace(/[^0-9A-Za-z.-]/g, "-")}-${fact.candidate.slice(0, 7)}`;
     if (fact.taskId !== base && !(fact.taskId.startsWith(`${base}-`) && /^\d{1,3}$/.test(fact.taskId.slice(base.length + 1))))
@@ -112,7 +91,6 @@ function releaseTaskMatches(store, fact) {
     LEFT JOIN task_scope s ON s.task_id = t.id WHERE t.id = ?`).get(fact.taskId);
     return row !== undefined && (row["candidate"] == null || row["candidate"] === fact.candidate);
 }
-/** -1, 0 or 1: numeric parts first, then a release above any of its pre-releases. */
 export function compareVersions(a, b) {
     const [ma, pa = ""] = a.split("-", 2);
     const [mb, pb = ""] = b.split("-", 2);
@@ -128,7 +106,6 @@ export function compareVersions(a, b) {
         return -1;
     return pa < pb ? -1 : 1;
 }
-/** Everything that keeps a task out of tidy, read once. */
 function exclusionsOf(store) {
     const refs = (sql) => new Set(store.handle.prepare(sql).all().map(row => Number(row["ref"])));
     const ids = (sql) => new Set(store.handle.prepare(sql).all().map(row => String(row["id"])));
@@ -142,7 +119,6 @@ function exclusionsOf(store) {
         restored: ids("SELECT DISTINCT task_id id FROM action_ledger WHERE action = 'task restored' AND task_id IS NOT NULL"),
     };
 }
-/** Why this family is never put away by tidy, or null. `auto`: tidy on its own (a restored family stays). */
 function excluded(row, ex, auto) {
     if (row.archived || row.live || row.broken || row.code === "complete")
         return true;
@@ -152,12 +128,7 @@ function excluded(row, ex, auto) {
         return true;
     return auto && row.memberIds.some(id => ex.restored.has(id));
 }
-/** Labels an automation's card files under (flow-triggers.ts makeCard), from before cards kept their kind (v126). */
 const AUTOMATION_FILERS = new Set(["Schedule", "Plane review", "GitHub"]);
-/** Whether this task was filed by the trigger's own automation, proven from Toolroll's records: a standing order's
- * firing names its task once and forever (`flow_trigger_event.task`); otherwise the flow engine filed it for this very
- * flow (`filed_via`), as the automation the card was made by (its kind, or an automation's label from before kinds).
- * Unknown provenance is never automation. */
 function automationFiled(store, taskId, flow, card, eventTask) {
     if (eventTask === taskId)
         return true;
@@ -168,9 +139,6 @@ function automationFiled(store, taskId, flow, card, eventTask) {
         return card.createdKind === "automation" || card.createdKind === null;
     return card.createdKind === null && row["filed_by_kind"] === "person" && typeof row["filed_by"] === "string" && row["filed_by"] === card.createdBy && AUTOMATION_FILERS.has(row["filed_by"]);
 }
-/** (a) Every schedule's own clock firings (a slot, a scripted slot, or a plane review's scheduled daily problem; never a
- * person's Run now, never a skipped or held firing), each with the automation-filed tasks it made, grouped by trigger (a
- * plane review: by trigger and problem). */
 function routineFirings(store) {
     const rows = store.handle.prepare(`SELECT e.trigger, e.key, e.at, e.on_time, e.state, e.task event_task, c.task card_task, c.primary_task, c.title,
       c.created_by, c.created_kind, t.flow
@@ -183,7 +151,6 @@ function routineFirings(store) {
         if (row["created_kind"] === "person")
             continue;
         const plane = /^plane:(.+):\d{4}-\d{2}-\d{2}$/.exec(key);
-        // A plane review's key is the same for Run now; only the clock's own firing (on_time) is a routine run.
         if (!/^(?:script:)?slot:/.test(key) && !(plane !== null && Number(row["on_time"]) === 1))
             continue;
         const family = `${Number(row["trigger"])}:${plane === null ? "" : plane[1]}`;
@@ -192,14 +159,11 @@ function routineFirings(store) {
         const all = [...new Set([row["event_task"], row["card_task"], row["primary_task"]].filter((one) => typeof one === "string" && one !== ""))];
         const tasks = all.filter(task => automationFiled(store, task, Number(row["flow"]), card, eventTask));
         const list = families.get(family) ?? [];
-        // Every firing counts toward which is newest, even one whose tasks can't be proven: its tasks are kept, never taken.
         list.push({ family, tasks, all, title: String(row["title"] ?? eventTask ?? "the newest run") });
         families.set(family, list);
     }
     return families;
 }
-/** (c) Every "Checks failed on <branch>: <workflow>" notice a checks trigger made, with its commit, its workflow and the
- * automation-filed tasks it made. */
 function ciNotices(store) {
     const rows = store.handle.prepare(`SELECT e.trigger, e.key, e.at, c.title, c.task, c.primary_task, c.created_by, c.created_kind, c.source_json, t.config_json, t.flow
     FROM flow_trigger_event e JOIN flow_trigger t ON t.id = e.trigger JOIN flow_card c ON c.id = e.card
@@ -217,8 +181,6 @@ function ciNotices(store) {
         }
         if (config["watch"] !== "checks" || typeof config["repo"] !== "string" || typeof config["branch"] !== "string")
             continue;
-        // Where the failure was, as the card recorded it when it was made (GitHub's own run link, never rewritten), not
-        // where the trigger points now: a trigger re-pointed later never lends its new repository's runs to old notices.
         let made = null;
         try {
             made = JSON.parse(String(row["source_json"] ?? "null"));
@@ -241,14 +203,11 @@ function ciNotices(store) {
     }
     return notices;
 }
-/** Every completed run the checks trigger saw on this repository's branch, oldest first. */
 function observationsOf(store, repo, branch) {
     return store.handle.prepare(`SELECT run_id, workflow, head_sha, conclusion, run_created_at FROM branch_check_run
     WHERE lower(repo) = lower(?) AND branch = ? ORDER BY run_created_at, run_id`).all(repo, branch)
         .map(row => ({ runId: Number(row["run_id"]), workflow: String(row["workflow"]), sha: String(row["head_sha"]), conclusion: row["conclusion"] === "success" ? "success" : "failure", createdAt: String(row["run_created_at"]) }));
 }
-/** The failing runs older "Checks failed" cards of this trigger name (their own GitHub run links) that aren't on record
- * yet, newest first, at most `limit`: the checks trigger reads each from GitHub so tidy can tell where it ran. */
 export function unprovenNoticeRuns(store, trigger, repo, limit = 5) {
     const rows = store.handle.prepare(`SELECT c.source_json FROM flow_trigger_event e JOIN flow_card c ON c.id = e.card
     WHERE e.trigger = ? AND e.key LIKE 'checks:%' ORDER BY e.at DESC, e.rowid DESC`).all(trigger);
@@ -273,9 +232,6 @@ export function unprovenNoticeRuns(store, trigger, repo, limit = 5) {
     }
     return runs;
 }
-/** A completed workflow run on the watched branch, as the checks trigger read it from GitHub (its poll through the
- * person's own gh login, or its signed webhook): kept once per run. Only a push to the watched branch of the watched
- * repository counts (a pull request from a fork whose branch is also called main does not). */
 export function recordBranchCheckRun(store, watched, run, now) {
     const workflow = run.name ?? "", sha = run.head_sha ?? "", created = Date.parse(run.created_at ?? "");
     if (run.id === undefined || !Number.isSafeInteger(run.id) || run.id <= 0 || workflow === "" || workflow.length > 200 || !/^[0-9a-f]{40}$/.test(sha) || Number.isNaN(created))
@@ -288,8 +244,6 @@ export function recordBranchCheckRun(store, watched, run, now) {
     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(watched.repo, run.id, watched.branch, workflow, sha, run.conclusion, new Date(created).toISOString(), now.toISOString());
     return Number(changed.changes) > 0;
 }
-/** What tidy would put away now, in group order, oldest first within a group. `days`: also offer finished tasks
- * untouched that long (a person's preview only); null is tidy's own automatic rules. `access`: whose lists. */
 export function tidyPreview(store, now, input) {
     const auto = input.days === null;
     const rows = workTidyRows(store, now, input.access ?? { principal: "operator", repos: null, includeUnplaced: true });
@@ -299,11 +253,8 @@ export function tidyPreview(store, now, input) {
             byId.set(id, row);
     const ex = exclusionsOf(store);
     const taken = new Map();
-    // Every task each schedule's newest firing touched, whoever filed it: no family holding one is ever put away.
     const firings = routineFirings(store);
     const keepAll = new Set([...firings.values()].flatMap(list => list.at(-1).all));
-    // `proven`: for a rule's own producer, every version of the family must be one it can prove it made (a person's
-    // later revision of a scheduled run keeps the whole family out); null for a person's own choice (finished tasks).
     const offer = (row, rule, reason, proven) => {
         if (row === undefined || taken.has(row.rootId) || excluded(row, ex, auto))
             return;
@@ -313,10 +264,8 @@ export function tidyPreview(store, now, input) {
             return;
         taken.set(row.rootId, { rule, taskId: row.currentId, title: row.title, repo: row.repo, reason, updatedAt: row.updatedAt, members: [...row.members].sort((a, b) => a - b) });
     };
-    // (b) Old releases: only when every journal reads, and only a task whose journals agree with its own records.
     if (input.releases.problem === null) {
         const facts = input.releases.facts.filter(one => releaseTaskMatches(store, one));
-        // The newest published version of each package (its GitHub repository and npm name).
         const latestOf = new Map();
         for (const one of facts)
             if (one.published && (latestOf.get(one.product) === undefined || compareVersions(one.version, latestOf.get(one.product)) > 0))
@@ -326,11 +275,9 @@ export function tidyPreview(store, now, input) {
             byTask.set(fact.taskId, [...(byTask.get(fact.taskId) ?? []), fact]);
         const journalNamed = new Set(byTask.keys());
         for (const [taskId, named] of byTask) {
-            // Every journal naming it must check out, for one package and one version.
             if (named.some(one => !facts.includes(one)) || new Set(named.map(one => `${one.product}\u0000${one.version}`)).size !== 1)
                 continue;
             const current = named.filter(one => !one.superseded);
-            // In flight: its current journal is neither done nor stopped (running, or waiting for an approval).
             if (current.some(one => !one.done && !one.stopped))
                 continue;
             const version = named[0].version, latest = latestOf.get(named[0].product) ?? null;
@@ -341,7 +288,6 @@ export function tidyPreview(store, now, input) {
                 offer(byId.get(taskId), "release", reason, journalNamed);
         }
     }
-    // (a) Old routine runs: everything but each schedule's newest firing.
     const routineMade = new Set([...firings.values()].flatMap(list => list.flatMap(one => one.tasks)));
     for (const list of firings.values()) {
         const newest = list.at(-1);
@@ -350,10 +296,6 @@ export function tidyPreview(store, now, input) {
                 offer(byId.get(task), "routine", `A newer run, “${newest.title}”, replaces it.`, routineMade);
         }
     }
-    // (c) Resolved CI notices: every workflow that failed on its commit was fixed by a later commit's green run, or a
-    // newer notice carries that workflow's failure while the branch stays red.
-    // A notice counts only once its own failing run is on record as a push to the watched repository and branch (the
-    // checks trigger reads it): a pull request from a fork whose branch is also called main never does.
     const seen = new Map();
     const observedFor = (notice) => {
         const key = `${notice.repo.toLowerCase()}\u0000${notice.branch}`;
@@ -365,7 +307,6 @@ export function tidyPreview(store, now, input) {
     const ciMade = new Set(notices.flatMap(one => one.tasks));
     for (const notice of notices) {
         const observed = observedFor(notice);
-        // What failed on its commit: the workflow it names, and any other the trigger saw fail on that commit.
         const failed = new Map([[notice.workflow, notice.at]]);
         for (const one of observed)
             if (one.sha === notice.sha && one.conclusion === "failure")
@@ -393,7 +334,6 @@ export function tidyPreview(store, now, input) {
         for (const task of notice.tasks)
             offer(byId.get(task), "ci", reason, ciMade);
     }
-    // Finished more than N days ago (a person's preview only): done, failed or stopped, untouched since.
     if (input.days !== null) {
         const before = new Date(now.getTime() - input.days * 86_400_000).toISOString();
         for (const row of rows) {
@@ -405,18 +345,14 @@ export function tidyPreview(store, now, input) {
     const order = (rule) => TIDY_GROUPS.findIndex(one => one.rule === rule);
     return [...taken.values()].sort((a, b) => order(a.rule) - order(b.rule) || a.updatedAt.localeCompare(b.updatedAt) || a.taskId.localeCompare(b.taskId));
 }
-/** The preview's identity: exactly which tasks under which rules, for how many days. A person's confirmation names it. */
 export function tidyDigest(items, days) {
-    // Each family exactly: its task, every version that goes with it, its project, its rule and the reason shown.
     const set = items.map(one => [one.taskId, one.members.join(","), one.repo ?? "", one.rule, one.reason]).sort((a, b) => a[0].localeCompare(b[0]));
     return createHash("sha256").update(JSON.stringify({ days, set }), "utf8").digest("hex").slice(0, 32);
 }
-/** The preview in its groups (empty ones left out), with each group's label. */
 export function tidyGroups(items, days) {
     return TIDY_GROUPS.map(group => ({ rule: group.rule, label: group.label.replace("{days}", String(days)), items: items.filter(one => one.rule === group.rule) }))
         .filter(group => group.items.length > 0);
 }
-/** A day count from a person (1–365), or the default. */
 export function tidyDays(raw) {
     if (raw === null || raw === undefined || raw === "")
         return TIDY_DEFAULT_DAYS;
@@ -425,8 +361,6 @@ export function tidyDays(raw) {
     const days = Number(raw);
     return days >= 1 && days <= 365 ? days : null;
 }
-/** A person puts away exactly what they previewed (or the ticked part of it), in one write transaction that recomputes
- * the preview and refuses when its digest moved or a ticked task isn't in it. */
 export function applyTidy(store, now, input) {
     return store.transact(() => {
         const items = tidyPreview(store, now, { releases: input.releases, days: input.days, ...(input.access === undefined ? {} : { access: input.access }) });
@@ -451,8 +385,6 @@ export function applyTidy(store, now, input) {
         return { ok: true, archived, skipped };
     });
 }
-/** Tidy on its own (the worker's reconcile pass): its automatic rules only, at most `limit` tasks, in one write
- * transaction. Idempotent: what is put away is skipped next time, and a restored task is never put away again. */
 export function runTidy(store, now, releases, limit = TIDY_PASS_LIMIT, access) {
     return store.transact(() => {
         const archived = [];
@@ -464,29 +396,22 @@ export function runTidy(store, now, releases, limit = TIDY_PASS_LIMIT, access) {
         return archived;
     });
 }
-/** Whether this person may still put away or restore work in this project, read under the write lock (check and write
- * together): an active approver who can see it. Null when they may; otherwise why not. */
 export function approverStandsNow(store, name, repo) {
     const account = store.accountOf(name);
     if (account === null || account.revokedAt !== null || account.role !== "approver" || !store.accountCanAccess(name, repo))
         return `${name} can't put away or restore tasks in this project.`;
     return null;
 }
-/** The repository of a task's family, from its first version (all versions share it). */
 export function familyRepoOf(store, refs) {
     return refs.length === 0 ? null : store.refById(refs[0])?.repo ?? null;
 }
-/** "Archived by tidy: <reason>" or "Archived by <person>: <reason>": the one sentence every surface shows. */
 export function archivedWords(archived) {
     return `${archived.byKind === "tidy" ? "Archived automatically" : `Archived by ${archived.by}`}: ${archived.reason}`;
 }
-/** The release journals beside the store's own database file (none for an in-memory one). */
 export function releaseFactsOf(store) {
     const file = store.databaseFile();
     return file === null ? { facts: [], problem: "this database has no state folder" } : releaseFactsFor(file);
 }
-/** The lists one person sees, for tidy: every project for an unrestricted account, otherwise exactly theirs. The CLI's
- * preview (`--as <name>`) and its apply read the same scope, so the same records give the same digest. */
 export function accessOf(store, name) {
     const account = store.accountOf(name);
     if (account === null || account.revokedAt !== null)
@@ -494,7 +419,6 @@ export function accessOf(store, name) {
     return account.projects === null ? { principal: "operator", repos: null, includeUnplaced: true }
         : { principal: "operator", repos: [...account.projects], includeUnplaced: store.accountCanAccess(name, null) };
 }
-/** Narrows `access` to the caller's own lens (a remote person's project limit): never wider. No lens: unchanged. */
 export function withinLens(access, lens) {
     if (lens === null || access.principal !== "operator")
         return access;

package/dist/tier-report.js

@@ -10,7 +10,6 @@ const minutesBetween = (from, to) => {
     const ms = Date.parse(to) - Date.parse(from);
     return Number.isFinite(ms) && ms >= 0 ? Math.round(ms / 6_000) / 10 : null;
 };
-/** Every routed task with a run in [from, to), by tier, and what the light tier saved. `items` are the month's spend. */
 export function tierReport(db, from, to, items) {
     const spendOf = new Map();
     for (const item of items)
@@ -56,7 +55,6 @@ export function tierReport(db, from, to, items) {
     };
 }
 const minutesWords = (minutes) => (minutes >= 90 ? `${Math.round(minutes / 6) / 10}h` : `${Math.round(minutes)}m`);
-/** The spend report's lines: one per tier, then what the tiers saved. Empty when no routed task ran this month. */
 export function tierLines(report, usd) {
     if (report.rows.length === 0)
         return [];

package/dist/token-notices.js

@@ -1,9 +1,3 @@
-/**
- * API token notices (v111): 7 days and 1 day before a token expires, its person is told once each, in their own chats
- * and browsers (a personal notification), and the ledger keeps it. Only the nearest notice newly due is sent, so a
- * token made with a day left says so once. Replaced and revoked tokens get none. The same pass records the end of each
- * rotated token whose overlap has passed; it already signs no one in (tokenLive), so a late pass grants nothing.
- */
 import { expiryNoticeDue, EXPIRY_NOTICE_DAYS } from "./api-tokens.js";
 export const TOKEN_NOTICE_KIND = "api-token-expiry";
 export function tokenNoticePass(store, now) {
@@ -15,7 +9,6 @@ export function tokenNoticePass(store, now) {
         if (days === null)
             continue;
         const key = (one) => `${TOKEN_NOTICE_KIND}:${token.id}:${one}`;
-        // A nearer notice already sent covers this one.
         if (EXPIRY_NOTICE_DAYS.filter(one => one <= days).some(one => store.handle.prepare("SELECT 1 AS hit FROM notification WHERE dedupe_key = ?").get(key(one)) !== undefined))
             continue;
         const fresh = store.enqueueNotification({
@@ -32,14 +25,13 @@ export function tokenNoticePass(store, now) {
     }
     return { sent, ended };
 }
-/** The loop beside the console: a pass a minute. */
 export function startTokenNotices(store, everyMs = 60_000) {
     let stopped = false;
     const tick = () => { if (stopped)
         return; try {
         tokenNoticePass(store, new Date());
     }
-    catch { /* the next pass tries again */ } };
+    catch { } };
     const timer = setInterval(tick, everyMs);
     timer.unref?.();
     const first = setTimeout(tick, 5_000);

package/dist/tokens-cli.js

@@ -1,17 +1,9 @@
-/**
- * `toolroll tokens create|list|revoke|rotate` (v111): a person's own API tokens, from the terminal of the machine that
- * keeps the database. Every verb is a step-up: the person's own password, typed at a hidden prompt or piped with
- * --password-stdin, never an argument, never the remembered login, a lead token or a remote caller's token. A new
- * secret is written once, in the answer to create or rotate; nothing else ever shows it, and only its hash is kept.
- */
 import { envelopeJson } from "./envelope.js";
 import { daysLeft, mintApiToken, ROTATION_OVERLAP_MAX_MINUTES, ROTATION_OVERLAP_MINUTES, TOKEN_DAYS, tokenLive, tokenRotationProblem, MCP_ROTATION_REFUSAL } from "./api-tokens.js";
 import { canonicalProject, projectName } from "./project.js";
 import { authenticateAccount } from "./scope.js";
 export const TOKENS_ACTIONS = ["create", "list", "revoke", "rotate"];
-/** The most a piped password may be: a password, not a file. */
 export const PASSWORD_STDIN_BYTES = 4096;
-/** Flags that would put a credential in argv. Refused by name, their values never echoed. */
 const SECRET_FLAGS = ["password", "token", "token-file", "token-env"];
 const EXIT = { ok: 0, failed: 1, usage: 2, refused: 3 };
 export async function runTokensCommand(positional, flags, context) {
@@ -31,7 +23,6 @@ export async function runTokensCommand(positional, flags, context) {
     const secretFlag = SECRET_FLAGS.find(name => flags.has(name));
     if (secretFlag !== undefined)
         return fail("usage", `--${secretFlag} isn't accepted here: type your password at the prompt, or pipe it with --password-stdin.`, EXIT.usage);
-    // Check the terms before asking for anything, so a typo never spends a password try.
     const verb = action;
     const terms = verb === "create" ? createTerms(flags) : null;
     if (terms !== null && "problem" in terms)
@@ -44,7 +35,6 @@ export async function runTokensCommand(positional, flags, context) {
     const overlap = verb === "rotate" ? overlapMinutes(text("overlap")) : null;
     if (overlap !== null && typeof overlap === "string")
         return fail("usage", overlap, EXIT.usage);
-    // Who, then their password: never the remembered login's password, never an argument.
     let name = text("as")?.trim() ?? context.rememberedName ?? undefined;
     const fromStdin = flags.has("password-stdin");
     if (!fromStdin && (!context.interactive() || json))
@@ -137,7 +127,6 @@ function overlapMinutes(given) {
     const minutes = Number(given);
     return Number.isInteger(minutes) && minutes >= 0 && minutes <= ROTATION_OVERLAP_MAX_MINUTES ? minutes : `--overlap is whole minutes, 0 to ${ROTATION_OVERLAP_MAX_MINUTES}.`;
 }
-/** Each named project, by path or by its name, among the projects this person may use now. */
 function resolveProjects(store, account, words) {
     const mine = [...new Set([...store.listProjects().map(one => one.path), ...store.knownRepos()])].filter(repo => store.accountCanAccess(account, repo));
     const paths = [];
@@ -152,7 +141,6 @@ function resolveProjects(store, account, words) {
     }
     return { paths };
 }
-/** A token of this person's by exact id, else by a name only one of their current tokens has. */
 function resolveToken(tokens, ref, now, current) {
     const live = tokens.filter(one => tokenLive(one, now.getTime()));
     const byId = live.find(one => one.id === ref);
@@ -168,7 +156,6 @@ function resolveToken(tokens, ref, now, current) {
         return { reason: "not-found", problem: "No live token of yours has that name or id." };
     return { row: named[0] };
 }
-/** What may be shown about a token: everything but its secret, which is never kept. */
 function listed(row, now) {
     return {
         id: row.id, name: row.name, access: row.access, projects: row.projects, createdAt: row.createdAt, lastUsedAt: row.lastUsedAt, expiresAt: row.expiresAt,

package/dist/tool-broker.js

@@ -1,22 +1,3 @@
-/**
- * The tool broker: where a build's project tools keep their secrets.
- *
- * Anything a fenced agent can read, its shell can read too, so no tool secret
- * may sit in its MCP config, its environment, an inherited descriptor or a
- * process it can inspect. The broker runs in Toolroll's own process, outside
- * the fence, for one launch: it holds each tool's resolved values in memory,
- * starts a local server itself (with the values as that server's environment,
- * inside the run's fence when it has one) or relays to a web server (adding
- * the sign-in headers), and serves each tool as streamable HTTP on a loopback
- * port. The agent's config names only that address and a token minted for
- * this launch: valid for exactly its opted-in tools (a research step's only
- * for their read-only actions), and revoked when the launch ends. A resumed
- * build is a new launch with its own broker and token.
- *
- * What it relays is plain JSON-RPC: a request gets its answer as JSON, a
- * notification is accepted, and a server's own requests (sampling, roots) are
- * answered "not supported" — a build has nobody to ask.
- */
 import { spawn } from "node:child_process";
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
@@ -27,14 +8,12 @@ const ANSWER_LIMIT = 32 * 1024 * 1024;
 const STOP_GRACE_MS = 2_000;
 const rpcError = (id, message, code = -32000) => ({ jsonrpc: "2.0", id: id ?? null, error: { code, message } });
 const isRequest = (message) => typeof message.method === "string" && message.id !== undefined && message.id !== null;
-/** A research step's server lists and calls only its read-only actions. */
 function limitList(message, actions) {
     if (actions === undefined || message === null || typeof message !== "object" || message.result === null || typeof message.result !== "object")
         return message;
     const result = message.result;
     return { ...message, result: { ...result,
             ...(Array.isArray(result["tools"]) ? { tools: result["tools"].filter(one => one !== null && typeof one === "object" && actions.includes(String(one.name))) } : {}),
-            // The research grant names tool actions only; it grants no resources or prompts.
             ...Object.fromEntries(["resources", "resourceTemplates", "prompts"].filter(key => Array.isArray(result[key])).map(key => [key, []])), } };
 }
 const RESEARCH_METHODS = new Set(["initialize", "ping", "notifications/initialized", "notifications/cancelled", "tools/list", "resources/list", "resources/templates/list", "prompts/list"]);
@@ -46,12 +25,8 @@ function refused(message, actions) {
         return null;
     return rpcError(message.id, "This step may only read: that action is not available.", -32601);
 }
-/** What a local server inherits from the launch: enough to run and find its tools, and nothing that could be
- * another tool's or a provider's secret. Its own configured values are added after. */
 export const SERVER_ENV = ["PATH", "HOME", "USER", "LANG", "TMPDIR", "SHELL", "TERM", "NODE_EXTRA_CA_CERTS", "SSL_CERT_FILE", "SSL_CERT_DIR",
     ...["HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "ALL_PROXY"].flatMap(name => [name, name.toLowerCase()])];
-/** A local server's environment: the allowlisted names from `base` (and its LC_* locale), less `omit`, then `pass`,
- * then the tool's own values. */
 export function serverEnv(base, omit, pass, values) {
     const env = {};
     for (const [name, value] of Object.entries(base))
@@ -61,16 +36,10 @@ export function serverEnv(base, omit, pass, values) {
         delete env[name];
     return Object.assign(env, pass, values);
 }
-/**
- * The first of a server's command and path-like arguments that resolves inside an untrusted folder (a build's checkout
- * or caches), or null. The command is resolved as spawn would: a path against `cwd`, a bare name through PATH; an
- * argument counts when it names an existing path (relative to `cwd`) or is written as one (`./x`, `../x`, `/x`).
- */
 export function workspaceBytes(command, args, cwd, path, untrusted) {
     if (untrusted.length === 0)
         return null;
     const base = cwd ?? process.cwd();
-    // Canonical on-disk names, folded where the filesystem ignores case (macOS, Windows), so `/Users/a/CHECKOUT` is the checkout.
     const fold = process.platform === "darwin" || process.platform === "win32" ? (one) => one.toLowerCase() : (one) => one;
     const real = (one) => { try {
         return fold(realpathSync.native(one));
@@ -80,7 +49,6 @@ export function workspaceBytes(command, args, cwd, path, untrusted) {
     } };
     const roots = untrusted.map(real);
     const within = (one) => { const at = real(one); return roots.some(root => at === root || at.startsWith(`${root}${sep}`)); };
-    // A root's name anywhere in an argument (inline code, a list of paths) counts, however it's spelled.
     const mentions = (arg) => { const text = fold(arg); return roots.some(root => text.includes(root)) || untrusted.some(root => text.includes(fold(root))); };
     const located = command.includes("/") || command.includes(sep) ? resolve(base, command)
         : (path ?? "").split(delimiter).filter(Boolean).map(dir => resolve(base, dir, command)).find(one => { try {
@@ -92,13 +60,11 @@ export function workspaceBytes(command, args, cwd, path, untrusted) {
         } }) ?? null;
     if (located !== null && within(located))
         return located;
-    // A relative path once meant "in the checkout" (servers started there): it is refused rather than read elsewhere.
     if (!isAbsolute(command) && (command.includes("/") || command.includes(sep)))
         return `${command} (a relative path)`;
     for (const arg of args) {
         if (mentions(arg))
             return `${arg} (names what this build writes)`;
-        // A flag's value (`--config=x`, `-c=x`) is checked as its own argument.
         for (const piece of [arg, ...(arg.startsWith("-") && arg.includes("=") ? [arg.slice(arg.indexOf("=") + 1)] : [])]) {
             if (piece.startsWith("./") || piece.startsWith("../"))
                 return `${piece} (a relative path)`;
@@ -109,7 +75,6 @@ export function workspaceBytes(command, args, cwd, path, untrusted) {
     }
     return null;
 }
-/** A local server, started on first use and spoken to over its stdin and stdout. */
 class LocalServer {
     tool;
     options;
@@ -187,11 +152,9 @@ class LocalServer {
         try {
             this.child?.stdin?.write(`${JSON.stringify(message)}\n`);
         }
-        catch { /* its exit answers whoever waits */ }
+        catch { }
     }
-    /** One message from the agent: a request's answer, or null for a notification. */
     send(message) {
-        // A new session (a reconnect) starts a fresh server: a server answers initialize once.
         if (message.method === "initialize" && this.initialized)
             this.stop();
         if (this.child === null && this.start() === null) {
@@ -225,14 +188,13 @@ class LocalServer {
                 else
                     child.kill(name);
             }
-            catch { /* gone */ }
+            catch { }
         };
         signal("SIGTERM");
         if (child.exitCode === null && child.signalCode === null)
             setTimeout(() => signal("SIGKILL"), STOP_GRACE_MS).unref();
     }
 }
-/** A web server, relayed with its sign-in headers added here and nowhere else. */
 async function relayWeb(tool, request, body) {
     const spec = tool.spec;
     const headers = { "content-type": "application/json", accept: "application/json, text/event-stream" };
@@ -247,7 +209,6 @@ async function relayWeb(tool, request, body) {
         if (tool.values[secret])
             headers[header] = tool.values[secret];
     try {
-        // Never followed: a redirect would carry the sign-in headers to wherever it points.
         const response = await fetch(spec.url, { method: request.method ?? "POST", headers, redirect: "error", ...(request.method === "POST" ? { body } : {}) });
         const text = (await response.text()).slice(0, ANSWER_LIMIT);
         return { status: response.status, type: response.headers.get("content-type") ?? "application/json", body: text, session: response.headers.get("mcp-session-id") };
@@ -263,8 +224,6 @@ async function relayWeb(tool, request, body) {
         return { status: 200, type: "application/json", body: JSON.stringify(rpcError(id, "The tool's server could not be reached.")) };
     }
 }
-/** A relayed answer with a research step's list limited, JSON or event stream alike. An answer that isn't JSON (an
- * accepted notification's empty 202) carries no list and passes as it is. */
 function limitAnswer(answer, actions) {
     if (actions === undefined)
         return answer;
@@ -290,7 +249,6 @@ function limitAnswer(answer, actions) {
         : limit(answer.body);
     return { ...answer, body };
 }
-/** A body's JSON, or undefined when it is empty or not JSON. */
 function jsonOf(body) {
     if (body.trim() === "")
         return undefined;
@@ -301,12 +259,6 @@ function jsonOf(body) {
         return undefined;
     }
 }
-/**
- * A research batch's relayed answer with the broker's refusals added: always something the agent can read. An event
- * stream gets them as further events; anything else becomes one JSON 200 holding the server's answers, when it gave
- * some as JSON, and the refusals. An empty or non-JSON answer (an accepted notification's 202) is never passed on
- * alone, which would drop the refusals; a request the server left unanswered gets an error instead.
- */
 function withRefusals(answer, allowed, refusals) {
     if (answer.type.includes("text/event-stream")) {
         return { ...answer, body: answer.body + refusals.map(one => `\nevent: message\ndata: ${JSON.stringify(one)}\n\n`).join("") };
@@ -334,7 +286,6 @@ function readBody(request) {
         request.on("error", () => resolve(null));
     });
 }
-/** Start one launch's broker on a loopback port. */
 export async function startToolBroker(tools, options = {}) {
     const token = randomBytes(32).toString("base64url");
     const expected = Buffer.from(`Bearer ${token}`);
@@ -382,7 +333,6 @@ export async function startToolBroker(tools, options = {}) {
         const messages = Array.isArray(parsed) ? parsed : [parsed];
         if (messages.length === 0 || messages.some(one => one === null || typeof one !== "object" || Array.isArray(one) || typeof one.method !== "string"))
             return reply(response, json(400, rpcError(null, "Invalid request", -32600)));
-        // A refused action is answered here and never reaches the tool.
         const refusals = messages.map(one => refused(one, tool.actions));
         const deniedAnswers = refusals.filter((one, index) => one !== null && isRequest(messages[index]));
         if (refusals.every(one => one !== null))
@@ -391,7 +341,6 @@ export async function startToolBroker(tools, options = {}) {
                 : json(200, Array.isArray(parsed) ? deniedAnswers : deniedAnswers[0]));
         if (server === undefined) {
             const allowed = messages.filter((_, index) => refusals[index] === null);
-            // Relay exactly what was parsed and authorized, never ambiguous raw JSON.
             const answer = limitAnswer(await relayWeb(tool, request, JSON.stringify(Array.isArray(parsed) ? allowed : allowed[0])), tool.actions);
             return reply(response, deniedAnswers.length === 0 ? answer : withRefusals(answer, allowed, deniedAnswers));
         }

package/dist/tool-launcher.js

@@ -1,20 +1,6 @@
-/**
- * The launcher a Codex build starts each project tool through (v80):
- * `node tool-launcher.js <config.json>`. Codex hands its own environment
- * to the agent's shell whatever `shell_environment_policy` says (checked
- * against codex-cli 0.156), so nothing rides Codex's environment. A build's
- * launch file names its run's tool broker (tool-broker.ts) and that launch's
- * token, and this process relays stdio to it over HTTP; the tool's own
- * secrets stay in the broker. A launch file naming a local program is refused
- * (docs/plans/sandbox-parity.md C2): Codex starts this launcher outside its
- * command sandbox, so a program started here would run unfenced; every local
- * server runs in the broker, inside the server fence.
- */
 import { readFileSync } from "node:fs";
 import { createInterface } from "node:readline";
-/** The refusal for a launch file naming a local program: nothing is started (126, "could not be executed"). */
 const LOCAL_LAUNCH_REFUSED = "This tool's launch names a local program, which only Toolroll's tool broker may start (inside its fence); nothing was started.";
-/** stdio ↔ streamable HTTP: each line from Codex is POSTed; JSON or event-stream answers go back as lines. */
 function relayWeb(spec, values) {
     const headers = { "content-type": "application/json", accept: "application/json, text/event-stream" };
     if (spec.bearer !== null && values[spec.bearer])