toolroll 0.9.93 → 0.9.95

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;

package/dist/check-only.js

@@ -0,0 +1,99 @@
+/**
+ * Automatic recheck under a check-only authorization (docs/plans/plain-toolroll.md P2.2).
+ *
+ * When a build finishes, the approval that built its commit writes one authorization: this task, this exact commit, the
+ * approved check command's digest, the access the build's own check had, one automatic run, and an expiry. It never
+ * seals anything and starts no build and no agent: it asks the follow-up check road (result-follow-ups.ts), which checks
+ * the commit out in a fresh folder and runs the approved command, nothing else.
+ *
+ * The sweep uses it only when the result's verdict is missing or unreadable. A failed, passed or running check needs
+ * nothing, and closes it. The claim (used_at, compare-and-swap in the transaction that asks) is the cap: a second worker
+ * or a crash after the claim finds it spent, and the need stays with the person. A changed command is a different
+ * digest, so the old authorization covers nothing: Run checks on the new command is the person's act.
+ */
+import { assignmentChecksForRun } from "./assignment.js";
+import { runCheckLevel, repoOfRun, checkCommandFor } from "./check-levels.js";
+import { approvedScopeStands, authorizationProblem, readAuthorization } from "./check-only-standing.js";
+import { requestFollowUpChecks } from "./result-follow-ups.js";
+import { releaseCheckScope } from "./scope.js";
+import { refArchived } from "./task-archive.js";
+import { approvedCheckStateOf } from "./task-status.js";
+/** How long a recheck may still start after its build finished. */
+export const CHECK_ONLY_WINDOW_MS = 24 * 60 * 60_000;
+export 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 function authorizeCheckOnly(store, runId, now) {
+    return store.transact(() => {
+        const run = store.getRun(runId);
+        if (run === null || run.role !== "builder" || run.outcome !== "built" || run.headRevision === null || !/^[a-f0-9]{40}$/.test(run.headRevision))
+            return null;
+        const ref = store.refById(run.taskRef);
+        if (ref === null || ref.repo === null || refArchived(store, ref.id))
+            return null;
+        const scope = store.getScope(ref.externalId);
+        if (scope === null || scope.approvedDigest !== scope.digest || run.scopeDigest !== scope.digest)
+            return null;
+        // A release's check has its own road (check-failure.ts), and the nightly's its own.
+        if (releaseCheckScope(scope) || scope.releaseTerms != null)
+            return null;
+        if (!approvedScopeStands(store, ref.id, scope.digest, now))
+            return null;
+        const level = runCheckLevel(store, runId);
+        if (level === "off")
+            return null;
+        const chosen = checkCommandFor(store, ref.repo, level ?? "full");
+        if (chosen.command === null || chosen.level === "off")
+            return null;
+        const written = store.handle.prepare(`INSERT INTO check_authorization (task_ref, run, candidate, command_digest, level, check_access, scope_digest, written_at, expires_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT (task_ref, candidate, command_digest) DO NOTHING`)
+            .run(ref.id, runId, run.headRevision, chosen.command.digest, chosen.level, store.runCheckAccess(runId), scope.digest, now.toISOString(), new Date(now.getTime() + CHECK_ONLY_WINDOW_MS).toISOString());
+        return Number(written.changes) > 0 ? Number(written.lastInsertRowid) : null;
+    });
+}
+/** Claim one authorization and ask for its check, in one transaction. Null: nothing was asked. */
+export function claimRecheck(store, authorization, now) {
+    return store.transact(() => {
+        const row = store.handle.prepare("SELECT * FROM check_authorization WHERE id = ? AND used_at IS NULL AND closed_at IS NULL AND expires_at > ?").get(authorization, now.toISOString());
+        if (row === undefined)
+            return null;
+        const auth = readAuthorization(row);
+        const run = store.getRun(auth.run);
+        const repo = repoOfRun(store, auth.run);
+        if (run === null || repo === null || store.lastBuilderRun(auth.taskRef)?.id !== auth.run || store.hasLiveClaim(auth.taskRef, now))
+            return null;
+        const live = checkCommandFor(store, repo, auth.level).command;
+        if (live === null || authorizationProblem(store, auth, { head: run.headRevision ?? "", digest: live.digest }, now) !== null)
+            return null;
+        const asked = requestFollowUpChecks(store, { runId: auth.run, level: auth.level, actor: RECHECK_ACTOR, why: "recheck" }, now);
+        // An existing request is the person's own: it stands, and this authorization isn't spent on it.
+        if (!asked.ok || asked.existing)
+            return null;
+        const spent = store.handle.prepare("UPDATE check_authorization SET used_at = ?, used_request = ? WHERE id = ? AND used_at IS NULL").run(now.toISOString(), asked.request, auth.id);
+        if (Number(spent.changes) !== 1)
+            throw new Error("the recheck's authorization moved inside its own transaction");
+        return { request: asked.request };
+    });
+}
+/** Each sweep: a standing authorization whose result has no readable verdict asks for its one check. */
+export function requestMissingRechecks(store, root, now) {
+    const open = store.handle.prepare("SELECT * FROM check_authorization WHERE used_at IS NULL AND closed_at IS NULL AND expires_at > ? ORDER BY id").all(now.toISOString());
+    let asked = 0;
+    for (const row of open) {
+        const auth = readAuthorization(row);
+        const run = store.getRun(auth.run);
+        if (run === null || run.finishedAt === null)
+            continue;
+        const state = approvedCheckStateOf(assignmentChecksForRun(store, root, auth.run, now));
+        if (state === "not-run" || state === "unreadable") {
+            if (claimRecheck(store, auth.id, now) !== null)
+                asked++;
+            continue;
+        }
+        if (state !== "running")
+            store.handle.prepare("UPDATE check_authorization SET closed_at = ? WHERE id = ? AND used_at IS NULL").run(now.toISOString(), auth.id);
+    }
+    return asked;
+}

package/dist/check-repair.d.ts

@@ -0,0 +1,47 @@
+import type { Store } from "./store.js";
+export type CheckRepairState = "waiting" | "repairing" | "rerunning" | "with-person" | "parked" | "fixed" | "closed";
+export type CheckRepair = {
+    id: number;
+    familyRoot: string;
+    ownerTask: string;
+    repo: string;
+    revision: string;
+    sourceRun: number;
+    state: CheckRepairState;
+    why: string;
+    repairTask: string | null;
+    attempt: number | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export declare function checkRepairsOfTask(store: Store, taskId: string): CheckRepair[];
+export declare function checkRepairOfRun(store: Store, runId: number): CheckRepair | null;
+/** What makes this failure this failure: the command, how it ended, and which files failed. Never the log's own bytes,
+ * which differ on every run. */
+export declare function failureKeyOf(receipt: string, log: string): string;
+/**
+ * Route one failed check. Runs at disposition. A failure already on record for this family and revision changes nothing,
+ * unless it was the one rerun of an unrelated failure, which now goes to a person through the ledger's own rerun stop.
+ */
+export declare function routeFailedCheck(store: Store, repo: string, root: string, runId: number, now: Date): CheckRepair | null;
+export type StartRepair = {
+    ok: true;
+    draft: string;
+    attempt: number;
+    approved: boolean;
+} | {
+    ok: false;
+    reason: "unknown" | "refused";
+    message: string;
+};
+/** A person asks for the repair. The draft takes the normal plan approval: this is not that approval. */
+export declare function startCheckRepair(store: Store, root: string, runId: number, now: Date): StartRepair;
+/** A passing result in the family ends its failed-check rows. Rows the person already holds end too: the code passes now. */
+export declare function settleCheckRepairs(store: Store, taskId: string, verdict: string, now: Date): void;
+/** Each sweep: a parked failure whose task is free again takes its next step, unless a newer attempt replaced it. */
+export declare function resumeParkedRepairs(store: Store, root: string, now: Date): number;
+/** A build was accepted as finished: count what it answered, then route its check if it failed. Bookkeeping that never
+ * costs the build its result: a problem here leaves the finding open and the failed check on the result. */
+export declare function followBuiltRun(store: Store, repo: string, root: string, runId: number, worktree: string, now: Date): void;
+/** How a failed check stands, for a person, in one line. */
+export declare function checkRepairWords(row: CheckRepair): string;

package/dist/check-repair.js

@@ -0,0 +1,240 @@
+/**
+ * A failed check gets one owner and a bounded repair (docs/plans/fleet-follow-through.md, part 2).
+ *
+ * One `check_repair` row per task family, revision and failure: the UNIQUE key is what keeps the same failure on the
+ * same revision from starting a second repair, however many times it is seen. The row's owner is the task that built
+ * the revision. The repair itself is the existing ledger's (`maybeTriggerRepair`, `repair_chain`), so it is an ordinary
+ * revision: the source scope verbatim, the ordinary rails, the ordinary approval.
+ *
+ * Who says yes doesn't change here. A mode a person signed with automatic repair and a limit drafts and approves through
+ * the seal that already exists. Without that signature nothing is drafted and nothing spends: the row waits for a person,
+ * and a person's repair is a draft that takes the normal plan approval. A model never moves a row past that.
+ *
+ * Failure text never reaches this file's decisions: the failure key comes from the sealed receipt and the log's failing
+ * file names, and it only ever matches rows, it grants nothing.
+ */
+import { createHash } from "node:crypto";
+import { maybeTriggerRepair } from "./dispose.js";
+import { readingFleet } from "./fleet-schema.js";
+import { familyRootOf, settleFindingAnswers } from "./findings.js";
+import { failingTestsOf } from "./gate-failure.js";
+import { CHECK_REPAIR_LIMIT, modeTermsFromJson } from "./modes.js";
+import { releaseCheckScope } from "./scope.js";
+import { readVerificationView } from "./contracts/verification-view.js";
+import { failedVerificationEvidence } from "./verification-evidence.js";
+import { saveEvidencePair } from "./evidence-pair.js";
+const repairOf = (row) => ({
+    id: Number(row["id"]), familyRoot: String(row["family_root"]), ownerTask: String(row["owner_task"]), repo: String(row["repo"]), revision: String(row["revision"]),
+    sourceRun: Number(row["source_run"]), state: String(row["state"]), why: String(row["why"]), repairTask: row["repair_task"] === null ? null : String(row["repair_task"]),
+    attempt: row["attempt"] === null ? null : Number(row["attempt"]), createdAt: String(row["created_at"]), updatedAt: String(row["updated_at"]),
+});
+export function checkRepairsOfTask(store, taskId) {
+    return readingFleet(() => store.handle.prepare("SELECT * FROM check_repair WHERE family_root = ? ORDER BY id DESC").all(familyRootOf(store, taskId)).map(repairOf), []);
+}
+export function checkRepairOfRun(store, runId) {
+    return readingFleet(() => {
+        const row = store.handle.prepare("SELECT * FROM check_repair WHERE source_run = ? ORDER BY id DESC LIMIT 1").get(runId);
+        return row === undefined ? null : repairOf(row);
+    }, null);
+}
+/** What makes this failure this failure: the command, how it ended, and which files failed. Never the log's own bytes,
+ * which differ on every run. */
+export function failureKeyOf(receipt, log) {
+    const view = readVerificationView(receipt);
+    const facts = view.ok ? view.value : null;
+    const failing = failingTestsOf(log)?.map(one => one.file).sort() ?? [];
+    const result = facts === null ? null : facts.result;
+    return createHash("sha256").update(JSON.stringify(["toolroll:check-failure", facts?.command.digest ?? null, result?.exitCode ?? null, result?.failure ?? null, failing])).digest("hex").slice(0, 32);
+}
+/** Parked work stays quiet: a person already has this task, or it is stopped. */
+function parkedWhy(store, taskRef, runId, now) {
+    if (store.activeHolds(taskRef, now).length > 0)
+        return "This task is on hold.";
+    if (store.applicableStopFor(runId) !== null)
+        return "This attempt was stopped.";
+    if (store.decisionsForTask(taskRef).some(one => one.state === "open" || one.state === "expired"))
+        return "This task is waiting for an answer.";
+    if (store.pendingSteerCount(taskRef) > 0)
+        return "This task has a note waiting for its next attempt.";
+    return null;
+}
+/** Why an approved plan can't cover a repair of this result, or null when it can. */
+function notCovered(store, taskId, runId) {
+    const scope = store.getScope(taskId);
+    if (scope === null)
+        return "This task has no approved plan to repair under.";
+    if (scope.releaseTerms != null || releaseCheckScope(scope) || (scope.candidate ?? null) !== null)
+        return "Its plan only covers checking this commit. A fix needs a task of its own.";
+    if (store.lookupRef(taskId)?.deliverable === "report")
+        return "This task delivers a report: there's no code to repair.";
+    const publication = store.publicationForRun(runId);
+    if (publication !== null && !(publication.state === "intended" && publication.attempts === 0))
+        return "This result is published. Fix it through its pull request.";
+    return null;
+}
+/** The attempts this family's repair chain has spent. */
+const attemptsUsed = (store, taskId) => store.repairLineageOf(taskId).attempts.reduce((highest, row) => Math.max(highest, row.attempt), 0);
+function move(store, id, state, why, now, draft) {
+    store.handle.prepare("UPDATE check_repair SET state = ?, why = ?, updated_at = ?, repair_task = COALESCE(?, repair_task), attempt = COALESCE(?, attempt) WHERE id = ?")
+        .run(state, why, now.toISOString(), draft?.task ?? null, draft?.attempt ?? null, id);
+    store.bumpWake();
+}
+function askPerson(store, row, subject, body, now) {
+    store.enqueueNotification({ source: { run: row.sourceRun }, dedupeKey: `check-repair:${row.id}:${subject}`, kind: "check-repair", pushClass: "attention", subject, body, link: `/t/${encodeURIComponent(row.ownerTask)}` }, now);
+}
+/** Take the row one step, from where it stands now. A person's yes is never decided here: `person` only says a person asked for the draft. */
+function advance(store, repo, root, row, now, person) {
+    const run = store.getRun(row.sourceRun);
+    const ref = run === null ? null : store.refById(run.taskRef);
+    const verdict = store.proofVerdictFor(row.sourceRun);
+    if (run === null || ref === null || verdict === null) {
+        move(store, row.id, "with-person", "The failed attempt's records can't be read.", now);
+        return null;
+    }
+    const parked = person ? null : parkedWhy(store, run.taskRef, run.id, now);
+    if (parked !== null) {
+        move(store, row.id, "parked", parked, now);
+        return null;
+    }
+    const uncovered = notCovered(store, row.ownerTask, run.id);
+    if (uncovered !== null) {
+        move(store, row.id, "with-person", uncovered, now);
+        // A release's check speaks for itself (release-adapters.ts): one voice for one failure.
+        if (store.getScope(row.ownerTask)?.releaseTerms == null)
+            askPerson(store, row, "A failed check needs you", `The check failed on ${row.revision.slice(0, 7)}, and a repair can't run under this plan. ${uncovered}`, now);
+        return null;
+    }
+    const mode = store.activeMode(repo, now);
+    const terms = mode === null ? null : modeTermsFromJson(mode.termsJson);
+    const auto = terms?.repairAuto === true;
+    const limit = auto ? terms.repairMaxAttempts : CHECK_REPAIR_LIMIT;
+    const used = attemptsUsed(store, row.ownerTask);
+    if (used >= limit) {
+        const why = `${used} repair${used === 1 ? "" : "s"} tried, which is the limit. It's yours to decide.`;
+        move(store, row.id, "with-person", why, now);
+        askPerson(store, row, "Repairs ran out on a failed check", `The check still fails on ${row.revision.slice(0, 7)} after ${used} repair${used === 1 ? "" : "s"}. The failed check's log is on the result.`, now);
+        return null;
+    }
+    if (!auto && !person) {
+        move(store, row.id, "waiting", "Waiting for a person to start a repair.", now);
+        store.enqueueNotification({ source: { run: run.id }, dedupeKey: `check-repair:${row.id}:waiting`, kind: "check-repair", subject: "A check failed", body: `The check failed on ${row.revision.slice(0, 7)}. Start a repair on the task page.`, link: `/t/${encodeURIComponent(row.ownerTask)}` }, now);
+        return null;
+    }
+    const trigger = maybeTriggerRepair(store, repo, root, run.id, verdict.verdict, now, "verification", !person);
+    if (trigger.kind === "drafted") {
+        move(store, row.id, "repairing", trigger.approved ? `Repair ${trigger.draftTaskId} is approved under the signed mode and will build next.` : `Repair ${trigger.draftTaskId} is drafted and waits for its plan to be approved.`, now, { task: trigger.draftTaskId, attempt: trigger.attempt });
+        saveEvidencePair(store, root, { taskId: row.ownerTask, runId: run.id, by: "Toolroll" }, now);
+    }
+    else if (trigger.kind === "rerun") {
+        move(store, row.id, "rerunning", "The failure looks unrelated to this change, so the check runs once more on the same commit.", now);
+    }
+    else {
+        const why = trigger.kind === "stopped" ? stopWords(trigger.reason) : "A repair can't start from this result. It's yours to decide.";
+        move(store, row.id, "with-person", why, now);
+        if (trigger.kind === "stopped")
+            askPerson(store, row, "A repair stopped", why, now);
+    }
+    return trigger;
+}
+const stopWords = (reason) => ({
+    "repair-attempts-spent": "The repairs allowed were used up.",
+    "repair-no-progress": "Two repairs in a row didn't reduce what's failing, so Toolroll stopped.",
+    "repair-refused-integrity": "The result disagrees with its approved terms, so a person reads it first.",
+}[reason]);
+/**
+ * Route one failed check. Runs at disposition. A failure already on record for this family and revision changes nothing,
+ * unless it was the one rerun of an unrelated failure, which now goes to a person through the ledger's own rerun stop.
+ */
+export function routeFailedCheck(store, repo, root, runId, now) {
+    const run = store.getRun(runId);
+    if (run === null || run.role !== "builder" || run.finishedAt === null || !run.headRevision)
+        return null;
+    const taskId = store.externalIdFor(run.taskRef);
+    if (taskId === null)
+        return null;
+    const failure = failedVerificationEvidence(store, root, runId);
+    if (failure.kind !== "failed")
+        return null;
+    const familyRoot = familyRootOf(store, taskId);
+    const key = failureKeyOf(failure.receipt, failure.log);
+    return store.transact(() => {
+        const earlier = store.handle.prepare("SELECT * FROM check_repair WHERE family_root = ? AND revision = ? AND failure_key = ?").get(familyRoot, run.headRevision, key);
+        if (earlier !== undefined) {
+            const row = repairOf(earlier);
+            if (row.state === "rerunning") {
+                store.handle.prepare("UPDATE check_repair SET source_run = ? WHERE id = ?").run(runId, row.id);
+                maybeTriggerRepair(store, repo, root, runId, store.proofVerdictFor(runId)?.verdict ?? "refuted", now, "verification", true);
+                move(store, row.id, "with-person", "It failed again on the same commit. It's yours to decide.", now);
+            }
+            return repairOf(store.handle.prepare("SELECT * FROM check_repair WHERE id = ?").get(row.id));
+        }
+        // A newer failure replaces an older one nobody took up.
+        store.handle.prepare("UPDATE check_repair SET state = 'closed', why = 'A newer attempt replaced this result.', updated_at = ? WHERE family_root = ? AND state IN ('waiting', 'parked', 'rerunning')").run(now.toISOString(), familyRoot);
+        const made = store.handle.prepare(`INSERT INTO check_repair (family_root, owner_task, repo, revision, failure_key, source_run, state, why, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, 'waiting', '', ?, ?)`)
+            .run(familyRoot, taskId, repo, run.headRevision, key, runId, now.toISOString(), now.toISOString());
+        const row = repairOf(store.handle.prepare("SELECT * FROM check_repair WHERE id = ?").get(Number(made.lastInsertRowid)));
+        advance(store, repo, root, row, now, false);
+        return repairOf(store.handle.prepare("SELECT * FROM check_repair WHERE id = ?").get(row.id));
+    });
+}
+/** A person asks for the repair. The draft takes the normal plan approval: this is not that approval. */
+export function startCheckRepair(store, root, runId, now) {
+    const row = checkRepairOfRun(store, runId);
+    if (row === null)
+        return { ok: false, reason: "unknown", message: `Run ${runId} has no failed check to repair.` };
+    if (row.state !== "waiting" && row.state !== "parked" && row.state !== "with-person")
+        return { ok: false, reason: "refused", message: row.repairTask !== null ? `Repair ${row.repairTask} already exists for this failure.` : row.why };
+    return store.transact(() => {
+        const trigger = advance(store, row.repo, root, row, now, true);
+        if (trigger?.kind === "drafted")
+            return { ok: true, draft: trigger.draftTaskId, attempt: trigger.attempt, approved: trigger.approved };
+        return { ok: false, reason: "refused", message: repairOf(store.handle.prepare("SELECT * FROM check_repair WHERE id = ?").get(row.id)).why };
+    });
+}
+/** A passing result in the family ends its failed-check rows. Rows the person already holds end too: the code passes now. */
+export function settleCheckRepairs(store, taskId, verdict, now) {
+    if (verdict !== "verified" && verdict !== "attested")
+        return;
+    readingFleet(() => store.handle.prepare("UPDATE check_repair SET state = 'fixed', why = 'A later result passed its check.', updated_at = ? WHERE family_root = ? AND state NOT IN ('fixed', 'closed')").run(now.toISOString(), familyRootOf(store, taskId)), null);
+}
+/** Each sweep: a parked failure whose task is free again takes its next step, unless a newer attempt replaced it. */
+export function resumeParkedRepairs(store, root, now) {
+    return readingFleet(() => {
+        let moved = 0;
+        for (const raw of store.handle.prepare("SELECT * FROM check_repair WHERE state = 'parked'").all()) {
+            const row = repairOf(raw);
+            const run = store.getRun(row.sourceRun);
+            if (run === null)
+                continue;
+            if (parkedWhy(store, run.taskRef, run.id, now) !== null)
+                continue;
+            store.transact(() => {
+                if (store.lastBuilderRun(run.taskRef)?.id !== run.id)
+                    move(store, row.id, "closed", "A newer attempt replaced this result.", now);
+                else
+                    advance(store, row.repo, root, row, now, false);
+            });
+            moved++;
+        }
+        return moved;
+    }, 0);
+}
+/** A build was accepted as finished: count what it answered, then route its check if it failed. Bookkeeping that never
+ * costs the build its result: a problem here leaves the finding open and the failed check on the result. */
+export function followBuiltRun(store, repo, root, runId, worktree, now) {
+    try {
+        settleFindingAnswers(store, runId, worktree, now);
+    }
+    catch { /* the answers stay saved */ }
+    try {
+        store.transact(() => store.savepoint(() => routeFailedCheck(store, repo, root, runId, now)));
+    }
+    catch { /* the failure stays on the result */ }
+}
+/** How a failed check stands, for a person, in one line. */
+export function checkRepairWords(row) {
+    const head = `Check failed on ${row.revision.slice(0, 7)} (build #${row.sourceRun})`;
+    if (row.state === "with-person")
+        return `${head}, needs you. ${row.why}`;
+    return row.state === "parked" ? `${head}. Paused: ${row.why}` : `${head}. ${row.why}`;
+}

package/dist/check-report.d.ts

@@ -117,6 +117,8 @@ export declare function prepareCheckAttempt(store: Store, root: string, input: {
     /** Exact cases asked about for learning only (docs/plans/learning-loops.md): a separate handshake field, at most 200,
      * that never joins `watch`, the inventory or anything the check owes. */
     learn?: readonly string[];
+    /** The limit the check runs under when the plane gave it more than the approved one (check-load.ts checkLimitFor). */
+    limitMs?: number | undefined;
 }, now: Date): PreparedAttempt | null;
 /** Seal one JSON payload as a structured-output artifact under its capture label. */
 export declare function sealJson(store: Store, root: string, runId: number, name: string, value: unknown, capture: string, now: Date): number;

package/dist/check-report.js

@@ -220,7 +220,7 @@ export function prepareCheckAttempt(store, root, input, now) {
     // `reportBytes`: the largest report this plane reads back once sealed. A plane that doesn't say (0.9.77 and older) reads
     // only 64 KiB, so the check gives it no larger report rather than one that poisons the receipt (scripts/release-check.mjs).
     const learn = learnRequest(input.learn ?? []);
-    const stdin = JSON.stringify({ nonce, mode, plan, watch: [...(input.watch ?? [])], limitMs: input.command.timeoutMs, reportBytes: CHECK_ARTIFACT_CAP, ...(plan === null ? { owed, ciSubstitute } : {}), ...(learn.length > 0 ? { learn } : {}) });
+    const stdin = JSON.stringify({ nonce, mode, plan, watch: [...(input.watch ?? [])], limitMs: Number.isSafeInteger(input.limitMs) && input.limitMs >= input.command.timeoutMs ? input.limitMs : input.command.timeoutMs, reportBytes: CHECK_ARTIFACT_CAP, ...(plan === null ? { owed, ciSubstitute } : {}), ...(learn.length > 0 ? { learn } : {}) });
     return { runId: input.runId, nonce, stdin, mode, inventory, context, plan, snapshot, watch: [...(input.watch ?? [])], learn };
 }
 /** Seal one JSON payload as a structured-output artifact under its capture label. */

package/dist/check-stamp.d.ts

@@ -0,0 +1,46 @@
+import { type CheckAccess } from "./check-access.js";
+export declare const CHECK_STAMP_VERSION = 1;
+/** Every path: the launch had no write or read fence of that kind. */
+export declare const EVERYWHERE = "*";
+/** What the launch's network was: the machine's own, or the fence's, with exactly the hosts it allowed. */
+export type StampNetwork = {
+    mode: "machine";
+} | {
+    mode: "open" | "allowlist";
+    hosts: string[];
+};
+export type CheckStamp = {
+    version: typeof CHECK_STAMP_VERSION;
+    /** The level the commands ran at, whatever was sealed. */
+    level: CheckAccess;
+    /** The digest of the whole fence as given to the launch (invoke.ts fenceDigest); null with no fence. */
+    policyDigest: string | null;
+    /** Where it could write: exact grants, or [EVERYWHERE]. */
+    writable: string[];
+    /** What it was given to read beyond the fence's denies, or [EVERYWHERE]. */
+    readable: string[];
+    network: StampNetwork;
+};
+export type StampReading = {
+    state: "current";
+    stamp: CheckStamp;
+} | {
+    state: "unknown";
+    why: "missing" | "old" | "unreadable";
+};
+/** A launch with no fence at all. */
+export declare const unfencedStamp: () => CheckStamp;
+export declare const stampDigest: (stamp: CheckStamp) => string;
+/** One saved stamp, exactly its shape or unknown. */
+export declare function readStamp(text: unknown): StampReading;
+/**
+ * A run's whole account of its checks: every launch it stamped. Any it can't read makes the whole unknown (one launch of
+ * unknown reach is reach unknown); otherwise the widest stands, so a narrow command never hides a wider one. None: unknown.
+ */
+export declare function readStamps(texts: readonly unknown[]): StampReading;
+/** Why relying on `reading` for a check that had to stay within `sealed` isn't possible, or null when it can be. */
+export declare function stampRefusal(reading: StampReading, sealed: CheckAccess): string | null;
+/** How a check ran, as a person reads it after the fact; null for a current sandboxed one, which needs no line. */
+export declare function ranWords(reading: StampReading): string | null;
+/** v154: one row per distinct launch of a run's commands (a run's repeats of one launch are one row). */
+export declare const V154_SCHEMA = "\nCREATE TABLE IF NOT EXISTS check_stamp (\n  id      INTEGER PRIMARY KEY,\n  run_id  INTEGER NOT NULL,\n  digest  TEXT NOT NULL,\n  stamp   TEXT NOT NULL,\n  at      TEXT NOT NULL,\n  UNIQUE (run_id, digest)\n);\n";

package/dist/check-stamp.js

@@ -0,0 +1,93 @@
+/**
+ * A check's execution stamp (docs/plans/trusted-release-reports.md, H2): what actually ran, written at launch by the code
+ * that launched it. Before this, a run's `sandbox_access` was all there was, and a missing or unreadable value read as
+ * "sandboxed". That reading is right for one thing only, choosing how a later check may run (narrowest), and wrong for
+ * saying how a check DID run. Anything that relies on how a check ran reads a stamp here: a missing, old or damaged one
+ * is `unknown`, which refuses where it matters and is never said to be sandboxed.
+ *
+ * Reading a stamp is strict, and a new shape takes a new version: an older build's stamp is `unknown` to a newer one.
+ */
+import { createHash } from "node:crypto";
+import { canonicalJson } from "./canonical-json.js";
+import { isCheckAccess, widerThan } from "./check-access.js";
+export const CHECK_STAMP_VERSION = 1;
+/** Every path: the launch had no write or read fence of that kind. */
+export const EVERYWHERE = "*";
+/** A launch with no fence at all. */
+export const unfencedStamp = () => ({ version: CHECK_STAMP_VERSION, level: "unsandboxed", policyDigest: null, writable: [EVERYWHERE], readable: [EVERYWHERE], network: { mode: "machine" } });
+export const stampDigest = (stamp) => createHash("sha256").update(`toolroll:check-stamp:${canonicalJson(stamp)}`).digest("hex").slice(0, 32);
+const paths = (value) => Array.isArray(value) && value.every(one => typeof one === "string" && one !== "");
+const networkIs = (value) => {
+    if (value === null || typeof value !== "object")
+        return false;
+    const one = value;
+    if (one["mode"] === "machine")
+        return Object.keys(one).length === 1;
+    return (one["mode"] === "open" || one["mode"] === "allowlist") && paths(one["hosts"]) && Object.keys(one).length === 2;
+};
+/** One saved stamp, exactly its shape or unknown. */
+export function readStamp(text) {
+    if (typeof text !== "string")
+        return { state: "unknown", why: "missing" };
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return { state: "unknown", why: "unreadable" };
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return { state: "unknown", why: "unreadable" };
+    const one = value;
+    if (one["version"] !== CHECK_STAMP_VERSION)
+        return { state: "unknown", why: typeof one["version"] === "number" ? "old" : "unreadable" };
+    const digest = one["policyDigest"];
+    const whole = isCheckAccess(one["level"]) && (digest === null || (typeof digest === "string" && /^[0-9a-f]{32}$/.test(digest)))
+        && paths(one["writable"]) && paths(one["readable"]) && networkIs(one["network"]) && Object.keys(one).length === 6;
+    if (!whole)
+        return { state: "unknown", why: "unreadable" };
+    // No fence and a narrow level can't both be true: a stamp that says so is damaged.
+    if (digest === null && one["level"] !== "unsandboxed")
+        return { state: "unknown", why: "unreadable" };
+    return { state: "current", stamp: value };
+}
+/**
+ * A run's whole account of its checks: every launch it stamped. Any it can't read makes the whole unknown (one launch of
+ * unknown reach is reach unknown); otherwise the widest stands, so a narrow command never hides a wider one. None: unknown.
+ */
+export function readStamps(texts) {
+    if (texts.length === 0)
+        return { state: "unknown", why: "missing" };
+    let widest = null;
+    for (const text of texts) {
+        const one = readStamp(text);
+        if (one.state === "unknown")
+            return one;
+        if (widest === null || widerThan(one.stamp.level, widest.level))
+            widest = one.stamp;
+    }
+    return { state: "current", stamp: widest };
+}
+/** Why relying on `reading` for a check that had to stay within `sealed` isn't possible, or null when it can be. */
+export function stampRefusal(reading, sealed) {
+    if (reading.state === "unknown")
+        return reading.why === "old" ? "its check's record is from an older Toolroll, so how it ran can't be shown" : "how its check ran wasn't recorded";
+    return widerThan(reading.stamp.level, sealed) ? `its check ran ${reading.stamp.level}, wider than the ${sealed} it was approved for` : null;
+}
+/** How a check ran, as a person reads it after the fact; null for a current sandboxed one, which needs no line. */
+export function ranWords(reading) {
+    if (reading.state === "unknown")
+        return "How these checks ran wasn't recorded";
+    return reading.stamp.level === "sandboxed" ? null : reading.stamp.level === "unsandboxed" ? "Checks ran without a sandbox" : "Checks ran with model and GitHub sign-ins";
+}
+/** v154: one row per distinct launch of a run's commands (a run's repeats of one launch are one row). */
+export const V154_SCHEMA = `
+CREATE TABLE IF NOT EXISTS check_stamp (
+  id      INTEGER PRIMARY KEY,
+  run_id  INTEGER NOT NULL,
+  digest  TEXT NOT NULL,
+  stamp   TEXT NOT NULL,
+  at      TEXT NOT NULL,
+  UNIQUE (run_id, digest)
+);
+`;