toolroll 0.9.103 → 0.9.105

package/dist/attest.js

@@ -1,28 +1,8 @@
-/**
- * Tier-2 attestation (Parity II Phase 3, spec v1 D6 + v2 A2 + v3 B3 + v4 C3):
- * a provider outside tier 1 runs ONLY at versions its conformance fixtures
- * were proven against. The check is enforced at the one spawning gateway —
- * this module only states ranges and probes binaries; it spawns no agent.
- *
- * Guarantee, stated exactly (v4 C3): attestation proves the version of the
- * binary OBSERVED AT SPAWN TIME — probe and spawn share one resolved
- * absolute path, revalidated by a fresh stat immediately before use. A
- * concurrent atomic replacement between that stat and the kernel exec is
- * acknowledged as unprovable without content-addressed snapshots, and
- * nothing here claims otherwise.
- *
- * Re-attestation is a release act: run the conformance suite against the
- * new CLI, move `ceiling` in a reviewed commit. Removal criterion (ruling
- * 13's N, fixed): three consecutive minor releases failing conformance
- * without a fixable adapter change retire the adapter, typed.
- */
 import { ACP_AGENTS, isAcpProvider } from "./acp-agents.js";
 import { execFile } from "node:child_process";
 import { realpathSync, statSync, accessSync, constants } from "node:fs";
 import { delimiter, isAbsolute, join } from "node:path";
 import { ALL_CREDENTIAL_ENV } from "./provider.js";
-/** Tier-1 providers deliberately have NO entry: no probe, no new refusal —
- * their spawn road stays byte-identical (spec A2). */
 export const ATTESTATIONS = {
     gemini: { floor: "0.57.0", ceiling: "0.58.0", fixturesAt: "0.57.0" },
 };
@@ -30,8 +10,6 @@ export function attestationOf(provider) {
     return ATTESTATIONS[provider] ?? null;
 }
 const PROBE_TIMEOUT_MS = 5_000;
-/** Only a PLAIN release attests (v2 A2): prerelease, nightly, malformed,
- * or empty version strings are out of range BY RULE, not by comparison. */
 const PLAIN_SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
 function parsePlain(version) {
     const match = PLAIN_SEMVER.exec(version.trim());
@@ -54,8 +32,6 @@ export function versionInRange(version, range) {
         return false;
     return atLeast(v, floor) && !atLeast(v, ceiling);
 }
-/** PATH resolution to ONE absolute realpath — the path the probe runs and
- * the path the gateway spawns (v3 B3: no second resolution). */
 export function resolveExecutable(binary) {
     const candidates = [];
     if (binary.includes("/") || isAbsolute(binary)) {
@@ -79,14 +55,10 @@ export function resolveExecutable(binary) {
     return null;
 }
 const cache = new Map();
-/** Tests only. */
 export function resetAttestationCache() {
     cache.clear();
 }
 const defaultProbe = (file, args, timeoutMs) => new Promise(resolve => {
-    // A version probe needs NO credential (Codex gemini verify, finding
-    // 2): strip every provider key from the child so an authoritative
-    // attestation spawn cannot leak one.
     const env = { ...process.env };
     for (const name of ALL_CREDENTIAL_ENV)
         delete env[name];
@@ -94,15 +66,7 @@ const defaultProbe = (file, args, timeoutMs) => new Promise(resolve => {
         resolve({ code: error === null ? 0 : 1, stdout: String(stdout ?? "") });
     });
 });
-/**
- * The pre-spawn check (v2 A2): resolve, revalidate, probe if anything
- * moved, compare. Every failure is a typed refusal with words — never a
- * throw, never a silent pass. Returns null for tier-1 providers.
- */
 export async function attestProvider(provider, binary, probe = defaultProbe) {
-    // An ACP agent runs only on a passed conformance check of the exact binary here (docs/plans/acp-adapter.md
-    // § Admission). Absence is denial: there is no "tier 1, allow" for it. The check itself arrives with layer E;
-    // until then no ACP agent runs.
     if (isAcpProvider(provider)) {
         return { ok: false, problem: `${ACP_AGENTS[provider].name} isn't checked on this computer — run \`toolroll agents check ${provider}\``, version: null };
     }
@@ -158,8 +122,6 @@ export async function attestProvider(provider, binary, probe = defaultProbe) {
     }
     return { ok: true, executable: resolved, version };
 }
-/** What the installed CLI says its version is, with no range attached: a recogniser's own check (exhaustion.ts), asked of
- * the exact executable PATH resolves on this runner, only when a terminal already reads as a plan limit. Null: no answer. */
 export async function reportedVersion(binary, probe = defaultProbe) {
     const resolved = resolveExecutable(binary);
     if (resolved === null)

package/dist/audit-cli.js

@@ -1,9 +1,3 @@
-/**
- * `toolroll audit`: who did what on this server with their API tokens (remote-audit.ts). On the server's own machine
- * it lists everyone; run remotely it is the caller's own view — an approver sees everyone within their projects, a
- * viewer only themselves. `--token` names a token locally; remotely, where `--token` is always a refused credential
- * flag, the same filter is `--token-name`.
- */
 import { basename } from "node:path";
 import { checkedEnvelopeJson } from "./contracts/cli.js";
 import { AUDIT_LIMIT, AUDIT_SOURCES, cursorOf, OWNER_READER, remoteAudit, sinceOf } from "./remote-audit.js";
@@ -11,7 +5,6 @@ const EXIT = { ok: 0, usage: 2, refused: 3 };
 const COMMAND = "audit";
 const FLAGS = new Set(["person", "token", "token-name", "source", "since", "limit", "cursor", "json", "db"]);
 export const AUDIT_USAGE = "Use audit [--person <name>] [--token <name>] [--source api|mcp] [--since <days>d] [--limit <n>] [--cursor <id>] [--json].";
-/** The reader a run is: the machine's owner locally, else the remote caller with their role and projects. */
 export function readerOf(store, remote) {
     if (remote === undefined)
         return OWNER_READER;
@@ -70,13 +63,11 @@ export function auditCommand(positional, flags, context) {
     context.write(lines.join("\n"));
     return EXIT.ok;
 }
-/** One line per action: outcome first, then who, token, source, what and where. */
 export function auditLine(action) {
     const outcome = action.outcome === "ok" ? "ok" : `${action.outcome}${action.reason === null ? "" : ` (${action.reason})`}`;
     const where = action.repo === null ? "" : `  ${basename(action.repo)}`;
     return `${action.at.slice(0, 16).replace("T", " ")}  ${outcome}  ${action.person}  ${action.token ?? "unknown token"}  ${action.source}  ${action.name}${where}`;
 }
-/** The filters again for the next page, quoted when they need it. */
 function flagsAgain(flags) {
     const quote = (one) => /^[A-Za-z0-9_./:@-]+$/.test(one) ? one : `'${one.replaceAll("'", "'\\''")}'`;
     return ["person", "token", "token-name", "source", "since", "limit"].flatMap(name => {

package/dist/backend.js

@@ -1,24 +1,3 @@
-/**
- * The contract every work graph is driven through, and the guard around it.
- *
- * §4's interface, with one deliberate omission: `hold` is not here. A hold is
- * an operational pause — "not tonight, we are waiting on a person" — and not a
- * claim about how the work is structured, so it lives in the overlay where it
- * costs nobody else's tracker anything. Dependency edges are the opposite, and
- * that asymmetry is the whole rule:
- *
- * **Scheduling edges are never emulated.** A backend with no native edges is
- * *ineligible for dependency scheduling*, not repaired with invisible ones. A
- * private graph is shadow data: teammates and other tools read a task as ready
- * while our overlay privately calls it blocked, and the divergence becomes
- * migration-critical the moment anybody wants out. So `addEdge` on a backend
- * whose edges are unverified refuses, and says why, rather than storing
- * something only we can see.
- *
- * Every method answers with an outcome rather than throwing. These call other
- * people's binaries over other people's networks; failure is a normal Tuesday,
- * and one unreachable backend must not end a run covering four others.
- */
 import { BUILT_IN } from "./store.js";
 import { permits } from "./grant.js";
 export const ok = (value) => ({ ok: true, value });
@@ -27,14 +6,9 @@ export const no = (reason, message) => ({
     reason,
     message,
 });
-/**
- * The refusal a backend without confirmed edges gives, spelled once so every
- * adapter says the same thing and nobody is tempted to soften it.
- */
 export function edgesNotEmulated(name) {
     return no("unsupported", `${name} dependency edges are not confirmed here, and Toolroll does not invent them — a graph only we can see would read as ready to everyone else`);
 }
-/** Turn a failed command into words, without pretending to know more than we do. */
 export function describeFailure(result) {
     if (result.notFound)
         return "the command is not installed";
@@ -51,17 +25,6 @@ export function parseJson(text) {
         return null;
     }
 }
-/**
- * The built-in store, behind the same contract as everyone else.
- *
- * Worth the wrapper even though it is ours: the scheduler should not be able
- * to tell which backend it is driving, and the day this is the only one with a
- * privileged shortcut is the day the interface stops being tested.
- *
- * It is the only backend here whose edges are both native and ours to write,
- * so it is also the only one where dependency scheduling is unconditionally
- * available.
- */
 export function builtIn(store, now = () => new Date()) {
     return {
         name: BUILT_IN,
@@ -78,9 +41,6 @@ export function builtIn(store, now = () => new Date()) {
             return ok(task === null ? null : { id: task.id, title: task.title, state: task.state });
         },
         async create(spec) {
-            // The id is derived from the title here rather than by the caller, so
-            // that every backend's `create` has the same shape: hand it a spec, get
-            // an id back.
             const id = `${slug(spec.title)}-${now().toISOString().slice(11, 19).replace(/:/g, "")}`;
             if (store.getTask(id) !== null)
                 return no("rejected", `\`${id}\` already exists`);
@@ -114,18 +74,6 @@ function slug(title) {
         .join("-");
     return words === "" ? "task" : words;
 }
-/**
- * Wrap a backend so nothing can write through it without a grant.
- *
- * Applied once, at construction, rather than checked inside each adapter — an
- * authorization that every implementation has to remember to call is one that
- * a future adapter will forget, and it will forget it silently. Here the only
- * way to reach a mutating method is through the wrapper, and adding a backend
- * later inherits the check by construction.
- *
- * Reads pass straight through. Discovery has always been read-only and needs
- * no permission; it is writing to somebody else's tracker that requires one.
- */
 export function guarded(backend, options) {
     const { store, repo } = options;
     const allowed = (mutation, id) => {
@@ -133,8 +81,6 @@ export function guarded(backend, options) {
             repo,
             backend: backend.name,
             mutation,
-            // Read from the overlay, never from the caller. A task we have merely
-            // seen is `theirs` until something explicitly makes it ours.
             origin: id === undefined ? "ours" : store.originOf(backend.name, id),
         });
         return verdict.ok ? null : no("denied", verdict.message);
@@ -145,15 +91,10 @@ export function guarded(backend, options) {
         listReady: () => backend.listReady(),
         get: id => backend.get(id),
         async create(spec) {
-            // A task we are about to create is ours by definition; there is no id to
-            // ask the overlay about yet, and the selector cannot be what stops it.
             const denied = allowed("create");
             return denied ?? backend.create(spec);
         },
         async setState(id, state) {
-            // Closing somebody's issue and moving our own task along are different
-            // acts to a person, however alike they look to a database, so they check
-            // against different mutation classes.
             const terminal = state === "done" || state === "failed" || state === "cancelled";
             const denied = allowed(terminal ? "close" : "transition", id);
             return denied ?? backend.setState(id, state);

package/dist/backup-ui.js

@@ -1,25 +1,16 @@
-/**
- * Settings → Backups (sprint 8): how the last backup went and one button to
- * back up now, then the schedule, past backups and how to restore. Built from
- * the revamp kit (src/design/KIT.md); the Settings frame adds the title.
- */
 import { html, joinHtml, postForm } from "./html.js";
 import { bytesWords } from "./storage.js";
 import { whenUtc } from "./when-html.js";
 import { btn, chip, codeLine, formRow, infoLine, input, note, notice, select, settingsRecord, settingsSection } from "./server/kit.js";
 import { kitSectionForm } from "./settings-kit.js";
-/** The schedules on offer and the most copies kept. Here rather than in backup.ts so the page never loads `node:sqlite`. */
 export const BACKUP_EVERY_HOURS = [1, 6, 12, 24];
-/** The continuous copy's choices, in minutes (live-backup.ts LIVE_EVERY_MINUTES; here so the page never loads it). */
 export const LIVE_EVERY = [1, 5, 15, 30];
 export const MAX_KEEP = 100;
 const when = (at) => whenUtc(at);
 const whenWords = (at) => `${at.slice(0, 16).replace("T", " ")} UTC`;
 const everyWords = (hours) => hours === 1 ? "Every hour" : hours === 24 ? "Every day" : `Every ${hours} hours`;
 const fileName = (path) => path.slice(path.lastIndexOf("/") + 1);
-/** The page is kit pieces now; nothing of the old look is left. Kept as an export for the shared stylesheet. */
 export const BACKUP_CSS = "";
-/** The continuous copy in one line: its latest verified copy, or why there is none. */
 function liveLine(view) {
     const live = view.live;
     if (live === undefined)
@@ -32,7 +23,6 @@ function liveLine(view) {
         return note("The first continuous copy is made within a few minutes of Toolroll starting.");
     return html `<p class="k-note" data-live-copy>Continuous copy checked ${when(live.state.latest.madeAt)}, every ${live.state.settings.everyMinutes === 1 ? "minute" : `${live.state.settings.everyMinutes} minutes`}.</p>`;
 }
-/** The last backup as one record: what happened, the next one, and Back up now. */
 function state(view) {
     const last = view.runs[0];
     const good = view.runs.find(one => one.ok === true);
@@ -52,7 +42,6 @@ function state(view) {
     return settingsRecord({ title: html `Backed up ${when(last.startedAt)}`, attrs: { "data-backup-state": "ok" }, action: now,
         sub: `${last.bytes === null ? "" : `${bytesWords(last.bytes)} · `}${next}` });
 }
-/** One past backup: when, how it went, its file, and whether it was by hand. */
 function runRow(run) {
     const how = run.trigger === "manual" ? "By hand" : "Scheduled";
     const attrs = { "data-backup-run": run.id };
@@ -92,7 +81,6 @@ export function backupHtml(view, said) {
         ]) });
     return joinHtml([now, schedule, history, restore]);
 }
-/** The continuous copy's two choices, beside the schedule's: how often, and where (blank: beside the database). */
 function liveFields(view) {
     const live = view.live;
     if (live === undefined)

package/dist/backup.js

@@ -1,17 +1,3 @@
-/**
- * Backups (sprint 8): the database, copied on a schedule with SQLite's online
- * backup (one read snapshot, so the console and workers keep writing), into
- * a folder the operator chooses (by default `backups` beside the database),
- * keeping the newest N. Each backup is checked (it opens, it passes SQLite's
- * quick check) before it counts, and each one's outcome is kept.
- *
- * Only the database is copied. Provider keys, sign-in files and other secrets
- * live in their own files beside it and are never part of a backup.
- *
- * `restore` puts a backup back, only with Toolroll stopped: it checks
- * the backup's schema version and walks its ledger chain first, keeps the
- * current database as a copy, and with --dry-run changes nothing.
- */
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { chmodSync, closeSync, constants, copyFileSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, realpathSync, renameSync, rmSync, statSync } from "node:fs";
 import { hostname } from "node:os";
@@ -21,23 +7,15 @@ import { BACKUP_EVERY_HOURS, MAX_KEEP } from "./backup-ui.js";
 import { verifyLedgerChain } from "./ledger-chain.js";
 import { DEFAULT_LIVENESS_MS } from "./runner.js";
 import { openStore, readSchemaVersion, SCHEMA_VERSION } from "./store.js";
-/** A scheduled backup's name: the database it came from (see `databaseTag`), then when it was made. Backups made
- * before the tag was added have none. Retention only ever removes files named like this. */
-const BACKUP_NAME = /^standing-orders-(?:([0-9a-f]{8})-)?(\d{4}-\d{2}-\d{2}-\d{6})(?:-(\d+))?\.db$/;
-/** The oldest schema whose ledger has a hash chain to verify. */
+const BACKUP_NAME = /^(?:toolroll|standing-orders)-(?:([0-9a-f]{8})-)?(\d{4}-\d{2}-\d{2}-\d{6})(?:-(\d+))?\.db$/;
 export const OLDEST_RESTORABLE = 103;
 export { BACKUP_EVERY_HOURS, MAX_KEEP };
-/** How long the console's lease lasts without a renewal: a console that stopped holds it no longer than this. */
 const LEASE_MS = 3 * 60_000;
-/** A worker that heartbeat this recently is taken to be running (runner.ts DEFAULT_LIVENESS_MS). */
 const RUNNER_FRESH_MS = DEFAULT_LIVENESS_MS;
 export const defaultBackupFolder = (databaseFile) => join(dirname(databaseFile), "backups");
 export const backupFolderOf = (settings, databaseFile) => settings.folder ?? defaultBackupFolder(databaseFile);
-/** 2026-09-28T05:34:39.123Z → 2026-09-28-053439 (UTC). */
 const stampOf = (now) => now.toISOString().replace(/\.\d+Z$/, "").replace("T", "-").replace(/:/g, "");
 const message = (error) => error instanceof Error ? error.message : String(error);
-/** Loaded on first use, as store.ts does, so modules that only import this one (the console, and tests that load it
- * in a browser-like environment) never need `node:sqlite` itself. */
 function sqlite() {
     return createRequire(import.meta.url)("node:sqlite");
 }
@@ -46,11 +24,8 @@ function connect(file) {
     db.exec("PRAGMA busy_timeout = 5000");
     return db;
 }
-/** Copy `sourceFile` into `target` with the online backup (all pages in one step: one consistent snapshot, and
- * writers carry on meanwhile), then make the copy one self-contained file and check it. */
 export async function onlineCopy(sourceFile, target) {
     const source = connect(sourceFile);
-    // Every page in one step (SQLite's -1 means that too, but newer Node builds take only a positive rate).
     try {
         await sqlite().backup(source, target, { rate: 1_000_000 });
     }
@@ -80,33 +55,28 @@ export async function onlineCopy(sourceFile, target) {
     }
     return { bytes: statSync(target).size, schemaVersion };
 }
-/** A folder the operator may choose: a full path, outside every project and build checkout (agents work there). */
 export function checkBackupFolder(path, forbidden) {
     const folder = path.trim();
     if (!isAbsolute(folder) || folder.length > 500 || /[\u0000-\u001f]/.test(folder))
-        return "The folder is a full path, like /Volumes/Backup/standing-orders.";
+        return "The folder is a full path, like /Volumes/Backup/toolroll.";
     const at = resolve(folder);
     const inside = (one, parent) => one === parent || one.startsWith(`${parent}/`);
     if (forbidden.some(one => inside(at, resolve(one)) || inside(resolve(one), at)))
         return "Choose a folder outside your projects and build checkouts: agents work there.";
     return null;
 }
-/** A short tag for one database, from its full path, so databases that share a backup folder tell their backups apart. */
 export function databaseTag(databaseFile) {
     let path = resolve(databaseFile);
     try {
         path = realpathSync(path);
     }
-    catch { /* not there yet: its path as given */ }
+    catch { }
     return createHash("sha256").update(path).digest("hex").slice(0, 8);
 }
 export function backupOwner(store, databaseFile) {
     const made = store.handle.prepare("SELECT file FROM backup_run WHERE ok = 1 AND file IS NOT NULL").all().map(row => resolve(String(row["file"])));
     return { tag: databaseTag(databaseFile), made: new Set(made) };
 }
-/** This database's backups in a folder, made on a schedule or by `backup now`, newest first. A backup tagged for
- * another database is never this one's. An untagged one (made before backups were tagged) is this one's only when its
- * own history records making it: pruning deletes, so what can't be proved ours is left alone. */
 export function backupFiles(folder, owner) {
     let names;
     try {
@@ -130,7 +100,6 @@ export function backupFiles(folder, owner) {
         }
     });
 }
-/** Remove all but this database's newest `keep` backups. Never touches another database's, or anything else in the folder. */
 export function pruneBackups(folder, keep, owner) {
     let removed = 0;
     for (const one of backupFiles(folder, owner).slice(Math.max(1, keep))) {
@@ -138,11 +107,10 @@ export function pruneBackups(folder, keep, owner) {
             rmSync(one.path);
             removed++;
         }
-        catch { /* the next backup tries again */ }
+        catch { }
     }
     return removed;
 }
-/** A failure in plain words: the common file-system ones by name, anything else as SQLite or Node said it. */
 function failureWords(error, folder) {
     const code = error?.code;
     if (code === "EACCES" || code === "EPERM" || code === "EROFS")
@@ -153,7 +121,6 @@ function failureWords(error, folder) {
         return `${folder} isn't a folder.`;
     return message(error);
 }
-/** Back the database up now, keep the newest N, and record how it went. */
 export async function backupNow(store, databaseFile, trigger, clock = () => new Date()) {
     const settings = store.backupSettings();
     const folder = backupFolderOf(settings, databaseFile);
@@ -162,11 +129,9 @@ export async function backupNow(store, databaseFile, trigger, clock = () => new
     try {
         mkdirSync(folder, { recursive: true, mode: 0o700 });
         const stamp = `${databaseTag(databaseFile)}-${stampOf(clock())}`;
-        let name = `standing-orders-${stamp}.db`;
+        let name = `toolroll-${stamp}.db`;
         for (let n = 2; existsSync(join(folder, name)); n++)
-            name = `standing-orders-${stamp}-${n}.db`;
-        // The whole chain walked and its head checkpointed first, so the copy carries the checkpoint. A broken chain gets
-        // none (the walk raises the console's chain alarm, as any whole walk does); the backup goes ahead either way.
+            name = `toolroll-${stamp}-${n}.db`;
         let checkpoint;
         try {
             checkpoint = store.ledgerCheckpoint("system", clock(), {});
@@ -196,7 +161,6 @@ export async function backupNow(store, databaseFile, trigger, clock = () => new
         return { ok: false, id, error: words };
     }
 }
-/** Whether a scheduled backup is due: the last good one is older than the schedule, and the last try over an hour ago. */
 export function backupDue(store, now) {
     const settings = store.backupSettings();
     if (!settings.enabled)
@@ -211,7 +175,6 @@ export function backupDue(store, now) {
         return false;
     return last === undefined || now.getTime() - Date.parse(last.startedAt) >= Math.min(every, 60 * 60_000);
 }
-/** One pass of the loop beside the console: renew the lease (a restore sees it), and back up when due. */
 export async function backupPass(store, databaseFile, holder, clock = () => new Date()) {
     const now = clock();
     if (!store.holdBackupLease(holder, now, new Date(now.getTime() + LEASE_MS)))
@@ -220,7 +183,6 @@ export async function backupPass(store, databaseFile, holder, clock = () => new
         return null;
     return backupNow(store, databaseFile, "scheduled", clock);
 }
-/** The loop beside the console: a pass a minute. */
 export function startBackups(store, databaseFile, everyMs = 60_000) {
     const holder = `${hostname()}:${process.pid}:${randomUUID().slice(0, 8)}`;
     let stopped = false, timer = null;
@@ -230,7 +192,7 @@ export function startBackups(store, databaseFile, everyMs = 60_000) {
         try {
             await backupPass(store, databaseFile, holder);
         }
-        catch { /* the next pass tries again */ }
+        catch { }
         if (!stopped) {
             timer = setTimeout(() => void pass(), everyMs);
             timer.unref?.();
@@ -245,10 +207,9 @@ export function startBackups(store, databaseFile, everyMs = 60_000) {
         try {
             store.releaseBackupLease(holder);
         }
-        catch { /* the lease runs out on its own */ }
+        catch { }
     };
 }
-/** What's running against the database now: the console (its backup lease), and workers (watch leases, runner heartbeats). */
 export function runningNow(store, now) {
     const running = [];
     if (store.backupLease(now) !== null)
@@ -260,11 +221,6 @@ export function runningNow(store, now) {
         running.push(runners.length === 0 ? "a worker" : `the worker ${runners.join(", ")}`);
     return running;
 }
-/**
- * Put a backup back in place of the database. Refuses while Toolroll is running, when the backup isn't a
- * Toolroll database this build can read (its schema version), or when its ledger chain doesn't verify. The
- * backup is copied beside the database first and every check runs on that copy, so what was checked is what goes in.
- */
 export async function restoreDatabase(options) {
     const { databaseFile, dryRun, now } = options;
     const file = resolve(options.file);
@@ -281,7 +237,6 @@ export async function restoreDatabase(options) {
         return refuse("not-found", `${file} isn't a plain file.`);
     if (existsSync(databaseFile) && resolve(databaseFile) === file)
         return refuse("same-file", "That's the database in use now, not a backup.");
-    // What's running, and where the copy of the current database goes, from the database as it is.
     let folder;
     {
         const store = openStore(databaseFile);
@@ -338,8 +293,6 @@ export async function restoreDatabase(options) {
         finally {
             db.close();
         }
-        // It must open as this build's database (every table it needs, every step up to this schema) before it may replace
-        // the live one: a sound file with the right version can still be missing what Toolroll reads.
         if (report.refusals.length === 0) {
             const probe = `${staged}.probe`;
             try {
@@ -360,7 +313,6 @@ export async function restoreDatabase(options) {
             report.ok = report.refusals.length === 0;
             return report;
         }
-        // Keep the database as it is now, checked like any backup, before anything replaces it.
         mkdirSync(folder, { recursive: true, mode: 0o700 });
         const saved = join(folder, `before-restore-${stampOf(now)}-${randomBytes(3).toString("hex")}.db`);
         const partial = `${saved}.partial`;
@@ -373,7 +325,6 @@ export async function restoreDatabase(options) {
             throw new Error(`the current database couldn't be saved first, so nothing was replaced (${message(error)})`);
         }
         report.savedAs = saved;
-        // Again, just before the swap: nothing may have started meanwhile.
         const store = openStore(databaseFile);
         try {
             const running = runningNow(store, new Date());
@@ -383,7 +334,6 @@ export async function restoreDatabase(options) {
         finally {
             store.close();
         }
-        // Fold the write-ahead log in and drop it, so nothing of the old database is left beside the new one.
         const live = connect(databaseFile);
         try {
             live.exec("PRAGMA wal_checkpoint(TRUNCATE)");
@@ -396,8 +346,6 @@ export async function restoreDatabase(options) {
             rmSync(`${databaseFile}${suffix}`, { force: true });
         renameSync(staged, databaseFile);
         keepStaged = true;
-        // The restored database brought up to this build, and the restore in its ledger. Should it still not open, the
-        // database it replaced goes back, and the restore says so.
         let restored;
         try {
             restored = openStore(databaseFile);
@@ -425,7 +373,6 @@ export async function restoreDatabase(options) {
             rmSync(staged, { force: true });
     }
 }
-/** An error's first line, for a sentence. */
 function firstLine(error) {
     return (error instanceof Error ? error.message : String(error)).split("\n")[0].slice(0, 200);
 }

package/dist/batch-checks.js

@@ -10,7 +10,6 @@ import { boundStreamHeadTail, redactSecretLines, scanForSecrets, storeEvidence }
 import { repoClause } from "./check-levels.js";
 import { projectBatchChecks } from "./batch-policy.js";
 import { CHECKS_FINISHED, CHECKS_REQUESTED, CHECKS_STARTED, FOLLOW_UP_LOG, FOLLOW_UP_RECEIPT, followUpChecksOf, waitingRequestsOfAnyKind, } from "./result-follow-ups.js";
-/** Queue a finished build's commit for a batch check, bound to the exact approved command. Once per commit. */
 export function queueBatchCheck(store, input, now) {
     return store.transact(() => {
         const [where, params] = repoClause(input.repo);
@@ -24,7 +23,6 @@ export function queueBatchCheck(store, input, now) {
         return id;
     });
 }
-/** The batch pass: settle what can't be checked, then check every cohort that is ready. Returns how many results it settled. */
 export async function runBatchChecks(store, root, deps = {}) {
     const now = deps.now ?? (() => new Date());
     const waiting = waitingRequestsOfAnyKind(store, now()).filter(one => one.why === "batch");
@@ -35,7 +33,6 @@ export async function runBatchChecks(store, root, deps = {}) {
         const ref = run === null ? null : store.refById(run.taskRef);
         if (run === null || ref === null || ref.repo === null)
             continue;
-        // Not finished yet: the build is still sealing its result.
         if (run.finishedAt === null)
             continue;
         const finish = (detail) => { claim(store, one, ref.repo, ref.externalId, 0, now()) && finishOne(store, one, ref.repo, ref.externalId, "not-run", detail, now()); settled++; };
@@ -48,7 +45,6 @@ export async function runBatchChecks(store, root, deps = {}) {
             finish("The approved check changed while it waited. Run checks to check it now.");
             continue;
         }
-        // A cohort shares one check level: results whose own checks ran at different levels are checked apart (check-access.ts).
         const key = `${ref.repo}\u0000${one.digest}\u0000${store.runCheckAccess(one.runId)}`;
         cohorts.set(key, [...(cohorts.get(key) ?? []), { request: one.request, runId: one.runId, task: ref.externalId, head: one.head, base: one.base ?? null, at: one.at }]);
     }
@@ -58,8 +54,6 @@ export async function runBatchChecks(store, root, deps = {}) {
         const repo = key.split("\u0000")[0];
         const policy = projectBatchChecks(store, repo);
         const oldest = Math.min(...members.map(one => Date.parse(one.at)));
-        // A cohort closes when a second result joins it, or when its oldest has waited the window.
-        // Turned off while waiting: no point waiting any longer.
         if (members.length < 2 && policy.on && now().getTime() - oldest < policy.windowMs)
             continue;
         if (policy.on)
@@ -83,35 +77,28 @@ function finishOne(store, one, repo, task, status, detail, at) {
     store.bumpWake();
     return true;
 }
-/** Check one cohort. Every member is claimed first; every claimed member ends with a sealed receipt. */
 async function checkCohort(store, root, repo, cohort, deps) {
     const now = deps.now ?? (() => new Date());
     const runner = deps.runner ?? execRun;
-    // The project's repository and checkouts of builds' commits, both agent-writable: the hardened git (teardown-git.ts).
     const git = deps.git ?? hardenedGit(execRun);
     const command = store.liveVerifyCommand(repo);
     if (command === null)
         return 0;
     const setup = store.liveWorktreeSetup(repo);
-    // The longest a full split could take: every subset checked once, with its setup.
     const limit = (command.timeoutMs + (setup?.timeoutMs ?? 0) + 240_000) * Math.max(1, 2 * cohort.length - 1);
     const members = cohort.filter(one => claim(store, one, repo, one.task, limit, now())).sort((a, b) => a.request - b.request);
     if (members.length === 0)
         return 0;
-    // The project base: the oldest member's recorded base, else its own parent.
     const base = members[0].base;
     const logs = new Map(members.map(one => [one.request, []]));
     const attempts = new Map(members.map(one => [one.request, []]));
     const bound = (text) => { const hits = scanForSecrets(text); return boundStreamHeadTail(hits.length > 0 ? redactSecretLines(text, hits) : text, 12 * 1024); };
     const section = (label, shown, result) => `=== ${label} ===\n$ ${shown}\n(exit ${result.code}${result.notFound ? ", could not start" : ""}${result.timedOut ? ", timed out" : ""})\n\n--- stdout ---\n${bound(result.stdout)}\n\n--- stderr ---\n${bound(result.stderr)}`;
-    // How each command actually ran (check-access.ts), per result: only the commands it was part of count for its receipt.
     const ranAtOf = new Map();
     const note = (set, text) => { for (const one of set)
         logs.get(one.request).push(text); };
     const attempt = (set, tested, outcome) => { for (const one of set)
         attempts.get(one.request).push({ members: set.map(m => m.task), tested, outcome }); };
-    /** One approved check of `set` in a temporary detached checkout: the merge of every member onto the base,
-     * or a single member's own commit. Never a real ref: the checkout is detached and always removed. */
     const checkOnce = async (set) => {
         const folder = mkdtempSync(join(deps.scratch ?? tmpdir(), "toolroll-batch-"));
         const checkout = join(folder, "checkout");
@@ -125,7 +112,6 @@ async function checkCohort(store, root, repo, cohort, deps) {
             }
             if (set.length > 1) {
                 for (const one of set) {
-                    // A local merge commit in the detached checkout only: no hooks, no signing, no branch.
                     const merged = await git("git", ["-C", checkout, "-c", "user.name=Toolroll batch check", "-c", "user.email=batch-check@toolroll.invalid", "-c", "commit.gpgsign=false",
                         "-c", "core.hooksPath=/dev/null", "merge", "--no-ff", "--no-edit", "--no-verify", "-m", `Batch check: ${one.task}`, one.head], { timeoutMs: 120_000 });
                     if (merged.code !== 0) {
@@ -141,10 +127,7 @@ async function checkCohort(store, root, repo, cohort, deps) {
                 return { conflict: false, tested: null, outcome: { ran: false, failure: "The batch commit couldn't be read." }, setupFailed: false };
             if (deps.shouldStop?.() === true)
                 return { conflict: false, tested, outcome: { ran: false, failure: "Stopped before the check started." }, setupFailed: false };
-            // The approvals are re-read before every spawn: a revoked or changed command never runs.
             const liveSetup = store.liveWorktreeSetup(repo);
-            // Worked out again right before each command (check-access.ts): a narrowing meanwhile applies to the next one. Each
-            // member is credited with exactly the commands of this set.
             const setRan = (level) => { for (const one of set)
                 ranAtOf.set(one.request, [...(ranAtOf.get(one.request) ?? []), level]); };
             if ((liveSetup?.digest ?? null) !== (setup?.digest ?? null))
@@ -213,20 +196,17 @@ async function checkCohort(store, root, repo, cohort, deps) {
             return;
         }
         if ((outcome.ran && outcome.exitCode !== 0) || result.setupFailed) {
-            // Something in this batch breaks the check: split it until the result that breaks it is found.
             attempt(set, tested, "failed");
             const half = Math.ceil(set.length / 2);
             await checkSet(set.slice(0, half), "split");
             await checkSet(set.slice(half), "split");
             return;
         }
-        // It couldn't run at all (time, approvals, a stop): nothing is known about any member.
         attempt(set, tested, "not-run");
         for (const one of set)
             seal(one, mode, [one], null, outcome);
     };
     await checkSet(members, "alone").catch(error => {
-        // An unexpected failure still ends every claimed member, visibly.
         for (const one of members)
             if (followUpChecksOf(store, one.runId, now()).find(f => f.request === one.request)?.state === "running")
                 finishOne(store, one, repo, one.task, "not-run", `The batch check failed to run: ${String(error).slice(0, 200)}`, now());

package/dist/batch-policy.js

@@ -1,15 +1,12 @@
-/** Ledger action for the project setting. The newest entry wins; none means off. */
 export const BATCH_POLICY_ACTION = "batch checks changed";
 export const BATCH_WINDOW_MS = 10 * 60_000;
 export const BATCH_HINT = "Results that finish within 10 minutes of each other share one full check.";
-/** A project's batch setting. Off unless an approver turned it on. */
 export function projectBatchChecks(store, repo) {
     const row = store.handle.prepare("SELECT actor, at, outcome FROM action_ledger WHERE repo = ? AND task_id IS NULL AND action = ? ORDER BY id DESC LIMIT 1").get(repo, BATCH_POLICY_ACTION);
     if (row === undefined || (row["outcome"] !== "on" && row["outcome"] !== "off"))
         return { on: false, windowMs: BATCH_WINDOW_MS, setBy: null, at: null };
     return { on: row["outcome"] === "on", windowMs: BATCH_WINDOW_MS, setBy: String(row["actor"]), at: String(row["at"]) };
 }
-/** An approver's act: turn batching on or off for one project. The ledger keeps before → after. */
 export function setProjectBatchChecks(store, repo, on, by, now) {
     const before = projectBatchChecks(store, repo);
     if (before.on === on)
@@ -19,7 +16,6 @@ export function setProjectBatchChecks(store, repo, on, by, now) {
     store.bumpWake();
     return { changed: true, before: before.on };
 }
-/** The builder's question at its gate: does this Full check wait for a batch? */
 export function batchesFullCheck(store, repo, level, command) {
     return repo !== null && level === "full" && command !== null && command.repo === repo && projectBatchChecks(store, repo).on;
 }