toolroll 0.9.104 → 0.9.105

package/dist/release.js

@@ -1,66 +1,20 @@
-/**
- * `toolroll release <branch>` (D10): the whole release of Toolroll itself as one resumable command. The owner's
- * approval of the release scope is the only human step; everything else runs headless, each waiting step with a time
- * limit:
- *
- *   gate → approval → check → complete → quiet → deploy → link → ci → merge → tree → tag → publish → homebrew → done
- *
- * gate, before filing a task for that commit, looks at the pull request's required checks on it: one that failed stops
- * the release before anything is filed or sent for approval; it waits, naming them, for checks not started or still
- * running, and stops if they don't finish within its limit (a task already filed is not looked at again; ci checks
- * once more before merging). It then files a prepared-candidate task pinned to the branch's exact commit, with the full
- * release check. approval
- * waits for an active approver's yes to that exact scope (never a mode's, an AI's or the lead's). check requires a Full
- * result of that commit: a failed check stops the release and stays visible, nothing reruns it. complete marks that
- * exact result Complete through the task's own authorization. quiet waits until nothing builds. deploy runs the
- * candidate's own deploy (scripts/deploy-browser.mjs: drain, backup, rehearsal, swap, health) and keeps the runtime its
- * final JSON names; an interrupted one is recovered from its saved stage (--phase recover) before anything else. link
- * points both CLI names at that runtime's bin.js, putting them back if either doesn't answer, and goes on only when
- * the console, worker and both names run the gated commit. ci waits for every
- * reported pull-request check on that same commit to pass, with every required check present: pending, missing,
- * skipped or failed never merges. merge
- * squash-merges with the head pinned to the gated commit, tree proves main's new commit has exactly the gated tree,
- * and only then tag pushes the version tag, whose macOS matrix must pass before npm publication (publish.yml). publish
- * waits for npm, the GitHub release and the macOS checks; homebrew updates the tap's formula and merges it (after its checks, when the tap runs any).
- *
- * A private journal (mode 0600, written whole then renamed) records what each step is about to do before it does
- * anything outside this machine, and what it saw after. A stop — a time limit, a failure, a crash, Ctrl-C — leaves the
- * journal at its step; running the same command again finds what already happened (the task, the completion, the
- * merge, the tag, the package, the tap change) instead of doing it twice, and continues from the first unfinished
- * step. A branch, pull request or tag that no longer matches what was gated stops the release rather than guess.
- *
- * Everything outside this module is an adapter (release-adapters.ts), so the state machine is tested without git,
- * GitHub, npm or a running Toolroll.
- */
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
 import { personProof } from "./person-proof.js";
 import { RELEASE_CI_RUNNING_WORDS as CI_RUNNING_WORDS } from "./release-ci-hold.js";
 import { transientFailure } from "./release-net.js";
-/** The pull-request checks a release waits for, by exact job name (docs/plans/test-matrix.md). Every one must have
- * concluded `success` — executed, never skipped — on the gated commit; src/ci-workflow.test.ts holds the workflows to
- * this list, and publish.yml's release proof to the same list. */
 export const REQUIRED_PR_CHECKS = [
-    // The unit suite on Node 24 (ci.yml "test-shard" and "test"), on every pull request.
     "node 24 · ubuntu-latest",
-    // The area lanes (ci.yml), on every pull request except a documentation-only one (scripts/ci-scope.mjs), where they
-    // are skipped; a release's pull request runs them.
     "linux native containment · delegated cgroup v2",
     "linux fence · sandbox-runtime",
     "Windows Job Object containment",
-    // The git lanes (ci.yml job "git"): the declared floor (git-floor.ts) and Debian trixie's 2.47.
     "git 2.41 · debian trixie",
     "git 2.47 · debian trixie",
-    // The unit suite on macOS (ci.yml jobs "macos-shard" and "macos"; pipeline-speed.md, item 3a), Node 24.
     "node 24 · macos-latest",
-    // Node 22, the engines floor, on Linux and macOS (release-candidate.yml): on a release-* branch's pull request,
-    // skipped on every other pull request.
     "node 22 · ubuntu-latest",
     "node 22 · macos-latest",
 ];
-/** The workflow file each REQUIRED_PR_CHECKS job belongs to: a job of that name from any other workflow (a lookalike
- * added beside it) never stands for it (Codex review round 1, inherited CI limitation). */
 export const REQUIRED_PR_CHECKS_WORKFLOW = {
     "node 24 · ubuntu-latest": ".github/workflows/ci.yml",
     "linux native containment · delegated cgroup v2": ".github/workflows/ci.yml",
@@ -72,76 +26,44 @@ export const REQUIRED_PR_CHECKS_WORKFLOW = {
     "node 22 · ubuntu-latest": ".github/workflows/release-candidate.yml",
     "node 22 · macos-latest": ".github/workflows/release-candidate.yml",
 };
-/**
- * The pull-request checks main's GitHub protection is not yet required to name (eval-harness review 2, finding 1).
- * Empty since the test matrix (docs/plans/test-matrix.md): publication's release proof trusts what main's protection
- * required at the merge, so main's protection must name every REQUIRED_PR_CHECKS check, and a release refuses to merge
- * (and so to publish) until it does.
- */
 export const PROTECTION_REPORT_ONLY_CHECKS = [];
-/** The checks main's protection must require at minimum: every required check that isn't report-only. */
 export const PROTECTION_MINIMUM_CHECKS = REQUIRED_PR_CHECKS.filter(name => !PROTECTION_REPORT_ONLY_CHECKS.includes(name));
-/**
- * Pull-request checks a release never waits for or fails on, by exact name and the workflow file that defines them:
- * youiyoux's UI drift check (src/design/KIT.md), which fails a pull request that adds design drift but says nothing
- * about whether a build is safe to release, and the scripted journeys on a pull request (journeys.yml,
- * docs/plans/ci-speed.md item 4), advisory while they settle in CI: the release check runs every journey itself. Only a
- * GitHub Actions run of that name from that workflow is left out; the same name from anywhere else is judged like any
- * other check. Never a required check.
- */
 export const ADVISORY_PR_CHECKS = {
     "youiyoux · UI drift": ".github/workflows/youiyoux.yml",
     "journeys · app (scripted)": ".github/workflows/journeys.yml",
     "journeys · flows (scripted)": ".github/workflows/journeys.yml",
     "upgrade path · scope": ".github/workflows/upgrade-path.yml",
     "upgrade path": ".github/workflows/upgrade-path.yml",
+    "install smoke · ubuntu-24.04": ".github/workflows/install-smoke.yml",
+    "install smoke · macos-latest": ".github/workflows/install-smoke.yml",
 };
-/** The checks a release's publication waits for on its tag (.github/workflows/publish.yml, docs/plans/test-matrix.md):
- * the release proof (the tagged tree passed every REQUIRED_PR_CHECKS check on its pull request, read from GitHub) and
- * the publish job that needs it. The tag runs no tests again. Nothing else reported on the merge commit (main-push.yml)
- * holds publication. */
 export const RELEASE_TAG_CHECKS = ["release proof", "publish"];
 export const RELEASE_TAG_WORKFLOW = ".github/workflows/publish.yml";
 export const RELEASE_STEPS = ["gate", "approval", "check", "complete", "quiet", "deploy", "link", "ci", "merge", "tree", "tag", "publish", "homebrew", "done"];
-/** How long each waiting step may take, in minutes, before the release stops there (rerunning continues from it). The
- * check's covers the first attempt and the two same-commit reruns the plane may give it, each of which a busy machine
- * may stretch to two hours (check-load.ts). */
 export const RELEASE_LIMITS = { gate: 60, approval: 24 * 60, check: 360, quiet: 60, deploy: 30, ci: 60, publish: 45, homebrew: 45 };
 const POLL_MS = 15_000;
-/**
- * Failure classes replace a flat flake allowance (docs/plans/eval-harness.md; check-failure.ts says the classes): only a
- * failure the plane itself confirmed as infrastructure is ever run again under the same approval — at most once per
- * incident and twice per candidate — for a release check and for a GitHub CI job alike. A failing test, a typecheck, an
- * attack test, a migration: none tolerated. An unexplained failure blocks, and a person decides.
- */
 export const INFRA_RERUNS_PER_INCIDENT = 1;
 export const INFRA_RERUNS_PER_CANDIDATE = 2;
-/** A stop the release reports: the step it stopped at and why, in words. */
 class Stop extends Error {
     reason;
     build;
-    /** `build`: the release build itself failed before its check (not a failed check). */
     constructor(reason, message, build = false) {
         super(message);
         this.reason = reason;
         this.build = build;
     }
 }
-/** The tap change's checks failed: Homebrew's own state, never a stop of a published release. */
 class HomebrewFailed extends Error {
 }
-/** The branch moved before the deploy reservation: carry the approval to the new head, or file it for a person. */
 class Restart extends Error {
     head;
     updated;
-    /** `updated`: Toolroll itself brought the branch up to main; the new commit is a new candidate and nothing carries. */
     constructor(head, updated = false) {
         super(`restart at ${head}`);
         this.head = head;
         this.updated = updated;
     }
 }
-/** Every commit that landed after the approval, in words: the summary and the merge message list them all. */
 export function landedWords(landed) {
     if (landed.length === 0)
         return [];
@@ -151,7 +73,6 @@ export function landedWords(landed) {
 const branchFile = (branch) => branch.replace(/[^A-Za-z0-9._-]+/g, "_");
 export const journalFile = (stateDir, branch) => join(stateDir, "releases", `${branchFile(branch)}.json`);
 export const resumeCommand = (branch, checkout) => `toolroll release ${releaseBranchArg(branch)} --repo ${checkout}`;
-/** Whole or not at all: a private temp file, synced, renamed into place, its folder synced. */
 export function writeJournal(file, journal) {
     mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
     const temp = `${file}.${randomUUID()}.tmp`;
@@ -182,10 +103,7 @@ export function readJournal(file) {
         throw new Error(`${file} is not a release journal this version reads`);
     return parsed;
 }
-/** The release task's id: one per exact commit, so a rerun finds the task it filed instead of filing another. */
 export const gateTaskId = (version, sha) => `release-${version.replace(/[^0-9A-Za-z.-]/g, "-")}-${sha.slice(0, 7)}`;
-/** Whether the scope's approval is the owner's own yes to these exact bytes: a person through the password (or
- * identity) ceremony or a chat confirmation — never a mode's coverage, an AI teammate, a routine or the lead. */
 export function ownerApproval(gate, digest) {
     const approval = gate.approval;
     if (approval === null)
@@ -200,8 +118,6 @@ export function ownerApproval(gate, digest) {
         return { ok: false, why: `approved as ${approval.by}, not by a person` };
     if (approval.role !== "approver" || !approval.active)
         return { ok: false, why: `approved by ${approval.by}, who is not an active approver` };
-    // A person's proof, recorded for these exact bytes (approval policy §1.5): a lead token or a remote API token sealed
-    // through the person's road before the fix said `password` too. A plane that can't say is not a yes.
     if (approval.person === undefined)
         return { ok: false, why: "the plane can't show a person gave this approval; update it first" };
     if (!approval.person.ok)
@@ -210,10 +126,8 @@ export function ownerApproval(gate, digest) {
         return { ok: false, why: "approved with a machine credential, not by a person" };
     return { ok: true, by: approval.by, at: approval.at };
 }
-/** Every required check present, and every reported check's newest attempt completed successfully. */
 export function checksVerdict(runs, required) {
     const failed = [], waiting = [];
-    // The adapter orders attempts oldest first, so the last attempt for each name is authoritative.
     const latest = new Map(runs.map(run => [run.name, run]));
     for (const name of new Set([...required, ...latest.keys()])) {
         const run = latest.get(name);
@@ -228,19 +142,10 @@ export function checksVerdict(runs, required) {
         return { state: "failed", failed };
     return waiting.length > 0 ? { state: "pending", waiting } : { state: "passed" };
 }
-/**
- * Publication's verdict on the tag commit (test-matrix.md): only RELEASE_TAG_CHECKS, from GitHub Actions runs of
- * publish.yml bound to the tag's push, each by its newest attempt. Every other check on the merge commit — main's own
- * push run — is not waited for: the candidate's checks already passed on its exact head before the merge, the merged
- * tree was proved equal to it, and publish.yml's release proof checks both again from GitHub's record.
- */
 export function tagChecksVerdict(runs) {
     const names = RELEASE_TAG_CHECKS;
-    // Only GitHub Actions runs of publish.yml bound to the tag's own push (release-adapters.ts readCheckRuns): a check of
-    // the same name from another workflow, an unbound run or another app is never counted (security scan).
     return checksVerdict(runs.filter(run => names.includes(run.name) && run.app === "github-actions" && workflowIs(run.workflowPath, RELEASE_TAG_WORKFLOW)), RELEASE_TAG_CHECKS);
 }
-/** Run the release from wherever its journal stopped. */
 export async function runRelease(options, adapters) {
     const file = journalFile(options.stateDir, options.branch);
     const resume = resumeCommand(options.branch, options.checkout);
@@ -251,10 +156,8 @@ export async function runRelease(options, adapters) {
     let step = "preflight";
     let freshApproval = false;
     let supersededTask = null;
-    /** The commit whose check stopped the release being set aside. The stop tells a person to approve it again with --new. */
     let stoppedCheck = null;
     const save = () => { journal.updatedAt = adapters.now().toISOString(); writeJournal(file, journal); };
-    /** Tell the progress record about a step (v146). Never throws and never waits: the release goes on whatever it says. */
     const mark = (at, state, detail = null) => {
         const j = journal;
         if (j === null || adapters.progress === undefined || at === "done")
@@ -262,7 +165,7 @@ export async function runRelease(options, adapters) {
         try {
             adapters.progress({ taskId: j.task.id, tag: j.tag, version: j.packageVersion, pr: j.pr, step: at, state, at: adapters.now(), detail });
         }
-        catch { /* best effort */ }
+        catch { }
     };
     const advance = (next) => { const was = journal.step; journal.step = next; journal.stopped = null; save(); if (was !== next)
         mark(was, "done"); };
@@ -280,8 +183,6 @@ export async function runRelease(options, adapters) {
         delete j.intents.deploy;
         save();
     };
-    /** Ask `probe` until it answers, within this step's limit. A short network failure on the way to GitHub (git or gh
-     * timing out) is no answer yet, never the release's end: the next poll asks again, until the step's own limit. */
     const waitFor = async (at, what, probe) => {
         const deadline = adapters.now().getTime() + limits[at] * 60_000;
         let said = false, unreachable = null;
@@ -334,17 +235,11 @@ export async function runRelease(options, adapters) {
             say(`Released ${journal.tag} (${journal.candidate.sha.slice(0, 7)}) — nothing left to do.`);
             return { ok: true, journal, file };
         }
-        // Published, with Homebrew still to finish: this run finishes it, waiting for the tap's checks within its limit.
         const finishingHomebrew = journal !== null && journal.step === "homebrew" && journal.published !== null && options.fresh !== true;
         if (!await adapters.github.authenticated())
             throw new Stop("github-auth", "GitHub CLI is not signed in: run `gh auth login`, then rerun.");
         if (journal === null) {
             journal = await begin(options, adapters, adapters.now());
-            // The earlier attempt needs a person's fresh approval (a CI failure after its deploy): this one files a task of its
-            // own for the same commit, so the old approval can't carry it.
-            // A check that stopped this same commit is the same: its task keeps that failure, so reusing it would only stop again
-            // (a passing run on it, run 3333, can't erase it). A new task reruns the check and asks a person, never the plane.
-            // Only an id that has never existed, numbered after the superseded one: never a task whose approval still stands.
             if (freshApproval || journal.candidate.sha === stoppedCheck) {
                 const base = journal.task.id;
                 const suffix = supersededTask === null ? null : supersededTask === base ? 1 : supersededTask.startsWith(`${base}-`) ? Number(supersededTask.slice(base.length + 1)) : null;
@@ -365,13 +260,11 @@ export async function runRelease(options, adapters) {
         else
             say(`Resuming the release of ${journal.tag} (${journal.candidate.sha.slice(0, 7)}) at ${journal.step}.`);
         const j = journal;
-        // A journal an older coordinator filed ahead of CI: its deploy reads CI fresh too.
         if (j.ciAhead === true && j.ciBeforeDeploy !== true)
             j.ciBeforeDeploy = true;
         if (j.checkout !== options.checkout)
             throw new Stop("checkout", `This release runs in ${j.checkout}; rerun with --repo ${j.checkout}.`);
         save();
-        // Before anything merges, the branch and its pull request must still be the gated commit.
         const pinned = async () => {
             const head = await adapters.repo.remoteHead(j.branch);
             if (head !== j.candidate.sha)
@@ -381,14 +274,7 @@ export async function runRelease(options, adapters) {
                 throw new Stop("drift", `Pull request #${j.pr} no longer has ${j.candidate.sha.slice(0, 7)} at its head.`);
             return pr;
         };
-        // ---- Homebrew, finished apart from publication (pipeline-speed.md, P1) ------------------------------------------
         let homebrewLeft = null;
-        /**
-         * One look at the tap: propose the formula change when it's missing, judge its checks (once, or within the Homebrew
-         * limit when `wait`), and merge exactly the proposed head once every check passed. A tap that already names a newer
-         * version is never overwritten, checked again right before the merge. Checksums come from npm's own tarball
-         * (release-adapters.ts propose), unchanged.
-         */
         const homebrewPass = async (wait) => {
             const brew = adapters.homebrew;
             let state = await brew.state(j.packageVersion);
@@ -396,8 +282,6 @@ export async function runRelease(options, adapters) {
                 return { state: "superseded", why: `the tap already names ${state.version}` };
             if (state.kind === "current")
                 return { state: "current", why: null };
-            // A change this release already proposed is the only one it ever merges (security scan): another pull request for
-            // the same version, a moved head or a closed change is failed, never adopted or merged.
             const journaled = j.homebrew?.pr != null && j.homebrew.head != null ? { pr: j.homebrew.pr, head: j.homebrew.head } : null;
             if (journaled !== null && state.kind === "missing")
                 return { state: "failed", why: `${brew.repo} #${journaled.pr} was closed before it merged` };
@@ -412,13 +296,9 @@ export async function runRelease(options, adapters) {
             const proposed = state;
             j.homebrew = { pr: proposed.pr, head: proposed.head, merged: false, state: "pending", why: null };
             save();
-            // Whatever checks do register are always judged; an empty set passes only for a tap whose workflows never run
-            // on a change, and only when it's still empty a poll later.
             const checked = await brew.checked(proposed.head);
             let emptyLooks = 0;
             const probe = async () => {
-                // Check runs and commit statuses are judged apart, so neither stands in for the other or hides its failure.
-                // Two apps may name a check alike; each app's attempts stand for themselves.
                 const runs = (await adapters.github.checks(brew.repo, proposed.head)).map(run => ({ ...run, name: `${run.app ?? "unknown app"}: ${run.name}` }));
                 const statuses = await brew.statuses(proposed.head);
                 const verdicts = [runs, statuses].filter(one => one.length > 0).map(one => checksVerdict(one, [...new Set(one.map(run => run.name))]));
@@ -427,8 +307,6 @@ export async function runRelease(options, adapters) {
                     throw new HomebrewFailed(`the tap change's checks failed: ${failed.join(", ")}`);
                 if (verdicts.some(one => one.state === "pending"))
                     return null;
-                // GitHub registers checks asynchronously; an empty set says nothing about success.
-                // A workflow is owed: only its own run counts, not another app's green check.
                 if (checked && !runs.some(run => run.app === "github-actions"))
                     return null;
                 if (runs.length === 0 && statuses.length === 0)
@@ -443,12 +321,10 @@ export async function runRelease(options, adapters) {
             catch (error) {
                 if (error instanceof HomebrewFailed)
                     return { state: "failed", why: `${brew.repo} #${proposed.pr}: ${error.message}` };
-                // Waiting ran out: still pending, never a stop of a published release.
                 if (error instanceof Stop && error.reason === "timeout")
                     return { state: "pending", why: error.message };
                 throw error;
             }
-            // Ordering, once more right before the merge: a newer formula landed meanwhile is never overwritten.
             const now = await brew.state(j.packageVersion);
             if (now.kind === "newer")
                 return { state: "superseded", why: `the tap already names ${now.version}` };
@@ -464,15 +340,12 @@ export async function runRelease(options, adapters) {
             await brew.merge(proposed.pr, proposed.head);
             return { state: "current", why: null };
         };
-        // ---- one approval per release (release-once.md) -------------------------------------------------------------
         const rel = adapters.release;
-        /** One-tap release approval: tell the plane, never stopping or changing the release whatever it answers. */
         const tell = async (act) => { if (rel?.ready === undefined)
             return; try {
             await act(rel.ready);
         }
-        catch { /* best effort */ } };
-        /** The last pull request checks this run read on the candidate (the gate reads them before the task exists). */
+        catch { } };
         let lastCi = null;
         const noteCi = async (runs, verdict) => {
             lastCi = { candidate: j.candidate.sha, state: verdict.state === "pending" ? "running" : verdict.state, failed: verdict.failed ?? [], runs: runs.filter(run => REQUIRED_PR_CHECKS.includes(run.name)) };
@@ -481,9 +354,7 @@ export async function runRelease(options, adapters) {
         };
         const currentCi = () => lastCi;
         let epoch = null;
-        // This invocation's own lease owner (review round 1): two runs of the same journal never share an epoch.
         const owner = `${j.id}:${randomUUID()}`;
-        /** Take the release's lease (a takeover raises its epoch), then settle every operation still open before any new work. */
         const hold = async () => {
             if (rel === undefined || !j.authority)
                 return;
@@ -497,11 +368,8 @@ export async function runRelease(options, adapters) {
             if (rel === undefined || !j.authority)
                 return;
             for (const op of (await rel.operations(j.authority.id)).filter(one => one.state === "reserved" || one.state === "running" || one.state === "unknown")) {
-                // A started call whose issuer may still be alive may still land (review round 2): nothing is settled for it on
-                // elapsed time. It stays as it is, and a person looks.
                 const inFlight = () => new Stop("operation-in-flight", `An earlier ${op.kind} (operation ${op.id}) was started by a process that may still be running. Nothing was settled: check that process, then rerun.`);
                 if (op.kind === "deploy") {
-                    // Reserved and never started: nothing to undo (a start after this takeover is refused: its epoch moved).
                     if (op.state === "reserved") {
                         await rel.finish(op.id, "failed", { detail: "the call never started" }, epoch);
                         continue;
@@ -513,7 +381,6 @@ export async function runRelease(options, adapters) {
                     if (!op.issuerGone)
                         throw inFlight();
                     if (op.direct) {
-                        // A person's own deploy: its process is gone; its lock, update pause and journal must say nothing is half done.
                         if (!await adapters.toolroll.deploymentIdle(op.stage))
                             throw new Stop("deploy-recovery", `A person's deploy of this release (operation ${op.id}) ended without finishing${op.stage === null ? "" : `; its journal is in ${op.stage}`}. Recover it, then rerun.`);
                         await rel.finish(op.id, "failed", { detail: "reconciled: the deploy's process ended, and nothing is deployed or half done" }, epoch);
@@ -523,7 +390,6 @@ export async function runRelease(options, adapters) {
                     await rel.finish(op.id, "failed", { detail: "reconciled: recovered the previous build" }, epoch);
                 }
                 else {
-                    // The pull request decides an unknown merge: merged from the gated head is a success, whoever issued it.
                     const pr = await adapters.github.pullRequest(j.github, j.branch);
                     if (pr?.state === "merged" && pr.number === j.pr && pr.head === op.candidate && pr.mergeCommit !== null)
                         await rel.finish(op.id, "succeeded", { externalRef: pr.mergeCommit, detail: "reconciled: the pull request is merged from the gated head" }, epoch);
@@ -538,11 +404,6 @@ export async function runRelease(options, adapters) {
                 }
             }
         };
-        /**
-         * Who and what the release is, read again: the repository, the pull request (open, its number, base main) and its
-         * head, and the live-release predicate for the coming action. Before the deploy reservation a moved head restarts
-         * the release for the new commit; after it, it stops, and the new commit needs a person.
-         */
         const identity = async (action, beforeReservation) => {
             if (rel === undefined) {
                 await pinned();
@@ -563,27 +424,17 @@ export async function runRelease(options, adapters) {
             }
             if (j.authority) {
                 const live = await rel.live(j.task.id, action);
-                // Fail closed: once the release has an authority, its task must be one the predicate applies to AND accepts.
                 if (!live.applies || !live.ok)
                     throw new Stop("release", `Task ${j.task.id} can't ${action === "dispatch" ? "go on" : action}: ${live.applies ? live.why ?? "its release approval doesn't stand" : "it belongs to no release approval this plane can find"}.`);
                 if (epoch !== null && !await rel.renew(j.authority.id, owner, epoch))
                     throw new Stop("lease", "Another release coordinator took over this release.");
             }
         };
-        /** The head moved before the deploy reservation: carry the approval to it, or file it for a person. Nothing kept from
-         * the old step is used afterwards: the journal is rewritten and the state machine runs again. */
-        /**
-         * A pull request check failed after the deploy reservation (Alex, 2026-10-25): the candidate froze at deploy, so the
-         * release needs a person's fresh approval, even for the same commit. It is persisted (the authority stops; the
-         * journal says so) before the release stops; `--new` files the commit for a person again.
-         */
         const ciFailedAfterDeploy = async (what, deploy = "after") => {
             j.needsApproval = true;
             save();
-            // An automatic approval never outlives a CI failure: the owner is told, and a person approves again.
             if (j.auto?.state === "approved")
                 await rel?.auto?.giveUp(j.task.id, deploy === "after" ? `${what}, after the deploy` : what);
-            // Fail closed: the authority must have stopped; otherwise its approval could still carry the commit.
             if (rel !== undefined && j.authority && (epoch === null || !await rel.needsApproval(j.authority.id, deploy === "after" ? "a pull request check failed after the deploy" : "a pull request check failed before the deploy", epoch))) {
                 throw new Stop("lease", `${what}. Nothing was merged, but this release's approval couldn't be stopped (another coordinator holds it, or a merge is reserved). Check it with \`toolroll release ${j.branch} --repo ${j.checkout}\` before going on.`);
             }
@@ -591,16 +442,7 @@ export async function runRelease(options, adapters) {
                 ? `${what}. Nothing was merged. The deploy had already started, so this commit needs a person's approval again: run \`toolroll release ${j.branch} --repo ${j.checkout} --new\`.`
                 : `${what}. Nothing was deployed or merged. This commit needs a person's approval: run \`toolroll release ${j.branch} --repo ${j.checkout} --new\`.`);
         };
-        /** An automatic approval's CI allowance: only attempts GitHub shows failing before the tests ran, at most
-         * INFRA_RERUNS_PER_CANDIDATE on the commit; a person's approval judges each job by its latest attempt. */
         const autoCap = () => (j.auto?.state === "approved" ? { auto: true } : {});
-        /**
-         * An automatically approved release stands only while its CI does (auto-approve-green.md): the complete, current
-         * checks on the exact commit are read again right before each step that can't be taken back — the deploy, the CLI
-         * relink, the merge and the tag. Anything but green (failed, a job re-run and pending, an earlier failure GitHub
-         * doesn't show as the runner's own) stops the
-         * release, revokes its approval and tells the owner; the commit then needs a person.
-         */
         const autoCiHolds = async (before) => {
             if (j.auto?.state !== "approved")
                 return;
@@ -612,7 +454,6 @@ export async function runRelease(options, adapters) {
                 return;
             }
             if (before === "the tag") {
-                // Already merged: nothing to revoke. It isn't tagged or published, and a person decides — durably, in the plane.
                 const why = `Pull request checks on ${j.candidate.sha.slice(0, 7)} stopped passing after the merge`;
                 await rel?.auto?.holdPublish(j.task.id, why);
                 await rel?.auto?.giveUp(j.task.id, why);
@@ -620,13 +461,11 @@ export async function runRelease(options, adapters) {
             }
             await ciFailedAfterDeploy(`Pull request checks on ${j.candidate.sha.slice(0, 7)} are no longer all passing before ${before}: ${(verdict.state === "failed" ? verdict.failed : verdict.waiting).join(", ")}`, before === "the deploy" && j.deploy === null ? "before" : "after");
         };
-        /** A publication held for a person (the plane's record) stops the tag, the publication and Homebrew. */
         const publishHold = async () => {
             const held = rel?.auto === undefined ? null : await rel.auto.publishHeld(j.task.id);
             if (held !== null)
                 throw new Stop("approval", `${held}. It was merged; nothing more is tagged, published or sent to Homebrew until a person lets it go on: \`toolroll release publish-ok ${j.task.id} --as <you> --token <password>\`, then rerun.`);
         };
-        /** GitHub's nightly lane debt before a deploy, the merge or the tag (evals-nightly.md, part A2). */
         const nightlyHolds = async (phase) => {
             if (rel?.nightly === undefined)
                 return;
@@ -636,14 +475,8 @@ export async function runRelease(options, adapters) {
             if (!answer.ok)
                 throw new Stop("nightly-debt", `${answer.why} Nothing was ${phase === "deploy" ? "deployed" : phase === "merge" ? "merged" : "tagged or published"}; rerun the release once it passes.`);
         };
-        /** identity(), on a plane that keeps release authority; a legacy plane keeps the old rules. */
         const watch = async (action) => { if (rel !== undefined)
             await identity(action, true); };
-        /**
-         * Behind main (plain-toolroll.md P2.6): update the branch under this release's lease and the head it was gated on.
-         * A concurrent push aborts it. The approval stops first, so nothing can ride it across the update; the updated head
-         * is a new candidate with a new approval, fresh CI and a fresh check, and there is no carry.
-         */
         const updateFromMain = async () => {
             const update = adapters.github.updateBranch;
             if (update === undefined)
@@ -667,10 +500,6 @@ export async function runRelease(options, adapters) {
                 return head !== null && head !== j.candidate.sha ? head : null;
             });
         };
-        /**
-         * Move the release back to an earlier step: write the fields the caller names (and only those), drop the named steps'
-         * intents, set the step, and save the journal. Every step-back goes through here.
-         */
         const rewindTo = (step, fields, dropIntents = []) => {
             Object.assign(j, fields);
             for (const one of dropIntents)
@@ -679,7 +508,6 @@ export async function runRelease(options, adapters) {
             save();
         };
         const restart = async (head, updated = false) => {
-            // The step this commit was at ends here: the release goes on with the new commit (and, filed again, a new task).
             mark(j.step, "failed", `${j.branch} moved to ${head.slice(0, 7)}`);
             const tree = await adapters.repo.tree(head);
             if (updated)
@@ -689,7 +517,6 @@ export async function runRelease(options, adapters) {
                 const carried = await rel.carry(j.authority.id, head, randomUUID(), epoch);
                 if (carried.ok) {
                     const view = await rel.authority(carried.taskId);
-                    // The candidate is written before the gate is read, as it always was: a gate that fails leaves it moved.
                     j.candidate = { sha: head, tree };
                     const task = { id: carried.taskId, scopeDigest: (await adapters.toolroll.gate(carried.taskId)).scopeDigest };
                     rewindTo("check", { task, check: null, completion: null, landed: view?.landed ?? j.landed ?? [], stopped: null }, ["check", "complete"]);
@@ -704,19 +531,11 @@ export async function runRelease(options, adapters) {
             rewindTo("gate", { candidate: { sha: head, tree }, task: { id: gateTaskId(j.packageVersion, head), scopeDigest: null },
                 approval: null, check: null, completion: null, authority: null, auto: null, stopped: null }, ["gate", "check", "complete"]);
         };
-        /**
-         * The automatic road ended without an approval: the plane takes its `auto-check` back (the task asks a person, its
-         * passing check kept) and tells the owner; the release waits at approval for a person, as without the setting.
-         */
         const autoRefused = async (why) => {
             rewindTo("approval", { auto: { state: "refused", why }, check: null });
             await rel?.auto?.giveUp(j.task.id, why);
             throw new Stop("approval", `Not approved automatically: ${why}. A person approves task ${j.task.id} (\`toolroll task approve ${j.task.id} --digest ${j.task.scopeDigest}\`, or the console), then rerun \`${resume}\`.`);
         };
-        /**
-         * CI passed on the candidate as the coordinator read it: the plane reads it itself and lifts the approval hold it
-         * placed when the task was filed ahead of CI (round 1, finding 4). A refusal stops here; nobody was asked.
-         */
         const liftCiHold = async (ask, nothing) => {
             const lift = rel?.auto?.ciPassed;
             if (lift === undefined)
@@ -725,11 +544,6 @@ export async function runRelease(options, adapters) {
             if (!lifted.ok)
                 throw new Stop("ci-failed", `The plane didn't confirm CI passed on ${j.candidate.sha.slice(0, 7)}: ${lifted.why}. ${nothing}. Rerun \`${resume}\` once every pull request check passes.`);
         };
-        /**
-         * One look at the pull request's required checks on the exact commit while CI may still run: a failed check stops
-         * (`nothing` says what hasn't happened), passed ends the plane's "CI still running" note, pending (or GitHub not
-         * answering) answers false. Judged as the ci step judges a person's release (prChecksVerdict, ci.yml, exact head).
-         */
         const ciWhileRunning = async (nothing, ask) => {
             let runs;
             try {
@@ -747,8 +561,6 @@ export async function runRelease(options, adapters) {
             }
             if (verdict.state !== "passed")
                 return false;
-            // The plane's note can survive a crash before the journal saved ciAhead. Clear it on the plane's own reading,
-            // even on an older/resumed journal whose flags say nothing about CI.
             await liftCiHold(ask, nothing);
             if (j.ciAhead === true) {
                 j.ciAhead = false;
@@ -756,8 +568,6 @@ export async function runRelease(options, adapters) {
             }
             return true;
         };
-        /** Every person's release reads exact-head CI at deployment, even if it was green at the gate or an older
-         * journal has no ciBeforeDeploy flag. An approval and the release check can outlive that earlier green reading. */
         const personCiBeforeDeploy = async () => {
             if (j.auto?.state === "approved")
                 return;
@@ -773,15 +583,9 @@ export async function runRelease(options, adapters) {
                 return null;
             });
         };
-        /**
-         * The task is approved for `action`: a release task (a carried commit, or any task once the release has an
-         * authority) only when the live-release predicate applies to it AND accepts it — fail closed, whatever its own seal
-         * says. Anything else needs the owner's own approval of these exact words (which a carried seal never is).
-         */
         const approved = async (gate, action = "dispatch") => {
             if (gate.candidate !== j.candidate.sha || gate.scopeDigest !== j.task.scopeDigest)
                 throw new Stop("scope-changed", `Task ${j.task.id}'s candidate or scope changed after approval.`);
-            // Checking automatically: the plane's `auto-check` seal must still stand (the setting on, its evidence, this digest).
             if (j.auto?.state === "checking" && !j.authority) {
                 const standing = rel?.auto === undefined ? { ok: false, why: "this plane can't approve releases automatically" } : await rel.auto.checking(j.task.id);
                 if (standing.ok)
@@ -804,7 +608,6 @@ export async function runRelease(options, adapters) {
             if (gate.result.check !== "passed")
                 throw new Stop("check-failed", checkFailedWords({ sha: j.candidate.sha, run: gate.result.run, class: null, why: `its check reads ${gate.result.check}`, branch: j.branch, checkout: j.checkout, taskId: j.task.id }));
         };
-        /** The commit the passing build recorded: what the deployed runtime is stamped with. */
         const builtHead = () => j.check?.head ?? j.candidate.sha;
         const checked = async (gate, action = "dispatch") => {
             await approved(gate, action);
@@ -814,7 +617,6 @@ export async function runRelease(options, adapters) {
         };
         if (j.needsApproval === true)
             throw new Stop("ci-failed", `A pull request check failed after the deploy, so ${j.candidate.sha.slice(0, 7)} needs a person's approval again: run \`toolroll release ${j.branch} --repo ${j.checkout} --new\`.`);
-        // A resumed release that already has an authority takes its lease and settles every open operation first.
         await hold();
         while (j.step !== "done" && homebrewLeft === null) {
             step = j.step;
@@ -824,8 +626,6 @@ export async function runRelease(options, adapters) {
                 switch (j.step) {
                     case "gate": {
                         await pinned();
-                        // The same commit's earlier gate belongs to a release that no longer stands (a CI failure after its deploy, a
-                        // revoke): a fresh task asks a person again, and their yes opens a new generation.
                         if (rel !== undefined && j.freshTask !== true) {
                             const base = gateTaskId(j.packageVersion, j.candidate.sha);
                             for (let n = 1; n < 50; n++) {
@@ -840,8 +640,6 @@ export async function runRelease(options, adapters) {
                                 }
                             }
                         }
-                        // The tree CI tested (the pull request's head, not GitHub's merge commit) is the tree that merges only when the
-                        // branch already contains main's head: refused here, before anything is filed, and again right before merging.
                         try {
                             await containsMain(adapters, j, "Nothing was filed or sent for approval");
                         }
@@ -856,21 +654,15 @@ export async function runRelease(options, adapters) {
                         if (j.intents.gate === undefined)
                             await mainProtection(adapters, j, false, "Nothing was filed or sent for approval");
                         const existing = await adapters.toolroll.gate(j.task.id);
-                        // A fresh task this journal never filed has appeared under its id: it isn't ours, and isn't a fresh approval.
                         if (existing.exists && j.freshTask === true && j.intents.gate === undefined)
                             throw new Stop("approval", `Task ${j.task.id} appeared before this release filed it; rerun with --new.`);
                         if (existing.exists) {
-                            // Filed already (a resume after a lost answer): the task stands, and the ci step judges its checks.
                             if (existing.candidate !== j.candidate.sha)
                                 throw new Stop("conflict", `Task ${j.task.id} exists for a different commit (${existing.candidate?.slice(0, 7) ?? "none"}).`);
                             j.task.scopeDigest = existing.scopeDigest;
                         }
                         else {
-                            // The gate only stops on a check that already failed: the task is filed and a person asked while CI runs, and
-                            // the release check runs beside it (pipeline-speed.md, D2 and "Decision: a person's release asks during
-                            // CI"). The automatic approval waits for CI (the check step); nothing deploys before it passes (the deploy).
                             const settled = await earlyChecks(adapters, j, (what, probe) => waitFor("gate", what, probe), { pendingIsEnough: true, seen: (runs, verdict) => noteCi(runs, verdict) });
-                            // Recorded before the task exists, so its approval card says CI still runs from the first moment.
                             if (!settled)
                                 await rel?.auto?.ciRunning?.(j.task.id, j.candidate.sha);
                             j.ciAhead = !settled;
@@ -889,7 +681,6 @@ export async function runRelease(options, adapters) {
                                 ...(rel === undefined ? {} : { release: { version: j.packageVersion, pr: j.pr, branch: j.branch, noCarry: options.noCarry === true } }),
                             });
                             j.task.scopeDigest = filed.scopeDigest;
-                            // The checks the gate read before the task existed, kept for its approval sheet now that it does.
                             const seen = currentCi();
                             if (seen !== null)
                                 await tell(ready => ready.ci({ taskId: j.task.id, ...seen }));
@@ -898,9 +689,6 @@ export async function runRelease(options, adapters) {
                         break;
                     }
                     case "approval": {
-                        // Approve automatically when checks pass (auto-approve-green.md): with the project's setting on, the plane seals
-                        // `auto-check` so the release check runs first; the approval itself is sealed after it passed. A fresh task
-                        // after a CI failure after the deploy, or an automatic refusal, always asks a person.
                         const auto = rel?.auto;
                         if (auto !== undefined && j.freshTask !== true && j.auto?.state !== "refused" && j.task.scopeDigest !== null && await auto.setting(j.task.id)) {
                             await watch("dispatch");
@@ -921,12 +709,8 @@ export async function runRelease(options, adapters) {
                                 say(`  Not approved automatically: ${authorized.why}. A person approves it.`);
                             }
                         }
-                        // Filed while CI still runs: the person is asked now (Alex, 2026-10-29), and told nothing deploys until CI passes.
-                        // A check that already failed asks nobody (as at the gate).
                         if (j.ciAhead === true)
                             await ciWhileRunning("Nothing was deployed or merged", true);
-                        // One push, on every entry to this step (a fresh filing or a resumed one): the plane files it once per task and
-                        // scope digest, so a crash between filing and here is healed by the next run.
                         await tell(ready => ready.asked(j.task.id));
                         say(`  The release scope needs your approval: \`toolroll task approve ${j.task.id} --digest ${j.task.scopeDigest}\`, or open the task in the console.`);
                         say(`  Or approve it from here: \`toolroll release approve ${releaseBranchArg(j.branch)}\`.`);
@@ -934,8 +718,6 @@ export async function runRelease(options, adapters) {
                             say(`  ${CI_RUNNING_WORDS}`);
                         const approved = await waitFor("approval", `a person to approve task ${j.task.id}`, async () => {
                             await watch("dispatch");
-                            // While asking: a check that failed stops here (nobody approves a red commit), and CI passing ends the card's
-                            // "still running" note (and lifts a hold an older coordinator placed).
                             if (j.ciAhead === true)
                                 await ciWhileRunning("Nothing was deployed or merged", true);
                             const gate = await adapters.toolroll.gate(j.task.id);
@@ -948,7 +730,6 @@ export async function runRelease(options, adapters) {
                         });
                         j.approval = { by: approved.by, at: approved.at };
                         say(`  approved by ${approved.by}`);
-                        // The person's yes to release terms opened the release's authority: hold its lease from here on.
                         if (rel !== undefined) {
                             const view = await rel.authority(j.task.id);
                             if (view !== null) {
@@ -964,15 +745,11 @@ export async function runRelease(options, adapters) {
                     }
                     case "check": {
                         const checkProbe = async () => {
-                            // Before acting on an old candidate's failure: a moved head restarts the release first.
                             await watch("dispatch");
                             const gate = await adapters.toolroll.gate(j.task.id);
                             await approved(gate);
-                            // A rerun of the same approved commit is on its way: the failure before it is not this release's answer.
                             if (gate.pending === true && gate.result?.check !== "passed")
                                 return null;
-                            // A failed Full check: the plane says why (its own records only) and reruns it under the same approval only
-                            // for confirmed infrastructure; every attempt stays in the evidence. Anything else stops, saying its class.
                             if (gate.failed === null && gate.result !== null && gate.result.level === "full" && gate.result.check === "failed" && rel?.recheck !== undefined) {
                                 const answer = await rel.recheck(j.task.id);
                                 if (answer.action === "pending")
@@ -987,8 +764,6 @@ export async function runRelease(options, adapters) {
                                 throw new Stop("check-failed", `The release build of ${j.task.id} failed: ${gate.failed}. Fix it and release the new commit with --new.`, true);
                             if (gate.result === null || gate.result.check === "running" || gate.result.check === "pending")
                                 return null;
-                            // The build records a prepared candidate as a commit of its own (its message names the task): it must hold
-                            // exactly the candidate's tree, or it isn't the release.
                             const head = gate.result.head;
                             if (head === null || (head !== j.candidate.sha && await adapters.repo.tree(head) !== await adapters.repo.tree(j.candidate.sha))) {
                                 throw new Stop("drift", `The release result is for ${head?.slice(0, 7) ?? "no commit"}, which doesn't hold exactly ${j.candidate.sha.slice(0, 7)}'s files.`);
@@ -996,8 +771,6 @@ export async function runRelease(options, adapters) {
                             fullCheck(gate);
                             if (gate.result.worktree === null)
                                 throw new Stop("worktree", `Run ${gate.result.run} names no checkout to deploy from.`);
-                            // A pass stands only when no earlier attempt on this commit failed for a reason other than confirmed
-                            // infrastructure the release reran; what passed only on a retry is said (and an automatic approval refuses it).
                             if (rel?.standing !== undefined) {
                                 const standing = await rel.standing(j.task.id, gate.result.run);
                                 if (!standing.ok)
@@ -1007,8 +780,6 @@ export async function runRelease(options, adapters) {
                                 else if (standing.retried.length > 0)
                                     say(`  run ${gate.result.run} passed, but only on a retry: ${standing.retried.join(", ")}`);
                             }
-                            // A sandboxed Full check must show that what it skipped passed elsewhere (trusted-release-reports.md H3). The plane
-                            // answers at once for a check that ran unsandboxed, as Toolroll's own do: nothing there skips for this reason.
                             if (rel?.fencedCoverage !== undefined) {
                                 const covered = await rel.fencedCoverage(j.task.id, gate.result.run, j.candidate.sha);
                                 if (!covered.ok)
@@ -1023,8 +794,6 @@ export async function runRelease(options, adapters) {
                                 return await checkProbe();
                             }
                             catch (error) {
-                                // A failed check (or a changed candidate) ends the automatic road: the owner is told, and a person decides.
-                                // A failed check is told, and stays checkable again on the same commit (a flake); anything else ends the road.
                                 if (error instanceof Stop && j.auto?.state === "checking" && error.reason === "check-failed" && !error.build)
                                     await rel?.auto?.checkFailed(j.task.id, error.message.replace(/\.$/, ""));
                                 else if (error instanceof Stop && j.auto?.state === "checking" && error.reason !== "approval")
@@ -1035,8 +804,6 @@ export async function runRelease(options, adapters) {
                         j.check = result;
                         say(`  run ${result.run} passed on ${j.candidate.sha.slice(0, 7)}`);
                         if (j.auto?.state === "checking" && !j.authority) {
-                            // The check ran beside CI (the gate didn't wait): it waits for every pull request check now. A failure ends the
-                            // automatic road, and the person's road refuses it too (the approval step waits for CI first).
                             if (j.ciAhead === true) {
                                 try {
                                     await earlyChecks(adapters, j, (what, probe) => waitFor("gate", what, probe), { nothing: "Nothing was approved" });
@@ -1052,7 +819,6 @@ export async function runRelease(options, adapters) {
                                 j.ciAhead = false;
                                 save();
                             }
-                            // The release approval, sealed only now: the plane reads CI on the exact commit itself and proves the check.
                             const sealed = rel?.auto === undefined ? { ok: false, why: "this plane can't approve releases automatically" }
                                 : await rel.auto.approve({ taskId: j.task.id, digest: j.task.scopeDigest, candidate: j.candidate.sha, run: result.run, receipt: result.receipt });
                             if (!sealed.ok)
@@ -1080,8 +846,6 @@ export async function runRelease(options, adapters) {
                         await checked(gate, "complete");
                         if (gate.completion?.digest !== check.receipt) {
                             intend("complete");
-                            // Toolroll proves the check's build stopped by itself (stop-proof.ts) a short while after it finished: the
-                            // release waits for that, never for a person to confirm it.
                             const done = await waitFor("quiet", "Toolroll to make sure the release check stopped", async () => {
                                 const tried = await adapters.toolroll.complete(j.task.id, check.receipt);
                                 return !tried.ok && tried.reason === "stopping" ? null : tried;
@@ -1109,16 +873,12 @@ export async function runRelease(options, adapters) {
                         const check = j.check;
                         await recoverDeploy();
                         await checked(await adapters.toolroll.gate(j.task.id), "deploy");
-                        // A deployment that finished but whose answer was lost: the services already run a runtime of this commit.
                         let runtime = await served(adapters, builtHead());
-                        // Already running this candidate (a new generation after a CI failure, or a lost answer): the release still
-                        // reserves its deploy, so its merge has a deploy to stand on.
                         if (runtime !== null && rel !== undefined && j.authority && epoch !== null) {
                             const authority = await rel.authority(j.task.id);
                             if (authority !== null && authority.state === "open") {
                                 await personCiBeforeDeploy();
                                 await watch("deploy");
-                                // Every deploy reservation, whatever the journal saved: CI must still be green on the exact commit.
                                 await autoCiHolds("the deploy");
                                 await nightlyHolds("deploy");
                                 const reserved = await rel.reserve({ authority: j.authority.id, kind: "deploy", taskId: j.task.id, candidate: j.candidate.sha, epoch });
@@ -1130,13 +890,9 @@ export async function runRelease(options, adapters) {
                             }
                         }
                         if (runtime === null) {
-                            // The last moment a moved head restarts; then the deploy reservation freezes the candidate in the store.
-                            // A person's release: every required check passed on the exact commit, read now (the approval may have come
-                            // while CI ran). A check that failed stops here, before anything is deployed.
                             await personCiBeforeDeploy();
                             await watch("deploy");
                             await pinned();
-                            // Every deploy issued, whatever the journal saved (a retry after a rollback included): CI still green.
                             await autoCiHolds("the deploy");
                             await nightlyHolds("deploy");
                             let operation, secret = "";
@@ -1151,8 +907,6 @@ export async function runRelease(options, adapters) {
                             }
                             j.deployAttempt = { stage: join(options.stateDir, "staged-upgrades", `browser-${j.candidate.sha.slice(0, 7)}-${randomUUID()}`) };
                             intend("deploy");
-                            // The issuing fence, immediately before the deploy is spawned (review round 2): lease, epoch and the live
-                            // release again, in one transaction that marks the operation as issued by this process.
                             if (operation !== undefined && !await rel.start(operation, epoch))
                                 throw new Stop("lease", "Another release coordinator took over this release; the deploy didn't start.");
                             const result = await adapters.toolroll.deploy({ run: check.run, worktree: check.worktree, stage: j.deployAttempt.stage, ...(operation === undefined ? {} : { operation: { id: operation, secret } }) });
@@ -1163,7 +917,6 @@ export async function runRelease(options, adapters) {
                             if (!/[\\/]dist$/.test(result.runtime))
                                 throw new Stop("deploy", `The deployment named ${result.runtime} as its runtime, which is not a dist folder.`);
                             runtime = result.runtime;
-                            // Saved at once: everything after this (relinking, a rerun) uses the runtime the deployer named.
                             j.deploy = { runtime, at: adapters.now().toISOString() };
                             save();
                         }
@@ -1220,11 +973,9 @@ export async function runRelease(options, adapters) {
                             j.merge = { sha: pr.mergeCommit, tree: null };
                         }
                         else {
-                            // After the deploy reservation a moved head, a changed pull request or a stopped release stops it here.
                             if (rel !== undefined && j.authority)
                                 await identity("merge", false);
                             await pinned();
-                            // A squash merge only reproduces the gated (and CI-tested) tree when main hasn't moved past the branch's base.
                             let main;
                             try {
                                 main = await containsMain(adapters, j, "Nothing was merged");
@@ -1232,7 +983,6 @@ export async function runRelease(options, adapters) {
                             catch (error) {
                                 if (!(error instanceof Stop) || error.reason !== "base-moved")
                                     throw error;
-                                // Past the deploy: the updated commit isn't what's running, so it starts over, with a person.
                                 const head = await updateFromMain();
                                 if (head === null)
                                     throw error;
@@ -1240,17 +990,11 @@ export async function runRelease(options, adapters) {
                                 save();
                                 throw new Stop("approval", `${j.branch} was behind main, so it's now at ${head.slice(0, 7)}. Nothing was merged. The new commit needs a person's approval: run \`toolroll release ${j.branch} --repo ${j.checkout} --new\`.`);
                             }
-                            // Every release merges only where GitHub itself refuses a branch behind main.
                             await mainProtection(adapters, j, j.auto?.state === "approved", "Nothing was merged");
-                            // The checks again, at the moment of merging: a rerun that failed since must not merge.
                             const verdict = prChecksVerdict(await adapters.github.checks(j.github, j.candidate.sha), j.candidate.sha, REQUIRED_PR_CHECKS, { ...autoCap(), workflow: REQUIRED_PR_CHECKS_WORKFLOW });
                             if (verdict.state !== "passed")
                                 await ciFailedAfterDeploy(`Pull request checks are no longer all passing on ${j.candidate.sha.slice(0, 7)}`);
-                            // GitHub's nightly lane debt (a bounded read), before main's last read so it doesn't widen that window; the
-                            // reservation below checks the stored debt again in its own transaction.
                             await nightlyHolds("merge");
-                            // Main once more, from GitHub, the last thing before the merge is reserved: moved since the comparison, it
-                            // stops here (finding 4). GitHub's own up-to-date rule refuses the rest of the window.
                             const now = await adapters.github.mainHead(j.github);
                             if (now !== main)
                                 throw new Stop("base-moved", `The branch is behind main; update it and push. Main moved to ${now.slice(0, 7)} while ${j.branch} was being merged, so what merges wouldn't be the tree CI tested. Nothing was merged: release the updated commit with \`toolroll release ${j.branch} --repo ${j.checkout} --new\`.`);
@@ -1265,7 +1009,6 @@ export async function runRelease(options, adapters) {
                             }
                             intend("merge");
                             const message = landedWords(j.landed ?? []).join("\n");
-                            // The issuing fence, immediately before gh is spawned (review round 2).
                             if (operation !== undefined && !await rel.start(operation, epoch))
                                 throw new Stop("lease", "Another release coordinator took over this release; the merge didn't start.");
                             let merged;
@@ -1282,7 +1025,6 @@ export async function runRelease(options, adapters) {
                             j.merge = { sha: merged, tree: null };
                         }
                         save();
-                        // This also runs after discovering a merge whose response was lost. Never delete a reused branch.
                         await adapters.repo.deleteBranch(j.branch, j.candidate.sha);
                         advance("tree");
                         break;
@@ -1294,7 +1036,6 @@ export async function runRelease(options, adapters) {
                         merge.tree = tree;
                         if (tree !== j.candidate.tree)
                             throw new Stop("tree-mismatch", `Main's merge commit ${merge.sha.slice(0, 7)} has tree ${tree.slice(0, 12)}, not the gated ${j.candidate.tree.slice(0, 12)}: main changed what was checked. Nothing was tagged; the deployed build stays as it is.`);
-                        // The release's verified record (trusted-release-reports.md A1): the next release's change list starts here.
                         await tell(ready => ready.verified({ taskId: j.task.id, merge: merge.sha }));
                         advance("tag");
                         break;
@@ -1335,9 +1076,6 @@ export async function runRelease(options, adapters) {
                     }
                     case "homebrew": {
                         await publishHold();
-                        // Homebrew is finished apart from publication (pipeline-speed.md, P1): npm and the GitHub release are verified,
-                        // so the release is published. This run proposes the tap's change and reads its checks once; only a run that
-                        // resumes to finish Homebrew waits for them. Pending or failed, the state is kept and the run ends published.
                         const progress = await homebrewPass(finishingHomebrew);
                         j.homebrew = { pr: j.homebrew?.pr ?? null, head: j.homebrew?.head ?? null, merged: progress.state === "current" && j.homebrew?.head != null ? true : j.homebrew?.merged ?? false, state: progress.state, why: progress.why };
                         save();
@@ -1362,12 +1100,11 @@ export async function runRelease(options, adapters) {
             say(`Released ${j.tag}: deployed, merged as ${j.merge.sha.slice(0, 7)}, tagged, published and ${j.homebrew?.state === "superseded" ? `left Homebrew as it is (${j.homebrew.why ?? "the tap names a newer version"})` : "on Homebrew"}.`);
         else
             say(`Published ${j.tag} (deployed, merged as ${j.merge.sha.slice(0, 7)}, tagged, on npm and GitHub); Homebrew ${left.state}${left.why === null ? "" : `: ${left.why}`}. Finish it with \`${resume}\`.`);
-        // The automatic road's note, once: when this run published (a run that only finishes Homebrew already said it).
         if (j.auto?.state === "approved" && !finishingHomebrew) {
             try {
                 await rel?.auto?.released(j.task.id, j.tag);
             }
-            catch { /* the release is done; the note is best effort */ }
+            catch { }
         }
         for (const line of landedWords(j.landed ?? []))
             say(line);
@@ -1380,21 +1117,19 @@ export async function runRelease(options, adapters) {
             try {
                 save();
             }
-            catch { /* the stop is still reported */ }
+            catch { }
             mark(journal.step, "failed", stop.message);
-            // A person's release that stops tells them (trusted-release-reports.md A5); the automatic road keeps its own notices.
             const ready = adapters.release?.ready;
             if (ready !== undefined && journal.auto?.state !== "checking" && journal.auto?.state !== "approved") {
                 try {
                     await ready.stopped({ taskId: journal.task.id, step: journal.step, reason: stop.reason, message: stop.message });
                 }
-                catch { /* best effort */ }
+                catch { }
             }
         }
         return { ok: false, reason: stop.reason, message: stop.message, step: journal?.step ?? step, journal, file, resume };
     }
 }
-/** The first run: everything checked before anything changes. */
 async function begin(options, adapters, now) {
     const { branch, checkout } = options;
     if (["main", "master"].includes(branch))
@@ -1437,13 +1172,11 @@ async function begin(options, adapters, now) {
         merge: null, tagged: null, published: null, homebrew: null, intents: {}, stopped: null, createdAt: at, updatedAt: at,
     };
 }
-/** A deployment stop; when it left an update pause before the swap, the guided way to lift it. */
 function deployStop(reason, message, stop) {
     if (stop.gate === undefined)
         return new Stop(reason, message);
     return new Stop("gate-held", `${message} New work is still paused by update ${stop.gate.id} (its journal stopped at ${stop.gate.phase}, before the swap). Check and lift that pause with \`toolroll release --release-gate ${stop.gate.id}\`, then rerun.`);
 }
-/** The one runtime the launchd services run, when it records the gated commit; otherwise null. */
 async function served(adapters, candidate) {
     const installed = await adapters.toolroll.installed();
     const runtimes = new Set(installed.services);
@@ -1452,7 +1185,6 @@ async function served(adapters, candidate) {
     const [runtime] = runtimes;
     return runtime !== undefined && await adapters.toolroll.runtimeCommit(runtime) === candidate ? runtime : null;
 }
-/** The one runtime the services and both CLI names run, when it records the gated commit; otherwise null. */
 async function deployed(adapters, candidate) {
     const installed = await adapters.toolroll.installed();
     const runtimes = new Set([...installed.services, ...installed.clis.map(one => one.runtime ?? "")]);
@@ -1461,20 +1193,7 @@ async function deployed(adapters, candidate) {
     const [runtime] = runtimes;
     return runtime !== undefined && runtime !== "" && await adapters.toolroll.runtimeCommit(runtime) === candidate ? runtime : null;
 }
-/**
- * The gate's look at the pull request's required checks on the exact commit, before anything is filed or anyone is
- * asked to approve (#237): a required check that failed or was cancelled stops here; checks not started or still
- * running are named, and the gate waits for them; ones that never finish within the gate's limit stop here too. GitHub
- * not answering is waited out the same way, never taken for a pass. The ci step still checks again before merging.
- */
-/**
- * The branch must contain main's head as GitHub's API answers now: CI tests the pull request's head commit,
- * so only a branch that already holds main merges into exactly the tested tree. Refused in plain words otherwise.
- */
 async function containsMain(adapters, j, nothing) {
-    // GitHub's own answers (eval-harness review 1, finding 4): main's head and the comparison are read from its API by
-    // this coordinator, never from refs/remotes/origin/main in a checkout a build can write. The checkout is still synced
-    // for what the gate reads from it later.
     await adapters.repo.sync(j.branch);
     const main = await adapters.github.mainHead(j.github);
     if (!/^[0-9a-f]{40}$/.test(main))
@@ -1483,13 +1202,8 @@ async function containsMain(adapters, j, nothing) {
         return main;
     throw new Stop("base-moved", `The branch is behind main; update it and push. ${j.branch} at ${j.candidate.sha.slice(0, 7)} doesn't contain main's head ${main.slice(0, 7)}, so what merges wouldn't be the tree CI tested. ${nothing}: release the updated commit with \`toolroll release ${j.branch} --repo ${j.checkout} --new\`.`);
 }
-/**
- * GitHub must refuse a branch behind main for every release (eval-harness review 1, finding 4). A person's approval
- * cannot make the final main read and merge atomic, so absent or unreadable protection stops that release too.
- */
 async function mainProtection(adapters, j, auto, nothing) {
     let protection, unread = null;
-    // Couldn't read (after the adapter's network retries) is its own stop, never "doesn't hold" and never "holds".
     try {
         protection = await adapters.github.upToDateRequired(j.github);
     }
@@ -1497,7 +1211,6 @@ async function mainProtection(adapters, j, auto, nothing) {
         protection = null;
         unread = String(error?.message ?? error).slice(0, 400);
     }
-    // The git lanes main's protection doesn't name yet are said, never refused (PROTECTION_REPORT_ONLY_CHECKS).
     if (protection !== null && protection.notYetRequired.length > 0)
         adapters.say(`  Note: main's protection doesn't require ${protection.notYetRequired.join(", ")} yet; add ${protection.notYetRequired.length === 1 ? "it" : "them"} to its required checks.`);
     if (protection?.effective === true)
@@ -1507,11 +1220,6 @@ async function mainProtection(adapters, j, auto, nothing) {
     }
     throw new Stop("base-unprotected", `main's protection doesn't hold: ${protection.missing.join("; ")}, so this release can't merge${auto ? " automatically" : ""}. ${nothing}. Restore effective main protection and try again.`);
 }
-/**
- * Wait for every required pull request check on the candidate to pass; stop on one that failed. `pendingIsEnough` (the
- * automatic road's gate, pipeline-speed.md D2): checks still running are no reason to wait — returns false then, true
- * once they all passed. `nothing` says what hasn't happened yet when a check failed.
- */
 async function earlyChecks(adapters, j, wait, options = {}) {
     const nothing = options.nothing ?? "Nothing was filed or sent for approval";
     const sha = j.candidate.sha.slice(0, 7);
@@ -1552,33 +1260,18 @@ async function earlyChecks(adapters, j, wait, options = {}) {
         throw new Stop("ci-missing", `Pull request checks on ${sha} didn't all finish in time${named === "" ? (unread ? " (GitHub didn't answer)" : "") : `: ${named}`}. ${nothing}. Start or rerun them on GitHub, then run this command again.`);
     }
 }
-/** A probe's failure that is only the network to GitHub failing for now (release-net.ts transientFailure: a timeout, a
- * connection or name failure, a 5xx, an answer cut short, a secondary rate limit), never a decision (a Stop), a
- * definitive answer or another error. */
 export function transientNetworkError(error) {
     if (error instanceof Stop || error instanceof Restart)
         return false;
     return transientFailure(String(error?.message ?? error)) !== null;
 }
-/** The part of a network failure worth saying: its matching phrase. */
 function networkWords(error) {
     return transientFailure(String(error?.message ?? error))?.words ?? "a network failure";
 }
-/**
- * The pull request's checks on exactly `head`, every attempt (the adapter asks GitHub for all of them, filter=all):
- * each reported attempt must be filed under `head` with a check-run id; a required check counts only from GitHub
- * Actions (an app that names a check alike can't stand in for it); attempts are grouped by the job they belong to — the
- * app, its check suite (a workflow run, whose re-runs stay in it) and the name — and every group is judged by its
- * latest attempt; every required check needs a group. With `auto` (an automatic approval), every other failed attempt on
- * the commit — an earlier attempt, or a job a newer run renamed or dropped — must be one GitHub's own job record shows ending before any workflow step ran (`beforeTests`: confirmed
- * infrastructure), and at most INFRA_RERUNS_PER_CANDIDATE of them on the commit; any other earlier failure — a test,
- * a typecheck, or one nothing explains — fails the verdict, so a person decides. The failures it tolerated are returned.
- */
 export function prChecksVerdict(runs, head, required, options = {}) {
     const failed = [], waiting = [], failures = [];
     const valid = [];
     for (const run of runs) {
-        // youiyoux's drift check from its own workflow neither holds nor fails a release (ADVISORY_PR_CHECKS).
         const advisory = Object.hasOwn(ADVISORY_PR_CHECKS, run.name) ? ADVISORY_PR_CHECKS[run.name] : undefined;
         if (advisory !== undefined && !required.includes(run.name) && run.app === "github-actions" && workflowIs(run.workflowPath, advisory))
             continue;
@@ -1594,8 +1287,6 @@ export function prChecksVerdict(runs, head, required, options = {}) {
             failed.push(`${run.name} (reported by ${run.app ?? "an unknown app"}, not GitHub Actions)`);
             continue;
         }
-        // A required name counts only from the workflow that defines it: a job of the same name in another workflow (or
-        // one whose workflow GitHub doesn't name) fails the verdict rather than stand in for it.
         if (options.workflow !== undefined && required.includes(run.name)) {
             const want = typeof options.workflow === "string" ? options.workflow : options.workflow[run.name];
             if (want === undefined || !workflowIs(run.workflowPath, want)) {
@@ -1609,9 +1300,6 @@ export function prChecksVerdict(runs, head, required, options = {}) {
         }
         valid.push(run);
     }
-    // Supersession by trusted workflow identity (GitHub's workflow-run API, read by the adapter): a newer run of the same
-    // workflow on this commit replaces the older ones — its jobs are the current ones. A suite whose workflow isn't known
-    // is its own workflow (nothing supersedes it), and another app's suites stand on their own.
     const workflowOf = (run) => run.app === "github-actions" && typeof run.workflow === "number" ? `w:${run.workflow}` : `s:${run.app ?? ""}:${run.suite ?? ""}`;
     const current = new Map();
     for (const run of valid) {
@@ -1620,22 +1308,17 @@ export function prChecksVerdict(runs, head, required, options = {}) {
         if (was === undefined || (suite !== null && (was === null || suite > was)))
             current.set(key, suite);
     }
-    // Jobs: a workflow and a name, every attempt in every suite of it; judged by the latest attempt in the current suite.
     const groups = new Map();
     for (const run of valid) {
         const key = JSON.stringify([workflowOf(run), run.name]);
         groups.set(key, [...(groups.get(key) ?? []), run]);
     }
     const judged = new Set();
-    // The attempt each current job stands on (its latest in the current run); every other attempt on the commit is
-    // history, whatever its job is called now.
     const standing = new Set();
     for (const attempts of groups.values()) {
         const ordered = [...attempts].sort((a, b) => a.id - b.id);
         const now = current.get(workflowOf(ordered[0])) ?? null;
         const live = ordered.filter(one => (one.suite ?? null) === now);
-        // A job only an older run had (the newer run no longer has it, or calls it something else) doesn't stand for a
-        // required check; its failures are still history below.
         if (live.length === 0)
             continue;
         const latest = live.at(-1), name = latest.name;
@@ -1645,9 +1328,6 @@ export function prChecksVerdict(runs, head, required, options = {}) {
             waiting.push(`${name} (${latest.status})`);
             continue;
         }
-        // Skipped is never success (test-matrix.md): GitHub's protection reads a skipped job as passing a merge, a release
-        // never does. A documentation-only pull request skips the area lanes, and any pull request but a release-* branch's
-        // skips Node 22, so a release needs every lane executed on its exact head.
         if (latest.conclusion === "skipped" && required.includes(name)) {
             failed.push(`${name} (skipped: a release needs it run on this exact commit; release from a branch named release-*, whose pull request runs every lane)`);
             continue;
@@ -1657,11 +1337,6 @@ export function prChecksVerdict(runs, head, required, options = {}) {
             continue;
         }
     }
-    // Every failed attempt on the commit that no current job stands on — an earlier attempt of a job, a job a newer run
-    // renamed, dropped, or never ran again — is classified before anything is superseded (eval-harness review 1, finding
-    // 1): a renamed or vanished job never erases a failure. An automatic approval tolerates only confirmed
-    // infrastructure (GitHub's job record shows the runner failing before any workflow step ran), and waits out any
-    // earlier attempt still running.
     const history = valid.filter(one => !standing.has(one));
     if (options.auto === true) {
         for (const one of history)
@@ -1688,10 +1363,6 @@ export function prChecksVerdict(runs, head, required, options = {}) {
         return { state: "failed", failed };
     return waiting.length > 0 ? { state: "pending", waiting } : { state: "passed", failures };
 }
-/**
- * What a failed release check means and what happens next, by its class (check-failure.ts), in words. Only confirmed
- * infrastructure reruns on its own; nothing else is rerun to pass.
- */
 export function checkFailedWords(input) {
     const short = input.sha.slice(0, 7), again = `\`toolroll release ${input.branch} --repo ${input.checkout} --new\``;
     switch (input.class) {
@@ -1707,18 +1378,13 @@ export function checkFailedWords(input) {
             return `The Full release check of ${short} did not pass (run ${input.run}): ${input.why}. Fix the branch and release the new commit with ${again}.`;
     }
 }
-/** Whether GitHub's workflow-run `path` names exactly `file` (it may carry the ref it ran from, after an `@`). */
 export function workflowIs(path, file) {
     if (typeof path !== "string")
         return false;
     if (path === file)
         return true;
-    // GitHub may append @ref, but ci.yml@evil.yml is also a valid *different* workflow filename. Multiple @ signs
-    // likewise cannot distinguish that filename from a ref. Refuse ambiguous suffixes instead of granting its checks.
     const ref = path.startsWith(`${file}@`) ? path.slice(file.length + 1) : "";
     return /^[A-Za-z0-9._+/-]+$/.test(ref) && !/\.ya?ml$/i.test(ref);
 }
-/** The words `toolroll release` reads as its own (release-cli.ts), never as a branch: such a branch is named with --branch. */
 const RELEASE_WORDS = new Set(["status", "nightly", "carry", "revoke", "ask-every-commit", "unsandboxed-carry", "auto-approve", "publish-ok", "approve"]);
-/** How a person names this branch to `toolroll release` again. */
 export function releaseBranchArg(branch) { return RELEASE_WORDS.has(branch) ? `--branch ${branch}` : branch; }