toolroll 0.9.77 → 0.9.78

package/dist/release-adapters.js

@@ -575,7 +575,7 @@ export function releaseAdapters(options) {
                 return prs.find(one => one.state === "open") ?? prs.filter(one => one.state === "merged").sort((a, b) => b.number - a.number)[0] ?? null;
             },
             // Every attempt (filter=all), with its app, check suite and commit: the release judges each job by its latest attempt.
-            async checks(repo, sha) { return readCheckRuns(run, ciGh, repo, sha); },
+            async checks(repo, sha, options) { return readCheckRuns(run, ciGh, repo, sha, options); },
             async complete(repo, sha) { return readSuitesComplete(run, ciGh, repo, sha); },
             async mainHead(repo) { return readMainHead(run, ciGh, repo); },
             async contains(repo, sha, ancestor) { return readContains(run, ciGh, repo, sha, ancestor); },
@@ -653,8 +653,16 @@ export function releaseAdapters(options) {
                 const current = await formulaAt(branch);
                 if (current.text.includes(`-${version}.tgz`))
                     return { kind: "current" };
-                const open = (await ghJson("gh pr list", "pr", "list", "--repo", tap, "--head", brewBranch(version), "--state", "open", "--json", "number,headRefOid"));
-                const pr = open[0];
+                // Ordering (pipeline-speed.md, P1): a tap already on a later version is never moved back by an older release.
+                const named = formulaVersion(current.text);
+                if (named !== null && versionAfter(named, version))
+                    return { kind: "newer", version: named };
+                // Only a change from the tap's own branch counts: a fork's pull request of the same branch name never does.
+                const open = (await ghJson("gh pr list", "pr", "list", "--repo", tap, "--head", brewBranch(version), "--state", "open", "--json", "number,headRefOid,headRepository,headRepositoryOwner,isCrossRepository"));
+                const own = open.filter(one => tapOwnHead(one, tap));
+                if (own.length > 1)
+                    throw new Error(`${tap} has ${own.length} open changes for ${brewBranch(version)}`);
+                const pr = own[0];
                 return pr === undefined ? { kind: "missing" } : { kind: "proposed", pr: Number(pr["number"]), head: String(pr["headRefOid"]) };
             },
             async propose(version) {
@@ -664,14 +672,20 @@ export function releaseAdapters(options) {
                     throw new Error(`downloading ${tarball} answered ${response.status}`);
                 const sha256 = createHash("sha256").update(Buffer.from(await response.arrayBuffer())).digest("hex");
                 const base = await defaultBranch();
-                const current = await formulaAt(base);
+                const baseSha = String(object(object(await ghJson("gh api git/ref", "api", `repos/${tap}/git/ref/heads/${base}`))["object"])["sha"]);
+                const current = await formulaAt(baseSha);
+                const baseVersion = formulaVersion(current.text);
+                if (baseVersion === null || versionAfter(baseVersion, version))
+                    throw new Error("The tap current version is unreadable or newer; no downgrade was proposed.");
                 const next = bumpFormula(current.text, tarball, sha256);
                 const branch = brewBranch(version);
-                const baseSha = String(object(object(await ghJson("gh api git/ref", "api", `repos/${tap}/git/ref/heads/${base}`))["object"])["sha"]);
                 // A branch left by an earlier attempt is reused.
                 const made = await gh("api", "-X", "POST", `repos/${tap}/git/refs`, "-f", `ref=refs/heads/${branch}`, "-f", `sha=${baseSha}`);
                 if (made.code !== 0 && !/Reference already exists/.test(made.stderr + made.stdout))
                     throw new Error(`creating ${tap} ${branch}: ${made.stderr.trim()}`);
+                // A branch left by an earlier attempt starts again from the base (security scan): none of its history is kept.
+                if (made.code !== 0)
+                    await must(gh("api", "-X", "PATCH", `repos/${tap}/git/refs/heads/${branch}`, "-f", `sha=${baseSha}`, "-F", "force=true"), `resetting ${tap} ${branch}`);
                 const onBranch = await formulaAt(branch);
                 if (onBranch.text !== next) {
                     await must(gh("api", "-X", "PUT", `repos/${tap}/contents/${formula}`, "-f", `message=toolroll ${version}`, "-f", `branch=${branch}`, "-f", `sha=${onBranch.sha}`, "-f", `content=${Buffer.from(next).toString("base64")}`), `updating ${formula}`);
@@ -680,6 +694,24 @@ export function releaseAdapters(options) {
                 const opened = (await ghJson("gh pr view", "pr", "view", branch, "--repo", tap, "--json", "number,headRefOid"));
                 return { pr: Number(opened["number"]), head: String(opened["headRefOid"]) };
             },
+            async verified(pr, head, version) {
+                // The change at exactly `head` is the tap's own, and its formula is exactly today's formula with npm's published
+                // tarball and that tarball's own sha256: nothing else is ever merged.
+                const view = object(await ghJson("gh pr view", "pr", "view", String(pr), "--repo", tap, "--json", "number,headRefOid,headRefName,baseRefName,headRepository,headRepositoryOwner,isCrossRepository,state"));
+                const base = await defaultBranch();
+                const baseHead = String(object(object(await ghJson("gh api git/ref", "api", `repos/${tap}/git/ref/heads/${base}`))["object"])["sha"]);
+                // The whole change against the tap's default branch head: its merge base, its commits and every file it touches.
+                const compare = object(await ghJson("gh api compare", "api", `repos/${tap}/compare/${encodeURIComponent(baseHead)}...${encodeURIComponent(head)}`));
+                const tarball = `https://registry.npmjs.org/toolroll/-/toolroll-${version}.tgz`;
+                const response = await get(tarball, { signal: AbortSignal.timeout(60_000) });
+                if (!response.ok)
+                    return { ok: false, why: `downloading ${tarball} answered ${response.status}` };
+                const sha256 = createHash("sha256").update(Buffer.from(await response.arrayBuffer())).digest("hex");
+                const current = (await formulaAt(baseHead)).text;
+                const expected = bumpFormula(current, tarball, sha256);
+                const problem = tapChangeProblem({ tap, pr, head, version, formula, defaultBranch: base, baseHead, baseVersion: formulaVersion(current), view, compare, expected, atHead: (await formulaAt(head)).text, sha256 });
+                return problem === null ? { ok: true } : { ok: false, why: problem };
+            },
             async merge(pr, head) {
                 const merged = object(await ghJson(`merging ${tap} #${pr}`, "api", "-X", "PUT", `repos/${tap}/pulls/${pr}/merge`, "-f", "merge_method=squash", "-f", `sha=${head}`));
                 if (merged["merged"] !== true || typeof merged["sha"] !== "string")
@@ -696,6 +728,58 @@ export function releaseAdapters(options) {
     }
 }
 const brewBranch = (version) => `toolroll-${version}`;
+/**
+ * Why a tap change isn't exactly the formula bump this release proposed (security scan), or null when it is: the tap's
+ * own open pull request number `pr` at exactly `head`, from its version branch into the default branch; compared with
+ * the default branch's head it is one commit on top of exactly that head, changing exactly one file, the formula; and
+ * the formula there is exactly today's with npm's published tarball and that tarball's own sha256.
+ */
+export function tapChangeProblem(input) {
+    const { tap, pr, head, version, view, compare } = input;
+    // State may have changed since the coordinator checked it. Judge the immutable base used for this comparison.
+    if (input.baseVersion === null)
+        return `${tap} current version cannot be read`;
+    if (versionAfter(input.baseVersion, version))
+        return `${tap} already names newer ${input.baseVersion}; refusing ${version}`;
+    if (Number(view["number"]) !== pr || view["headRefOid"] !== head || view["headRefName"] !== brewBranch(version) || view["state"] !== "OPEN" || !tapOwnHead(view, tap)) {
+        return `${tap} #${pr} isn't the tap's own open change at ${head.slice(0, 7)}`;
+    }
+    if (view["baseRefName"] !== input.defaultBranch)
+        return `${tap} #${pr} merges into ${String(view["baseRefName"])}, not ${input.defaultBranch}`;
+    const mergeBase = compare["merge_base_commit"] !== null && typeof compare["merge_base_commit"] === "object" ? compare["merge_base_commit"]["sha"] : undefined;
+    if (mergeBase !== input.baseHead)
+        return `${tap} #${pr} isn't on ${input.defaultBranch}'s head ${input.baseHead.slice(0, 7)}`;
+    if (compare["status"] !== "ahead" || compare["ahead_by"] !== 1 || compare["behind_by"] !== 0)
+        return `${tap} #${pr} isn't exactly one commit on ${input.defaultBranch}'s head`;
+    const files = Array.isArray(compare["files"]) ? compare["files"] : null;
+    if (files === null || files.length !== 1 || files[0]["filename"] !== input.formula || files[0]["status"] !== "modified")
+        return `${tap} #${pr} changes more than ${input.formula}`;
+    if (input.atHead !== input.expected)
+        return `${tap} #${pr}'s formula isn't npm's ${version} tarball with its sha256 ${input.sha256.slice(0, 12)}`;
+    return null;
+}
+/** Whether a pull request's head is a branch of the tap itself (never a fork's). */
+export function tapOwnHead(pr, tap) {
+    const [owner, name] = tap.split("/");
+    const repo = pr["headRepository"], who = pr["headRepositoryOwner"];
+    const repoName = repo !== null && typeof repo === "object" ? repo["name"] : undefined;
+    const ownerLogin = who !== null && typeof who === "object" ? who["login"] : undefined;
+    return pr["isCrossRepository"] === false && typeof repoName === "string" && typeof ownerLogin === "string"
+        && repoName.toLowerCase() === (name ?? "").toLowerCase() && ownerLogin.toLowerCase() === (owner ?? "").toLowerCase();
+}
+/** The version a formula's tarball url names (`…/toolroll-<x.y.z>.tgz`), or null. */
+export function formulaVersion(text) {
+    const found = /^\s*url "[^"]*-(\d+\.\d+\.\d+)\.tgz"/m.exec(text);
+    return found === null ? null : found[1];
+}
+/** Whether version `a` comes after `b` (both x.y.z). */
+export function versionAfter(a, b) {
+    const pa = a.split(".").map(Number), pb = b.split(".").map(Number);
+    for (let i = 0; i < 3; i++)
+        if ((pa[i] ?? 0) !== (pb[i] ?? 0))
+            return (pa[i] ?? 0) > (pb[i] ?? 0);
+    return false;
+}
 /** The events that put checks on a change. */
 const CHANGE_EVENTS = new Set(["pull_request", "pull_request_target", "push", "merge_group"]);
 /**
@@ -918,7 +1002,11 @@ function ciEnv() {
  * lists only the latest of each), every page — with its id, app, check suite and the commit it is filed under, oldest
  * first. A row that doesn't parse stops the read: a partial answer is never taken for the whole.
  */
-export async function readCheckRuns(run, gh, repo, sha) {
+export async function readCheckRuns(run, gh, repo, sha, 
+/** A release tag (pipeline-speed.md, item 3): a push of exactly this tag binds its workflow file too. */
+options = {}) {
+    if (options.tag !== undefined && !/^v\d+\.\d+\.\d+$/.test(options.tag))
+        throw new Error("not a release tag");
     if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || !/^[0-9a-f]{40}$/.test(sha))
         throw new Error("not a repository and commit GitHub can be asked about");
     const out = await must(run(gh, ["api", "--hostname", "github.com", "--paginate", `repos/${repo}/commits/${sha}/check-runs?filter=all&per_page=100`,
@@ -964,7 +1052,7 @@ export async function readCheckRuns(run, gh, repo, sha) {
         const prs = (Array.isArray(one["prs"]) ? one["prs"] : []).map(pr => (pr !== null && typeof pr === "object" ? pr : {}));
         const ours = prs.length > 0 && prs.every(pr => Number.isSafeInteger(pr["number"]) && pr["repo"] === `https://api.github.com/repos/${repo}`);
         const untouched = one["event"] !== "pull_request" || (ours && !(await Promise.all(prs.map(pr => everRetargeted(Number(pr["number"]))))).some(Boolean));
-        if (mainTriggered(one) && untouched)
+        if ((options.tag === undefined ? mainTriggered(one) : tagTriggered(one, options.tag)) && untouched)
             pathOf.set(Number(one["suite"]), String(one["path"]));
     }
     const runs = out.split("\n").filter(Boolean).map(line => {
@@ -1227,6 +1315,10 @@ export async function readUpToDateRequired(run, gh, repo, branch = "main") {
     const protection = await readMainProtection(run, gh, repo, branch);
     return protection === null ? null : protection.effective;
 }
+/** Whether a workflow run is the push of exactly this release tag (its workflow file is the tagged commit's own, on main). */
+function tagTriggered(run, tag) {
+    return tag !== undefined && run["event"] === "push" && run["branch"] === tag;
+}
 /** Whether a workflow run was triggered on main: a push to main, or a pull request whose every base is main. */
 function mainTriggered(run) {
     const bases = Array.isArray(run["bases"]) ? run["bases"] : [];

package/dist/release-carry.d.ts

@@ -1,5 +1,5 @@
 import { type TreeChange, type VerifiedCommit } from "./commit-extract.js";
-import { type ReleasePolicy, type ReleaseTerms } from "./contracts/release-terms.js";
+import { type ReleaseCheckPurpose, type ReleasePolicy, type ReleaseTerms } from "./contracts/release-terms.js";
 import { type ExecResult } from "./exec.js";
 import { type ReleaseAuthority, type ReleaseCarry, type Store } from "./store.js";
 /** The journey scripts: tests, by Alex's decision (they carry). */
@@ -66,6 +66,26 @@ export declare function releaseTermsFor(store: Store, input: {
     ok: false;
     why: string;
 };
+/**
+ * A release check's purpose (docs/plans/pipeline-speed.md, P0), for a release whose terms can't be made (its checks run
+ * outside the sandbox, or carrying is off): from the plane's own records — the project's repository, the approved commit
+ * and its verified tree, the live release check grant and the check access. It never carries a later commit; it marks
+ * this exact candidate as a release's check (strict report rules, no CI stand-in, the plane's own rerun after confirmed
+ * infrastructure on the same candidate under the same approval). Null with why when even that can't be read.
+ */
+export declare function releaseCheckPurposeFor(store: Store, input: {
+    repo: string;
+    version: string;
+    branch: string;
+    pr: number;
+    candidate: string;
+}): {
+    ok: true;
+    purpose: ReleaseCheckPurpose;
+} | {
+    ok: false;
+    why: string;
+};
 /** One carried commit, as the summary and the merge message list it. */
 export type LandedCommit = {
     sha: string;

package/dist/release-carry.js

@@ -165,6 +165,28 @@ export function releaseTermsFor(store, input) {
             expiresAt: new Date(input.now.getTime() + 3 * 24 * 60 * 60_000).toISOString(),
         } };
 }
+/**
+ * A release check's purpose (docs/plans/pipeline-speed.md, P0), for a release whose terms can't be made (its checks run
+ * outside the sandbox, or carrying is off): from the plane's own records — the project's repository, the approved commit
+ * and its verified tree, the live release check grant and the check access. It never carries a later commit; it marks
+ * this exact candidate as a release's check (strict report rules, no CI stand-in, the plane's own rerun after confirmed
+ * infrastructure on the same candidate under the same approval). Null with why when even that can't be read.
+ */
+export function releaseCheckPurposeFor(store, input) {
+    const gitDir = projectGitDir(input.repo);
+    if (gitDir === null)
+        return { ok: false, why: "the project's Git directory can't be read" };
+    const commit = readVerifiedCommit(gitDir, input.candidate);
+    if (!commit.ok)
+        return { ok: false, why: commit.message };
+    const grant = store.liveVerifyCommand(input.repo);
+    if (grant === null)
+        return { ok: false, why: "the project has no approved release check" };
+    return { ok: true, purpose: {
+            version: 1, purpose: "release-check", repo: input.repo, packageVersion: input.version, branch: input.branch, pr: input.pr, base: "main",
+            approvedSha: input.candidate, approvedTree: commit.value.tree, grant: { id: grant.id, digest: grant.digest }, access: store.projectCheckAccess(input.repo),
+        } };
+}
 /**
  * Step 2, read-only: nothing from the candidate is installed, built or run here. Objects come from the project's own
  * Git directory as Toolroll records it, hashed here; the authority is read live.

package/dist/release-cli.d.ts

@@ -7,6 +7,7 @@
  */
 import { type ReleaseAdapters } from "./release.js";
 import { type GateReleaseWorld } from "./release-gate.js";
+import { type RescueWorld } from "./deploy-rescue.js";
 export declare const RELEASE_HELP: string;
 /** A runner lease id (claim.ts mints randomUUID()). */
 export declare const LEASE_SHAPED: RegExp;
@@ -20,6 +21,8 @@ export type ReleaseCliDeps = {
     warn?: (line: string) => void;
     /** What --release-gate reads and changes (release-gate.ts); the installation's own by default. */
     gateWorld?: GateReleaseWorld;
+    /** What --recover-deploy reads and runs (deploy-rescue.ts); the installation's own by default. */
+    rescueWorld?: RescueWorld;
     /** The plane's database for the authority commands (default: this installation's). */
     database?: string;
     now?: () => Date;

package/dist/release-cli.js

@@ -14,7 +14,8 @@ const sqlite = () => createRequire(import.meta.url)("node:sqlite");
 import { checkedEnvelopeJson } from "./contracts/cli.js";
 import { RELEASE_LIMITS, runRelease } from "./release.js";
 import { processes, releaseAdapters } from "./release-adapters.js";
-import { releaseGate } from "./release-gate.js";
+import { journals, releaseGate } from "./release-gate.js";
+import { rescueDeployment } from "./deploy-rescue.js";
 import { databasePath, openStore, revokeRelease } from "./store.js";
 import { carryRefusalWords, proveCarry, setAskEveryReleaseCommit, setUnsandboxedCarry } from "./release-carry.js";
 import { authenticateApprover, machineActing, personProof, proveCredential } from "./scope.js";
@@ -39,6 +40,13 @@ toolroll release --release-gate <id> [--yes] — lift the update pause a deploym
   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
@@ -74,15 +82,17 @@ Options
   --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
+  --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>\`.`;
 /** A runner lease id (claim.ts mints randomUUID()). */
 export const LEASE_SHAPED = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export const LEASE_DEPRECATION = "`toolroll release <lease>` is now `toolroll worker release <lease>`; the old form goes in the next minor version.";
-const VALUE_FLAGS = new Set(["--repo", "--limit", "--tap", "--release-gate", "--to", "--request", "--as", "--token", "--schedule"]);
-const BARE_FLAGS = new Set(["--new", "--json", "--help", "--yes", "--no-carry", "--start"]);
+const VALUE_FLAGS = new Set(["--repo", "--limit", "--tap", "--release-gate", "--to", "--request", "--as", "--token", "--schedule", "--stage"]);
+const BARE_FLAGS = new Set(["--new", "--json", "--help", "--yes", "--no-carry", "--start", "--recover-deploy"]);
 export async function runReleaseCommand(args, write, deps = {}) {
     // The flag, not a secret's value that happens to read "--json".
     // A secret is never exactly one of these names (the loop below refuses that as a missing value).
@@ -94,6 +104,7 @@ export async function runReleaseCommand(args, write, deps = {}) {
     };
     const positional = [];
     const limits = {};
+    let stage;
     let repo, tap, gate, to, request, as, token, scheduleFlag;
     for (let i = 0; i < args.length; i += 1) {
         const raw = args[i];
@@ -126,6 +137,8 @@ export async function runReleaseCommand(args, write, deps = {}) {
                 tap = value;
             else if (arg === "--release-gate")
                 gate = value;
+            else if (arg === "--stage")
+                stage = value;
             else {
                 const match = /^([a-z]+)=([0-9]+)$/.exec(value);
                 if (match === null || !(match[1] in RELEASE_LIMITS) || Number(match[2]) < 1)
@@ -147,8 +160,15 @@ export async function runReleaseCommand(args, write, deps = {}) {
             return refuse("usage", "--release-gate <id> takes no branch or release options.", 2);
         return runGateRelease(gate, bare.has("--yes"), write, json, deps.gateWorld ?? installedGateWorld());
     }
+    if (bare.has("--recover-deploy")) {
+        if (positional.length > 0 || args.some(arg => ["--repo", "--limit", "--tap", "--new", "--release-gate"].includes(arg.split("=")[0])))
+            return refuse("usage", "--recover-deploy takes only --stage <dir>, --yes and --json.", 2);
+        return runRescue(stage, bare.has("--yes"), write, json, deps.rescueWorld ?? installedRescueWorld(deps.cwd ?? process.cwd()));
+    }
+    if (stage !== undefined)
+        return refuse("usage", "--stage goes with --recover-deploy.", 2);
     if (bare.has("--yes"))
-        return refuse("usage", "--yes goes with --release-gate <id>; a release needs no confirmation beyond the owner's approval.", 2);
+        return refuse("usage", "--yes goes with --release-gate <id> or --recover-deploy; a release needs no confirmation beyond the owner's approval.", 2);
     if (positional[0] === "nightly" && positional.length === 1)
         return runNightlyCommand({ repo: repo === undefined ? undefined : resolve(deps.cwd ?? process.cwd(), repo), as, token, schedule: scheduleFlag, start: bare.has("--start") }, write, json, deps);
     if (["carry", "revoke", "ask-every-commit", "unsandboxed-carry", "auto-approve", "publish-ok"].includes(positional[0] ?? "") && positional.length === 2) {
@@ -217,6 +237,55 @@ function installedGateWorld() {
             .filter(path => existsSync(path)).map(path => ({ path, text: readFileSync(path, "utf8") })),
     };
 }
+/** The installation's deployments, its plane's records and the release's own recovery road, for --recover-deploy. */
+function installedRescueWorld(cwd) {
+    const database = databasePath(process.env, homedir());
+    const stateDir = dirname(database);
+    const adapters = releaseAdapters({ checkout: cwd, say: line => process.stderr.write(`${line}\n`) });
+    return {
+        database, stateDir,
+        journals: () => journals(stateDir),
+        runWorktree: run => {
+            if (!existsSync(database))
+                return null;
+            const db = new (sqlite().DatabaseSync)(database, { readOnly: true });
+            try {
+                const row = db.prepare("SELECT worktree FROM run WHERE id = ?").get(run);
+                return typeof row?.["worktree"] === "string" && row["worktree"] !== "" ? row["worktree"] : null;
+            }
+            catch {
+                return null;
+            }
+            finally {
+                db.close();
+            }
+        },
+        recover: async (input) => {
+            const answer = await adapters.toolroll.recoverDeploy(input);
+            return answer.ok ? { ok: true } : { ok: false, message: answer.message };
+        },
+    };
+}
+async function runRescue(stage, yes, write, json, world) {
+    let outcome;
+    try {
+        outcome = await rescueDeployment(stage, yes, world);
+    }
+    catch (error) {
+        outcome = { ok: false, reason: "failed", message: `${error.message} Run \`toolroll release --recover-deploy --yes\` again once the cause is fixed.` };
+    }
+    if (!outcome.ok) {
+        write(json ? checkedEnvelopeJson({ ok: false, command: "release", reason: outcome.reason, message: outcome.message }) : `✗ ${outcome.message}`);
+        return outcome.reason === "usage" ? 2 : 3;
+    }
+    if (json) {
+        write(checkedEnvelopeJson({ ok: true, command: "release", recovery: { acted: outcome.acted, stage: outcome.stage, phase: outcome.phase, said: outcome.words } }));
+        return 0;
+    }
+    for (const line of outcome.words)
+        write(outcome.acted ? `✓ ${line}` : line);
+    return 0;
+}
 function runGateRelease(id, yes, write, json, world) {
     let outcome;
     try {

package/dist/release-gate.d.ts

@@ -61,6 +61,11 @@ export type GateProof = {
 };
 /** The owner id written into the live pause's triggers, when there is one pause and it names one id. */
 export declare function gateOwner(db: Database): string | null;
+/** Every deployment journal under staged-upgrades/: the stage it is in and what it holds, or why it can't be read. */
+export declare function journals(stateDir: string): {
+    stage: string;
+    journal: Record<string, unknown> | null;
+}[];
 /** Whether the pause owned by `id` was left by a deployment that never began its swap, and the evidence that says so. */
 export declare function proveBeforeSwap(id: string, world: GateReleaseWorld): GateProof;
 export type GateReleaseOutcome = {

package/dist/release-gate.js

@@ -36,7 +36,7 @@ export function gateOwner(db) {
     return ids.size === 1 ? [...ids][0] : null;
 }
 /** Every deployment journal under staged-upgrades/: the stage it is in and what it holds, or why it can't be read. */
-function journals(stateDir) {
+export function journals(stateDir) {
     const root = join(stateDir, "staged-upgrades");
     let stages = [];
     try {

package/dist/release-recheck.js

@@ -25,7 +25,7 @@ import { readVerifiedCommit, verifiedTreeDiff } from "./commit-extract.js";
 import { checkContextSchema, fileIdentity, groupIdentity, journeyIdentity, obligationSnapshotSchema, readCheckReport, sealedInventorySchema, targetedPlanSchema, unitIdentity, versionIdentity, } from "./contracts/release-check.js";
 import { parseContract } from "./contracts/contract.js";
 import { releaseAuthority, releaseAuthorityOfTask, releaseCarries } from "./release-authority.js";
-import { liveReleaseOf } from "./scope.js";
+import { liveReleaseOf, releaseCheckScope } from "./scope.js";
 import { checkAttemptOf } from "./store.js";
 /** The sanity pass every targeted check runs beside its plan: a few fast tests of the core rules, when the tree has them. */
 export const SANITY_UNITS = Object.freeze(["src/scope.test.ts", "src/contract.test.ts", "src/check-report.test.ts", "src/update-safe-migrations.test.ts"]);
@@ -485,7 +485,8 @@ export function settleCoverage(store, root, input, gateOf) {
         }
         // A release's Full check (its task carries signed release terms, before or after its authority opens — an automatic
         // approval's check runs before) counts only with a complete, valid result (check-report.ts): anything less is no result.
-        const release = b.attempt.authority !== null || (store.getScope(input.taskId)?.releaseTerms ?? null) !== null;
+        // A release check purpose (pipeline-speed.md, P0) counts too: a termsless release is held to the same rules.
+        const release = b.attempt.authority !== null || releaseCheckScope(store.getScope(input.taskId));
         if (release && fullCheckProblem({ report: b.report, inventory: b.inventory, exitCode: input.exitCode }) !== null)
             return { coverage: "no-result", composed: null };
         return { coverage: "full", composed: null };

package/dist/release.d.ts

@@ -34,7 +34,7 @@
  */
 /** 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 declare const REQUIRED_PR_CHECKS: readonly ["node 22 · ubuntu-latest", "node 24 · ubuntu-latest", "linux native containment · delegated cgroup v2", "linux fence · sandbox-runtime", "Windows Job Object containment", "git 2.41 · debian trixie", "git 2.47 · debian trixie"];
+export declare const REQUIRED_PR_CHECKS: readonly ["node 22 · ubuntu-latest", "node 24 · ubuntu-latest", "linux native containment · delegated cgroup v2", "linux fence · sandbox-runtime", "Windows Job Object containment", "git 2.41 · debian trixie", "git 2.47 · debian trixie", "node 22 · macos-latest", "node 24 · macos-latest"];
 /** 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 declare const REQUIRED_PR_CHECKS_WORKFLOW = ".github/workflows/ci.yml";
@@ -57,8 +57,11 @@ export type MainProtection = {
     missing: string[];
     notYetRequired: string[];
 };
-/** The checks a release tag runs (.github/workflows/publish.yml), awaited before Homebrew moves. */
-export declare const RELEASE_TAG_CHECKS: readonly ["node 22 · macos-latest", "node 24 · macos-latest", "publish"];
+/** The checks a release's publication waits for on its tag (.github/workflows/publish.yml, pipeline-speed.md item 3):
+ * the publish job and the macOS legs it needs, each named. Nothing else reported on the merge commit (main's own CI push
+ * run) holds publication. */
+export declare const RELEASE_TAG_CHECKS: readonly ["publish", "tag macOS · node 22", "tag macOS · node 24"];
+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";
@@ -170,6 +173,8 @@ export type DeployStop = {
         phase: string;
     };
 };
+/** The tap's formula for a version: current, a proposal open, missing — or `newer`: the tap's default branch already
+ * names a later version, which an older release must never overwrite. */
 export type HomebrewState = {
     kind: "current";
 } | {
@@ -178,7 +183,14 @@ export type HomebrewState = {
     head: string;
 } | {
     kind: "missing";
+} | {
+    kind: "newer";
+    version: string;
 };
+/** Homebrew after publication (pipeline-speed.md, P1): its own durable state, finished by `toolroll release <branch>`.
+ * `pending`: a change proposed or its checks still running; `failed`: its checks failed (a later run reads them again);
+ * `current`: merged, or already on the tap; `superseded`: the tap already names a newer version, so nothing was changed. */
+export type HomebrewProgress = "pending" | "failed" | "current" | "superseded";
 /** One commit that landed after the approval, with its files and line counts (release_carry). */
 export type LandedCommit = {
     sha: string;
@@ -442,7 +454,10 @@ export type ReleaseAdapters = {
     github: {
         authenticated(): Promise<boolean>;
         pullRequest(repo: string, branch: string): Promise<PullRequest | null>;
-        checks(repo: string, sha: string): Promise<CheckRun[]>;
+        /** `tag`: a release tag's push binds its workflow file too (only that exact tag's push). */
+        checks(repo: string, sha: string, options?: {
+            tag?: string;
+        }): Promise<CheckRun[]>;
         /** Whether GitHub's check history of this commit can be read whole (fewer check suites than the check-runs
          * endpoint's ceiling). Absent or false: an automatic release fails closed; a person's is unaffected. */
         complete?(repo: string, sha: string): Promise<boolean>;
@@ -472,6 +487,14 @@ export type ReleaseAdapters = {
             pr: number;
             head: string;
         }>;
+        /** Right before the merge: the change is the tap's own open pull request at exactly `head`, and its formula is
+         * exactly the tap's formula with npm's published tarball for `version` and that tarball's own sha256. */
+        verified(pr: number, head: string, version: string): Promise<{
+            ok: true;
+        } | {
+            ok: false;
+            why: string;
+        }>;
         merge(pr: number, head: string): Promise<void>;
     };
 };
@@ -538,6 +561,9 @@ export type ReleaseJournal = {
         pr: number | null;
         head: string | null;
         merged: boolean;
+        /** Absent in a journal from before Homebrew was finished apart: read from `merged`. */
+        state?: HomebrewProgress;
+        why?: string | null;
     } | null;
     /** The release's authority record (release-once.md), once a person approved terms: the id and generation. */
     authority?: {
@@ -635,6 +661,13 @@ export declare function checksVerdict(runs: readonly CheckRun[], required: reado
     state: "failed";
     failed: string[];
 };
+/**
+ * Publication's verdict on the tag commit (pipeline-speed.md, item 3): only RELEASE_TAG_CHECKS, from GitHub Actions
+ * runs of publish.yml bound to the tag's push, each by its newest attempt. Every other check on the merge commit — main's
+ * own CI run — is not waited for: the candidate's checks already passed on its exact head before the merge, and the
+ * merged tree was proved equal to it.
+ */
+export declare function tagChecksVerdict(runs: readonly CheckRun[]): ReturnType<typeof checksVerdict>;
 /** Run the release from wherever its journal stopped. */
 export declare function runRelease(options: ReleaseOptions, adapters: ReleaseAdapters): Promise<ReleaseOutcome>;
 /** A probe's failure that is only the network to GitHub being slow, never a decision (a Stop) or another error. */