toolroll 0.9.103 → 0.9.105

package/dist/check-only.js

@@ -1,16 +1,3 @@
-/**
- * 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";
@@ -18,13 +5,8 @@ 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);
@@ -36,7 +18,6 @@ export function authorizeCheckOnly(store, runId, now) {
         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))
@@ -53,7 +34,6 @@ export function authorizeCheckOnly(store, runId, now) {
         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());
@@ -68,7 +48,6 @@ export function claimRecheck(store, authorization, now) {
         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);
@@ -77,7 +56,6 @@ export function claimRecheck(store, authorization, now) {
         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;

package/dist/check-progress.js

@@ -1,4 +1,3 @@
-/** Live facts extracted from the approved check's ordinary output. */
 export const CHECK_SUITES = ["unit", "flows", "app"];
 const emptySuite = () => ({ state: "pending", passed: 0, failed: 0, skipped: 0, total: null });
 function cleanLine(value) {
@@ -35,7 +34,6 @@ function countWords(name, suite) {
 export function checkProgressLine(suites) {
     return CHECK_SUITES.map(name => suiteWords(name, suites[name])).join(" · ");
 }
-/** A machine-only count line that is safe to send through a push provider. */
 export function isCheckProgressLine(value) {
     const suite = String.raw `(?:unit|flows|app) (?:…|\?(?: [0-9]{1,9})?|[0-9]{1,9}(?:\/[0-9]{1,9})?|✓ [0-9]{1,9}(?:\/[0-9]{1,9})?|✕ [0-9]{1,9}(?:\/[0-9]{1,9})?)(?: · [0-9]{1,9}\/[0-9]{1,9} groups)?`;
     return new RegExp(`^${suite}(?: · ${suite}){2}$`).test(value);
@@ -77,10 +75,6 @@ export function parseCheckProgressSnapshot(raw) {
         return null;
     }
 }
-/**
- * Incrementally reads stdout and stderr. Each stream keeps its own partial
- * line so simultaneous journey output cannot splice two records together.
- */
 export class CheckProgressTracker {
     update;
     suites = {
@@ -92,8 +86,6 @@ export class CheckProgressTracker {
     events = new Set();
     last = "";
     recognized = false;
-    /** Each part's parallel journey run (scripts/e2e-parallel.mjs), by its release-check tag ("" for untagged output):
-     * the scripted flows and app parts run at once, so one shared run would mix their groups. */
     parallels = new Map();
     constructor(update) {
         this.update = update;
@@ -132,8 +124,6 @@ export class CheckProgressTracker {
     emit(final = false, force = false) {
         const snapshot = this.snapshot(final);
         const identity = JSON.stringify(snapshot);
-        // Live progress is advisory: a snapshot the store would refuse (output read in a way that counted past a total) is
-        // never handed on, so reading output can't break the check that prints it (release check 3264).
         if ((force || identity !== this.last) && parseCheckProgressSnapshot(identity) !== null) {
             this.last = identity;
             this.update(snapshot);
@@ -144,9 +134,6 @@ export class CheckProgressTracker {
         const cleaned = cleanLine(raw);
         if (cleaned === "")
             return;
-        // scripts/release-check.mjs streams each part's lines as they come, tagged `<part> | ` (partTag). The unit part and
-        // the scripted journeys are read as their own output; the other parts (the build, the real-model journeys, the
-        // upgrade path) count toward no suite here.
         const tagged = /^(typecheck|build|unit|flows|app|flows-real|app-real|upgrade) \| ?(.*)$/.exec(cleaned);
         if (tagged !== null && !["unit", "flows", "app"].includes(tagged[1]))
             return;
@@ -167,12 +154,8 @@ export class CheckProgressTracker {
             }
             return;
         }
-        // The unit part speaks only through its Vitest summary; a test's own print is never a journey's.
         if (key === "unit")
             return;
-        // scripts/e2e-parallel.mjs: "Running 7 groups, at most 4 at once (12.0 GB available, about 400 MB each): console,
-        // task, …" (before: "Running 7 groups at once: …"), then every group's lines as "[group] [app] …", then
-        // "✅ group  3.1 min" per group and "N of M groups passed …".
         const starting = /^Running ([0-9]+) groups(?:, at most [0-9]+)? at once(?: \([^)]*\))?: (.+)$/.exec(line);
         if (starting !== null) {
             const total = safeCount(starting[1]);
@@ -249,7 +232,6 @@ export class CheckProgressTracker {
         };
         this.emit();
     }
-    /** One group's journey line: count its events, and take its own totals line as that group's result. */
     readGroup(parallel, name, suite, body) {
         if (parallel.suite !== null && parallel.suite !== suite)
             return;
@@ -281,7 +263,6 @@ export class CheckProgressTracker {
             group.skipped += 1;
         this.summarize(parallel);
     }
-    /** The suite is the sum of its groups; its total is known once every group has reported one. */
     summarize(parallel, allPassed) {
         const name = parallel.suite;
         if (name === null)
@@ -306,17 +287,7 @@ export class CheckProgressTracker {
     }
 }
 const emptyGroup = () => ({ passed: 0, failed: 0, skipped: 0, total: null, result: null });
-/** How often a running check's display snapshot may be written: the page and the phone read it, nobody needs more. */
 export const CHECK_PROGRESS_WRITE_MS = 1_000;
-/**
- * Coalesced display writes for a running check (isolated-checks.md, stage 1): a test runner can print thousands of
- * lines a second, and every changed snapshot was its own write transaction. Display snapshots are now written at most
- * once per interval, the latest one winning; the final snapshot is written at once, exactly, and nothing older is ever
- * written after it. A final snapshot whose write fails is kept until a write of it succeeds (the next flush, or a later
- * final push replacing it): Codex review round 1, finding 6. A failing display store never throws out of the writer,
- * so it can't keep the check's outcome from being sealed. The check's evidence (its log, exit and report) never passes
- * through here.
- */
 export function coalescedProgressWriter(save, options = {}) {
     const intervalMs = options.intervalMs ?? CHECK_PROGRESS_WRITE_MS;
     const now = options.now ?? (() => Date.now());
@@ -325,12 +296,10 @@ export function coalescedProgressWriter(save, options = {}) {
     let lastWrite = Number.NEGATIVE_INFINITY;
     let pending = null;
     let timer = null;
-    // Once a final snapshot arrives nothing older is written; `unsavedFinal` holds it until a write of it succeeds.
     let finished = false;
     let unsavedFinal = null;
     const cancel = () => { if (timer !== null)
         clearTimer(timer); timer = null; };
-    /** One display write; false when the store refused it (display only: never thrown). */
     const write = (snapshot) => {
         lastWrite = now();
         try {
@@ -352,7 +321,6 @@ export function coalescedProgressWriter(save, options = {}) {
         timer = null;
         const snapshot = pending;
         pending = null;
-        // A display write that fails here only leaves the page one snapshot behind; the next one (or the final) follows.
         if (snapshot !== null && !finished)
             write(snapshot);
     };

package/dist/check-repair.js

@@ -1,18 +1,3 @@
-/**
- * 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";
@@ -37,8 +22,6 @@ export function checkRepairOfRun(store, 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;
@@ -46,7 +29,6 @@ export function failureKeyOf(receipt, log) {
     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.";
@@ -58,7 +40,6 @@ function parkedWhy(store, taskRef, runId, now) {
         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)
@@ -72,7 +53,6 @@ function notCovered(store, taskId, runId) {
         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 = ?")
@@ -82,7 +62,6 @@ function move(store, id, state, why, now, draft) {
 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);
@@ -99,7 +78,6 @@ function advance(store, repo, root, row, now, person) {
     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;
@@ -141,10 +119,6 @@ const stopWords = (reason) => ({
     "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)
@@ -168,7 +142,6 @@ export function routeFailedCheck(store, repo, root, runId, 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());
@@ -177,7 +150,6 @@ export function routeFailedCheck(store, repo, root, runId, now) {
         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)
@@ -191,13 +163,11 @@ export function startCheckRepair(store, root, runId, now) {
         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;
@@ -219,19 +189,16 @@ export function resumeParkedRepairs(store, root, now) {
         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 */ }
+    catch { }
     try {
         store.transact(() => store.savepoint(() => routeFailedCheck(store, repo, root, runId, now)));
     }
-    catch { /* the failure stays on the result */ }
+    catch { }
 }
-/** 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")

package/dist/check-report.js

@@ -1,22 +1,3 @@
-/**
- * The release check's structured report, on the plane's side (docs/plans/release-once.md, part 2 and rollout phase A).
- *
- * Before a Full check of a prepared candidate runs, the builder seals a `release_check_attempt` row: the intended mode
- * (`full`, or `targeted` with its plan and obligation snapshot), the hash of a fresh nonce, the inventory the check must
- * account for (the unit files, from the verified tree and Vitest's include globs, and the parts selected) and the
- * execution context. It then writes `{"nonce","mode","plan","watch"}` on the check's stdin and closes it.
- *
- * After the check, the report is the last `TOOLROLL_CHECK_REPORT <json>` line of its output that carries that nonce
- * (a line a test prints, or one a leftover process writes, has no nonce and is ignored). It is read strictly and sealed
- * as `check-report.json`, beside `check-inventory.json` (what was sealed, and the groups and versions the check
- * declared). A Full release check qualifies only with all of it (fullCheckProblem): a valid report carrying this run's
- * nonce, a complete inventory, a terminal result for every part, file, journey group and upgrade version it owed, and a
- * successful exit. Anything less — no report, a malformed or cut-short one, one whose exit disagrees, a part that never
- * finished, a file with no result — is an error, "no result", and never a pass. A failed check's report only has to be
- * valid: what it failed on is its result.
- *
- * Coverage trusts test code (the trust decision in the plan). Nothing here decides who may release or deploy.
- */
 import { createHash, randomBytes } from "node:crypto";
 import { lstatSync, realpathSync } from "node:fs";
 import { join } from "node:path";
@@ -25,26 +6,20 @@ import { CHECK_PARTS, CHECK_REPORT_MAX_BYTES, CHECK_REPORT_PREFIX, learnRequest,
 import { readVerifiedArtifact, storeEvidence } from "./evidence.js";
 import { releaseBaselineRecord } from "./release-card.js";
 import { checkAttemptOf, recordCheckAttempt } from "./store.js";
-/** The sealed artifacts' capture labels: what a reader looks for, by exact name. */
 export const CHECK_REPORT_CAPTURE = "release check report v1";
 export const CHECK_INVENTORY_CAPTURE = "release check inventory v1";
 export const TARGETED_PLAN_CAPTURE = "release check targeted plan v1";
 export const OBLIGATION_SNAPSHOT_CAPTURE = "release check obligation snapshot v1";
 export const CHECK_CONTEXT_CAPTURE = "release check context v1";
-/** How large a sealed check artifact may be (the report's own bound). */
 export const CHECK_ARTIFACT_CAP = CHECK_REPORT_MAX_BYTES;
-/** The release check's harness, named: the orchestrator, its runners and helpers, Vitest's configuration and setup, and
- * the reporter. These never carry (release-carry.ts). The execution context digests far more (inHarnessDigest). */
 export const HARNESS_FILES = Object.freeze([
     "scripts/release-check.mjs", "scripts/release-check-ci.mjs", "scripts/upgrade-rule.mjs", "scripts/suite-lifecycle.mjs", "scripts/provider-gate.mjs",
     "scripts/e2e-parallel.mjs", "scripts/e2e-kit.mjs", "scripts/upgrade-path.mjs", "scripts/check-results.mjs",
     "vitest.config.ts", "test/attacks/vitest.config.ts",
     "test/setup-state.ts", "test/fresh-store.ts", "test/temp-root.ts", "test/ensure-build.ts", "test/release-reporter.ts",
 ]);
-/** Vitest's include globs (vitest.config.ts), as the plane reads them: a change to that file is a harness change. */
 export const UNIT_INCLUDE = Object.freeze([/^src\/.+\.test\.ts$/, /^test\/attacks\/.+\.test\.ts$/]);
 export const isUnitFile = (path) => UNIT_INCLUDE.some(one => one.test(path));
-/** The project's own Git directory as Toolroll records it: `<realpath(repo)>/.git`, a real directory. */
 export function projectGitDir(repo) {
     try {
         const named = join(realpathSync(repo), ".git");
@@ -55,14 +30,7 @@ export function projectGitDir(repo) {
     }
 }
 const sha256 = (value) => createHash("sha256").update(value).digest("hex");
-/** A digest of a payload, over its canonical JSON. */
 export const payloadDigest = (value) => sha256(JSON.stringify(value));
-/**
- * Whether a tree path is part of the harness for the execution context: every file EXCEPT the unit test files
- * themselves, the two journey scripts, docs and Markdown. No import tracing: a harness dependency reached by any road
- * (a `require`, a computed `import()`, a side-effect import, a `src/` helper, a config file) is inside this set, so a
- * change to it always changes the digest (fail closed).
- */
 export function inHarnessDigest(path) {
     if (isUnitFile(path))
         return false;
@@ -72,7 +40,6 @@ export function inHarnessDigest(path) {
         return false;
     return true;
 }
-/** The tree facts of `sha`, from objects hashed here (never the checkout). Null with why when they can't be read. */
 export function treeFactsOf(gitDir, sha) {
     const commit = readVerifiedCommit(gitDir, sha);
     if (!commit.ok)
@@ -91,24 +58,17 @@ export function treeFactsOf(gitDir, sha) {
             lockfile: ids.get("package-lock.json") ?? null,
         } };
 }
-/** The execution context a check runs in: what must match for results to stand beside each other. The machine's load
- * budget is left out: it changes how fast a check runs, never what passes (scripts/release-check.mjs checkBudget). */
 export function checkContextOf(facts, command, access) {
     return { version: 1, node: process.version, platform: process.platform, arch: process.arch, lockfile: facts.lockfile, harness: facts.harnessDigest, grant: { id: command.id, digest: command.digest }, access };
 }
-/** Every part a check can have. */
 export const FULL_PARTS = CHECK_PARTS;
-/** Changes no test reads: the plane's copy of scripts/release-check.mjs NOTHING (check-report.test.ts holds them equal). */
 export const NOTHING_PATHS = Object.freeze([/\.md$/, /^docs\//, /^evidence\//, /^design\//, /^output\//, /^LICENSE$/, /\.png$/]);
-/** Model-facing code, whose change runs the real-model journeys: the plane's copy of scripts/release-check.mjs MODEL. */
 export const MODEL_PATHS = Object.freeze([
     /^src\/(lead|converse|subscription-chat|chat-[a-z-]+|lead-[a-z-]+|memory-pass)\.ts$/,
     /^src\/(planner|planner-[a-z-]+|plan|builder|build-review|reviewer|scout|scout-[a-z-]+|decision|evidence)\.ts$/,
     /^src\/(subagents|subagent-work|task-sizing|flow-sort|flow-draft)\.ts$/,
     /^src\/(provider|provider-[a-z-]+|invoke|exec|attest|coding-provider|assignment-adapters|subscription-[a-z-]+)\.ts$/,
 ]);
-/** Whether a changed path can affect an upgrade: the plane's copy of scripts/release-check.mjs needsUpgrade. Its
- * version-only exception is decided apart, from verified blobs (versionOnlyChange), never from the path alone. */
 export function upgradeRelevant(file) {
     if (/^(docs|evidence|design|output)\//.test(file) || /\.md$/.test(file) || file === "LICENSE")
         return false;
@@ -120,27 +80,12 @@ export function upgradeRelevant(file) {
         return false;
     return true;
 }
-/** The paths that differ between two verified trees: added, removed, or with another mode or blob. */
 export function changedPaths(facts, base) {
     const before = new Map(base.entries.map(one => [one.path, `${one.mode} ${one.id}`]));
     const after = new Map(facts.entries.map(one => [one.path, `${one.mode} ${one.id}`]));
     return [...new Set([...before.keys(), ...after.keys()])].filter(path => before.get(path) !== after.get(path)).sort();
 }
-/**
- * The parts a Full check owes, decided by the plane before it runs (eval-harness review 1, finding 2), never by the
- * check's own report: the typecheck and the build always; the unit suite when anything a test reads changed since
- * `base` (the plane's own record of the last release, both trees verified here) and the tree has unit files; the
- * scripted journeys likewise when the tree has the journey scripts; the real-model journeys when model-facing code
- * changed; the upgrade path when a change can affect an upgrade and the tree has it. With no base every one the tree
- * can run is owed. The check is told these on its handshake and runs at least them.
- */
-export function fullObligationsOf(facts, base, 
-/** package.json / package-lock.json paths whose change since `base` is only the project's own version, proved by the
- * plane from both verified blobs (versionBumpsOf): such a change alone doesn't owe the upgrade path. */
-versionBumps = []) {
-    // What the tree can run is read from the candidate AND the last release (security scan): a candidate that deletes a
-    // journey script, the upgrade path or its unit files doesn't take away what was owed at the base — the part stays
-    // owed, and a check that can't run it has no result. Any entry counts, a symlink included, never only a regular file.
+export function fullObligationsOf(facts, base, versionBumps = []) {
     const trees = [facts, ...(base === null ? [] : [base])];
     const has = (path) => trees.some(tree => tree.entries.some(one => one.path === path));
     const units = trees.some(tree => tree.units.length > 0 || tree.entries.some(one => isUnitFile(one.path)));
@@ -159,24 +104,13 @@ versionBumps = []) {
         ...(upgrade ? ["upgrade"] : []),
     ];
 }
-/** What a check must account for, sealed before it runs: every unit file of the tree, whatever runs (a targeted
- * check accounts for the rest through its base), and the parts it owes (a full check's from fullObligationsOf), and
- * whether CI may stand in for its unit suite. */
 export function inventoryOf(facts, plan, full = { owed: FULL_PARTS, release: true }) {
     if (plan !== null)
         return { version: 1, units: facts.units, parts: ["typecheck", "build", ...plan.parts.filter(one => one !== "typecheck" && one !== "build")] };
     return { version: 1, units: facts.units, parts: [...full.owed], ciSubstitute: !full.release, release: full.release };
 }
-/** A Full check's preparation refused (eval-harness review 2, finding 4): the plane recorded a release whose commit it
- * can't verify now, so the check's obligations can't be decided. The check isn't run (builder.ts: `baseline-unverifiable`). */
 export class CheckBaselineUnverifiable extends Error {
 }
-/**
- * Seal a check's attempt row before its command is spawned: intended mode, nonce hash, inventory and context (and for a
- * targeted check its plan and obligation snapshot, sealed as artifacts first). Null when the plane can't read the
- * commit, which leaves the check running exactly as it always has, with no handshake. Throws CheckBaselineUnverifiable,
- * having sealed nothing, when a recorded last release can't be verified.
- */
 export function prepareCheckAttempt(store, root, input, now) {
     if (checkAttemptOf(store, input.runId) !== null)
         return null;
@@ -187,9 +121,6 @@ export function prepareCheckAttempt(store, root, input, now) {
     if (!read.ok)
         return null;
     const plan = input.plan ?? null, snapshot = input.snapshot ?? null;
-    // A full check owes what the plane decides here, from the last release it recorded (never a tag the checkout holds).
-    // No release recorded owes everything the candidate can run; a recorded one that can't be verified refuses the
-    // preparation (eval-harness review 2, finding 4): read as "no release", it would drop what the last release could run.
     const baseline = plan === null ? releaseBaselineRecord(store, input.repo) : { recorded: false };
     let baseFacts = null;
     if (baseline.recorded) {
@@ -216,24 +147,16 @@ export function prepareCheckAttempt(store, root, input, now) {
         planDigest: plan === null ? null : payloadDigest(plan), snapshotDigest: snapshot === null ? null : payloadDigest(snapshot),
         inventoryDigest: payloadDigest(inventory), contextDigest: payloadDigest(context), nonceHash: sha256(nonce),
     }, now);
-    // The command's own limit rides along, so the check ends itself (logs and report printed) before the plane stops it.
-    // `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: 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. */
 export function sealJson(store, root, runId, name, value, capture, now) {
     const bytes = Buffer.from(JSON.stringify(value), "utf8");
     if (bytes.length > CHECK_ARTIFACT_CAP)
         throw new Error(`${name} is over ${CHECK_ARTIFACT_CAP} bytes`);
     return storeEvidence(store, root, runId, "structured-output", name, bytes, capture, now, { captureStatus: "ok", cap: CHECK_ARTIFACT_CAP });
 }
-/**
- * The check's report from its output: the LAST `TOOLROLL_CHECK_REPORT <json>` line carrying this nonce, at most 256 KiB,
- * that matches the contract. Lines without the nonce (a test's print, a leftover process's write) are passed over.
- */
 export function reportFromOutput(stdout, nonce) {
     const lines = stdout.split("\n");
     for (let at = lines.length - 1; at >= 0; at--) {
@@ -259,10 +182,6 @@ export function reportFromOutput(stdout, nonce) {
     }
     return { ok: false, problem: "The check gave no report for this run." };
 }
-/**
- * After the check: seal its report (when it gave a valid one) and the inventory artifact. `exitCode` is the check's own
- * exit; a report that disagrees with it is no report. Returns the report, or null.
- */
 export function sealCheckOutcome(store, root, attempt, output, now) {
     const read = reportFromOutput(output.stdout, attempt.nonce);
     const report = read.ok && read.report.mode === attempt.mode && read.report.exitCode === output.exitCode &&
@@ -277,7 +196,6 @@ export function sealCheckOutcome(store, root, attempt, output, now) {
         sealJson(store, root, attempt.runId, "check-report.json", report, CHECK_REPORT_CAPTURE, now);
     return report;
 }
-/** One sealed check artifact of a run, read back and verified, or null (missing, ambiguous, cut short or changed). */
 export function readSealedJson(store, root, runId, capture) {
     const found = store.artifactsFor(runId).filter(one => one.kind === "structured-output" && one.capture === capture);
     if (found.length !== 1)
@@ -295,17 +213,6 @@ export function readSealedJson(store, root, runId, capture) {
         return null;
     }
 }
-/**
- * Why a Full release check has no result it can count — or null when it qualifies as one. The plane's own facts are the
- * exit it saw (`exitCode`, null when the check didn't exit on its own: timed out or stopped) and the inventory it sealed
- * before the check ran; the report must agree with both. A failed check (a nonzero exit) needs only a valid report: what
- * it failed on is its result. A passing exit needs every obligation the plane sealed (the inventory's parts, never the
- * report's own "selected") to have an outcome, and every part the report ran too: every part once, each run to its
- * end; the unit suite finished with a result for every sealed unit file (CI stands in only when the sealed plan allowed
- * it); every journey run finished, its groups listed before they ran, each passed group with a journey result; and the
- * upgrade path finished, its versions listed, every one run. An explicitly empty inventory (no groups of that kind) is
- * an outcome; a missing one is not. Missing, malformed, truncated or skipped-required results never read as a pass.
- */
 export function fullCheckProblem(input) {
     const { report, inventory, exitCode } = input;
     if (exitCode === null)
@@ -318,8 +225,6 @@ export function fullCheckProblem(input) {
         return `the check's report says exit ${report.exitCode}, but it exited ${exitCode}`;
     if (inventory === null)
         return "the check's sealed inventory can't be read";
-    // Sealed before it ran as a release's check, or it isn't one this can count (security scan: the decision is recorded
-    // with the attempt and a mismatch is no result).
     if (inventory.sealed.release !== true)
         return "the check wasn't sealed as a release's check before it ran";
     if (exitCode !== 0)
@@ -327,7 +232,6 @@ export function fullCheckProblem(input) {
     const parts = new Map(report.parts.map(one => [one.part, one]));
     if (parts.size !== report.parts.length || CHECK_PARTS.some(part => !parts.has(part)))
         return "the report doesn't account for every part of the check exactly once";
-    // The obligations are the plane's, sealed before the run: the typecheck and build always, and every part it owed.
     const owed = new Set(["typecheck", "build", ...inventory.sealed.parts]);
     for (const part of CHECK_PARTS)
         if (owed.has(part) && parts.get(part).selected !== true)
@@ -352,7 +256,6 @@ export function fullCheckProblem(input) {
             return `the unit suite had ${units.runErrors} errors no test owned`;
         if (units.files.some(one => one.state === "failed"))
             return "a unit file failed, yet the check exited 0";
-        // A release's check runs its own units, whatever was sealed (security scan): CI never stands in here.
         if (units.reusedFromCI)
             return "CI's run stood in for the unit suite, which a release's check never allows";
         if (!units.reusedFromCI) {
@@ -395,21 +298,13 @@ export function fullCheckProblem(input) {
     }
     return null;
 }
-/** Where a release bumps the project's own version: the plane's copy of scripts/release-check.mjs VERSIONED. */
 export const VERSIONED_PATHS = Object.freeze(["package.json", "package-lock.json"]);
-/**
- * Whether `path` changed from `before` to `after` only in the project's own version (pipeline-speed.md, item 4): the
- * plane's copy of scripts/release-check.mjs versionOnly — the top-level "version", and in the lockfile the root
- * package's. Anything else (a dependency, a script, a reordering, a duplicate key, a file added or removed, bytes that
- * aren't one JSON object) is a real change.
- */
 export function versionOnlyChange(path, before, after) {
     if (!VERSIONED_PATHS.includes(path) || before === null || after === null)
         return false;
     const rest = (bytes) => {
         const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
         const json = JSON.parse(text);
-        // Parsing is lossy for duplicate keys and rounded numbers. Such bytes never earn an exemption.
         const tokens = (value) => JSON.stringify(value.match(/"(?:\\.|[^"\\])*"|[^\s"{}\[\]:,]+|[{}\[\]:,]/g));
         if (tokens(text) !== tokens(JSON.stringify(json)))
             throw new Error("ambiguous JSON");
@@ -437,8 +332,6 @@ export function versionOnlyChange(path, before, after) {
         return false;
     }
 }
-/** The versioned files whose change from `base` to `facts` is only the version, read from verified blobs in the
- * project's own Git directory. Anything unreadable is a real change (owes more, never less). */
 export function versionBumpsOf(gitDir, base, facts) {
     const before = verifiedBlobs(gitDir, base.tree, VERSIONED_PATHS);
     const after = verifiedBlobs(gitDir, facts.tree, VERSIONED_PATHS);

package/dist/check-stamp.js

@@ -1,19 +1,8 @@
-/**
- * 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 !== "");
@@ -25,7 +14,6 @@ const networkIs = (value) => {
         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" };
@@ -46,15 +34,10 @@ export function readStamp(text) {
         && 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" };
@@ -68,19 +51,16 @@ export function readStamps(texts) {
     }
     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,