toolroll 0.9.103 → 0.9.105

package/dist/check-failure.js

@@ -1,24 +1,3 @@
-/**
- * Why a release check failed, in one of four classes (docs/plans/eval-harness.md, phase 1 C), and what each class
- * allows. This replaces the flat "two flakes" allowance (AUTO_FLAKE_CAP) for release checks and for GitHub CI.
- *
- *   deterministic    typecheck, build, a failing test, a scripted journey, an upgrade, a required test gone:
- *                    nothing tolerated, never rerun to pass; the branch is fixed and the new commit released.
- *   infrastructure   independently confirmed by the plane itself: the check never started, this worker lost the
- *                    build, Toolroll's own shutdown stopped it, it ran out of time on a machine the plane measured
- *                    busy enough to cut its budget to half or less (check-load.ts) — or, on GitHub, a job that failed before any of the
- *                    workflow's own steps ran. At most one rerun per incident and two per candidate, under the same
- *                    approval; a pass after them counts.
- *   unknown          exit 1 with no failing test named, an unexplained timeout or signal, no result at all: an error
- *                    that blocks. A diagnostic rerun may run, but its pass doesn't erase the failure: a person decides.
- *   agent-behaviour  a real-model journey failed (or passed only on its retry): counted, never rerun to pass.
- *
- * Only plane-side facts can make a failure "infrastructure": the sealed receipt's own result (which the builder writes
- * from the process it ran), and GitHub's own job and step records read by the plane's gh. Nothing the candidate writes —
- * its output, a label it prints, its report — can. The report is candidate-written: it is read only to choose among
- * the classes that block (deterministic, agent-behaviour, unknown), never to allow a rerun. gate-failure.ts's
- * classifyGateFailure reads the log and is never evidence that a release failure is harmless.
- */
 import { CHECK_REPORT_CAPTURE, readSealedJson } from "./check-report.js";
 import { readCheckReport } from "./contracts/release-check.js";
 import { busyMachineTimeout, CHECK_LOAD_CAPTURE, readCheckLoad } from "./check-load.js";
@@ -28,25 +7,15 @@ import { releaseCheckScope } from "./scope.js";
 import { isVerificationReceipt, verificationEvidence } from "./verification-evidence.js";
 import { checkAttemptOf } from "./store.js";
 import { endedInterrupted } from "./run-ending.js";
-/** The plane's limits for confirmed infrastructure failures (one rerun per incident, two per candidate). */
 export { INFRA_RERUNS_PER_CANDIDATE, INFRA_RERUNS_PER_INCIDENT };
-/** The ledger action that records each rerun the release asked for, and why. */
 export const RELEASE_RECHECK_ACTION = "release check rerun";
-/** The failures that mean the check never started or never finished for a reason the plane itself saw. */
 const PLANE_INFRA = {
     "spawn-failed": "the check never started: the machine couldn't start its command",
     "retry-spawn-failed": "the check's retry never started: the machine couldn't start its command",
     "custody-lost": "this worker lost the build before the check could finish",
     "stopped-by-toolroll": "Toolroll's own shutdown stopped the check before it finished",
 };
-/** How a timeout on a busy machine reads (its rerun is the release terms' "Toolroll's own machine fails"). */
 const busyWords = (why) => `${why}: Toolroll's own machine, so this commit's check runs again`;
-/**
- * One failed check, classified. `facts` come from the plane's sealed receipt and `load` from the plane's own sealed load
- * record (check-load.ts); `report` (the check's own report, sealed when valid) only ever picks among the classes that
- * block — a timeout is excused only when the report names nothing else that failed, and only by the plane's own facts:
- * its load readings cut the budget, and the check ran into its limit by the plane's own clock. Null when it passed.
- */
 export function classifyCheckFailure(facts, report, load = null) {
     const result = facts.result;
     const passedCoverage = facts.coverage === undefined || facts.coverage === "full" || facts.coverage === "composed";
@@ -60,8 +29,6 @@ export function classifyCheckFailure(facts, report, load = null) {
         if (infra !== undefined)
             return { class: "infrastructure", why: infra };
         if (failure === "timed-out" || failure === "retry-timed-out") {
-            // The plane stopped it at its limit. With the plane's own record of a cut budget, the machine's fault; otherwise
-            // (a normal budget, or no record) a timeout nothing explains, as ever.
             const busy = facts.grantMs === undefined ? null : busyMachineTimeout(load, facts.grantMs, true);
             return busy !== null ? { class: "infrastructure", why: busyWords(busy) } : { class: "unknown", why: "the check timed out, and nothing says why" };
         }
@@ -73,11 +40,9 @@ export function classifyCheckFailure(facts, report, load = null) {
             return { class: "deterministic", why: facts.coverage === "identity-removed" ? "a required test was removed, renamed or newly skipped" : "the check didn't cover everything it owed" };
         return { class: "unknown", why: `the check couldn't run to its end (${failure || "no reason recorded"})` };
     }
-    // It ran and exited nonzero (or its coverage fell short): what failed, from its report — only among blocking classes.
     if (report === null)
         return { class: "unknown", why: `the check exited ${result.exitCode ?? "nonzero"} and gave no report naming what failed` };
     const deterministic = [], agent = [], unexplained = [];
-    // Whether everything unexplained is a part that ran out of time (never a signal, never an error no test owned).
     let onlyTimeouts = true;
     for (const part of report.parts) {
         if (!part.selected || !part.ran || part.code === null)
@@ -113,8 +78,6 @@ export function classifyCheckFailure(facts, report, load = null) {
     if (agent.length > 0)
         return { class: "agent-behaviour", why: list(agent) };
     if (unexplained.length > 0) {
-        // Only parts that ran out of time, and the plane's own record says the machine cut the budget and the check ran
-        // into its limit: the machine's fault. The report can only withhold this (by naming anything else), never grant it.
         const busy = onlyTimeouts && facts.grantMs !== undefined ? busyMachineTimeout(load, facts.grantMs, false) : null;
         if (busy !== null)
             return { class: "infrastructure", why: busyWords(`${list(unexplained)}; ${busy}`) };
@@ -122,8 +85,6 @@ export function classifyCheckFailure(facts, report, load = null) {
     }
     return { class: "unknown", why: `the check exited ${result.exitCode ?? "nonzero"} with no failing test identified` };
 }
-/** What passed only on a retry inside a passing check (a real-model journey group, a unit file): counted and reported,
- * never silently part of a pass. Null when there is no valid report to read it from: unknown, never "no retries". */
 export function retriedInside(report) {
     if (report === null)
         return null;
@@ -132,8 +93,6 @@ export function retriedInside(report) {
         ...(report.units?.files ?? []).filter(file => file.flaky).map(file => `${file.file}`),
     ];
 }
-/** A run's check, classified from its sealed receipt and sealed report; null when it passed, or can't be read (then
- * `unreadable` says why — an unreadable receipt is itself unknown). */
 export function classifyRunCheck(store, root, runId) {
     const gate = verificationEvidence(store, root, runId);
     if (!gate.ok)
@@ -151,16 +110,10 @@ export function classifyRunCheck(store, root, runId) {
         return { class: "unknown", why: "the check's receipt names no result" };
     const sealed = readSealedJson(store, root, runId, CHECK_REPORT_CAPTURE);
     const parsed = sealed === null ? null : readCheckReport(sealed.value);
-    // The plane's own load record (check-load.ts): absent on older runs, and then nothing is excused.
     const loadSealed = readSealedJson(store, root, runId, CHECK_LOAD_CAPTURE);
     const grantMs = typeof receipt.command?.timeoutMs === "number" ? receipt.command.timeoutMs : undefined;
     return classifyCheckFailure({ result: receipt.result, coverage: receipt.coverage, grantMs }, parsed?.ok === true ? parsed.value : null, loadSealed === null ? null : readCheckLoad(loadSealed.value));
 }
-/**
- * What passed only on a retry inside a run's check (eval-harness review 1, finding 3): the summary sealed into its
- * protected receipt, which a damaged or lost report can't take away; for an older receipt without one, read from the
- * sealed report. Null — unknown — when neither can be read, or when a readable report disagrees with the receipt.
- */
 export function retriedOfRun(store, root, runId) {
     const sealed = readSealedJson(store, root, runId, CHECK_REPORT_CAPTURE);
     const parsed = sealed === null ? null : readCheckReport(sealed.value);
@@ -175,9 +128,6 @@ export function retriedOfRun(store, root, runId) {
     catch {
         return null;
     }
-    // The whole check rerun after the approved recovery setup (finding 6): its first attempt failed, and a missing
-    // executable is never confirmed infrastructure, so it counts as a retry like any other — reported, and an automatic
-    // approval refuses it.
     const replayed = body.result?.setupReplayed === true ? [setupReplayWords(body.result.firstAttempt)] : [];
     const receipt = body.check?.retried;
     if (receipt === undefined)
@@ -188,12 +138,7 @@ export function retriedOfRun(store, root, runId) {
         return null;
     return [...replayed, ...receipt];
 }
-/** How a check rerun after the approved recovery setup reads among the retries. */
 export const SETUP_REPLAY_RETRY = "the whole check, rerun after the approved setup";
-/**
- * The rerun's words with its first attempt's own class (eval-harness review 2, finding 5): a launch failure names the
- * missing program; a receipt that doesn't classify it (an older one) says so, never that it was a launch failure.
- */
 export function setupReplayWords(first) {
     const one = first !== null && typeof first === "object" ? first : null;
     if (one !== null && one.class === "launch" && typeof one.program === "string" && Number.isSafeInteger(one.exitCode)) {
@@ -201,13 +146,6 @@ export function setupReplayWords(first) {
     }
     return `${SETUP_REPLAY_RETRY} (its first attempt's failure isn't classified)`;
 }
-/**
- * An attempt interrupted before its candidate was even loaded (run 3326: the worker stopped under it — "The attempt was
- * stopped before the prepared candidate was loaded."): it ran no check, so it is no check failure of the commit. Only
- * the plane's own records say so, all of them at once: the run ended failed/interrupted, recorded no commit, and has no
- * check attempt (sealed before any check command runs), no recorded check and no check log or receipt. Any attempt that
- * got as far as its check keeps every rule below.
- */
 export function ranNoCheck(store, row) {
     if (!(endedInterrupted(row) || (row.outcome === "failed" && row.reason === "no-op")) || row.head !== null || row.checkRow !== null)
         return false;
@@ -217,18 +155,9 @@ export function ranNoCheck(store, row) {
         return false;
     return row.reason === "interrupted" || refusedBeforeAnything(store, row.id);
 }
-/** The ledger entry the build writes when it refuses a prepared candidate before any process (builder.ts). */
 export const NOTHING_STARTED_ACTION = "attempt refused before anything ran";
-/** Every table a process, an agent or a check of this run writes. */
 const RUN_TRACES = [["artifact", "run"], ["run_process", "run"], ["run_process_summary", "run"], ["run_tool", "run"], ["run_activity", "run"],
     ["check_stamp", "run_id"], ["release_check_attempt", "run"], ["run_note", "run"], ["agent_turn", "run"], ["run_checkpoint", "run"], ["run_decision", "run"]];
-/**
- * An attempt the build refused before anything ran (run 3332: Git couldn't read HEAD while it proved the candidate; the
- * next attempt passed). A failed attempt with reason `no-op` proves nothing alone: an agent's empty result and a check's
- * refusal end that way too. So the build's own ledger entry says so, written only where nothing has run, and the run's
- * records agree: no base stamped, no provider start, session, tokens or commit, and not one row of any process, agent or
- * check. All of them, or it stands as a failure, and a record that can't be read (an older database) never excuses one.
- */
 function refusedBeforeAnything(store, runId) {
     try {
         const said = store.handle.prepare("SELECT COUNT(*) AS n FROM action_ledger WHERE run_id = ? AND action = ? AND outcome = 'refused'").get(runId, NOTHING_STARTED_ACTION)?.["n"];
@@ -237,8 +166,6 @@ function refusedBeforeAnything(store, runId) {
         const run = store.handle.prepare("SELECT base_revision, head_revision, provider_started_at, session_id, tokens_in, tokens_out, cost_usd, committed FROM run WHERE id = ?").get(runId);
         if (run === undefined || Object.values(run).some(value => value !== null))
             return false;
-        // check_fact is a learning-loops table (eval-hooks.ts): read here in its own literal statement, never through the
-        // table list, so no SQL text that could name it is assembled outside its sole writer.
         if (store.handle.prepare("SELECT 1 FROM check_fact WHERE run = ? LIMIT 1").get(runId) !== undefined)
             return false;
         return RUN_TRACES.every(([table, column]) => store.handle.prepare(`SELECT 1 FROM ${table} WHERE ${column} = ? LIMIT 1`).get(runId) === undefined);
@@ -247,7 +174,6 @@ function refusedBeforeAnything(store, runId) {
         return false;
     }
 }
-/** The task's finished builder runs under `digest`, oldest first, each with whether its check passed or never ran. */
 function builderRuns(store, taskRef, digest) {
     return store.handle.prepare(`SELECT r.id, r.outcome, r.reason, r.head_revision, r.scope_digest, r.finished_at, c.status, c.run AS check_row FROM run r LEFT JOIN run_check c ON c.run = r.id
       WHERE r.task_ref = ? AND r.role = 'builder' AND r.finished_at IS NOT NULL AND r.scope_digest = ? ORDER BY r.id`).all(taskRef, digest)
@@ -255,18 +181,10 @@ function builderRuns(store, taskRef, digest) {
         passed: (row["outcome"] === "built" || row["outcome"] === "no-change") && row["status"] === "passed",
         noCheck: ranNoCheck(store, { id: Number(row["id"]), outcome: row["outcome"], reason: row["reason"], head: row["head_revision"] ?? null, checkRow: row["check_row"] ?? null }) }));
 }
-/** The reruns the release asked for on this task (each source run once): run id → its class. */
 function reruns(store, taskId) {
     const rows = store.handle.prepare("SELECT run_id, outcome FROM action_ledger WHERE task_id = ? AND action = ? AND run_id IS NOT NULL ORDER BY id").all(taskId, RELEASE_RECHECK_ACTION);
     return new Map(rows.map(row => [Number(row["run_id"]), String(row["outcome"])]));
 }
-/**
- * Whether a passing check of a release task stands, given every earlier attempt on the same candidate and signed scope:
- * each earlier failure must be confirmed infrastructure the release itself reran (at most two), and nothing in the
- * passing run may have passed only on a retry. A deterministic, unknown or agent failure before it isn't erased by a
- * later pass: a person decides. `retried` is reported even when it stands (a person's approval reads it; an automatic
- * one refuses on it).
- */
 export function releaseCheckStanding(store, root, input) {
     const ref = store.lookupRef(input.taskId);
     const scope = store.getScope(input.taskId);
@@ -282,7 +200,6 @@ export function releaseCheckStanding(store, root, input) {
     for (const one of builderRuns(store, ref.id, digest)) {
         if (one.id >= input.run || one.passed)
             continue;
-        // Interrupted before its candidate was loaded: no check ran, so there is no check failure to stand against a pass.
         if (one.noCheck)
             continue;
         const classified = one.outcome === "built" || one.outcome === "no-change" ? classifyRunCheck(store, root, one.id) : { class: "unknown", why: `its build ended ${one.outcome ?? "without an outcome"}` };
@@ -304,18 +221,11 @@ export const classWords = (kind) => ({
     unknown: "unexplained: a person decides",
     "agent-behaviour": "a real-model journey: counted, never rerun to pass",
 }[kind]);
-/**
- * After a failed release check: the plane classifies the task's newest attempt from its own records and, only for
- * confirmed infrastructure within its limits (one rerun per incident, two per candidate), runs the check again on the
- * same candidate under the same approval (dispose.ts regateTask keeps candidate, scope and approval). Every attempt
- * stays in the evidence; each rerun is in the ledger with its class. Anything else stops, saying which class and why.
- */
 export function recheckReleaseTask(store, root, taskId, now) {
     const ref = store.lookupRef(taskId);
     const scope = store.getScope(taskId);
     if (ref === null || scope === null || !releaseCheckScope(scope) || (scope.candidate ?? null) === null)
         return { action: "stop", class: null, why: `${taskId} isn't a release task`, source: null };
-    // One transaction: the binding, the rerun and its ledger row are read and land together, or nothing does.
     return store.transact(() => {
         const bound = releasePurposeBinding(store, store.getScope(taskId) ?? scope, ref.repo);
         if (bound !== null)
@@ -323,13 +233,6 @@ export function recheckReleaseTask(store, root, taskId, now) {
         return recheckInside(store, root, taskId, ref.repo, String(scope.candidate), now);
     });
 }
-/**
- * Why the release's sealed purpose no longer names this exact check, or null when it does (pipeline-speed.md, P0). A
- * release check purpose (a release that can't carry) authorizes a rerun only of the identical approved candidate: its
- * sealed commit is the scope's candidate, its project is the task's, the project's live release check grant is the one
- * sealed and its check access is the one sealed. Signed terms keep their own rules (a carried commit's candidate is
- * not the terms' first commit) and are held to the same project and grant.
- */
 function releasePurposeBinding(store, scope, repo) {
     const sealed = scope.releaseTerms ?? scope.releaseCheck ?? null;
     if (sealed === null)
@@ -351,7 +254,6 @@ function recheckInside(store, root, taskId, repo, candidate, now) {
     if (last === null)
         return { action: "stop", class: null, why: `${taskId} has no finished attempt`, source: null };
     const asked = reruns(store, taskId);
-    // Already rerun for this incident: the new attempt is queued or running.
     if (asked.has(last.id))
         return { action: "pending", source: last.id };
     const classified = last.outcome === "built" || last.outcome === "no-change" ? classifyRunCheck(store, root, last.id) : { class: "unknown", why: `its build ended ${last.outcome ?? "without an outcome"}` };

package/dist/check-levels-ui.js

@@ -1,12 +1,9 @@
-/** Settings → Projects → Checks: how much checks after each build, in plain
- * words. One choice (Quick, Full, Off) and the quick command beside the full
- * one. Every change takes the password and lands in the ledger; approving a
- * command restates exactly what will run, unattended, before the yes. */
 import { html, joinHtml } from "./html.js";
 import { CHECK_LEVELS, CHECK_LEVEL_HINTS, CHECK_LEVEL_WORDS } from "./check-levels.js";
 import { BATCH_HINT } from "./batch-policy.js";
 import { codeLine, disclose, formRow, infoLine, input, note, notice, radios, settingsSection, textarea } from "./server/kit.js";
 import { kitSectionForm } from "./settings-kit.js";
+const shellWord = (value) => /^[A-Za-z0-9_./~@%+=:,-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
 const list = (items) => html `<ul class="k-note">${items.map(one => html `<li>${one}</li>`)}</ul>`;
 export function checkSettingsHtml(view) {
     const form = (id, act, body, save, extra = {}) => kitSectionForm({ proof: "checks", action: "/settings/checks", id, hidden: { repo: view.repo, act, ...extra }, save, body });
@@ -16,7 +13,6 @@ export function checkSettingsHtml(view) {
         note(html `${view.name} · <span class="k-mono">${view.repo}</span>`),
     ]);
     const command = (one) => joinHtml([codeLine(one.command), note(`Up to ${Math.round(one.timeoutMs / 1000)}s · approved by ${one.approvedBy}`)]);
-    // Quick with no quick command runs the full check; say so where the choice is made.
     const fallsBack = view.level === "quick" && view.quick === null;
     const levelNotes = joinHtml([
         fallsBack ? note("No quick command yet, so builds run the full check.") : "",
@@ -46,10 +42,11 @@ export function checkSettingsHtml(view) {
                 ])]) });
     const full = settingsSection({ id: "full-check", title: "Full check", state: view.full === null ? " · None yet" : "",
         body: view.full === null
-            ? joinHtml([note("Approve one from the command line:"), codeLine(`toolroll verify set --repo … --command "…"`)])
+            ? joinHtml([note("Set the command that tests this project from the command line, for example npm test:"),
+                codeLine(`toolroll verify set --repo ${shellWord(view.repo)} --command "npm test"`),
+                view.needsPassword === true ? note("Setting a check needs a password. Run toolroll password set first.") : ""])
             : command(view.full) });
     return joinHtml([head, level, fastHtml(view), batchHtml(view), reviewHtml(view), quick, full]);
-    /** Small tasks: one state, one sentence, and its one change behind a disclosure (the password). */
     function fastHtml(view) {
         if (view.fast === undefined)
             return "";
@@ -58,7 +55,6 @@ export function checkSettingsHtml(view) {
             lead: "New task shows the exact terms and Build approves them, with no plan step. It takes a person, and only small, ordinary changes.",
             body: view.canChange ? disclose(act, form("small-tasks-form", "small-tasks", html ``, { label: act, variant: "outline" }, { on: view.fast.on ? "0" : "1" })) : "" });
     }
-    /** Batch checks: one state and one sentence; turning it on restates exactly what happens before the password. */
     function batchHtml(view) {
         const batch = view.batch;
         if (batch === undefined)
@@ -72,7 +68,6 @@ export function checkSettingsHtml(view) {
             body: joinHtml([batch.on && view.level !== "full" ? note("Only Full checks are batched.") : "",
                 view.canChange ? disclose(act, form("batch-form", "batch", terms, { label: act, variant: "outline" }, { on: batch.on ? "0" : "1" })) : ""]) });
     }
-    /** Automatic review: one state, one sentence, and its one change behind a disclosure (the password). */
     function reviewHtml(view) {
         const review = view.review;
         if (review === undefined)
@@ -84,7 +79,6 @@ export function checkSettingsHtml(view) {
             body: view.canChange ? disclose(act, form("review-form", "review", html ``, { label: act, variant: "outline" }, { on: review.on ? "0" : "1" })) : "" });
     }
 }
-/** The follow-up list's look (result-follow-ups.ts); the checks page itself is kit markup. */
 export const CHECK_SETTINGS_CSS = `
   .follow-ups .follow-up-list { margin: .4rem 0; padding-left: 1.1rem; display: grid; gap: .25rem; }
   .follow-ups .follow-up-acts, .follow-ups .follow-up-act { display: flex; flex-wrap: wrap; gap: .5rem; margin: .5rem 0 0; }

package/dist/check-levels.js

@@ -1,16 +1,3 @@
-/** Check levels: how much of the project check runs after a build.
- *
- * - Quick: a fast check while work is in progress (typecheck plus the tests
- *   near the change). New projects start here.
- * - Full: the project's approved check, as before. Projects that already
- *   had a check keep it.
- * - Off: no check. The result reads Ready for review, with "Checks: Off for this project" underneath.
- *
- * Nothing here needs a new table. A project's level and a task's choice are
- * append-only ledger entries (the newest one wins, and the ledger already
- * says who changed what, when). The quick command is a second approved
- * verification grant with its own digest, kept under a `quick:` key beside
- * the full one, so approving it is the same ceremony as `verify set`. */
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { approvalOf } from "./scope.js";
@@ -22,16 +9,16 @@ export const CHECK_LEVEL_HINTS = {
     full: "The project's full check after every build.",
     off: "No check. Results are Ready for review, and say no check ran.",
 };
-/** Ledger actions. The ledger is append-only, so the newest entry is the setting. */
 export const PROJECT_LEVEL_ACTION = "check level changed";
 export const TASK_LEVEL_ACTION = "task checks chosen";
 export const RUN_LEVEL_ACTION = "checks used";
-/** The quick command's grant lives beside the full one under its own key. */
 export const quickVerifyKey = (repo) => `quick:${repo}`;
 export function liveQuickCommand(store, repo) {
     return store.liveVerifyCommand(quickVerifyKey(repo));
 }
-/** Ledger reads go through the repo index: `repo = ?` (or IS NULL for unplaced work). */
+export function projectCheckSet(store, repo) {
+    return store.liveVerifyCommand(repo) !== null || liveQuickCommand(store, repo) !== null;
+}
 export const repoClause = (repo) => repo === null ? ["repo IS NULL", []] : ["repo = ?", [repo]];
 export function repoOfRun(store, runId) {
     const run = store.getRun(runId);
@@ -41,16 +28,12 @@ function newest(store, sql, ...params) {
     const row = store.handle.prepare(sql).get(...params);
     return row === undefined ? null : { actor: String(row["actor"]), at: String(row["at"]), outcome: String(row["outcome"]) };
 }
-/** A project's level. With nothing recorded it is Full: a project that existed
- * before levels keeps exactly the check it had. New projects are stamped Quick
- * when they are added (stampNewProjectLevel). */
 export function projectCheckLevel(store, repo) {
     const row = newest(store, "SELECT actor, at, outcome FROM action_ledger WHERE repo = ? AND task_id IS NULL AND action = ? ORDER BY id DESC LIMIT 1", repo, PROJECT_LEVEL_ACTION);
     if (row === null || !isCheckLevel(row.outcome))
         return { level: "full", setBy: null, at: null };
     return { level: row.outcome, setBy: row.actor, at: row.at };
 }
-/** An approver's act: set the project's level. The ledger keeps before → after. */
 export function setProjectCheckLevel(store, repo, level, by, now) {
     const before = projectCheckLevel(store, repo);
     if (before.level === level && before.setBy !== null)
@@ -59,8 +42,6 @@ export function setProjectCheckLevel(store, repo, level, by, now) {
         detail: `${CHECK_LEVEL_WORDS[before.level]} → ${CHECK_LEVEL_WORDS[level]}` });
     return { changed: before.level !== level, before: before.level };
 }
-/** A project added from now on starts on Quick. One that already has a level,
- * or an approved check from before levels existed, is left exactly as it is. */
 export function stampNewProjectLevel(store, repo, now) {
     const known = newest(store, "SELECT actor, at, outcome FROM action_ledger WHERE repo = ? AND task_id IS NULL AND action = ? LIMIT 1", repo, PROJECT_LEVEL_ACTION);
     if (known !== null)
@@ -72,7 +53,6 @@ export function stampNewProjectLevel(store, repo, now) {
         detail: "New project → Quick" });
     return true;
 }
-/** A task's own choice, if it made one; a revision inherits the task it revises. */
 export function taskCheckLevel(store, taskId) {
     let id = taskId;
     for (let depth = 0; id !== null && depth < 64; depth++) {
@@ -85,8 +65,6 @@ export function taskCheckLevel(store, taskId) {
     }
     return null;
 }
-/** A filing choice: this task's checks, overriding the project. Fixed once its
- * plan is approved, so what the approver saw is what runs. */
 export function setTaskCheckLevel(store, taskId, level, by, now) {
     const ref = store.lookupRef(taskId);
     if (ref === null)
@@ -106,8 +84,6 @@ export function effectiveCheckLevel(store, repo, taskId) {
         return { level: own, from: "task" };
     return { level: repo === null ? "full" : projectCheckLevel(store, repo).level, from: "project" };
 }
-/** The command a level runs. Quick without its own command runs the full one
- * (and says so: the level that ran is Full). Off runs nothing. */
 export function checkCommandFor(store, repo, level) {
     if (level === "off")
         return { level: "off", command: null };
@@ -118,24 +94,18 @@ export function checkCommandFor(store, repo, level) {
     }
     return { level: "full", command: store.liveVerifyCommand(repo) };
 }
-/** Readiness uses the result's level, falling back to the task/project for legacy
- * runs. Quick's approved command (or its Full fallback) is required; Off is not. */
 export function requiredCheckCommandFor(store, repo, taskId, level) {
     return repo === null ? null : checkCommandFor(store, repo, level ?? effectiveCheckLevel(store, repo, taskId).level).command;
 }
-/** The builder records which level a run used, so its result says it honestly. */
 export function recordRunCheckLevel(store, run, level, from, now) {
     store.recordAction({ at: now.toISOString(), actor: "system", repo: run.repo, taskId: run.taskId, runId: run.id, action: RUN_LEVEL_ACTION, outcome: level, source: "work",
         detail: `${CHECK_LEVEL_WORDS[level]} checks (${from === "task" ? "this task's choice" : "project setting"})` });
 }
-/** The level a finished run's checks used; null for a run from before levels. */
 export function runCheckLevel(store, runId) {
     const [where, params] = repoClause(repoOfRun(store, runId));
     const row = newest(store, `SELECT actor, at, outcome FROM action_ledger WHERE ${where} AND run_id = ? AND action = ? ORDER BY id DESC LIMIT 1`, ...params, runId, RUN_LEVEL_ACTION);
     return row !== null && isCheckLevel(row.outcome) ? row.outcome : null;
 }
-/** A starting point for the quick command, from the project's own scripts.
- * It is only a suggestion: a person approves the exact command. */
 export function suggestQuickCommand(repo) {
     const file = join(repo, "package.json");
     if (!existsSync(file))
@@ -153,7 +123,6 @@ export function suggestQuickCommand(repo) {
     const has = (name) => typeof scripts[name] === "string";
     const runner = existsSync(join(repo, "pnpm-lock.yaml")) ? "pnpm" : existsSync(join(repo, "yarn.lock")) ? "yarn" : "npm";
     const run = (name) => runner === "npm" ? `npm run ${name}` : `${runner} ${name}`;
-    // A project's own quick script knows its tests best (Toolroll's runs the attack suite when a guard changes).
     if (has("check:quick"))
         return run("check:quick");
     const exec = runner === "npm" ? "npx" : `${runner} exec`;
@@ -166,7 +135,6 @@ export function suggestQuickCommand(repo) {
         return parts.join(" && ");
     return has("lint") ? run("lint") : null;
 }
-/** "skip the tests", "run the full checks": a filing request in chat, as a level. */
 export function checkLevelFromWords(text) {
     const said = text.toLowerCase().replace(/[’']/g, "'");
     if (/\b(skip|without|no|don't run|do not run|turn off|switch off)\b[^.!?\n]{0,20}\b(the )?(tests|checks)\b/.test(said) || /\b(tests|checks) off\b/.test(said))

package/dist/check-load.js

@@ -1,40 +1,13 @@
-/**
- * The plane's own record of the machine a release check ran on (docs/plans/heavy-jobs.md, layer 1b). The check sizes
- * its budget from the load it finds (scripts/release-check.mjs checkBudget), so on a busy machine it runs on one or two
- * lanes — and ran out of its approved hour twice in one evening (runs 3311 and 3315), which read as an unexplained
- * failure a person had to re-approve.
- *
- * Two plane-side answers, never the check's own words:
- *   - the limit: a release check that starts with its budget cut to half its normal size or less gets more time, in
- *     proportion to the budget it lost, never more than twice the approved limit nor past a hard ceiling (two hours);
- *   - the evidence: the load the plane measured itself (when the check started and every 15 s while it ran), the limit
- *     it gave and why, and how long the check ran, sealed beside its receipt (CHECK_LOAD_CAPTURE). check-failure.ts reads
- *     only this record — never the check's output or report — to call a timeout under a cut budget the machine's own
- *     fault. Nothing the candidate writes can make a failure infrastructure.
- *
- * The budget arithmetic is the plane's copy of the check's (src/check-load.test.ts holds them equal), so the budget the
- * plane judges is the one the check gives itself from the same load.
- */
 import { availableParallelism, loadavg } from "node:os";
 import { z } from "zod";
 export const CHECK_LOAD_CAPTURE = "release check load v1";
 export const machineSample = (platform = process.platform, read = loadavg, cores = availableParallelism) => ({ cores: cores(), load: platform === "win32" ? Number.NaN : read()[0] ?? Number.NaN });
-/** The check's budget on a quiet machine: three quarters of the cores, at least 2 (release-check.mjs checkBudget). */
 export const normalFree = (cores) => Math.max(2, Math.floor(cores * 0.75));
-/** The check's budget under `load` (release-check.mjs checkBudget's `free`). Unmeasured load budgets from the cores. */
 export const freeAt = (cores, load) => Math.max(2, normalFree(cores) - (Number.isFinite(load) && load > 0 ? Math.floor(load) : 0));
-/** Cut: the budget is at most half its normal size. Unmeasured load is never cut. */
 export const budgetCut = (cores, load) => Number.isFinite(load) && freeAt(cores, load) * 2 <= normalFree(cores);
-/** A release check's limit never goes past this, however busy the machine. */
 export const CHECK_LIMIT_CEILING_MS = 120 * 60_000;
-/** …nor past this many times the approved limit. */
 export const CHECK_LIMIT_MAX_FACTOR = 2;
 const minutes = (ms) => `${Math.round(ms / 60_000)} min`;
-/**
- * The limit a release check runs under: the approved one, unless the machine's load at its start cuts the check's
- * budget to half or less — then the approved limit times normal/granted, at most twice it and never past the ceiling
- * (an approved limit already at or past the ceiling is never extended). `why` says which, in words.
- */
 export function checkLimitFor(grantMs, sample) {
     const normal = normalFree(sample.cores), free = freeAt(sample.cores, sample.load);
     if (!budgetCut(sample.cores, sample.load)) {
@@ -44,12 +17,7 @@ export function checkLimitFor(grantMs, sample) {
     const limitMs = Math.min(ceiling, Math.round(grantMs * normal / free));
     return { limitMs, why: `the approved ${minutes(grantMs)}${limitMs > grantMs ? `, extended to ${minutes(limitMs)}` : ", not extended (it is at the ceiling)"}: load ${sample.load.toFixed(1)} on ${sample.cores} cores left the check ${free} of its normal ${normal}, so it gets time in proportion, at most ${minutes(ceiling)}` };
 }
-/** When a check ends itself before its limit (release-check.mjs checkDeadline, from its start): src/check-load.test.ts
- * holds the two equal. A check that ran at least this long ran into its own limit. */
 export const selfStopAfter = (limitMs) => limitMs - Math.min(Math.max(3 * 60_000, Math.round(limitMs / 10)), Math.round(limitMs / 2));
-/** The samples read for the budget the check started with: the check waits up to ten minutes for the load to drop
- * (release-check.mjs), so the least load in its first eleven — before its own load counts — is what it budgeted from at
- * best. The least, so a check that found a quieter moment is never called cut. */
 export const CUT_WINDOW_MS = 11 * 60_000;
 const SAMPLE_EVERY_MS = 15_000;
 const MAX_SAMPLES = 1000;
@@ -60,27 +28,17 @@ const recordSchema = z.strictObject({
     limitMs: z.int().min(1),
     why: z.string().max(1000),
     startedAt: z.string().max(40),
-    /** How long the check's last attempt ran, by the plane's clock (null: it never started). */
     elapsedMs: z.int().min(0).nullable(),
-    /** Each reading, `atMs` after the check started; null where load isn't measured. */
     samples: z.array(z.strictObject({ atMs: z.int().min(0), load: z.number().min(0).nullable() })).max(MAX_SAMPLES),
 });
-/** A sealed record read back, or null when it isn't one (an older run has none: then nothing is excused). */
 export function readCheckLoad(value) {
     const read = recordSchema.safeParse(value);
     if (!read.success)
         return null;
     const record = read.data;
-    // A limit the plane could never have given is no record at all.
     const ceiling = Math.max(record.grantMs, Math.min(record.grantMs * CHECK_LIMIT_MAX_FACTOR, CHECK_LIMIT_CEILING_MS));
     return record.limitMs < record.grantMs || record.limitMs > ceiling ? null : record;
 }
-/**
- * Why a release check that ran out of time did so because the machine was busy — or null. Every fact is the plane's:
- * its load readings in the first eleven minutes (the least of them) cut the check's budget to half or less, and the
- * check's last attempt ran into its own limit (at least `selfStopAfter(limitMs)`), or the plane stopped it at the limit
- * (`stoppedAtLimit`). A check with its normal budget that times out is never excused here: a real hang stays a failure.
- */
 export function busyMachineTimeout(record, grantMs, stoppedAtLimit) {
     if (record === null || record.grantMs !== grantMs)
         return null;
@@ -94,10 +52,6 @@ export function busyMachineTimeout(record, grantMs, stoppedAtLimit) {
         return null;
     return `the machine was busy: its load stayed at ${least.toFixed(1)} or more on ${record.cores} cores as the check started, cutting its budget to ${freeAt(record.cores, least)} of its normal ${normalFree(record.cores)} cores, and it ran out of its ${minutes(record.limitMs)}`;
 }
-/**
- * Watches one release check: the limit at its start, the load every 15 s while it runs, and how long its last attempt
- * took. Advisory to the check itself (the limit is a plane value the check is told), and the only source of the record.
- */
 export class CheckLoadWatch {
     grantMs;
     options;
@@ -123,7 +77,7 @@ export class CheckLoadWatch {
         this.timer = every > 0 ? setInterval(() => { try {
             this.push(clock() - this.started, sample().load);
         }
-        catch { /* a missed reading */ } }, every) : null;
+        catch { } }, every) : null;
         this.timer?.unref?.();
     }
     push(atMs, load) {
@@ -134,11 +88,9 @@ export class CheckLoadWatch {
         }
         this.samples.push({ atMs: Math.max(0, Math.round(atMs)), load: Number.isFinite(load) && load >= 0 ? Math.round(load * 100) / 100 : null });
     }
-    /** Around each attempt of the command: the last one's time is the record's. */
     attemptStarted() { this.attemptStart = (this.options.clock ?? Date.now)(); }
     attemptEnded() { if (this.attemptStart !== null)
         this.elapsed = Math.max(0, Math.round((this.options.clock ?? Date.now)() - this.attemptStart)); }
-    /** Stops the readings and gives the record to seal. */
     finish() {
         if (this.timer !== null)
             clearInterval(this.timer);

package/dist/check-only-standing.js

@@ -1,5 +1,3 @@
-/** Whether a check-only authorization stands for one automatic recheck (check-only.ts), read at every step. Kept apart
- * from the sweep so the follow-up runner reads it without loading the road that asks. */
 import { authorityStandsSql } from "./approval-authority.js";
 import { checkAccessOf } from "./check-access.js";
 import { refArchived } from "./task-archive.js";
@@ -8,15 +6,12 @@ export function readAuthorization(row) {
         level: row["level"] === "quick" ? "quick" : "full", access: checkAccessOf(row["check_access"]), scopeDigest: String(row["scope_digest"]), expiresAt: String(row["expires_at"]),
         usedRequest: row["used_request"] === null || row["used_request"] === undefined ? null : Number(row["used_request"]) };
 }
-/** The approval an authorization stands on: the plan's seal, on these exact bytes, still standing as dispatch reads it. */
 export function approvedScopeStands(store, taskRef, scopeDigest, now) {
     const stamp = now.toISOString();
     return store.handle.prepare(`SELECT 1 AS hit FROM task_scope JOIN task_ref ON task_ref.id = ? AND task_scope.task_id = task_ref.external_id
     WHERE task_scope.digest = ? AND task_scope.approved_digest = task_scope.digest AND task_scope.approved_at IS NOT NULL
       AND ${authorityStandsSql("task_scope", "task_ref.repo", "?")}`).get(taskRef, scopeDigest, stamp, stamp, stamp, stamp) !== undefined;
 }
-/** The plain reason an authorization doesn't stand, or null: this exact commit and command, on the result it was
- * written for, under the same standing approval, not put away. */
 export function authorizationProblem(store, auth, input, now) {
     if (auth.candidate !== input.head)
         return "The commit changed.";
@@ -28,7 +23,6 @@ export function authorizationProblem(store, auth, input, now) {
         return "Its approval no longer stands.";
     return null;
 }
-/** At the run: the used authorization this request claimed. */
 export function recheckStanding(store, input) {
     const row = store.handle.prepare("SELECT * FROM check_authorization WHERE used_request = ? AND run = ?").get(input.request, input.runId);
     if (row === undefined)