toolroll 0.9.93 → 0.9.95

package/dist/release-cli.d.ts

@@ -8,6 +8,7 @@
 import { type ReleaseAdapters } from "./release.js";
 import { type GateReleaseWorld } from "./release-gate.js";
 import { type RescueWorld } from "./deploy-rescue.js";
+import { type RunLockSeams, type SettleWorld } from "./release-next.js";
 export declare const RELEASE_HELP: string;
 /** A runner lease id (claim.ts mints randomUUID()). */
 export declare const LEASE_SHAPED: RegExp;
@@ -23,6 +24,9 @@ export type ReleaseCliDeps = {
     gateWorld?: GateReleaseWorld;
     /** What --recover-deploy reads and runs (deploy-rescue.ts); the installation's own by default. */
     rescueWorld?: RescueWorld;
+    /** What a stopped deployment left, settled before the release goes on (release-next.ts). Tests that inject adapters skip it. */
+    settle?: SettleWorld;
+    runLock?: RunLockSeams;
     /** The plane's database for the authority commands (default: this installation's). */
     database?: string;
     now?: () => Date;

package/dist/release-cli.js

@@ -16,6 +16,7 @@ import { RELEASE_LIMITS, runRelease } from "./release.js";
 import { processes, releaseAdapters } from "./release-adapters.js";
 import { journals, releaseGate } from "./release-gate.js";
 import { rescueDeployment } from "./deploy-rescue.js";
+import { settleDeployment, takeReleaseRun } from "./release-next.js";
 import { databasePath, elapsedSeconds, latestReleaseStepTask, openStore, releaseProgressFor, revokeRelease } from "./store.js";
 import { dur } from "./design/kit.js";
 import { carryRefusalWords, proveCarry, setAskEveryReleaseCommit, setUnsandboxedCarry } from "./release-carry.js";
@@ -34,7 +35,10 @@ export const RELEASE_HELP = `toolroll release <branch> — release Toolroll itse
   squash-merges, deletes the matching remote branch, verifies the merged tree and tags. Both macOS legs gate npm
   publication; Homebrew waits for its checks to register and all pass before merging.
 
-  Run the same command to resume after a stop. Interrupted deployments recover their saved stage before retrying.
+  Run the same command to go on after any stop. It reads where the release got to and does the one thing that's next:
+  finishes a deployment forward, puts one back, lifts a pause left before a swap, waits for another run of the release
+  (naming its computer and process), or waits for your approval. It says what it did. A branch behind main is brought up
+  to date for you; that new commit needs its own approval, CI and check.
 
   A branch whose name is one of this command's own words (approve, status, nightly, carry…) is named with --branch <name>
   or after --: \`toolroll release --branch status\`.
@@ -47,19 +51,6 @@ toolroll release approve [<branch>] [--repo <path>] — approve the release wait
 toolroll release status [<task>] — the steps of a release (the newest one recorded, or the release task named): each
   step's state and how long it took, and where it stopped
 
-toolroll release --release-gate <id> [--yes] — lift the update pause a deployment left before its swap
-
-  Shows why it is safe first: the pause is that deployment's, its journal stopped before the swap, and the
-  database, service definition and running service are all still the previous build's. --yes lifts that one pause.
-  Any missing or contradicting evidence refuses and leaves the pause in place.
-
-toolroll release --recover-deploy [--stage <dir>] [--yes] — put back a deployment that stopped half way
-
-  Finds the one unfinished deployment (or the stage named) and shows what its recovery will do; --yes does it. When
-  the old service isn't proved stopped, it boots the service out and stops what it left running, but only processes
-  proved, by exact runtime path and arguments, to be that deployment's own; then it starts the previous service
-  again, waits for it, and lifts the update pause. Anything it can't prove refuses. Safe to run again.
-
 toolroll release carry <release> --to <commit> [--request <id>] — carry a person's release approval to a later commit
 
   Only tests, docs and the changelog may change after the approval, within the limits, with an identical production
@@ -100,10 +91,6 @@ Options
   --new                  release a new commit on the branch, setting the earlier unfinished release aside
   --limit <step>=<min>   change one step's time limit (${Object.entries(RELEASE_LIMITS).map(([step, minutes]) => `${step} ${minutes}`).join(", ")})
   --tap <owner/name>     the Homebrew tap (default ap9000/homebrew-toolroll)
-  --release-gate <id>    check (and with --yes, lift) one update pause left before a deployment's swap
-  --yes                  with --release-gate: lift the pause once it is proved safe; with --recover-deploy: recover
-  --recover-deploy       recover the unfinished deployment (see above)
-  --stage <dir>          with --recover-deploy: the deployment's staging folder, when more than one is unfinished
   --json                 answer with one machine envelope
 
 A runner's lease is returned with \`toolroll worker release <lease>\`.`;
@@ -270,8 +257,23 @@ export async function runReleaseCommand(args, write, deps = {}) {
     const adapters = deps.adapters === undefined
         ? releaseAdapters({ checkout, say, ...(tap === undefined ? {} : { tap }), ...(limits["deploy"] === undefined ? {} : { deployMinutes: limits["deploy"] }) })
         : { ...deps.adapters, say };
-    const outcome = await runRelease({ branch, checkout, stateDir, limits, fresh: bare.has("--new"), noCarry: bare.has("--no-carry") }, adapters);
-    return report(outcome, write, json, lines);
+    // One command: wait out another run of this release, settle what a stopped deployment left, then go on from the journal.
+    const taken = await takeReleaseRun(stateDir, branch, say, deps.runLock);
+    if (!taken.ok)
+        return refuse("running", `Another release of ${branch} is still running on ${taken.holder.host} (process ${taken.holder.pid}). Nothing was changed.`, 3);
+    try {
+        const world = deps.settle ?? (deps.adapters === undefined ? { rescue: installedRescueWorld(checkout), gate: installedGateWorld() } : null);
+        if (world !== null) {
+            const settled = await settleDeployment(world, say);
+            if (!settled.ok)
+                return refuse("deployment", settled.message, 3);
+        }
+        const outcome = await runRelease({ branch, checkout, stateDir, limits, fresh: bare.has("--new"), noCarry: bare.has("--no-carry") }, adapters);
+        return report(outcome, write, json, lines);
+    }
+    finally {
+        taken.release();
+    }
 }
 function report(outcome, write, json, lines) {
     const release = outcome.journal === null ? null : {
@@ -590,10 +592,15 @@ async function runStatusCommand(task, write, json, deps) {
         }
         const word = { running: "running", waiting: "waiting", done: "done", failed: "failed" };
         write(`Release ${progress.version} (${progress.tag})${progress.pr === null ? "" : ` · pull request #${progress.pr}`} · task ${taskId}`);
-        for (const one of steps)
-            write(`  ${one.step.padEnd(9)} ${word[one.state].padEnd(8)} ${one.seconds === null ? "–" : dur(one.seconds)}${one.detail === null ? "" : `  ${one.detail}`}`);
+        for (const one of steps) {
+            // A failure the release has gone on from is history, as on the task page.
+            const passed = one.state === "failed" && progress.stopped === null;
+            write(`  ${one.step.padEnd(9)} ${(passed ? "went on" : word[one.state]).padEnd(8)} ${one.seconds === null ? "–" : dur(one.seconds)}${one.detail === null ? "" : `  ${one.detail}`}`);
+        }
         if (progress.stopped !== null)
             write(`Stopped at ${progress.stopped.step}: ${progress.stopped.message}`);
+        if (progress.building !== null)
+            write(`Build #${progress.building.run} is running the check.`);
         return 0;
     }
     finally {

package/dist/release-coverage.js

@@ -26,7 +26,7 @@ export const gitIsAncestor = (repo, ancestor, descendant) => {
     let answer;
     try {
         // Every git version through a frozen read view, bounded (eval-harness review 1, finding 7).
-        const status = viewedGitSync(repo, ["merge-base", "--is-ancestor", ancestor, descendant], { timeoutMs: 5_000 }).status;
+        const status = viewedGitSync(repo, ["merge-base", "--is-ancestor", ancestor, descendant], { timeoutMs: 5_000, binding: { repo } }).status;
         if (status !== 0)
             throw Object.assign(new Error("git merge-base"), { status });
         answer = true;

package/dist/release-next.d.ts

@@ -0,0 +1,48 @@
+import { type RescueWorld } from "./deploy-rescue.js";
+import { type GateReleaseWorld } from "./release-gate.js";
+import { type ReleaseJournal } from "./release.js";
+import type { Store } from "./store.js";
+/** How long a run waits for another before it says so and stops. */
+export declare const RELEASE_WAIT_MS: number;
+export type RunHolder = {
+    host: string;
+    pid: number;
+};
+export type RunLockSeams = {
+    host?: string;
+    pid?: number;
+    alive?: (pid: number) => boolean;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    waitMs?: number;
+    pollMs?: number;
+};
+/** Take this branch's run lock, waiting for a live holder. Answers how to give it back, or who kept it. */
+export declare function takeReleaseRun(stateDir: string, branch: string, say: (line: string) => void, seams?: RunLockSeams): Promise<{
+    ok: true;
+    release: () => void;
+} | {
+    ok: false;
+    holder: RunHolder;
+}>;
+export type SettleWorld = {
+    rescue: RescueWorld;
+    gate: GateReleaseWorld;
+};
+export type DeployAction = "none" | "lift-pause" | "forward" | "roll-back" | "refuse";
+/** The one action a deployment's journal calls for. */
+export declare function deployActionOf(phase: unknown): DeployAction;
+/** Settle what a stopped deployment left, saying what was done. A refusal stops the release before it does anything. */
+export declare function settleDeployment(world: SettleWorld, say: (line: string) => void): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+}>;
+export declare 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 declare function resumeAllowedReleases(store: Store, stateDir: string, run: (journal: ReleaseJournal) => Promise<unknown>, now: Date): Promise<number>;

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,15 @@ 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;
@@ -536,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

@@ -93,6 +93,8 @@ 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",
 };
 /** 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
@@ -101,8 +103,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 +133,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. */
@@ -244,6 +251,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) => {
@@ -317,6 +326,8 @@ export async function runRelease(options, adapters) {
             say(`Kept the earlier release journal at ${aside}.`);
             freshApproval = journal.needsApproval === true;
             supersededTask = journal.task.id;
+            if (journal.stopped?.reason === "check-failed")
+                stoppedCheck = journal.candidate.sha;
             journal = null;
         }
         if (journal?.step === "done") {
@@ -331,8 +342,10 @@ export async function runRelease(options, adapters) {
             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) {
+            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;
                 let picked = null;
@@ -626,11 +639,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) {
@@ -808,7 +851,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);
@@ -963,6 +1016,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 () => {
@@ -1175,7 +1237,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.
@@ -1290,7 +1366,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;

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>;