toolroll 0.9.77 → 0.9.79

package/dist/release-adapters.js

@@ -12,6 +12,7 @@ import { basename, delimiter, dirname, join } from "node:path";
 import { createRequire } from "node:module";
 import { parse as parseYaml } from "yaml";
 import { sleep } from "./sleep.js";
+import { callLabel, readOnlyCall, retryCall, retryingExec, writeWithRecheck } from "./release-net.js";
 // Loaded on first use, like the store: a static import prints Node's SQLite warning before the CLI can quiet it.
 const sqlite = () => createRequire(import.meta.url)("node:sqlite");
 import { PROTECTION_MINIMUM_CHECKS, PROTECTION_REPORT_ONLY_CHECKS } from "./release.js";
@@ -28,7 +29,7 @@ import { proveCarry } from "./release-carry.js";
 import { randomBytes, randomUUID } from "node:crypto";
 import { deploymentGate } from "./deploy-gate.js";
 import { extractCommit } from "./commit-extract.js";
-import { checkoutIncludes } from "./teardown-git.js";
+import { teardownGit, refusal as gitRefusal } from "./teardown-git.js";
 import { RELEASE_REMOTE, releaseConfigProblem, releaseGitArgs, releaseGitEnv, releaseRemote, releaseTools } from "./release-git.js";
 export { RELEASE_PATH, RELEASE_REMOTE, releaseConfigProblem, releaseGitArgs, releaseGitEnv, releaseRemote, releaseTools } from "./release-git.js";
 /** A child process, its output kept whole; a missing program or a time limit is exit 127 or 124, never a throw. */
@@ -51,10 +52,12 @@ const cleanEnv = (extra = {}) => {
     delete env["NODE_OPTIONS"];
     return env;
 };
+/** A failed call, in the words every release stop uses: what, its exit code and the last lines it printed. */
+const failed = (result, what) => new Error(`${what} failed (exit ${result.code}): ${(result.stderr || result.stdout).trim().split("\n").slice(-3).join(" ")}`);
 const must = async (run, what) => {
     const result = await run;
     if (result.code !== 0)
-        throw new Error(`${what} failed (exit ${result.code}): ${(result.stderr || result.stdout).trim().split("\n").slice(-3).join(" ")}`);
+        throw failed(result, what);
     return result.stdout;
 };
 /** owner/name from an https or ssh GitHub remote. */
@@ -227,8 +230,16 @@ export function releaseAdapters(options) {
     const pause = options.sleep ?? ((ms) => new Promise(done => setTimeout(done, ms)));
     const tools = options.tools ?? releaseTools();
     const gitEnv = releaseGitEnv();
+    const say = options.say ?? ((line) => { process.stdout.write(`${line}\n`); });
+    /** A short network failure on the way to GitHub (release-net.ts): reads are asked again for up to ~3 minutes; a
+     * write never is, unless GitHub says it didn't happen (writeWithRecheck). */
+    const net = { say, sleep: options.sleep ?? sleep, ...(options.now === undefined ? {} : { now: options.now }) };
+    const reads = retryingExec(run, net);
     // Never a PATH lookup or the checkout's Git config: gh by its absolute path, from a neutral folder, naming the repo.
-    const gh = (...args) => run(tools.gh, args, { cwd: "/", env: gitEnv });
+    // Reads ride out a short network failure; anything that isn't provably a read passes straight through (readOnlyCall).
+    const gh = (...args) => reads(tools.gh, args, { cwd: "/", env: gitEnv });
+    /** A write by gh, never retried by itself. */
+    const ghWrite = (remainingMs, ...args) => run(tools.gh, args, { cwd: "/", env: gitEnv, timeoutMs: Math.min(120_000, remainingMs) });
     const ghJson = async (what, ...args) => JSON.parse(await must(gh(...args), what));
     const toolroll = async (...args) => {
         const result = await run("toolroll", [...args, "--json"], { env: cleanEnv(), timeoutMs: 120_000 });
@@ -245,9 +256,9 @@ export function releaseAdapters(options) {
     const ciGh = options.tools?.gh ?? releaseTools("").gh;
     const observeCi = async (sha) => {
         const observedAt = (options.now ?? (() => new Date()))().toISOString();
-        const runs = (await readCheckRuns(run, ciGh, releaseRepo().slug, sha)).map(one => ({ id: one.id ?? null, name: one.name, status: one.status, conclusion: one.conclusion, app: one.app ?? null, suite: one.suite ?? null, head: one.head ?? null, workflow: one.workflow ?? null, workflowPath: one.workflowPath ?? null,
+        const runs = (await readCheckRuns(reads, ciGh, releaseRepo().slug, sha)).map(one => ({ id: one.id ?? null, name: one.name, status: one.status, conclusion: one.conclusion, app: one.app ?? null, suite: one.suite ?? null, head: one.head ?? null, workflow: one.workflow ?? null, workflowPath: one.workflowPath ?? null,
             ...(one.beforeTests === undefined ? {} : { beforeTests: one.beforeTests }) }));
-        return { head: sha, observedAt, runs, complete: await readSuitesComplete(run, ciGh, releaseRepo().slug, sha) };
+        return { head: sha, observedAt, runs, complete: await readSuitesComplete(reads, ciGh, releaseRepo().slug, sha) };
     };
     const database = options.database ?? databasePath(process.env, homedir());
     let recorded = options.releaseRepo ?? null;
@@ -255,21 +266,55 @@ export function releaseAdapters(options) {
     const releaseRepo = () => recorded ??= recordedReleaseRepo(database, checkout);
     /**
      * The coordinator's one way to run Git (§0a.2): on the recorded Git directory, hardened, with an allowlisted
-     * environment and the absolute Git. Before every command the checkout's own config is read with includes off and
-     * as plain files; one that includes a file, names a command or redirects a remote stops the release, naming it.
+     * environment and the absolute Git. Every attempt uses the shared runner's private view: the audited config is
+     * the exact copy Git reads, so a build cannot redirect a command after its config was checked.
      */
     const git = async (...args) => {
         const repo = releaseRepo();
+        const full = [...releaseGitArgs(repo, tools), ...args];
         const stop = (why) => new Error(`Toolroll won't run Git in ${repo.checkout} for a release: ${why}. Remove it from the project's Git config, then rerun.`);
-        if (options.releaseRepo === undefined && checkoutIncludes(repo.checkout))
-            throw stop("its Git config includes another file, or couldn't be read as a plain file");
-        const listing = await run(tools.git, [`--git-dir=${repo.gitDir}`, "--no-optional-locks", "config", "--list", "--no-includes", "--show-scope", "-z"], { cwd: "/", env: gitEnv });
-        if (listing.code !== 0)
-            throw stop("its Git config couldn't be read");
-        const setting = releaseConfigProblem(listing.stdout);
-        if (setting !== null)
-            throw stop(`its Git config sets ${setting}, which a release doesn't run with (it could run a command, or change where Git connects or what it sends)`);
-        return run(tools.git, [...releaseGitArgs(repo, tools), ...args], { cwd: repo.checkout, env: gitEnv });
+        // The checkout's config is read again right before EVERY attempt, a retried one included (checked at the moment of use).
+        const once = async (remainingMs = 120_000) => {
+            const now = () => (options.now ?? (() => new Date()))().getTime();
+            const started = now();
+            const left = () => Math.min(120_000, remainingMs - Math.max(0, now() - started));
+            const checkConfig = (listing) => {
+                if (listing.code !== 0)
+                    throw stop("its Git config couldn't be read");
+                const setting = releaseConfigProblem(listing.stdout);
+                if (setting !== null)
+                    throw stop(`its Git config sets ${setting}, which a release doesn't run with (it could run a command, or change where Git connects or what it sends)`);
+            };
+            if (options.releaseRepo === undefined) {
+                // The shared runner pins both Git directories and freezes config/info in the plane's fenced view folder.
+                // Its private paths replace releaseGitArgs' first two directory flags; the recorded remote stays fixed.
+                const viewed = teardownGit(async (_command, argv, runOptions) => {
+                    const timeoutMs = left();
+                    if (timeoutMs <= 0)
+                        return { code: 124, stdout: "", stderr: "the network retry budget ran out", timedOut: true, notFound: false };
+                    const env = { ...gitEnv, ...Object.fromEntries(["GIT_DIR", "GIT_COMMON_DIR", "GIT_WORK_TREE"].map(key => [key, runOptions?.env?.[key]])) };
+                    const result = await run(tools.git, argv, { cwd: repo.checkout, env, timeoutMs });
+                    if (argv.includes("config"))
+                        checkConfig(result);
+                    return { ...result, timedOut: result.code === 124, notFound: result.code === 127 };
+                }, { repo: repo.checkout }, Math.max(0, left()), tools.git);
+                const result = await viewed(repo.checkout, full.slice(2));
+                const why = gitRefusal(result);
+                if (why !== null)
+                    throw stop(why);
+                return result;
+            }
+            // Injected repository/exec fixtures have no on-disk checkout, but exercise the same config policy per attempt.
+            if (left() <= 0)
+                return { code: 124, stdout: "", stderr: "the network retry budget ran out" };
+            const listing = await run(tools.git, [`--git-dir=${repo.gitDir}`, "--no-optional-locks", "config", "--list", "--no-includes", "--show-scope", "-z"], { cwd: "/", env: gitEnv, timeoutMs: left() });
+            checkConfig(listing);
+            if (left() <= 0)
+                return { code: 124, stdout: "", stderr: "the network retry budget ran out" };
+            return run(tools.git, full, { cwd: repo.checkout, env: gitEnv, timeoutMs: left() });
+        };
+        // ls-remote and fetch ride out a short network failure; a push or a local command is never retried (readOnlyCall).
+        return readOnlyCall(tools.git, full) === null ? once() : retryCall(once, callLabel(tools.git, full), net);
     };
     /** The remote every fetch, look and push names: the recorded URL, defined only on the command line. */
     const remoteUrl = () => RELEASE_REMOTE;
@@ -373,8 +418,8 @@ export function releaseAdapters(options) {
             rmSync(extracted.dir, { recursive: true, force: true });
         }
     };
-    const release = storeReleaseAdapter(() => openStore(database), store => store.close(), options.now ?? (() => new Date()), undefined, { observe: sha => observeCi(sha), mergeBase: (base, sha) => readMergeBase(run, ciGh, releaseRepo().slug, base, sha),
-        upToDateRequired: () => readUpToDateRequired(run, ciGh, releaseRepo().slug), evidenceRoot: join(dirname(database), "evidence"),
+    const release = storeReleaseAdapter(() => openStore(database), store => store.close(), options.now ?? (() => new Date()), undefined, { observe: sha => observeCi(sha), mergeBase: (base, sha) => readMergeBase(reads, ciGh, releaseRepo().slug, base, sha),
+        upToDateRequired: () => readUpToDateRequired(reads, ciGh, releaseRepo().slug), evidenceRoot: join(dirname(database), "evidence"),
         // A successful Actions job authenticates the job, not the candidate-writable JSON it uploads. Until the
         // executor protects that reporting channel, production releases must take the person's approval road.
         reportsProtected: false });
@@ -382,7 +427,7 @@ export function releaseAdapters(options) {
         ...(existsSync(database) ? { release } : {}),
         now: options.now ?? (() => new Date()),
         sleep: options.sleep ?? sleep,
-        say: options.say ?? (line => process.stdout.write(`${line}\n`)),
+        say,
         repo: {
             // The recorded owner/name, never the checkout's origin.
             async github() { return releaseRepo().slug; },
@@ -575,33 +620,38 @@ 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 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); },
-            async upToDateRequired(repo) { return readMainProtection(run, ciGh, repo); },
+            async checks(repo, sha, options) { return readCheckRuns(reads, ciGh, repo, sha, options); },
+            async complete(repo, sha) { return readSuitesComplete(reads, ciGh, repo, sha); },
+            async mainHead(repo) { return readMainHead(reads, ciGh, repo); },
+            async contains(repo, sha, ancestor) { return readContains(reads, ciGh, repo, sha, ancestor); },
+            async upToDateRequired(repo) { return readMainProtection(reads, ciGh, repo); },
             async merge(repo, pr, head, message) {
-                // The squash commit's message lists every commit that landed after the approval (release-once.md).
-                const merged = object(await ghJson("gh api pulls merge", "api", "-X", "PUT", `repos/${repo}/pulls/${pr}/merge`, "-f", "merge_method=squash", "-f", `sha=${head}`, ...(message === undefined ? [] : ["-f", `commit_message=${message}`])));
-                if (typeof merged["sha"] !== "string")
-                    throw new Error(`GitHub did not merge #${pr}: ${String(merged["message"] ?? "no merge commit")}`);
-                return merged["sha"];
-            },
-            async tag(repo, tag) {
-                const result = await gh("api", `repos/${repo}/git/ref/tags/${tag}`);
-                if (result.code !== 0) {
-                    if (/Not Found|HTTP 404/.test(result.stderr + result.stdout))
-                        return null;
-                    throw new Error(`gh api git/ref/tags/${tag} failed: ${result.stderr.trim()}`);
-                }
-                const target = object(object(JSON.parse(result.stdout))["object"]);
-                if (target["type"] !== "tag")
-                    return String(target["sha"]);
-                // An annotated tag: the commit it names.
-                return String(object(object(await ghJson("gh api git/tags", "api", `repos/${repo}/git/tags/${String(target["sha"])}`))["object"])["sha"]);
+                // The squash commit's message lists every commit that landed after the approval (release-once.md). Never asked
+                // again under stale approval/lease/CI checks: reconcile a lost answer, but another write needs a fresh
+                // coordinator pass through those guards. A PR still being open proves none of them.
+                return writeWithRecheck(`merging #${pr}`, { ...net, maxAttempts: 1 }, {
+                    write: remaining => ghWrite(remaining, "api", "-X", "PUT", `repos/${repo}/pulls/${pr}/merge`, "-f", "merge_method=squash", "-f", `sha=${head}`, ...(message === undefined ? [] : ["-f", `commit_message=${message}`])),
+                    accept: result => {
+                        const merged = object(JSON.parse(result.stdout));
+                        if (merged["merged"] !== true || typeof merged["sha"] !== "string" || !/^[0-9a-f]{40}$/.test(merged["sha"]))
+                            throw new Error(`GitHub did not merge #${pr}: ${String(merged["message"] ?? "no merge commit")}`);
+                        return merged["sha"];
+                    },
+                    refuse: result => { throw failed(result, "gh api pulls merge"); },
+                    recheck: bounded => pullMergedAt(repo, pr, head, "main", bounded, message),
+                });
             },
+            async tag(repo, tag) { return readTag(repo, tag); },
             async createTag(repo, tag, sha) {
-                await must(gh("api", "-X", "POST", `repos/${repo}/git/refs`, "-f", `ref=refs/tags/${tag}`, "-f", `sha=${sha}`), `creating ${tag}`);
+                await writeWithRecheck(`creating ${tag}`, net, {
+                    write: remaining => ghWrite(remaining, "api", "-X", "POST", `repos/${repo}/git/refs`, "-f", `ref=refs/tags/${tag}`, "-f", `sha=${sha}`),
+                    accept: () => undefined,
+                    refuse: result => { throw failed(result, `creating ${tag}`); },
+                    recheck: async (bounded) => {
+                        const at = await readTag(repo, tag, bounded);
+                        return at === sha ? { state: "done", value: undefined } : at === null ? { state: "not-done" } : { state: "other", why: `${tag} now points at ${at.slice(0, 7)}` };
+                    },
+                });
             },
             async release(repo, tag) { return (await gh("release", "view", tag, "--repo", repo, "--json", "tagName")).code === 0; },
         },
@@ -653,8 +703,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 +722,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,13 +744,76 @@ 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")
-                    throw new Error(`GitHub did not merge ${tap} #${pr}: ${String(merged["message"] ?? "no merge commit")}`);
+                const base = await defaultBranch();
+                await writeWithRecheck(`merging ${tap} #${pr}`, { ...net, maxAttempts: 1 }, {
+                    write: remaining => ghWrite(remaining, "api", "-X", "PUT", `repos/${tap}/pulls/${pr}/merge`, "-f", "merge_method=squash", "-f", `sha=${head}`),
+                    accept: result => {
+                        const merged = object(JSON.parse(result.stdout));
+                        if (merged["merged"] !== true || typeof merged["sha"] !== "string" || !/^[0-9a-f]{40}$/.test(merged["sha"]))
+                            throw new Error(`GitHub did not merge ${tap} #${pr}: ${String(merged["message"] ?? "no merge commit")}`);
+                    },
+                    refuse: result => { throw failed(result, `merging ${tap} #${pr}`); },
+                    recheck: async (bounded) => { const state = await pullMergedAt(tap, pr, head, base, bounded); return state.state === "done" ? { state: "done", value: undefined } : state; },
+                });
             },
         },
     };
+    /** A tag's commit as GitHub answers now (an annotated tag: the commit it names), or null when there is no such tag. */
+    async function readTag(repo, tag, bounded = net) {
+        const read = (path) => retryingExec(run, bounded)(tools.gh, ["api", path], { cwd: "/", env: gitEnv });
+        const result = await read(`repos/${repo}/git/ref/tags/${tag}`);
+        if (result.code !== 0) {
+            if (/Not Found|HTTP 404/.test(result.stderr + result.stdout))
+                return null;
+            throw new Error(`gh api git/ref/tags/${tag} failed: ${result.stderr.trim()}`);
+        }
+        const target = object(object(JSON.parse(result.stdout))["object"]);
+        if (target["type"] !== "tag")
+            return String(target["sha"]);
+        return String(object(object(JSON.parse(await must(read(`repos/${repo}/git/tags/${String(target["sha"])}`), "gh api git/tags")))["object"])["sha"]);
+    }
+    /** Whether a pull request is merged from exactly `head` (its merge commit), still open at `head` (not merged), or
+     * anything else — read after a merge's answer was lost. */
+    async function pullMergedAt(repo, pr, head, base, bounded, message) {
+        const read = async (path) => object(JSON.parse(await must(retryingExec(run, bounded)(tools.gh, ["api", path], { cwd: "/", env: gitEnv }), "gh api merge recovery")));
+        const pull = await read(`repos/${repo}/pulls/${pr}`);
+        const at = object(pull["head"])["sha"], commit = pull["merge_commit_sha"];
+        if (at !== head || object(pull["base"])["ref"] !== base)
+            return { state: "other", why: `#${pr} is no longer open at ${head.slice(0, 7)} into ${base}` };
+        if (pull["merged"] === true && pull["state"] === "closed" && typeof commit === "string" && /^[0-9a-f]{40}$/.test(commit)) {
+            // Another caller may have merged it. Only the same squash result counts, never merely "merged=true".
+            const source = await read(`repos/${repo}/git/commits/${head}`);
+            const merged = await read(`repos/${repo}/git/commits/${commit}`);
+            const tree = object(source["tree"])["sha"], parents = merged["parents"];
+            if (typeof tree === "string" && /^[0-9a-f]{40}$/.test(tree) && object(merged["tree"])["sha"] === tree
+                && Array.isArray(parents) && parents.length === 1
+                && (message === undefined || (typeof merged["message"] === "string" && merged["message"].endsWith(`\n\n${message}`))))
+                return { state: "done", value: commit };
+            return { state: "other", why: `#${pr}'s merge is not the approved squash result` };
+        }
+        if (pull["merged"] === false && pull["state"] === "open")
+            return { state: "not-done" };
+        return { state: "other", why: `#${pr} is no longer open at ${head.slice(0, 7)}` };
+    }
     async function defaultBranch() {
         return (await must(gh("api", `repos/${tap}`, "--jq", ".default_branch"), `gh api repos/${tap}`)).trim();
     }
@@ -696,6 +823,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 +1097,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 +1147,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 => {
@@ -1085,15 +1268,19 @@ export async function readContains(run, gh, repo, sha, ancestor) {
  * can't be bypassed by that account:
  * classic protection with "Do not allow bypassing the above settings" (`enforce_admins`); an active ruleset whose
  * bypass list reads whole, names no role, team or organization admin, and says this account never bypasses it. Read
- * only — Toolroll never changes a repository's settings. A layer that can't be read never holds; null only when nothing
- * could be read at all.
+ * only — Toolroll never changes a repository's settings. A layer that can't be read never holds. When no layer holds
+ * and one couldn't be read (gh failed for a reason other than "not protected", or its answer didn't parse), the read
+ * throws ProtectionUnreadable: "couldn't read GitHub" is never reported as "protection doesn't hold", and never as
+ * holding. Null only for a repository or branch name GitHub can't be asked about.
  */
 export async function readMainProtection(run, gh, repo, branch = "main") {
     if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || !/^[A-Za-z0-9._/-]+$/.test(branch) || branch.includes(".."))
         return null;
     const missing = [];
     const held = [];
-    let read = 0;
+    /** What couldn't be read at all, and the words gh gave. */
+    const unread = [];
+    const words = (out) => (out.stderr || out.stdout).trim().split("\n").slice(-1)[0]?.slice(0, 160) || `exit ${out.code}`;
     const judge = (where, strict, checks, bound, bypass) => {
         const own = [];
         if (!strict)
@@ -1139,46 +1326,41 @@ export async function readMainProtection(run, gh, repo, branch = "main") {
         catch { /* unreadable below */ }
         const p = object(answer), checks = p["required_status_checks"];
         if (answer === null || typeof answer !== "object" || Array.isArray(answer))
-            missing.push("classic protection couldn't be read");
-        else if (checks === undefined || checks === null) {
-            read++;
+            unread.push("classic protection (its answer didn't parse)");
+        else if (checks === undefined || checks === null)
             missing.push("classic protection: \"Require status checks to pass before merging\" is off");
-        }
         else {
             const rsc = object(checks), contexts = names(rsc["contexts"] ?? [], ""), apps = names(rsc["checks"] ?? [], "context");
             const admins = p["enforce_admins"];
+            // GitHub answered, but without the settings this judges: read, and not holding.
             if (contexts === null || apps === null || typeof rsc["strict"] !== "boolean" || admins === undefined || admins === null || typeof object(admins)["enabled"] !== "boolean")
-                missing.push("classic protection couldn't be read");
+                missing.push("classic protection: GitHub's answer doesn't say which checks it requires or whether administrators can bypass it");
             else {
-                read++;
                 judge("classic protection", rsc["strict"] === true, [...new Set([...contexts, ...apps])], actionsChecks(rsc["checks"], "app_id"), object(admins)["enabled"] === true ? [] : ["\"Do not allow bypassing the above settings\" is off, so administrators can merge past it"]);
             }
         }
     }
-    else if (notProtected(classic))
-        read++;
-    else
-        missing.push("classic protection couldn't be read");
+    else if (!notProtected(classic))
+        unread.push(`classic protection (${words(classic)})`);
     // Rulesets: every active rule requiring status checks on the branch, then its ruleset's enforcement and bypass list.
     const rules = await run(gh, ["api", "--hostname", "github.com", "--paginate", `repos/${repo}/rules/branches/${branch}`,
         "--jq", ".[] | select(.type == \"required_status_checks\") | @json"], { cwd: "/", env: ciEnv() });
     if (rules.code !== 0)
-        missing.push("main's rulesets couldn't be read");
+        unread.push(`main's rulesets (${words(rules)})`);
     else {
-        read++;
         for (const line of rules.stdout.split("\n").filter(one => one.trim() !== "")) {
             let rule;
             try {
                 rule = object(JSON.parse(line));
             }
             catch {
-                missing.push("a ruleset rule couldn't be read");
+                unread.push("a ruleset rule (its answer didn't parse)");
                 continue;
             }
             const id = rule["ruleset_id"], params = object(rule["parameters"]);
             const checks = names(params["required_status_checks"], "context");
             if (!Number.isSafeInteger(id) || Number(id) <= 0 || checks === null) {
-                missing.push("a ruleset rule couldn't be read");
+                missing.push("a ruleset rule doesn't name its ruleset or required checks");
                 continue;
             }
             const where = `ruleset ${id}`;
@@ -1192,7 +1374,7 @@ export async function readMainProtection(run, gh, repo, branch = "main") {
                 set = null;
             }
             if (set === null) {
-                missing.push(`${where}: its settings couldn't be read`);
+                unread.push(`${where}: its settings (${got.code === 0 ? "its answer didn't parse" : words(got)})`);
                 continue;
             }
             const bypass = [];
@@ -1216,17 +1398,37 @@ export async function readMainProtection(run, gh, repo, branch = "main") {
         const required = new Set(held.flat());
         return { effective: true, missing: [], notYetRequired: PROTECTION_REPORT_ONLY_CHECKS.filter(name => !required.has(name)) };
     }
-    if (read === 0)
-        return null;
+    if (unread.length > 0)
+        throw new ProtectionUnreadable(unread);
     if (missing.length === 0)
         missing.push("main has no branch protection or ruleset requiring status checks");
     return { effective: false, missing, notYetRequired: [] };
 }
+/** Main's protection couldn't be read from GitHub (after the network retries): not "doesn't hold", and never "holds". */
+export class ProtectionUnreadable extends Error {
+    unread;
+    constructor(unread) {
+        super(`couldn't read GitHub's branch protection for main: ${unread.join("; ")}`);
+        this.unread = unread;
+    }
+}
 /** Whether main's protection holds, as a yes/no (release-auto.ts sealAutoGreen): null when it can't be read. */
 export async function readUpToDateRequired(run, gh, repo, branch = "main") {
-    const protection = await readMainProtection(run, gh, repo, branch);
+    let protection;
+    try {
+        protection = await readMainProtection(run, gh, repo, branch);
+    }
+    catch (error) {
+        if (error instanceof ProtectionUnreadable)
+            return null;
+        throw error;
+    }
     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.