toolroll 0.9.104 → 0.9.105

package/dist/release-auto.js

@@ -1,17 +1,3 @@
-/**
- * Releases that approve themselves when green (docs/plans/auto-approve-green.md): the project setting "Release
- * approval: Ask me / Approve automatically when checks pass", and the plane's two automatic seals of a release task.
- *
- *   auto-check  (the approval step)  lets the release task's build run its check — nothing else;
- *   auto-green  (after the check)    the release approval, once the plane itself saw the pull request's CI and the
- *                                    release check pass on the exact candidate. It opens the release's authority as a
- *                                    person's seal of release terms does.
- *
- * Both are written only here, each in one write transaction that proves every fact again from the plane's own records,
- * its own `gh` observation (handed in by release-adapters.ts, which made it) and verified objects in the project's own
- * Git directory. No command or console road reaches these functions: `toolroll release` calls them through its store
- * adapter. Any refusal unseals `auto-check`, so the task asks a person, its passing check kept.
- */
 import { ROUTING_HOOK_FILES, routingHookProblem } from "./route-hooks.js";
 import { assignmentOf } from "./assignment.js";
 import { fullCheckProblem, projectGitDir } from "./check-report.js";
@@ -31,16 +17,9 @@ import { RELEASE_CI_HELD_ACTION, RELEASE_CI_PASSED_ACTION, RELEASE_CI_RUNNING_WO
 import { verificationEvidence } from "./verification-evidence.js";
 import { nightlyDebtHold } from "./nightly-github.js";
 export { RELEASE_APPROVAL_ACTION, releaseApprovalSetting, releaseAutoApproves };
-/** The setting's words, one place. */
 export const RELEASE_APPROVAL_WORDS = { ask: "Ask me", auto: "Approve automatically when checks pass" };
-/** How old the plane's own CI observation may be when it seals. */
 export const CI_OBSERVATION_MS = 5 * 60_000;
 const refuse = (why) => ({ ok: false, why });
-/**
- * Change the setting: an approver's act, proven by the caller (on: a password typed now; off: one click). Lowering it,
- * in the same transaction, unseals every automatic seal of the project whose release hasn't started merging and stops
- * their live releases, so nothing approves — or goes on — on the old setting.
- */
 export function setReleaseApproval(store, repo, auto, by, now) {
     return store.transact(() => {
         const before = releaseApprovalSetting(store, repo).auto;
@@ -58,12 +37,8 @@ export function setReleaseApproval(store, repo, auto, by, now) {
                 if (a !== null && a.state === "merged")
                     continue;
                 if (a !== null && a.state === "merge-reserved") {
-                    // A merge already issued (running, or its outcome unknown) is genuinely in flight: it finishes through its own
-                    // reconciliation. One only reserved, never issued, is stopped for good here, so it can't come back.
                     const issued = releaseOperations(store, a.id).some(op => op.kind === "merge" && (op.state === "running" || op.state === "unknown" || op.state === "succeeded"));
                     if (issued) {
-                        // In flight: it reconciles on its own (merged finishes; failed goes back to deploying) — but the seal is
-                        // withdrawn now, so a failed merge never regains the automatic approval, even with the setting back on.
                         withdraw(store, taskId, now);
                         continue;
                     }
@@ -83,20 +58,15 @@ export function setReleaseApproval(store, repo, auto, by, now) {
         return { changed: true, withdrawn };
     });
 }
-/** Take back an automatic seal for good: the task asks a person again (its result, if any, is kept), and its evidence is
- * marked withdrawn, so no later reading — the setting turned on again included — lets it stand. */
 function unseal(store, taskId, now) {
     withdraw(store, taskId, now);
     withdrawApproval(store, { where: "WHERE task_id = ? AND approval_basis IN ('auto-check', 'auto-green')", args: [taskId] }, { basisAfter: null, clearRoute: true, clearModeDigest: true });
 }
-/** Mark a task's automatic seal's evidence withdrawn for good (its seal row may stay while an issued merge reconciles). */
 function withdraw(store, taskId, now) {
     const sealedWith = store.handle.prepare("SELECT mode_digest FROM task_scope WHERE task_id = ? AND approval_basis IN ('auto-check', 'auto-green')").get(taskId)?.["mode_digest"];
     if (typeof sealedWith === "string")
         store.recordAction({ at: now.toISOString(), actor: "toolroll", repo: store.lookupRef(taskId)?.repo ?? null, taskId, runId: null, action: AUTO_WITHDRAWN_ACTION, outcome: sealedWith, source: "work" });
 }
-/** What every automatic seal needs before anything else: the setting on now, a release task in this project with its
- * candidate and release terms signed in, the exact digest the coordinator filed, and a person who can approve here. */
 function releaseTaskFacts(store, input) {
     const ref = store.lookupRef(input.taskId);
     const scope = store.getScope(input.taskId);
@@ -118,26 +88,20 @@ function releaseTaskFacts(store, input) {
     if (account === null || account.revokedAt !== null || account.role !== "approver" || !store.accountCanAccess(by, ref.repo))
         return refuse(`${by}, who turned on automatic release approval, can no longer approve in this project`);
     const terms = scope.releaseTerms;
-    // A release a person or Toolroll stopped (revoked, or a CI failure after its deploy) asks a person again.
     const stopped = store.handle.prepare("SELECT 1 AS hit FROM release_authority WHERE repo = ? AND version = ? AND pr = ? AND state = 'revoked' LIMIT 1").get(terms.repo, terms.packageVersion, terms.pr);
     if (stopped !== undefined)
         return refuse(`release ${terms.packageVersion} was stopped before, so a person approves it again`);
     return { ok: true, repo: ref.repo, by, taskRef: ref.id, version: terms.packageVersion, pr: terms.pr };
 }
-/** A refusal inside a seal's transaction: thrown, so nothing it wrote (the evidence row) stays. */
 class AutoRefused extends Error {
 }
-/** One evidence row, then the seal naming it, in the caller's transaction. Throws AutoRefused when the seal primitive
- * refused, so the evidence row rolls back with it. */
 function sealWith(store, kind, taskId, by, repo, detail, now, why) {
-    // Written whole (recordAction shortens details for display): the evidence is the record of what proved the seal.
     const written = store.handle.prepare("INSERT INTO action_ledger(at,actor,repo,task_id,run_id,action,outcome,source,detail) VALUES (?,?,?,?,?,?,?,?,?)")
         .run(now.toISOString(), "toolroll", repo, taskId, typeof detail["run"] === "number" ? detail["run"] : null, AUTO_EVIDENCE_ACTION, kind, "work", JSON.stringify({ v: 1, by, ...detail }));
     const id = Number(written.lastInsertRowid);
     if (!store.sealScopeApproval(taskId, by, now, {}, { kind, modeDigest: `auto:${id}` }, "automation"))
         throw new AutoRefused(why);
 }
-/** Run `body` in one write transaction; an AutoRefused inside it rolls everything back and is the answer. */
 function inTransaction(store, body) {
     try {
         return store.transact(body);
@@ -148,11 +112,6 @@ function inTransaction(store, body) {
         throw error;
     }
 }
-/**
- * The approval step with the setting on: seal `auto-check`, so the release task's build runs its check before anyone
- * approves it. Idempotent: an `auto-check` already standing on this digest is the answer. A person's own approval
- * already there is left alone (the coordinator then takes the person's road).
- */
 export function authorizeAutoCheck(store, input) {
     return inTransaction(store, () => {
         const facts = releaseTaskFacts(store, input);
@@ -175,44 +134,19 @@ export function authorizeAutoCheck(store, input) {
         return { ok: true, already: false };
     });
 }
-/** Test infrastructure that lives under src/ (helpers and fixtures, not tests): a person approves changes to it. */
 const SRC_TEST_INFRA = /^src\/(fixtures\/|(.*\/)?(test-[^/]*|[^/]*-test-support[^/]*|[^/]*fixtures?[^/]*)\.[cm]?[jt]sx?$)/;
-/** A test file (normalized path): `*.test.ts`, never inside a fixtures folder. */
 const TEST_FILE = /^(?!.*(^|\/)fixtures?\/)[^]*\.test\.ts$/;
-/** The eval set's and GitHub nightly's policy code (docs/plans/evals-nightly.md, part C, finding 10): the cases and
- * oracles, the evaluator, its gate, hooks and world, reviewer scoring, nightly ingestion, their contracts, and the
- * accounting readings evals trust (reported-usage.ts, run-efficiency.ts). Where they are called from, and the store's
- * accounting reads, are held by eval-hooks.ts instead (evalHookProblem). Results routing's policy is here too
- * (docs/plans/results-routing.md, Protection 1): the record evaluator, the rules, the one writer module, this scan's
- * manifest and the record contract; their callers and pinned bodies are route-hooks.ts's (routingHookProblem). The
- * learning-loops policy modules are here whole (docs/plans/learning-loops.md, Protection 1): check facts, flaky tests
- * (local and CI), lesson notes, memory use and tidy-up; their callers, pinned bodies and SQL writers are eval-hooks.ts's
- * (learningHookProblem). */
 const EVAL_POLICY = /^(evals\/|src\/evals[^/]*\.ts$|src\/eval-[^/]*\.ts$|src\/reviewer-evals\.ts$|src\/nightly-github\.ts$|src\/contracts\/evals[^/]*\.ts$|src\/reported-usage\.ts$|src\/run-efficiency\.ts$|src\/route-(?:results|rules|store|hooks)\.ts$|src\/contracts\/route-results\.ts$|src\/(?:check-facts|flaky|flaky-ci|lesson-notes|memory-use|memory-tidy)\.ts$)/;
-/** Build or type configuration anywhere: a person approves it. */
 const BUILD_CONFIG = /(^|\/)(tsconfig[^/]*\.json|[^/]*\.config\.[cm]?[jt]s|\.npmrc|\.nvmrc|\.node-version)$/;
-/**
- * What an automatic approval may ship without a person, as an allowlist over each changed path (auto-approve-green.md):
- * product code under `src/` (its tests included; never its test helpers or fixtures, nor build configuration), test files
- * under `test/` (only `*.test.ts`: never a helper, fixture or setup file; deleting any test needs a person), docs
- * (never the testing policy or plans, never agent or security policy), the changelog and README, and a version bump of
- * package.json and package-lock.json. Everything else — CI, scripts (the check, the build, the harness), test/,
- * dependencies, the lockfile beyond its version, config — and every path the release carry rules never carry, needs a
- * person. Null when the path may ship.
- */
 export function autoPathProblem(path) {
     const normal = rulePath(path);
     const testUnderTest = TEST_FILE.test(normal) && normal.startsWith("test/");
-    // Every deny rule first — the carry rules' never list (minus its blanket test/ rule, for test files there only) and
-    // build configuration — so a test file can't slip a policy or CI path through (test/attacks/.github/a.test.ts).
     for (const rule of CARRY_RULES.never) {
         if (testUnderTest && rule.matches("test/__probe__.test.ts"))
             continue;
         if (rule.matches(normal))
             return rule.why;
     }
-    // Test files under test/ carry the same trust as src's (Alex: test authors are trusted) — only the `.test.ts` files
-    // themselves, never a helper, fixture, setup or config file beside them, nor one inside a fixtures folder.
     if (EVAL_POLICY.test(normal))
         return "it's eval, nightly, model routing or learning policy code";
     if (testUnderTest)
@@ -229,13 +163,6 @@ export function autoPathProblem(path) {
         return null;
     return "it's outside what a release approves itself for (product code, tests, docs, the changelog and a version bump)";
 }
-/**
- * GitHub CI on the exact head, as the plane read it (every attempt): fresh, every run GitHub Actions, and the same
- * verdict every later release boundary uses (release.ts prChecksVerdict: exact head, each job by its latest attempt,
- * every required check present), where an earlier failure stands only as confirmed infrastructure (GitHub's job record
- * shows it ended before any workflow step ran), at most INFRA_RERUNS_PER_CANDIDATE of them. The tolerated failures are
- * returned for the evidence.
- */
 export function ciVerdict(observation, candidate, now) {
     const no = (problem) => ({ ok: false, problem });
     if (observation.head !== candidate)
@@ -255,13 +182,10 @@ export function ciVerdict(observation, candidate, now) {
         return no(`not finished: ${verdict.waiting.join(", ")}`);
     return { ok: true, failures: verdict.failures };
 }
-/** ciVerdict's problem, or null when CI passes. */
 export function ciProblem(observation, candidate, now) {
     const verdict = ciVerdict(observation, candidate, now);
     return verdict.ok ? null : verdict.problem;
 }
-/** package.json or package-lock.json with only its version fields left out, canonical (sorted keys); undefined when it
- * can't be read. */
 function withoutVersion(path, bytes) {
     if (bytes === undefined)
         return null;
@@ -285,7 +209,6 @@ function withoutVersion(path, bytes) {
         : value !== null && typeof value === "object" ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
     return JSON.stringify(canonical(copy));
 }
-/** The test infrastructure of one verified tree: its source files under src/ and test/ and its vitest configs, scanned. */
 function infrastructureAt(gitDir, tree) {
     const entries = verifiedTreeEntries(gitDir, tree);
     if (!entries.ok)
@@ -302,8 +225,6 @@ function infrastructureAt(gitDir, tree) {
         return null;
     }
 }
-/** What the candidate changes since `base` (the plane's own reading of where it left its base branch), from verified
- * objects, that an automatic approval never ships. Null when every change may ship. */
 function changeProblem(repo, base, candidate) {
     const gitDir = projectGitDir(repo);
     if (gitDir === null)
@@ -316,8 +237,6 @@ function changeProblem(repo, base, candidate) {
     const diff = verifiedTreeDiff(gitDir, before.value.tree, after.value.tree);
     if (!diff.ok)
         return `the candidate's change can't be read: ${diff.message}`;
-    // Test infrastructure found from the import graph (test-infra.ts), at the base — which the candidate can't rewrite —
-    // and at the candidate (a new helper only tests import). Unreadable: refuse.
     const scans = [];
     for (const tree of [before.value.tree, after.value.tree]) {
         const found = infrastructureAt(gitDir, tree);
@@ -326,27 +245,19 @@ function changeProblem(repo, base, candidate) {
         scans.push(found);
     }
     const infra = new Set(scans.flatMap(one => [...one.infra]));
-    // The eval and nightly enforcement calls the base holds must all still be in place at the candidate (eval-hooks.ts).
-    // One verified read of every listed file per tree (an unreadable tree reads as every file missing: a person decides).
     const blobAt = (tree) => { const blobs = verifiedBlobs(gitDir, tree, EVAL_HOOK_FILES); return (file) => blobs.ok ? blobs.value.get(file)?.bytes ?? null : null; };
     const hooks = evalHookProblem(blobAt(after.value.tree), blobAt(before.value.tree));
     if (hooks !== null)
         return `${hooks}: a person decides`;
-    // No changed file may write over a pinned Store method from outside store.ts (eval-hooks.ts storeRewriteProblem).
     const changed = diff.value.filter(change => change.after !== null).map(change => change.path);
-    // A failed read is no reader at all (a person decides), never files that read as absent.
     const changedAt = (tree) => { const blobs = verifiedBlobs(gitDir, tree, changed); return blobs.ok ? (file) => blobs.value.get(file)?.bytes ?? null : null; };
     const rewrites = storeRewriteProblem(changed, changedAt(after.value.tree), changedAt(before.value.tree));
     if (rewrites !== null)
         return `${rewrites}: a person decides`;
-    // Results routing (route-hooks.ts): its required calls and pinned bodies the base holds, and no changed file writing
-    // its rows (or the Models rows) from anywhere but their writers.
     const routingAt = (tree) => { const blobs = verifiedBlobs(gitDir, tree, ROUTING_HOOK_FILES); return (file) => blobs.ok ? blobs.value.get(file)?.bytes ?? null : null; };
     const routing = routingHookProblem({ candidate: routingAt(after.value.tree), base: routingAt(before.value.tree) }, { paths: changed, candidate: changedAt(after.value.tree), base: changedAt(before.value.tree) });
     if (routing !== null)
         return `${routing}: a person decides`;
-    // Learning loops (eval-hooks.ts learningHookProblem): the calls that record a check's facts, the strictly pinned
-    // memory and check bodies the base holds, and no changed file writing a learning-loops table outside its writers.
     const learningAt = (tree) => { const blobs = verifiedBlobs(gitDir, tree, LEARNING_HOOK_FILES); return (file) => blobs.ok ? blobs.value.get(file)?.bytes ?? null : null; };
     const learning = learningHookProblem({ candidate: learningAt(after.value.tree), base: learningAt(before.value.tree) }, { paths: changed, candidate: changedAt(after.value.tree), base: changedAt(before.value.tree) });
     if (learning !== null)
@@ -355,15 +266,10 @@ function changeProblem(repo, base, candidate) {
         const modes = [change.before?.mode, change.after?.mode].filter((one) => one !== undefined);
         if (modes.includes("120000") || modes.includes("160000"))
             return `${change.path} is a symlink or submodule`;
-        // Taking a test away is never automatic, wherever it lives.
         if (change.kind === "deleted" && TEST_FILE.test(rulePath(change.path)))
             return `${change.path} was deleted (removing a test needs a person)`;
-        // Counts cannot prove that an assertion survived, and an appended line can disarm what it follows (`vi.mock` hoists,
-        // a top-level hook reaches every case): a test file that was there stays exactly as it was (H4).
         if (change.before !== null && TEST_FILE.test(rulePath(change.path)))
             return `${change.path} changes existing test code (new tests go in a new file; rewriting tests needs a person)`;
-        // A new test may not reach into another: it would run that file's code, and its mocks, here. From the verified tree.
-        // Any test extension: `src/` passes autoPathProblem whatever the file is called, so `.test.ts` alone would miss `.test.tsx`.
         if (change.kind === "added" && isTestPath(rulePath(change.path))) {
             const read = verifiedBlobs(gitDir, after.value.tree, [change.path]);
             const bytes = read.ok ? read.value.get(change.path)?.bytes : undefined;
@@ -376,7 +282,6 @@ function changeProblem(repo, base, candidate) {
             return `${change.path} changed (${why})`;
         if (infra.has(change.path))
             return `${change.path} changed (tests import it and the product doesn't: it's test infrastructure)`;
-        // An import the tests make that couldn't be resolved might name this file: fail closed.
         for (const scan of scans) {
             const open = scan.unresolved.find(one => mightName(one, change.path, scan));
             if (open !== undefined)
@@ -392,18 +297,11 @@ function changeProblem(repo, base, candidate) {
     }
     return null;
 }
-/**
- * The release approval, once the check passed: seal `auto-green` over the standing `auto-check`, or refuse in words —
- * and on any refusal take the `auto-check` back, so a person decides. Everything is proven again in this one write
- * transaction (docs/plans/auto-approve-green.md, "What auto-green proves").
- */
 export function sealAutoGreen(store, input) {
     const answer = inTransaction(store, () => {
         const facts = releaseTaskFacts(store, input);
         if (!facts.ok)
             return facts;
-        // Head-only CI is the merged tree only when GitHub itself refuses a branch behind main (eval-harness review 1,
-        // finding 4): without that setting nothing approves itself.
         if (input.mainUpToDate !== true)
             return refuse(input.mainUpToDate === null
                 ? "GitHub's branch protection for main couldn't be read, so whether it refuses a branch behind main is unknown"
@@ -411,7 +309,6 @@ export function sealAutoGreen(store, input) {
         const checking = autoReleaseApprovalOf(store, input.taskId, "auto-check");
         if (!checking.ok)
             return refuse(`its check wasn't authorized automatically: ${checking.why}`);
-        // The release check: this task's build on this digest, its native receipt, a Full level and no failed check before.
         const run = store.getRun(input.run);
         if (run === null || run.taskRef !== facts.taskRef || run.role !== "builder" || run.finishedAt === null || !(run.outcome === "built" || run.outcome === "no-change"))
             return refuse(`run ${input.run} isn't a finished build of this release task`);
@@ -422,10 +319,6 @@ export function sealAutoGreen(store, input) {
             return refuse(`run ${input.run} recorded no commit`);
         if (runCheckLevel(store, run.id) !== "full")
             return refuse("the release check wasn't Full");
-        // Earlier builds of this task that didn't finish built with a passed check (a failed check, a check that never ran,
-        // a build that failed or was interrupted) stand only as confirmed infrastructure the release itself reran on the
-        // same signed scope, at most INFRA_RERUNS_PER_CANDIDATE (check-failure.ts): a failing test, an unexplained failure
-        // or a real-model journey before the pass means a person decides. So does anything that passed only on a retry.
         const failedRuns = store.handle.prepare(`SELECT r.id, r.scope_digest FROM run r LEFT JOIN run_check c ON c.run = r.id
         WHERE r.task_ref = ? AND r.role = 'builder' AND r.id <> ?
           AND NOT (COALESCE(r.outcome, '') IN ('built', 'no-change') AND COALESCE(c.status, '') = 'passed') ORDER BY r.id`).all(facts.taskRef, run.id);
@@ -436,7 +329,6 @@ export function sealAutoGreen(store, input) {
         const standing = releaseCheckStanding(store, input.evidenceRoot, { taskId: input.taskId, run: run.id });
         if (!standing.ok)
             return refuse(standing.why);
-        // Unknown is never "no retries" (eval-harness review 1, finding 3).
         if (standing.retried === null)
             return refuse("the release check's retry record can't be read (its report or receipt is missing or damaged), so whether anything passed only on a retry is unknown and a person decides");
         if (standing.retried.length > 0)
@@ -462,8 +354,6 @@ export function sealAutoGreen(store, input) {
         const command = gate["command"];
         if (gate["coverage"] !== undefined && gate["coverage"] !== "full")
             return refuse(`the release check didn't cover everything (${String(gate["coverage"])})`);
-        // A readable, valid report and inventory of a Full attempt, the receipt's own, every obligation accounted for, and
-        // the retry summary sealed in the receipt: an automatic approval never stands on evidence it can't read.
         const check = gate["check"];
         const sealed = sealedRun(store, input.evidenceRoot, run.id);
         if (check === undefined || sealed === null || sealed.attempt.mode !== "full" || check.attempt !== "full" || sealed.report === null || sealed.inventory === null || sealed.reportDigest !== check.report) {
@@ -474,8 +364,6 @@ export function sealAutoGreen(store, input) {
             return refuse(`the release check has no complete result: ${incomplete}`);
         if (!Array.isArray(check.retried))
             return refuse("the release check's receipt has no sealed retry record, so a person decides");
-        // Belt to the retry record (finding 6): a check that passed only on a rerun after the recovery setup never approves
-        // itself — its first failure isn't confirmed infrastructure.
         if (result?.setupReplayed === true)
             return refuse("the release check passed only when it was run again after the approved setup, so a person decides");
         if (gate["run"] !== run.id || gate["head"] !== head || gate["scopeDigest"] !== input.digest || result?.ran !== true || result.exitCode !== 0 || live === null || command?.command !== live.command) {
@@ -485,22 +373,16 @@ export function sealAutoGreen(store, input) {
         const receipt = assignment?.receipt ?? null;
         if (receipt === null || receipt.runId !== run.id || receipt.digest !== input.receipt || receipt.head !== head || receipt.scopeDigest !== input.digest)
             return refuse("the result the release read isn't this build's");
-        // The candidate's change, from verified objects: nothing that defines CI or the check, or steers agents.
         if (head !== input.candidate) {
-            // A prepared candidate's build records its own commit of exactly the candidate's tree (builder.ts).
             const gitDir = projectGitDir(facts.repo);
             const built = gitDir === null ? null : readVerifiedCommit(gitDir, head), wanted = gitDir === null ? null : readVerifiedCommit(gitDir, input.candidate);
             if (built === null || wanted === null || !built.ok || !wanted.ok || built.value.tree !== wanted.value.tree)
                 return refuse(`the build's commit ${head.slice(0, 7)} doesn't hold exactly ${input.candidate.slice(0, 7)}'s files`);
         }
-        // Compared with where the candidate left its base branch, as the plane read it when the check was authorized —
-        // the same base for every attempt, never a build's own recorded base (a task branch can be seeded ahead of time).
         const base = checking.evidence.base;
         const changed = changeProblem(facts.repo, base, input.candidate);
         if (changed !== null)
             return refuse(changed);
-        // GitHub CI, as the plane's own gh saw it moments ago, on exactly this commit.
-        // GitHub's nightly lane debt (evals-nightly.md, part A2): dormant while automatic approval is refused, held here too.
         const nightly = nightlyDebtHold(store, { repo: facts.repo, taskId: input.taskId, candidate: input.candidate, phase: "auto", release: true, now: input.now });
         if (nightly !== null)
             return refuse(nightly.why);
@@ -510,7 +392,6 @@ export function sealAutoGreen(store, input) {
         const observed = input.ci.runs.map(one => ({ id: one.id, name: one.name, suite: one.suite ?? null }));
         sealWith(store, "auto-green", input.taskId, facts.by, facts.repo, {
             digest: input.digest, candidate: input.candidate, run: run.id, receipt: input.receipt, head, base, ci: observed, observedAt: input.ci.observedAt,
-            // What failed first on this same commit and digest (flakes), for whoever reads the record later.
             ciFailures: ci.failures, checkFailures,
         }, input.now, "the release terms can't be approved now (an unsettled deploy, a merge already started, or rules that need a person)");
         store.enqueueNotification({ dedupeKey: `release-auto-approved:${input.taskId}:${input.digest}`, kind: "release-auto",
@@ -523,8 +404,6 @@ export function sealAutoGreen(store, input) {
         giveUpAutoApproval(store, { taskId: input.taskId, why: answer.why, now: input.now });
     return answer;
 }
-/** The automatic road ended without an approval (a refusal, a failed check, a CI failure after the deploy): take the
- * `auto-check` back so the task asks a person, and tell the owner why. Idempotent. */
 export function giveUpAutoApproval(store, input) {
     store.transact(() => {
         const ref = store.lookupRef(input.taskId);
@@ -533,7 +412,6 @@ export function giveUpAutoApproval(store, input) {
         unseal(store, input.taskId, input.now);
         const scope = store.getScope(input.taskId);
         const version = scope?.releaseTerms?.packageVersion ?? null;
-        // Still waiting for CI (round 1, finding 4): nobody is asked to approve yet; `liftCiHold` asks once CI passed.
         const ciHold = releaseCiHoldOf(store, input.taskId);
         if (ciHold !== null) {
             store.enqueueNotification({ dedupeKey: `release-auto-stopped:${input.taskId}:${input.why.slice(0, 120)}`, kind: "release-auto",
@@ -542,7 +420,6 @@ export function giveUpAutoApproval(store, input) {
                 link: chatControlHref("task", input.taskId), source: { taskRef: ref.id } }, input.now);
             return;
         }
-        // Filed while CI runs (Alex, 2026-10-29): a person may approve now; nothing deploys until CI passes.
         const running = releaseCiRunningOf(store, input.taskId) === null ? "" : ` ${RELEASE_CI_RUNNING_WORDS}`;
         store.enqueueNotification({ dedupeKey: `release-auto-stopped:${input.taskId}:${input.why.slice(0, 120)}`, kind: "release-auto", pushClass: "attention",
             subject: `Release${version === null ? "" : ` ${version}`} needs you`,
@@ -550,8 +427,6 @@ export function giveUpAutoApproval(store, input) {
             link: chatControlHref("task", input.taskId), source: { taskRef: ref.id } }, input.now);
     });
 }
-/** A release check failed while checking automatically: tell the owner. The `auto-check` stays: a rerun the release
- * itself made after confirmed infrastructure may still approve itself; any other failure means a person decides. */
 export function noteAutoCheckFailed(store, input) {
     const ref = store.lookupRef(input.taskId);
     if (ref === null)
@@ -562,7 +437,6 @@ export function noteAutoCheckFailed(store, input) {
         body: `${input.why}. Only a failure Toolroll confirmed as its own infrastructure is checked again automatically; for anything else, approve it yourself or fix the branch and release the new commit.`,
         link: chatControlHref("task", input.taskId), source: { taskRef: ref.id } }, input.now);
 }
-/** "Released 0.9.x automatically": the release that approved itself finished. */
 export function noteAutoRelease(store, input) {
     const ref = store.lookupRef(input.taskId);
     if (ref === null)
@@ -571,24 +445,19 @@ export function noteAutoRelease(store, input) {
         subject: `Released ${input.tag} automatically`, body: `${input.tag} is deployed, merged, tagged and published. CI and the release check passed, so nobody had to approve it.`,
         link: chatControlHref("task", input.taskId), source: { taskRef: ref.id } }, input.now);
 }
-/** Whether a task carries an automatic release seal (any state): it never merges or deploys outside `toolroll release`. */
 export function autoReleaseSealed(store, taskId) {
     return store.handle.prepare("SELECT 1 AS hit FROM task_scope WHERE task_id = ? AND approval_basis IN ('auto-check', 'auto-green')").get(taskId) !== undefined;
 }
-/** The plane's record that an automatic release's publication waits for a person (CI stopped passing after its merge),
- * and a person's answer. The newest row for the task wins. */
 export const PUBLISH_HELD_ACTION = "release publish held";
 export const PUBLISH_ALLOWED_ACTION = "release publish allowed";
 export function holdAutoPublish(store, input) {
     store.recordAction({ at: input.now.toISOString(), actor: "toolroll", repo: store.lookupRef(input.taskId)?.repo ?? null, taskId: input.taskId, runId: null,
         action: PUBLISH_HELD_ACTION, outcome: "held", source: "work", detail: input.why });
 }
-/** Why the release's tag, publication and Homebrew wait for a person, or null. */
 export function autoPublishHeld(store, taskId) {
     const row = store.handle.prepare("SELECT action, detail FROM action_ledger WHERE task_id = ? AND action IN (?, ?) ORDER BY id DESC LIMIT 1").get(taskId, PUBLISH_HELD_ACTION, PUBLISH_ALLOWED_ACTION);
     return row === undefined || row["action"] !== PUBLISH_HELD_ACTION ? null : String(row["detail"] ?? "This release's publication waits for a person");
 }
-/** A person lets a held publication go on: the caller proved a person (never the lead, a token or a mode). */
 export function allowAutoPublish(store, input) {
     if (autoPublishHeld(store, input.taskId) === null)
         return refuse("nothing about this release waits for a person");
@@ -596,11 +465,6 @@ export function allowAutoPublish(store, input) {
         action: PUBLISH_ALLOWED_ACTION, outcome: "allowed", source: "request", detail: `${input.by} lets the release's tag, publication and Homebrew go on` });
     return { ok: true };
 }
-/**
- * A release filed while its pull request's CI still ran (pipeline-speed.md D2): hold every approval but the automatic
- * road's until the plane reads exact-head CI passing (Codex review round 1, finding 4). Recorded before the task is
- * filed, so no moment exists where the filed task is approvable with CI pending. Idempotent.
- */
 export function holdApprovalForCi(store, input) {
     if (!/^[0-9a-f]{40}$/.test(input.candidate))
         throw new Error("a CI hold needs the exact candidate commit");
@@ -610,12 +474,6 @@ export function holdApprovalForCi(store, input) {
     store.recordAction({ at: input.now.toISOString(), actor: "toolroll", repo: store.lookupRef(input.taskId)?.repo ?? null, taskId: input.taskId, runId: null,
         action: RELEASE_CI_HELD_ACTION, outcome: "held", source: "work", detail: input.candidate });
 }
-/**
- * Lift a release's CI hold (an older coordinator's) or end its "CI still running" note on the plane's own reading of
- * GitHub CI (never the coordinator's word): fresh, whole, every run GitHub Actions, on exactly the held candidate, and
- * every required check passed (release.ts prChecksVerdict, as a person's road judges it: a person decides about earlier
- * attempts). With `ask`, the owner of a held release is told it needs them now. Nothing held or noted is a pass.
- */
 export function liftCiHold(store, input) {
     return store.transact(() => {
         const held = releaseCiHoldOf(store, input.taskId);