toolroll 0.9.92 → 0.9.94

package/dist/check-failure.d.ts

@@ -1,4 +1,5 @@
 import { type CheckReport } from "./contracts/release-check.js";
+import { type CheckLoadRecord } from "./check-load.js";
 import { INFRA_RERUNS_PER_CANDIDATE, INFRA_RERUNS_PER_INCIDENT, type FailureClassName } from "./release.js";
 import type { Store } from "./store.js";
 export type FailureClass = FailureClassName;
@@ -20,12 +21,16 @@ export type CheckFacts = {
         failure?: string;
     };
     coverage?: string | undefined;
+    /** The approved limit of the command the receipt names (receipt.command.timeoutMs): a load record must be for it. */
+    grantMs?: number | undefined;
 };
 /**
- * One failed check, classified. `facts` come from the plane's sealed receipt; `report` (the check's own report, sealed
- * when valid) only ever picks among the classes that block. Null when the check passed.
+ * 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 declare function classifyCheckFailure(facts: CheckFacts, report: CheckReport | null): ClassifiedFailure | null;
+export declare function classifyCheckFailure(facts: CheckFacts, report: CheckReport | null, load?: CheckLoadRecord | null): ClassifiedFailure | null;
 /** 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 declare function retriedInside(report: CheckReport | null): string[] | null;
@@ -45,6 +50,20 @@ export declare const SETUP_REPLAY_RETRY = "the whole check, rerun after the appr
  * missing program; a receipt that doesn't classify it (an older one) says so, never that it was a launch failure.
  */
 export declare function setupReplayWords(first: unknown): string;
+/**
+ * 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 declare function ranNoCheck(store: Store, row: {
+    id: number;
+    outcome: unknown;
+    reason: unknown;
+    head: unknown;
+    checkRow: unknown;
+}): boolean;
 /**
  * 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

package/dist/check-failure.js

@@ -5,7 +5,8 @@
  *   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 — or, on GitHub, a job that failed before any of 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
@@ -20,10 +21,12 @@
  */
 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";
 import { regateTask } from "./dispose.js";
 import { INFRA_RERUNS_PER_CANDIDATE, INFRA_RERUNS_PER_INCIDENT } from "./release.js";
 import { releaseCheckScope } from "./scope.js";
-import { verificationEvidence } from "./verification-evidence.js";
+import { isVerificationReceipt, verificationEvidence } from "./verification-evidence.js";
+import { checkAttemptOf } from "./store.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. */
@@ -35,11 +38,15 @@ const PLANE_INFRA = {
     "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; `report` (the check's own report, sealed
- * when valid) only ever picks among the classes that block. Null when the check passed.
+ * 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) {
+export function classifyCheckFailure(facts, report, load = null) {
     const result = facts.result;
     const passedCoverage = facts.coverage === undefined || facts.coverage === "full" || facts.coverage === "composed";
     if (result.configured && result.ran === true && result.exitCode === 0 && passedCoverage)
@@ -51,8 +58,12 @@ export function classifyCheckFailure(facts, report) {
         const infra = PLANE_INFRA[failure];
         if (infra !== undefined)
             return { class: "infrastructure", why: infra };
-        if (failure === "timed-out" || failure === "retry-timed-out")
-            return { class: "unknown", why: "the check timed out, and nothing says why" };
+        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" };
+        }
         if (failure === "baseline-unverifiable")
             return { class: "unknown", why: "the last release Toolroll recorded couldn't be verified, so what the check owed is unknown and it wasn't run" };
         if (failure === "no-result")
@@ -65,10 +76,14 @@ export function classifyCheckFailure(facts, report) {
     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)
             continue;
         if (part.timedOut || part.signal != null) {
+            if (!part.timedOut || part.signal != null)
+                onlyTimeouts = false;
             unexplained.push(`${part.part} ${part.timedOut ? "timed out" : `was ended by ${part.signal}`}`);
             continue;
         }
@@ -78,8 +93,10 @@ export function classifyCheckFailure(facts, report) {
     for (const file of report.units?.files ?? [])
         if (file.state === "failed")
             deterministic.push(`${file.file} failed`);
-    if ((report.units?.runErrors ?? 0) > 0 && !(report.units?.files ?? []).some(file => file.state === "failed"))
+    if ((report.units?.runErrors ?? 0) > 0 && !(report.units?.files ?? []).some(file => file.state === "failed")) {
+        onlyTimeouts = false;
         unexplained.push(`${report.units.runErrors} unit errors no test owned`);
+    }
     for (const run of report.journeys)
         for (const group of run.groups) {
             if (group.state !== "failed")
@@ -94,8 +111,14 @@ export function classifyCheckFailure(facts, report) {
         return { class: "deterministic", why: list(deterministic) };
     if (agent.length > 0)
         return { class: "agent-behaviour", why: list(agent) };
-    if (unexplained.length > 0)
+    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}`) };
         return { class: "unknown", why: list(unexplained) };
+    }
     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,
@@ -127,7 +150,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);
-    return classifyCheckFailure({ result: receipt.result, coverage: receipt.coverage }, parsed?.ok === true ? parsed.value : null);
+    // 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
@@ -174,12 +200,27 @@ export function setupReplayWords(first) {
     }
     return `${SETUP_REPLAY_RETRY} (its first attempt's failure isn't classified)`;
 }
-/** The task's finished builder runs under `digest`, oldest first, each with whether its check passed. */
+/**
+ * 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 (row.outcome !== "failed" || row.reason !== "interrupted" || row.head !== null || row.checkRow !== null)
+        return false;
+    if (checkAttemptOf(store, row.id) !== null)
+        return false;
+    return !store.artifactsFor(row.id).some(artifact => artifact.kind === "check-log" || isVerificationReceipt(artifact));
+}
+/** 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.scope_digest, r.finished_at, c.status FROM run r LEFT JOIN run_check c ON c.run = r.id
+    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)
         .map(row => ({ id: Number(row["id"]), outcome: row["outcome"] === null ? null : String(row["outcome"]), scopeDigest: String(row["scope_digest"]), finishedAt: String(row["finished_at"]),
-        passed: (row["outcome"] === "built" || row["outcome"] === "no-change") && row["status"] === "passed" }));
+        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) {
@@ -208,6 +249,9 @@ 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"}` };
         if (classified === null)
             continue;

package/dist/check-levels-ui.d.ts

@@ -24,6 +24,10 @@ export type CheckSettingsView = {
     batch?: {
         on: boolean;
     };
+    /** Small tasks start right away (fast-start.ts). */
+    fast?: {
+        on: boolean;
+    };
     said: string | null;
     problem: string | null;
 };

package/dist/check-levels-ui.js

@@ -48,7 +48,16 @@ export function checkSettingsHtml(view) {
         body: view.full === null
             ? joinHtml([note("Approve one from the command line:"), codeLine(`toolroll verify set --repo … --command "…"`)])
             : command(view.full) });
-    return joinHtml([head, level, batchHtml(view), reviewHtml(view), quick, 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 "";
+        const act = view.fast.on ? "Turn off" : "Turn on";
+        return settingsSection({ id: "small-tasks", title: "Small tasks start right away", state: html `<span data-small-tasks="${view.fast.on ? "on" : "off"}"> · ${view.fast.on ? "On" : "Off"}</span>`,
+            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;

package/dist/check-load.d.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+export declare const CHECK_LOAD_CAPTURE = "release check load v1";
+/** One reading of the machine: its cores and one-minute load (NaN where it isn't measured: Windows reports 0). */
+export type MachineSample = {
+    cores: number;
+    load: number;
+};
+export declare const machineSample: (platform?: NodeJS.Platform, read?: () => number[], cores?: () => number) => MachineSample;
+/** The check's budget on a quiet machine: three quarters of the cores, at least 2 (release-check.mjs checkBudget). */
+export declare const normalFree: (cores: number) => number;
+/** The check's budget under `load` (release-check.mjs checkBudget's `free`). Unmeasured load budgets from the cores. */
+export declare const freeAt: (cores: number, load: number) => number;
+/** Cut: the budget is at most half its normal size. Unmeasured load is never cut. */
+export declare const budgetCut: (cores: number, load: number) => boolean;
+/** A release check's limit never goes past this, however busy the machine. */
+export declare const CHECK_LIMIT_CEILING_MS: number;
+/** …nor past this many times the approved limit. */
+export declare const CHECK_LIMIT_MAX_FACTOR = 2;
+/**
+ * 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 declare function checkLimitFor(grantMs: number, sample: MachineSample): {
+    limitMs: number;
+    why: string;
+};
+/** 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 declare const selfStopAfter: (limitMs: number) => number;
+/** 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 declare const CUT_WINDOW_MS: number;
+declare const recordSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    cores: z.ZodInt;
+    grantMs: z.ZodInt;
+    limitMs: z.ZodInt;
+    why: z.ZodString;
+    startedAt: z.ZodString;
+    elapsedMs: z.ZodNullable<z.ZodInt>;
+    samples: z.ZodArray<z.ZodObject<{
+        atMs: z.ZodInt;
+        load: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CheckLoadRecord = z.infer<typeof recordSchema>;
+/** A sealed record read back, or null when it isn't one (an older run has none: then nothing is excused). */
+export declare function readCheckLoad(value: unknown): CheckLoadRecord | null;
+/**
+ * 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 declare function busyMachineTimeout(record: CheckLoadRecord | null, grantMs: number, stoppedAtLimit: boolean): string | null;
+/**
+ * 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 declare class CheckLoadWatch {
+    private readonly grantMs;
+    private readonly options;
+    private readonly started;
+    private readonly samples;
+    private readonly timer;
+    private readonly cores;
+    private attemptStart;
+    private elapsed;
+    readonly limitMs: number;
+    readonly why: string;
+    constructor(grantMs: number, options?: {
+        sample?: () => MachineSample;
+        clock?: () => number;
+        everyMs?: number;
+    });
+    private push;
+    /** Around each attempt of the command: the last one's time is the record's. */
+    attemptStarted(): void;
+    attemptEnded(): void;
+    /** Stops the readings and gives the record to seal. */
+    finish(): CheckLoadRecord;
+}
+export {};

package/dist/check-load.js

@@ -0,0 +1,147 @@
+/**
+ * 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)) {
+        return { limitMs: grantMs, why: `the approved ${minutes(grantMs)}: ${Number.isFinite(sample.load) ? `load ${sample.load.toFixed(1)} on ${sample.cores} cores left the check ${free} of its normal ${normal}` : "load isn't measured here"}` };
+    }
+    const ceiling = Math.max(grantMs, Math.min(grantMs * CHECK_LIMIT_MAX_FACTOR, CHECK_LIMIT_CEILING_MS));
+    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;
+const recordSchema = z.strictObject({
+    version: z.literal(1),
+    cores: z.int().min(1).max(4096),
+    grantMs: z.int().min(1),
+    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;
+    const early = record.samples.filter(one => one.atMs <= CUT_WINDOW_MS && one.load !== null).map(one => one.load);
+    if (early.length === 0)
+        return null;
+    const least = Math.min(...early);
+    if (!budgetCut(record.cores, least))
+        return null;
+    if (!stoppedAtLimit && (record.elapsedMs === null || record.elapsedMs < selfStopAfter(record.limitMs)))
+        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;
+    started;
+    samples = [];
+    timer;
+    cores;
+    attemptStart = null;
+    elapsed = null;
+    limitMs;
+    why;
+    constructor(grantMs, options = {}) {
+        this.grantMs = grantMs;
+        this.options = options;
+        const sample = options.sample ?? (() => machineSample());
+        const clock = options.clock ?? Date.now;
+        this.started = clock();
+        const first = sample();
+        this.cores = first.cores;
+        ({ limitMs: this.limitMs, why: this.why } = checkLimitFor(grantMs, first));
+        this.push(0, first.load);
+        const every = options.everyMs ?? SAMPLE_EVERY_MS;
+        this.timer = every > 0 ? setInterval(() => { try {
+            this.push(clock() - this.started, sample().load);
+        }
+        catch { /* a missed reading */ } }, every) : null;
+        this.timer?.unref?.();
+    }
+    push(atMs, load) {
+        if (this.samples.length >= MAX_SAMPLES) {
+            if (this.timer !== null)
+                clearInterval(this.timer);
+            return;
+        }
+        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);
+        return { version: 1, cores: this.cores, grantMs: this.grantMs, limitMs: this.limitMs, why: this.why, startedAt: new Date(this.started).toISOString(), elapsedMs: this.elapsed, samples: [...this.samples] };
+    }
+}

package/dist/check-only-standing.d.ts

@@ -0,0 +1,36 @@
+import type { CheckAccess } from "./check-access.js";
+import type { Store } from "./store.js";
+export type CheckAuthorization = {
+    id: number;
+    taskRef: number;
+    run: number;
+    candidate: string;
+    commandDigest: string;
+    level: "quick" | "full";
+    access: CheckAccess;
+    scopeDigest: string;
+    expiresAt: string;
+    usedRequest: number | null;
+};
+export declare function readAuthorization(row: Record<string, unknown>): CheckAuthorization;
+/** The approval an authorization stands on: the plan's seal, on these exact bytes, still standing as dispatch reads it. */
+export declare function approvedScopeStands(store: Store, taskRef: number, scopeDigest: string, now: Date): boolean;
+/** 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 declare function authorizationProblem(store: Store, auth: CheckAuthorization, input: {
+    head: string;
+    digest: string;
+}, now: Date): string | null;
+/** At the run: the used authorization this request claimed. */
+export declare function recheckStanding(store: Store, input: {
+    request: number;
+    runId: number;
+    head: string;
+    digest: string;
+}): {
+    ok: true;
+    access: CheckAccess;
+} | {
+    ok: false;
+    problem: string;
+};

package/dist/check-only-standing.js

@@ -0,0 +1,39 @@
+/** 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";
+export function readAuthorization(row) {
+    return { id: Number(row["id"]), taskRef: Number(row["task_ref"]), run: Number(row["run"]), candidate: String(row["candidate"]), commandDigest: String(row["command_digest"]),
+        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.";
+    if (auth.commandDigest !== input.digest)
+        return "The approved check changed.";
+    if (refArchived(store, auth.taskRef))
+        return "This task is put away.";
+    if (!approvedScopeStands(store, auth.taskRef, auth.scopeDigest, 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)
+        return { ok: false, problem: "Its authorization couldn't be read." };
+    const auth = readAuthorization(row);
+    const problem = authorizationProblem(store, auth, input, new Date());
+    return problem === null ? { ok: true, access: auth.access } : { ok: false, problem };
+}

package/dist/check-only.d.ts

@@ -0,0 +1,15 @@
+import type { Store } from "./store.js";
+/** How long a recheck may still start after its build finished. */
+export declare const CHECK_ONLY_WINDOW_MS: number;
+export declare const RECHECK_ACTOR = "Toolroll";
+/**
+ * Written only from the existing approval of this exact commit: the seal this run was admitted under, still standing,
+ * on the bytes this run built. Null when anything is missing, and the person's Run checks stays the only road.
+ */
+export declare function authorizeCheckOnly(store: Store, runId: number, now: Date): number | null;
+/** Claim one authorization and ask for its check, in one transaction. Null: nothing was asked. */
+export declare function claimRecheck(store: Store, authorization: number, now: Date): {
+    request: number;
+} | null;
+/** Each sweep: a standing authorization whose result has no readable verdict asks for its one check. */
+export declare function requestMissingRechecks(store: Store, root: string, now: Date): number;