toolroll 0.9.92 → 0.9.94

package/dist/release-next.js

@@ -0,0 +1,161 @@
+/**
+ * What `toolroll release <branch>` does before its journal's next step (docs/plans/plain-toolroll.md P2.6): one command,
+ * so a person never chooses between --recover-deploy, --release-gate and rerunning.
+ *
+ * - **Another run**: a run lock per branch, by host and pid. A live one is waited for, named; two coordinators never act
+ *   on one release at once. A lock whose process is proved gone on this host is taken over.
+ * - **A deployment left open**: the journal decides. Before the swap: its pause is lifted, once proved. Past the new
+ *   service's start: forward, by the release. Between: rolled back through its own recovery. Each of those re-proves
+ *   itself, so a crash at any phase ends the same on the next run.
+ */
+import { closeSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, writeSync } from "node:fs";
+import { hostname } from "node:os";
+import { dirname, join } from "node:path";
+import { FORWARD_ONLY, rescueDeployment } from "./deploy-rescue.js";
+import { BEFORE_SWAP, releaseGate } from "./release-gate.js";
+import { journalFile, readJournal } from "./release.js";
+import { autoPublishHeld, PUBLISH_ALLOWED_ACTION } from "./release-auto.js";
+import { sameMachineHost } from "./machine-identity.js";
+const lockFile = (stateDir, branch) => journalFile(stateDir, branch).replace(/\.json$/, ".running");
+/** How long a run waits for another before it says so and stops. */
+export const RELEASE_WAIT_MS = 30 * 60_000;
+const processAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+};
+function readHolder(file) {
+    try {
+        const read = JSON.parse(readFileSync(file, "utf8"));
+        return typeof read.host === "string" && Number.isSafeInteger(read.pid) ? { host: read.host, pid: read.pid } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Take this branch's run lock, waiting for a live holder. Answers how to give it back, or who kept it. */
+export async function takeReleaseRun(stateDir, branch, say, seams = {}) {
+    const file = lockFile(stateDir, branch);
+    const host = seams.host ?? hostname(), pid = seams.pid ?? process.pid;
+    const alive = seams.alive ?? processAlive, sleep = seams.sleep ?? (ms => new Promise(done => setTimeout(done, ms)));
+    const now = seams.now ?? Date.now;
+    const deadline = now() + (seams.waitMs ?? RELEASE_WAIT_MS);
+    mkdirSync(dirname(file), { recursive: true });
+    let said = false;
+    for (;;) {
+        try {
+            const fd = openSync(file, "wx", 0o600);
+            try {
+                writeSync(fd, JSON.stringify({ host, pid }));
+            }
+            finally {
+                closeSync(fd);
+            }
+            return { ok: true, release: () => { const mine = readHolder(file); if (mine?.pid === pid && mine.host === host)
+                    rmSync(file, { force: true }); } };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        const holder = readHolder(file);
+        // A lock with no readable holder, or a process proved gone on this computer, holds nothing. Another computer's can't
+        // be proved gone from here, so it is waited for.
+        if (holder === null || (sameMachineHost(holder.host, host) && !alive(holder.pid))) {
+            rmSync(file, { force: true });
+            continue;
+        }
+        if (!said) {
+            say(`Waiting: another release of ${branch} is running on ${holder.host} (process ${holder.pid}).`);
+            said = true;
+        }
+        if (now() >= deadline)
+            return { ok: false, holder };
+        await sleep(seams.pollMs ?? 5_000);
+    }
+}
+/** The one action a deployment's journal calls for. */
+export function deployActionOf(phase) {
+    if (typeof phase !== "string")
+        return "refuse";
+    if (phase === "released" || phase === "deployed")
+        return "none";
+    if (BEFORE_SWAP.includes(phase))
+        return "lift-pause";
+    if (FORWARD_ONLY.includes(phase))
+        return "forward";
+    return "roll-back";
+}
+/** Settle what a stopped deployment left, saying what was done. A refusal stops the release before it does anything. */
+export async function settleDeployment(world, say) {
+    const open = world.rescue.journals().filter(one => deployActionOf(one.journal?.["phase"]) !== "none");
+    if (open.length === 0)
+        return { ok: true };
+    if (open.length > 1)
+        return { ok: false, message: `${open.length} deployments are unfinished: ${open.map(one => one.stage).join(", ")}. Nothing was changed.` };
+    const { stage, journal } = open[0];
+    const action = deployActionOf(journal?.["phase"]);
+    if (action === "refuse")
+        return { ok: false, message: `The deployment journal in ${stage} can't be read. Nothing was changed.` };
+    if (action === "forward") {
+        say("Finishing the deployment that was under way.");
+        return { ok: true };
+    }
+    if (action === "lift-pause") {
+        const lifted = releaseGate(String(journal?.["id"] ?? ""), world.gate, true);
+        if (!lifted.ok)
+            return { ok: false, message: lifted.message };
+        say("Lifted the pause an unfinished deployment left before its swap.");
+        return { ok: true };
+    }
+    const back = await rescueDeployment(stage, true, world.rescue);
+    if (!back.ok)
+        return { ok: false, message: back.message };
+    say("Put back the deployment that stopped half way.");
+    return { ok: true };
+}
+// ---- a held release resumes itself -----------------------------------------------------------------------------------
+export const RELEASE_RESUMED_ACTION = "release resumed";
+/**
+ * A person let a held release go on (release-auto.ts allowAutoPublish; the Release sheet's button or `publish-ok`): each
+ * sweep, its journal goes on from where it stopped, once per that person's act, under the same run lock. It was merged
+ * already, so only the tag, publication and Homebrew are left, and each re-proves itself.
+ */
+export async function resumeAllowedReleases(store, stateDir, run, now) {
+    let folder;
+    try {
+        folder = readdirSync(join(stateDir, "releases")).filter(name => name.endsWith(".json") && !name.includes(".superseded-"));
+    }
+    catch {
+        return 0;
+    }
+    let resumed = 0;
+    for (const name of folder) {
+        const journal = readJournal(join(stateDir, "releases", name));
+        if (journal === null || !["tag", "publish", "homebrew"].includes(journal.step) || autoPublishHeld(store, journal.task.id) !== null)
+            continue;
+        const allowed = store.handle.prepare("SELECT id FROM action_ledger WHERE task_id = ? AND action = ? ORDER BY id DESC LIMIT 1").get(journal.task.id, PUBLISH_ALLOWED_ACTION);
+        if (allowed === undefined)
+            continue;
+        // Once per act: a resume that stops again waits for a person, never for the next sweep.
+        const done = store.handle.prepare("SELECT 1 AS hit FROM action_ledger WHERE task_id = ? AND action = ? AND outcome = ?").get(journal.task.id, RELEASE_RESUMED_ACTION, String(allowed["id"]));
+        if (done !== undefined)
+            continue;
+        const taken = await takeReleaseRun(stateDir, journal.branch, () => { }, { waitMs: 0 });
+        if (!taken.ok)
+            continue;
+        try {
+            store.recordAction({ at: now.toISOString(), actor: "system", repo: store.lookupRef(journal.task.id)?.repo ?? null, taskId: journal.task.id, runId: null, action: RELEASE_RESUMED_ACTION, outcome: String(allowed["id"]), source: "work", detail: journal.tag });
+            await run(journal);
+            resumed++;
+        }
+        finally {
+            taken.release();
+        }
+    }
+    return resumed;
+}

package/dist/release.d.ts

@@ -77,7 +77,9 @@ export declare const RELEASE_TAG_WORKFLOW = ".github/workflows/publish.yml";
 export declare const RELEASE_STEPS: readonly ["gate", "approval", "check", "complete", "quiet", "deploy", "link", "ci", "merge", "tree", "tag", "publish", "homebrew", "done"];
 export type ReleaseStep = typeof RELEASE_STEPS[number];
 type WaitingStep = "gate" | "approval" | "check" | "quiet" | "deploy" | "ci" | "publish" | "homebrew";
-/** How long each waiting step may take, in minutes, before the release stops there (rerunning continues from it). */
+/** 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 declare const RELEASE_LIMITS: Readonly<Record<WaitingStep, number>>;
 /** One check attempt; `app` is the GitHub App that made it (github-actions for a workflow), when known; `id` its check
  * run id, `suite` its check suite (one workflow run: its re-runs stay in it) and `head` the commit GitHub filed it
@@ -332,6 +334,43 @@ export type ReleaseAuthorityAdapter = {
         why: string;
         warning: string | null;
     }>;
+    /** Whether a sandboxed Full check's skipped cases are covered (fenced-check-coverage.ts, H3). Run `run`'s stamped level
+     * decides: an unsandboxed check answers at once. Absent: a plane that can't say, as for every older one. */
+    fencedCoverage?(taskId: string, run: number, candidate: string): Promise<{
+        ok: true;
+        covered: number;
+    } | {
+        ok: false;
+        why: string;
+    }>;
+    /** One-tap release approval (docs/plans/trusted-release-reports.md, slice A): what the plane tells a person and
+     * keeps for the approval sheet. Best effort: a failure here never changes the release. Absent on an older plane. */
+    ready?: ReleaseReadyAdapter;
+};
+/** What the coordinator tells the plane for a person's release (release-approval.ts). Ids and its own readings only. */
+export type ReleaseReadyAdapter = {
+    /** The approval step was entered (a fresh filing or a resumed one): one notification per task and scope digest. */
+    asked(taskId: string): Promise<void>;
+    /** The pull request's required checks on the candidate, as this coordinator just read them. */
+    ci(input: {
+        taskId: string;
+        candidate: string;
+        state: "passed" | "running" | "failed";
+        failed: readonly string[];
+        runs: readonly CheckRun[];
+    }): Promise<void>;
+    /** A person's release stopped: one attention notification per task, step and reason. */
+    stopped(input: {
+        taskId: string;
+        step: string;
+        reason: string;
+        message: string;
+    }): Promise<void>;
+    /** Main's merge commit was proved to hold the approved tree: the plane checks it again and keeps the release's record. */
+    verified(input: {
+        taskId: string;
+        merge: string;
+    }): Promise<void>;
 };
 /** The plane's automatic release approval, as the coordinator asks it. Every answer is the plane's own: the coordinator
  * hands it ids, never evidence (the plane reads GitHub CI itself for `approve`). */
@@ -451,11 +490,13 @@ export type ReleaseAdapters = {
         }): Promise<{
             scopeDigest: string;
         }>;
+        /** `reason` "stopping": Toolroll is still proving the check's build stopped (stop-proof.ts); it clears on its own. */
         complete(taskId: string, receipt: string): Promise<{
             ok: true;
         } | {
             ok: false;
             message: string;
+            reason?: string;
         }>;
         busy(): Promise<{
             running: number;
@@ -506,6 +547,14 @@ export type ReleaseAdapters = {
         mainHead(repo: string): Promise<string>;
         /** Whether `sha` already holds `ancestor`, by GitHub's own comparison. */
         contains(repo: string, sha: string, ancestor: string): Promise<boolean>;
+        /** Bring a pull request's branch up to main, only while its head is `expectedHead` (GitHub's own compare-and-swap: a
+         * push that got there first refuses). Absent: a behind branch stops, for a person to update. */
+        updateBranch?(repo: string, pr: number, expectedHead: string): Promise<{
+            ok: true;
+        } | {
+            ok: false;
+            why: string;
+        }>;
         /** Whether GitHub refuses to merge a branch that is behind main ("Require branches to be up to date before
          * merging"); null when it can't be read. Read only. */
         upToDateRequired(repo: string): Promise<MainProtection | null>;

package/dist/release.js

@@ -101,8 +101,10 @@ export const ADVISORY_PR_CHECKS = {
 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). */
-export const RELEASE_LIMITS = { gate: 60, approval: 24 * 60, check: 120, quiet: 60, deploy: 30, ci: 60, publish: 45, homebrew: 45 };
+/** 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
@@ -129,9 +131,12 @@ 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;
-    constructor(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. */
@@ -453,6 +458,20 @@ export async function runRelease(options, adapters) {
         };
         // ---- 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). */
+        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)) };
+            const seen = lastCi;
+            await tell(ready => ready.ci({ taskId: j.task.id, ...seen }));
+        };
+        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()}`;
@@ -612,11 +631,41 @@ export async function runRelease(options, adapters) {
         /** 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); };
-        const restart = async (head) => {
+        /**
+         * 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)
+                return null;
+            if (rel !== undefined && j.authority) {
+                if (epoch === null || !await rel.renew(j.authority.id, owner, epoch))
+                    throw new Stop("lease", "Another release coordinator took over this release.");
+            }
+            const pr = await adapters.github.pullRequest(j.github, j.branch);
+            if (pr === null || pr.number !== j.pr || pr.state !== "open" || pr.head !== j.candidate.sha)
+                throw new Stop("drift", `${j.branch} moved while it was being brought up to main. Nothing was changed; rerun \`${resume}\`.`);
+            if (rel !== undefined && j.authority && !await rel.needsApproval(j.authority.id, "the branch was brought up to main, so its new commit needs a fresh approval", epoch)) {
+                throw new Stop("lease", "The release's approval couldn't be stopped before the update, so the branch wasn't updated.");
+            }
+            say(`  ${j.branch} is behind main: bringing it up to date`);
+            const moved = await update(j.github, j.pr, j.candidate.sha);
+            if (!moved.ok)
+                throw new Stop("drift", `${j.branch} couldn't be brought up to main: ${moved.why}. Rerun \`${resume}\`.`);
+            return waitFor("ci", `${j.branch} to move past ${j.candidate.sha.slice(0, 7)}`, async () => {
+                const head = await adapters.repo.remoteHead(j.branch);
+                return head !== null && head !== j.candidate.sha ? head : null;
+            });
+        };
+        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 (rel !== undefined && j.authority && epoch !== null) {
+            if (updated)
+                say(`  ${j.branch} is at ${head.slice(0, 7)}: a new commit, so it needs its own approval, CI and check`);
+            else if (rel !== undefined && j.authority && epoch !== null) {
                 say(`  ${j.branch} moved to ${head.slice(0, 7)}: checking whether the approval carries`);
                 const carried = await rel.carry(j.authority.id, head, randomUUID(), epoch);
                 if (carried.ok) {
@@ -693,6 +742,7 @@ export async function runRelease(options, adapters) {
                 throw error;
             }
             const verdict = prChecksVerdict(runs, j.candidate.sha, REQUIRED_PR_CHECKS, { workflow: REQUIRED_PR_CHECKS_WORKFLOW });
+            await noteCi(runs, verdict);
             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 ${releaseBranchArg(j.branch)} --repo ${j.checkout} --new\`.`);
             }
@@ -793,7 +843,17 @@ 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");
+                        try {
+                            await containsMain(adapters, j, "Nothing was filed or sent for approval");
+                        }
+                        catch (error) {
+                            if (!(error instanceof Stop) || error.reason !== "base-moved")
+                                throw error;
+                            const head = await updateFromMain();
+                            if (head === null)
+                                throw error;
+                            throw new Restart(head, true);
+                        }
                         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);
@@ -810,7 +870,7 @@ export async function runRelease(options, adapters) {
                             // 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 });
+                            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);
@@ -830,6 +890,10 @@ 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 }));
                         }
                         advance("approval");
                         break;
@@ -862,7 +926,11 @@ export async function runRelease(options, adapters) {
                         // 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)}\`.`);
                         if (j.ciAhead === true)
                             say(`  ${CI_RUNNING_WORDS}`);
                         const approved = await waitFor("approval", `a person to approve task ${j.task.id}`, async () => {
@@ -940,6 +1008,15 @@ 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)
+                                    throw new Stop("check-failed", `Run ${gate.result.run} passed on ${j.candidate.sha.slice(0, 7)}, but ${covered.why}.`);
+                                if (covered.covered > 0)
+                                    say(`  ${covered.covered} cases skipped inside the sandbox passed in this commit's macOS CI`);
+                            }
                             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 () => {
@@ -1007,7 +1084,12 @@ export async function runRelease(options, adapters) {
                         await checked(gate, "complete");
                         if (gate.completion?.digest !== check.receipt) {
                             intend("complete");
-                            const done = await adapters.toolroll.complete(j.task.id, check.receipt);
+                            // 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;
+                            });
                             if (!done.ok)
                                 throw new Stop("complete", `Couldn't mark task ${j.task.id} complete: ${done.message} Mark that exact result complete in the console, then rerun.`);
                         }
@@ -1147,7 +1229,21 @@ export async function runRelease(options, adapters) {
                                 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.
-                            const main = await containsMain(adapters, j, "Nothing was merged");
+                            let main;
+                            try {
+                                main = await containsMain(adapters, j, "Nothing was merged");
+                            }
+                            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;
+                                j.needsApproval = true;
+                                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.
@@ -1202,6 +1298,8 @@ 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;
                     }
@@ -1260,7 +1358,7 @@ export async function runRelease(options, adapters) {
             catch (error) {
                 if (!(error instanceof Restart))
                     throw error;
-                await restart(error.head);
+                await restart(error.head, error.updated);
             }
         }
         const left = homebrewLeft;
@@ -1288,6 +1386,14 @@ export async function runRelease(options, adapters) {
             }
             catch { /* the stop is still reported */ }
             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 */ }
+            }
         }
         return { ok: false, reason: stop.reason, message: stop.message, step: journal?.step ?? step, journal, file, resume };
     }
@@ -1428,6 +1534,7 @@ async function earlyChecks(adapters, j, wait, options = {}) {
                 return null;
             }
             const verdict = prChecksVerdict(runs.filter(run => required.includes(run.name)), j.candidate.sha, required, { workflow: REQUIRED_PR_CHECKS_WORKFLOW });
+            await options.seen?.(runs, verdict);
             if (verdict.state === "failed") {
                 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).`);
             }
@@ -1616,6 +1723,6 @@ export function workflowIs(path, file) {
     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"]);
+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; }

package/dist/remote-destination.d.ts

@@ -0,0 +1,36 @@
+export type Lookup = (host: string) => Promise<readonly string[]>;
+export declare const lookupAll: Lookup;
+export type Destination = {
+    scheme: "https" | "ssh";
+    host: string;
+    port: number;
+    literal: boolean;
+};
+export type Pin = {
+    /** `-c` settings for git, or nothing for ssh. */
+    gitArgs: string[];
+    /** Environment on top of remote-main.ts's ENV. */
+    env: Record<string, string>;
+    /** The proxy's host name when the read goes through the operator's proxy. */
+    proxy: string | null;
+};
+export type PinResult = {
+    ok: true;
+    pin: Pin;
+} | {
+    ok: false;
+    why: string;
+};
+/** Whether an address is loopback, unspecified, link-local, or an IPv4-mapped or NAT64 form of these. */
+export declare function addressRefused(address: string): boolean;
+/** The host, effective port and scheme a recorded URL connects to; null when it can't be read. The caller has already
+ * passed remoteUrlProblem. Node's URL parser normalizes every spelling of a literal host. */
+export declare function destinationOf(url: string): Destination | null;
+/** Whether curl would skip the proxy for this host; "unknown" when an entry can't be decided. */
+export declare function noProxyApplies(noProxy: string, host: string): boolean | "unknown";
+/**
+ * Decide the route and pin it. `env` is what git will see (the names remote-main.ts's ENV_ALLOWLIST passes). ssh never
+ * uses a proxy. Through a proxy, the proxy's own address is checked and pinned; the operator's proxy then chooses the
+ * final destination, and the caller says so.
+ */
+export declare function pinDestination(url: string, env: Readonly<Record<string, string | undefined>>, lookup?: Lookup): Promise<PinResult>;