toolroll 0.9.75 → 0.9.77

package/dist/release.js

@@ -36,6 +36,7 @@ import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, re
 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";
 /** The pull-request checks a release waits for, by exact job name (.github/workflows/ci.yml). Every one must have
  * concluded `success` on the gated commit; src/ci-workflow.test.ts holds the workflow to this list. */
 export const REQUIRED_PR_CHECKS = [
@@ -44,19 +45,44 @@ export const REQUIRED_PR_CHECKS = [
     "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 workflow file every 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 = ".github/workflows/ci.yml";
+/**
+ * The pull-request checks main's GitHub protection is not yet required to name (eval-harness review 2, finding 1): the
+ * git lanes join main's protection once they have run there, so a protection without them is reported, never refused.
+ * A later release empties this list; from then on main's protection must name every REQUIRED_PR_CHECKS check.
+ */
+export const PROTECTION_REPORT_ONLY_CHECKS = ["git 2.41 · debian trixie", "git 2.47 · debian trixie"];
+/** 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));
 /** The checks a release tag runs (.github/workflows/publish.yml), awaited before Homebrew moves. */
 export const RELEASE_TAG_CHECKS = ["node 22 · macos-latest", "node 24 · macos-latest", "publish"];
 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). */
 export const RELEASE_LIMITS = { gate: 60, approval: 24 * 60, check: 120, 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;
-    constructor(reason, message) {
+    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 branch moved before the deploy reservation: carry the approval to the new head, or file it for a person. */
@@ -255,6 +281,9 @@ 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();
@@ -367,14 +396,54 @@ export async function runRelease(options, adapters) {
          * 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) => {
+        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, "a pull request check failed after the deploy", epoch))) {
+            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.`);
             }
-            throw new Stop("ci-failed", `${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\`.`);
+            throw new Stop("ci-failed", deploy === "after"
+                ? `${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;
+            const read = await adapters.github.checks(j.github, j.candidate.sha);
+            const whole = adapters.github.complete === undefined ? false : await adapters.github.complete(j.github, j.candidate.sha);
+            const verdict = whole ? prChecksVerdict(read, j.candidate.sha, REQUIRED_PR_CHECKS, { auto: true, workflow: REQUIRED_PR_CHECKS_WORKFLOW }) : { state: "failed", failed: ["GitHub's check history of this commit can't be read whole"] };
+            if (verdict.state === "passed") {
+                await liftCiHold(false, `The release cannot continue before ${before}`);
+                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);
+                throw new Stop("ci-failed", `Pull request checks on ${j.candidate.sha.slice(0, 7)} are no longer all passing: ${(verdict.state === "failed" ? verdict.failed : verdict.waiting).join(", ")}. It was merged, but nothing was tagged or published; a person decides how to go on.`);
+            }
+            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.`);
         };
         /** identity(), on a plane that keeps release authority; a legacy plane keeps the old rules. */
         const watch = async (action) => { if (rel !== undefined)
@@ -409,6 +478,7 @@ export async function runRelease(options, adapters) {
             j.check = null;
             j.completion = null;
             j.authority = null;
+            j.auto = null;
             epoch = null;
             delete j.intents.gate;
             delete j.intents.check;
@@ -417,6 +487,77 @@ export async function runRelease(options, adapters) {
             j.stopped = null;
             save();
         };
+        /**
+         * 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) => {
+            j.auto = { state: "refused", why };
+            j.check = null;
+            j.step = "approval";
+            save();
+            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)
+                return;
+            const lifted = await lift(j.task.id, j.candidate.sha, ask);
+            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 {
+                runs = await adapters.github.checks(j.github, j.candidate.sha);
+            }
+            catch (error) {
+                if (transientNetworkError(error))
+                    return false;
+                throw error;
+            }
+            const verdict = prChecksVerdict(runs, j.candidate.sha, REQUIRED_PR_CHECKS, { workflow: REQUIRED_PR_CHECKS_WORKFLOW });
+            if (verdict.state === "failed") {
+                throw new Stop("ci-failed", `GitHub's checks failed on ${j.candidate.sha.slice(0, 7)}: ${verdict.failed.join(", ")}. ${nothing}. ${j.approval === null ? "" : `The approval covers ${j.candidate.sha.slice(0, 7)} only. `}Rerun the failed job on GitHub and run \`${resume}\` again, or fix the branch and release the new commit with \`toolroll release ${j.branch} --repo ${j.checkout} --new\`.`);
+            }
+            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;
+                save();
+            }
+            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;
+            let said = false;
+            await waitFor("ci", `the pull request checks on ${j.candidate.sha.slice(0, 7)} before the deploy`, async () => {
+                await watch("deploy");
+                if (await ciWhileRunning("Nothing was deployed, merged, tagged or published", false))
+                    return true;
+                if (!said) {
+                    say(`  ${CI_RUNNING_WORDS}`);
+                    said = true;
+                }
+                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
@@ -425,6 +566,13 @@ export async function runRelease(options, adapters) {
         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)
+                    return;
+                return await autoRefused(standing.why);
+            }
             if (rel !== undefined && (j.authority || gate.approval?.basis === "carried")) {
                 const live = await rel.live(j.task.id, action);
                 if (live.applies && live.ok)
@@ -439,7 +587,7 @@ export async function runRelease(options, adapters) {
             if (gate.result?.level !== "full")
                 throw new Stop("check-level", `A Full check is required for this release (run ${gate.result?.run ?? "unknown"}: ${gate.result?.level ?? "unknown"}). Quick and Off checks cannot release a build.`);
             if (gate.result.check !== "passed")
-                throw new Stop("check-failed", `The Full release check of ${j.candidate.sha.slice(0, 7)} did not pass (run ${gate.result.run}: ${gate.result.check}). It stays as it is: fix the branch and release the new commit with --new.`);
+                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;
@@ -476,6 +624,11 @@ 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.
+                        await containsMain(adapters, j, "Nothing was filed or sent for approval");
+                        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)
@@ -487,7 +640,20 @@ export async function runRelease(options, adapters) {
                             j.task.scopeDigest = existing.scopeDigest;
                         }
                         else {
-                            await earlyChecks(adapters, j, (what, probe) => waitFor("gate", what, probe));
+                            // 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 });
+                            // 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;
+                            if (!settled)
+                                j.ciBeforeDeploy = true;
+                            save();
+                            if (!settled) {
+                                say(`  Pull request checks on ${j.candidate.sha.slice(0, 7)} are still running: the release check runs beside them, and nothing deploys before they pass`);
+                            }
                             intend("gate");
                             await adapters.repo.sync(j.branch);
                             const filed = await adapters.toolroll.fileGate({
@@ -502,9 +668,42 @@ 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");
+                            const gate = await adapters.toolroll.gate(j.task.id);
+                            if (gate.scopeDigest !== j.task.scopeDigest)
+                                throw new Stop("scope-changed", `The scope of ${j.task.id} changed after it was filed; the release only runs on the scope it filed.`);
+                            if (!ownerApproval(gate, j.task.scopeDigest).ok) {
+                                const authorized = await auto.authorizeCheck({ taskId: j.task.id, digest: j.task.scopeDigest, candidate: j.candidate.sha });
+                                if (authorized.ok) {
+                                    j.auto = { state: "checking" };
+                                    say(`  Approving automatically once CI and the release check pass on ${j.candidate.sha.slice(0, 7)} (this project's release approval setting)`);
+                                    advance("check");
+                                    break;
+                                }
+                                j.auto = { state: "refused", why: authorized.why };
+                                save();
+                                await auto.giveUp(j.task.id, authorized.why);
+                                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);
                         say(`  The release scope needs your approval: \`toolroll task approve ${j.task.id} --digest ${j.task.scopeDigest}\`, or open the task in the console.`);
+                        if (j.ciAhead === true)
+                            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);
                             if (gate.scopeDigest !== j.task.scopeDigest)
                                 throw new Stop("scope-changed", `The scope of ${j.task.id} changed after it was filed; the release only runs on the scope it filed.`);
@@ -530,7 +729,7 @@ export async function runRelease(options, adapters) {
                         break;
                     }
                     case "check": {
-                        const result = await waitFor("check", `the release check of ${j.candidate.sha.slice(0, 7)}`, async () => {
+                        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);
@@ -538,8 +737,20 @@ export async function runRelease(options, adapters) {
                             // 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")
+                                    return null;
+                                if (answer.action === "rerun") {
+                                    say(`  run ${gate.result.run} failed: ${answer.why}. Toolroll confirmed it as its own infrastructure, so the check runs again on ${j.candidate.sha.slice(0, 7)} under the same approval`);
+                                    return null;
+                                }
+                                throw new Stop("check-failed", checkFailedWords({ sha: j.candidate.sha, run: gate.result.run, class: answer.class, why: answer.why, branch: j.branch, checkout: j.checkout, taskId: j.task.id }));
+                            }
                             if (gate.failed !== null)
-                                throw new Stop("check-failed", `The release build of ${j.task.id} failed: ${gate.failed}. Fix it and release the new commit with --new.`);
+                                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
@@ -551,10 +762,74 @@ 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)
+                                    throw new Stop("check-failed", `Run ${gate.result.run} passed on ${j.candidate.sha.slice(0, 7)}, but ${standing.why}: approve this commit again with \`toolroll release ${j.branch} --repo ${j.checkout} --new\`, or fix the branch and release the new commit the same way.`);
+                                if (standing.retried === null)
+                                    say(`  run ${gate.result.run} passed, but its report can't be read, so whether anything passed only on a retry is unknown`);
+                                else if (standing.retried.length > 0)
+                                    say(`  run ${gate.result.run} passed, but only on a retry: ${standing.retried.join(", ")}`);
+                            }
                             return { run: gate.result.run, receipt: gate.result.receipt, worktree: gate.result.worktree, head };
+                        };
+                        const result = await waitFor("check", `the release check of ${j.candidate.sha.slice(0, 7)}`, async () => {
+                            try {
+                                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")
+                                    await rel?.auto?.giveUp(j.task.id, error.message.replace(/\.$/, ""));
+                                throw error;
+                            }
                         });
                         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" });
+                                    await liftCiHold(false, "Nothing was approved");
+                                }
+                                catch (error) {
+                                    if (error instanceof Stop && error.reason === "ci-failed") {
+                                        j.auto = { state: "refused", why: error.message };
+                                        j.check = null;
+                                        j.step = "approval";
+                                        save();
+                                        await rel?.auto?.giveUp(j.task.id, error.message.replace(/\.$/, ""));
+                                    }
+                                    throw error;
+                                }
+                                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)
+                                await autoRefused(sealed.why);
+                            else {
+                                j.auto = { state: "approved", ci: sealed.ci.map(one => one.id) };
+                                j.approval = { by: `${sealed.by} (automatic)`, at: sealed.at };
+                                const view = await rel.authority(j.task.id);
+                                if (view === null)
+                                    throw new Stop("release", `The automatic approval of ${j.task.id} opened no release record; a person approves it.`);
+                                j.authority = { id: view.id, generation: view.generation };
+                                j.landed = view.landed;
+                                save();
+                                await hold();
+                                say(`  Approved automatically: CI and the release check passed on ${j.candidate.sha.slice(0, 7)}`);
+                            }
+                        }
                         advance("complete");
                         break;
                     }
@@ -596,7 +871,10 @@ export async function runRelease(options, adapters) {
                         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");
                                 const reserved = await rel.reserve({ authority: j.authority.id, kind: "deploy", taskId: j.task.id, candidate: j.candidate.sha, epoch });
                                 if (!reserved.ok)
                                     throw new Stop("release", `The deploy couldn't be reserved: ${reserved.why}`);
@@ -607,8 +885,13 @@ 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");
                             let operation, secret = "";
                             if (rel !== undefined && j.authority && epoch !== null) {
                                 const reserved = await rel.reserve({ authority: j.authority.id, kind: "deploy", taskId: j.task.id, candidate: j.candidate.sha, epoch });
@@ -648,6 +931,7 @@ export async function runRelease(options, adapters) {
                     }
                     case "link": {
                         const runtime = j.deploy.runtime;
+                        await autoCiHolds("the CLI names move");
                         if (await served(adapters, builtHead()) !== runtime)
                             throw new Stop("drift", `The console and worker no longer run ${runtime}; the CLI names were not moved.`);
                         if (j.links === undefined || j.links === null) {
@@ -670,7 +954,7 @@ export async function runRelease(options, adapters) {
                     case "ci": {
                         await waitFor("ci", `the pull request checks on ${j.candidate.sha.slice(0, 7)}`, async () => {
                             await pinned();
-                            const verdict = checksVerdict(await adapters.github.checks(j.github, j.candidate.sha), REQUIRED_PR_CHECKS);
+                            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 === "failed")
                                 await ciFailedAfterDeploy(`Pull request checks failed on ${j.candidate.sha.slice(0, 7)}: ${verdict.failed.join(", ")}`);
                             return verdict.state === "passed" ? true : null;
@@ -693,15 +977,19 @@ export async function runRelease(options, adapters) {
                             if (rel !== undefined && j.authority)
                                 await identity("merge", false);
                             await pinned();
-                            // A squash merge only reproduces the gated tree when main hasn't moved past the branch's base.
-                            await adapters.repo.sync(j.branch);
-                            const main = await adapters.repo.mainHead();
-                            if (!await adapters.repo.contains(j.candidate.sha, main))
-                                throw new Stop("base-moved", `main moved to ${main.slice(0, 7)}, which ${j.branch} doesn't contain, so the merge wouldn't be the gated tree. Nothing was merged: update the branch and release the new commit with --new.`);
+                            // A squash merge only reproduces the gated (and CI-tested) tree when main hasn't moved past the branch's base.
+                            const main = await containsMain(adapters, j, "Nothing was merged");
+                            // 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 = checksVerdict(await adapters.github.checks(j.github, j.candidate.sha), REQUIRED_PR_CHECKS);
+                            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)}`);
+                            // 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\`.`);
                             let operation;
                             if (rel !== undefined && j.authority && epoch !== null) {
                                 const reserved = await rel.reserve({ authority: j.authority.id, kind: "merge", taskId: j.task.id, candidate: j.candidate.sha, epoch });
@@ -747,10 +1035,12 @@ export async function runRelease(options, adapters) {
                     }
                     case "tag": {
                         const merge = j.merge;
+                        await publishHold();
                         const at = await adapters.github.tag(j.github, j.tag);
                         if (at !== null && at !== merge.sha)
                             throw new Stop("conflict", `${j.tag} already points at ${at.slice(0, 7)}, not the merge ${merge.sha.slice(0, 7)}.`);
                         if (at === null) {
+                            await autoCiHolds("the tag");
                             intend("tag");
                             await adapters.github.createTag(j.github, j.tag, merge.sha);
                         }
@@ -759,6 +1049,7 @@ export async function runRelease(options, adapters) {
                         break;
                     }
                     case "publish": {
+                        await publishHold();
                         if (j.intents.publish === undefined)
                             intend("publish");
                         await waitFor("publish", `npm, the GitHub release and the tag's checks for ${j.tag}`, async () => {
@@ -776,6 +1067,7 @@ export async function runRelease(options, adapters) {
                         break;
                     }
                     case "homebrew": {
+                        await publishHold();
                         const brew = adapters.homebrew;
                         let state = await brew.state(j.packageVersion);
                         if (state.kind === "missing") {
@@ -825,6 +1117,12 @@ export async function runRelease(options, adapters) {
             }
         }
         say(`Released ${j.tag}: deployed, merged as ${j.merge.sha.slice(0, 7)}, tagged, published and on Homebrew.`);
+        if (j.auto?.state === "approved") {
+            try {
+                await rel?.auto?.released(j.task.id, j.tag);
+            }
+            catch { /* the release is done; the note is best effort */ }
+        }
         for (const line of landedWords(j.landed ?? []))
             say(line);
         return { ok: true, journal: j, file };
@@ -914,12 +1212,54 @@ async function deployed(adapters, candidate) {
  * 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.
  */
-async function earlyChecks(adapters, j, wait) {
+/**
+ * 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))
+        throw new Stop("base-moved", `GitHub named no commit for main. ${nothing}.`);
+    if (await adapters.github.contains(j.github, j.candidate.sha, main))
+        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;
+    try {
+        protection = await adapters.github.upToDateRequired(j.github);
+    }
+    catch {
+        protection = null;
+    }
+    // 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)
+        return;
+    const lacking = protection === null ? "GitHub's branch protection for main couldn't be read" : `main's protection doesn't hold: ${protection.missing.join("; ")}`;
+    throw new Stop("base-unprotected", `${lacking}, 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);
     const required = REQUIRED_PR_CHECKS;
     let named = "", unread = false;
     try {
-        await wait(`the pull request checks on ${sha}`, async () => {
+        return await wait(`the pull request checks on ${sha}`, async () => {
             let runs;
             try {
                 runs = await adapters.github.checks(j.github, j.candidate.sha);
@@ -930,12 +1270,14 @@ async function earlyChecks(adapters, j, wait) {
                 unread = true;
                 return null;
             }
-            const verdict = checksVerdict(runs.filter(run => required.includes(run.name)), required);
+            const verdict = prChecksVerdict(runs.filter(run => required.includes(run.name)), j.candidate.sha, required, { workflow: REQUIRED_PR_CHECKS_WORKFLOW });
             if (verdict.state === "failed") {
-                throw new Stop("ci-failed", `Pull request checks already failed on ${sha}: ${verdict.failed.join(", ")}. Nothing was filed or sent for approval. Fix the branch, then release the new commit with \`toolroll release ${j.branch} --repo ${j.checkout} --new\` (or rerun the failed job on GitHub and run this command again).`);
+                throw new Stop("ci-failed", `Pull request checks already failed on ${sha}: ${verdict.failed.join(", ")}. ${nothing}. Fix the branch, then release the new commit with \`toolroll release ${j.branch} --repo ${j.checkout} --new\` (or rerun the failed job on GitHub and run this command again).`);
             }
             if (verdict.state === "passed")
                 return true;
+            if (options.pendingIsEnough === true)
+                return false;
             const now = verdict.waiting.join(", ");
             if (now !== named) {
                 adapters.say(`  Pull request checks on ${sha} not finished yet: ${now}.`);
@@ -947,7 +1289,7 @@ async function earlyChecks(adapters, j, wait) {
     catch (error) {
         if (!(error instanceof Stop) || error.reason !== "timeout")
             throw error;
-        throw new Stop("ci-missing", `Pull request checks on ${sha} didn't all finish in time${named === "" ? (unread ? " (GitHub didn't answer)" : "") : `: ${named}`}. Nothing was filed or sent for approval. Start or rerun them on GitHub, then run this command again.`);
+        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.`);
     }
 }
 /** The network failures a release's waits ride out: git or gh timing out (or cut off) on the way to GitHub. */
@@ -962,3 +1304,136 @@ export function transientNetworkError(error) {
 function networkWords(error) {
     return TRANSIENT_NETWORK.exec(String(error?.message ?? error))?.[0] ?? "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) {
+        if (run.head !== head) {
+            failed.push(`${run.name} (reported for ${run.head == null ? "no commit" : run.head.slice(0, 7)}, not ${head.slice(0, 7)})`);
+            continue;
+        }
+        if (typeof run.id !== "number" || !Number.isSafeInteger(run.id) || run.id <= 0) {
+            failed.push(`${run.name} (no check run id)`);
+            continue;
+        }
+        if (required.includes(run.name) && run.app !== "github-actions") {
+            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) && !workflowIs(run.workflowPath, options.workflow)) {
+            failed.push(`${run.name} (from ${run.workflowPath ?? "a workflow GitHub doesn't name"}, not ${options.workflow})`);
+            continue;
+        }
+        if (run.app === "github-actions" && (typeof run.suite !== "number" || !Number.isSafeInteger(run.suite))) {
+            failed.push(`${run.name} (no workflow run)`);
+            continue;
+        }
+        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) {
+        const key = workflowOf(run), suite = run.suite ?? null;
+        const was = current.get(key);
+        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;
+        judged.add(name);
+        standing.add(latest);
+        if (latest.status !== "completed") {
+            waiting.push(`${name} (${latest.status})`);
+            continue;
+        }
+        if (latest.conclusion !== "success") {
+            failed.push(`${name} (${latest.conclusion ?? "no conclusion"})`);
+            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)
+            if (one.status !== "completed")
+                waiting.push(`${one.name} (an earlier attempt still running)`);
+    }
+    const flaked = history.filter(one => one.status === "completed" && one.conclusion !== "success");
+    if (options.auto === true) {
+        const unexplained = new Map();
+        for (const one of flaked)
+            if (one.beforeTests !== true)
+                unexplained.set(one.name, (unexplained.get(one.name) ?? 0) + 1);
+        for (const [name, count] of unexplained)
+            failed.push(`${name} (failed ${count === 1 ? "once" : `${count} times`} on this commit, and GitHub doesn't show its runner failing before the tests ran)`);
+    }
+    const infrastructure = flaked.filter(one => one.beforeTests === true).length;
+    failures.push(...flaked.map(one => ({ id: one.id, name: one.name, conclusion: one.conclusion })));
+    if (options.auto === true && infrastructure > INFRA_RERUNS_PER_CANDIDATE)
+        failed.push(`GitHub's runners failed ${infrastructure} times on this commit before the tests ran (at most ${INFRA_RERUNS_PER_CANDIDATE} are rerun)`);
+    for (const name of required)
+        if (!judged.has(name))
+            waiting.push(`${name} (not started)`);
+    if (failed.length > 0)
+        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) {
+        case "deterministic":
+            return `The Full release check of ${short} failed (run ${input.run}): ${input.why}. That is a failure in the code or its tests, so it isn't run again: fix the branch, then release the new commit with ${again}.`;
+        case "agent-behaviour":
+            return `The Full release check of ${short} failed (run ${input.run}): ${input.why}. Real-model journeys are counted, never rerun until they pass, so a person decides: fix the branch and release the new commit with ${again}, or approve this commit again with ${again}.`;
+        case "infrastructure":
+            return `The Full release check of ${short} failed (run ${input.run}): ${input.why}. It was already run again as often as a commit is (${INFRA_RERUNS_PER_CANDIDATE} times), so a person decides: approve this commit again with ${again}.`;
+        case "unknown":
+            return `The Full release check of ${short} failed (run ${input.run}) with no failure Toolroll could explain: ${input.why}. It isn't rerun to pass. To look into it, \`toolroll task regate ${input.taskId}\` runs it again on the same commit, but a pass then doesn't erase this failure: a person decides, and approves this commit again with ${again}, or fixes the branch and releases the new commit the same way.`;
+        default:
+            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) {
+    return typeof path === "string" && (path === file || path.startsWith(`${file}@`));
+}