toolroll 0.9.76 → 0.9.78

package/dist/release-adapters.js

@@ -14,13 +14,16 @@ import { parse as parseYaml } from "yaml";
 import { sleep } from "./sleep.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";
 import { activeUpdateWork } from "./desktop-update-gate.js";
 import { BEFORE_SWAP, gateOwner } from "./release-gate.js";
 import { findCliLinks, switchCliLinks } from "./release-links.js";
 import { databasePath, finishReleaseOperation, requireFreshReleaseApproval, openStore, releaseAuthorityOfTask, releaseCarries, releaseOperations, renewReleaseLease, reserveRelease, runReleaseOperation, Store, releaseIssuerGone, takeReleaseLease, } from "./store.js";
 import { acquireDeploymentLock } from "./deploy-lock.js";
 import { autoReleaseApprovalOf, liveReleaseOf } from "./scope.js";
-import { autoPublishHeld, holdAutoPublish, authorizeAutoCheck, giveUpAutoApproval, noteAutoCheckFailed, noteAutoRelease, releaseAutoApproves, sealAutoGreen } from "./release-auto.js";
+import { recheckReleaseTask, releaseCheckStanding } from "./check-failure.js";
+import { noteCiRunning, releaseCiHoldOf, releaseCiRunningOf } from "./release-ci-hold.js";
+import { autoPublishHeld, holdAutoPublish, liftCiHold, authorizeAutoCheck, giveUpAutoApproval, noteAutoCheckFailed, noteAutoRelease, releaseAutoApproves, sealAutoGreen } from "./release-auto.js";
 import { proveCarry } from "./release-carry.js";
 import { randomBytes, randomUUID } from "node:crypto";
 import { deploymentGate } from "./deploy-gate.js";
@@ -242,7 +245,8 @@ 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 }));
+        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,
+            ...(one.beforeTests === undefined ? {} : { beforeTests: one.beforeTests }) }));
         return { head: sha, observedAt, runs, complete: await readSuitesComplete(run, ciGh, releaseRepo().slug, sha) };
     };
     const database = options.database ?? databasePath(process.env, homedir());
@@ -369,7 +373,11 @@ 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), 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(run, ciGh, releaseRepo().slug, base, sha),
+        upToDateRequired: () => readUpToDateRequired(run, 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 });
     return {
         ...(existsSync(database) ? { release } : {}),
         now: options.now ?? (() => new Date()),
@@ -424,8 +432,6 @@ export function releaseAdapters(options) {
                 const result = await git("show", `${sha}:${path}`);
                 return result.code === 0 ? result.stdout : null;
             },
-            async mainHead() { return (await must(git("rev-parse", "refs/remotes/origin/main"), "git rev-parse origin/main")).trim(); },
-            async contains(sha, ancestor) { return (await git("merge-base", "--is-ancestor", ancestor, sha)).code === 0; },
         },
         toolroll: {
             async installed() { return { services: serviceRuntimes(), clis: cliRuntimes() }; },
@@ -569,8 +575,11 @@ 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); },
+            async upToDateRequired(repo) { return readMainProtection(run, 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}`])));
@@ -644,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) {
@@ -655,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}`);
@@ -671,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")
@@ -687,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"]);
 /**
@@ -746,6 +839,21 @@ auto) {
     } };
     return {
         ...(auto === undefined ? {} : { auto: autoReleaseAdapter(withStore, now, auto) }),
+        // After a failed release check, and before a pass is taken: the plane's own classification (check-failure.ts).
+        ...(auto === undefined ? {} : {
+            async recheck(taskId) {
+                return withStore(store => {
+                    const answer = recheckReleaseTask(store, auto.evidenceRoot, taskId, now());
+                    return answer.action === "rerun" ? { action: "rerun", why: answer.why } : answer.action === "pending" ? { action: "pending" } : { action: "stop", class: answer.class, why: answer.why };
+                });
+            },
+            async standing(taskId, run) {
+                return withStore(store => {
+                    const standing = releaseCheckStanding(store, auto.evidenceRoot, { taskId, run });
+                    return standing.ok ? { ok: true, retried: standing.retried } : { ok: false, why: standing.why, retried: standing.retried };
+                });
+            },
+        }),
         async authority(taskId) {
             return withStore(store => {
                 const found = releaseAuthorityOfTask(store, taskId);
@@ -790,6 +898,8 @@ auto) {
 /** The plane's automatic release approval through a store (release-auto.ts): what `toolroll release` asks. It hands the
  * plane ids only; the plane reads CI itself (`observe`) right before it seals. */
 function autoReleaseAdapter(withStore, now, auto) {
+    const reportProblem = () => auto.reportsProtected === true ? null
+        : "CI test reports aren't protected from candidate writes, so a person must approve this release";
     return {
         async setting(taskId) {
             return withStore(store => { try {
@@ -801,6 +911,9 @@ function autoReleaseAdapter(withStore, now, auto) {
             } });
         },
         async authorizeCheck(input) {
+            const problem = reportProblem();
+            if (problem !== null)
+                return { ok: false, why: problem };
             // The comparison base for what the release changes: GitHub's own merge base of the candidate with the release's
             // base branch (its signed terms), read by the plane — never a task branch or a build's recorded base.
             const branch = withStore(store => store.getScope(input.taskId)?.releaseTerms?.base ?? null);
@@ -816,9 +929,17 @@ function autoReleaseAdapter(withStore, now, auto) {
             return withStore(store => { const answer = authorizeAutoCheck(store, { ...input, base, now: now() }); return answer.ok ? { ok: true } : answer; });
         },
         async checking(taskId) {
+            const problem = reportProblem();
+            if (problem !== null)
+                return { ok: false, why: problem };
             return withStore(store => { const answer = autoReleaseApprovalOf(store, taskId, "auto-check"); return answer.ok ? { ok: true } : { ok: false, why: answer.why }; });
         },
         async approve(input) {
+            const unprotected = reportProblem();
+            if (unprotected !== null) {
+                withStore(store => giveUpAutoApproval(store, { taskId: input.taskId, why: unprotected, now: now() }));
+                return { ok: false, why: unprotected };
+            }
             let ci = null, problem = "";
             // A short network failure is asked again a few times; GitHub not answering is never a pass.
             for (let attempt = 0; attempt < 3 && ci === null; attempt++) {
@@ -835,9 +956,36 @@ function autoReleaseAdapter(withStore, now, auto) {
                 return { ok: false, why };
             }
             const observed = ci;
-            return withStore(store => sealAutoGreen(store, { ...input, ci: observed, evidenceRoot: auto.evidenceRoot, now: now() }));
+            let upToDate;
+            try {
+                upToDate = await auto.upToDateRequired();
+            }
+            catch {
+                upToDate = null;
+            }
+            return withStore(store => sealAutoGreen(store, { ...input, ci: observed, mainUpToDate: upToDate, evidenceRoot: auto.evidenceRoot, now: now() }));
         },
         async giveUp(taskId, why) { withStore(store => giveUpAutoApproval(store, { taskId, why, now: now() })); },
+        async ciRunning(taskId, candidate) { withStore(store => noteCiRunning(store, { taskId, candidate, now: now() })); },
+        async ciPassed(taskId, candidate, ask) {
+            // Reconcile the plane's record, not journal flags; without a pending row there is nothing to lift.
+            if (!withStore(store => releaseCiHoldOf(store, taskId) !== null || releaseCiRunningOf(store, taskId) !== null))
+                return { ok: true };
+            // The plane reads CI itself; a short network failure is asked again a few times, and unreadable is never a pass.
+            let ci = null, problem = "";
+            for (let attempt = 0; attempt < 3 && ci === null; attempt++) {
+                try {
+                    ci = await auto.observe(candidate);
+                }
+                catch (error) {
+                    problem = String(error?.message ?? error).slice(0, 200);
+                }
+            }
+            if (ci === null)
+                return { ok: false, why: `GitHub CI on ${candidate.slice(0, 7)} couldn't be read (${problem})` };
+            const observed = ci;
+            return withStore(store => liftCiHold(store, { taskId, candidate, ci: observed, ask, now: now() }));
+        },
         async checkFailed(taskId, why) { withStore(store => noteAutoCheckFailed(store, { taskId, why, now: now() })); },
         async released(taskId, tag) { withStore(store => noteAutoRelease(store, { taskId, tag, now: now() })); },
         async holdPublish(taskId, why) { withStore(store => holdAutoPublish(store, { taskId, why, now: now() })); },
@@ -854,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`,
@@ -862,16 +1014,46 @@ export async function readCheckRuns(run, gh, repo, sha) {
     // Which workflow each check suite is a run of (GitHub's workflow-run API): a newer run of a workflow supersedes its
     // older runs on this commit (release.ts prChecksVerdict).
     const flows = await must(run(gh, ["api", "--hostname", "github.com", "--paginate", `repos/${repo}/actions/runs?head_sha=${sha}&per_page=100`,
-        "--jq", ".workflow_runs[] | {suite: .check_suite_id, workflow: .workflow_id, head: .head_sha}"], { cwd: "/", env: ciEnv() }), "gh api actions/runs");
+        "--jq", ".workflow_runs[] | {suite: .check_suite_id, workflow: .workflow_id, path: .path, head: .head_sha, event: .event, branch: .head_branch, bases: [(.pull_requests // [])[] | .base.ref], prs: [(.pull_requests // [])[] | {number, repo: .base.repo.url}]}"], { cwd: "/", env: ciEnv() }), "gh api actions/runs");
+    // A pull request's base can be edited after its runs: a run counts only if no pull request it belongs to ever had its
+    // base changed (GitHub's timeline), so a run made against another base can't later read as a run into main.
+    const retargeted = new Map();
+    const everRetargeted = async (pr) => {
+        const known = retargeted.get(pr);
+        if (known !== undefined)
+            return known;
+        let changed = true;
+        try {
+            const events = await run(gh, ["api", "--hostname", "github.com", "--paginate", `repos/${repo}/issues/${pr}/timeline?per_page=100`, "--jq", ".[] | .event"], { cwd: "/", env: ciEnv() });
+            changed = events.code !== 0 || events.stdout.split("\n").some(line => line.trim() === "base_ref_changed");
+        }
+        catch {
+            changed = true;
+        }
+        retargeted.set(pr, changed);
+        return changed;
+    };
     const workflowOf = new Map();
+    // Each suite's workflow file: a required check counts only from the workflow that defines it (release.ts).
+    const pathOf = new Map();
     for (const line of flows.split("\n").filter(Boolean)) {
         const one = object(JSON.parse(line));
-        if (!Number.isSafeInteger(one["suite"]) || !Number.isSafeInteger(one["workflow"]) || one["head"] !== sha)
+        if (!Number.isSafeInteger(one["suite"]) || !Number.isSafeInteger(one["workflow"]) || one["head"] !== sha || typeof one["path"] !== "string" || one["path"] === "")
             throw new Error("GitHub answered a workflow run this can't read");
         const known = workflowOf.get(Number(one["suite"]));
-        if (known !== undefined && known !== Number(one["workflow"]))
+        if (known !== undefined && (known !== Number(one["workflow"]) || pathOf.get(Number(one["suite"])) !== one["path"]))
             throw new Error("GitHub named two workflows for one check suite");
         workflowOf.set(Number(one["suite"]), Number(one["workflow"]));
+        // Only a run on a pull request into main, or a push to main, binds its workflow file: a pull request into another
+        // branch reads that branch's workflow and join verifier, which the candidate may control (security scan of the
+        // join). Any other run keeps no path, so no required check counts from it.
+        // Each pull request the run belongs to must be this repository's own (a number from another repository names a
+        // different pull request here): any other refuses the run.
+        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 ((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 => {
         const one = object(JSON.parse(line));
@@ -879,12 +1061,64 @@ export async function readCheckRuns(run, gh, repo, sha) {
             throw new Error("GitHub answered a check run this can't read");
         const suite = Number.isSafeInteger(one["suite"]) ? Number(one["suite"]) : null;
         return { id: Number(one["id"]), name: one["name"], status: one["status"], conclusion: textOr(one["conclusion"]), app: textOr(one["app"]),
-            suite, head: textOr(one["head"]), workflow: suite === null ? null : workflowOf.get(suite) ?? null };
+            suite, head: textOr(one["head"]), workflow: suite === null ? null : workflowOf.get(suite) ?? null, workflowPath: suite === null ? null : pathOf.get(suite) ?? null };
     });
     if (new Set(runs.map(one => one.id)).size !== runs.length)
         throw new Error("GitHub answered the same check run twice");
+    // Each unsuccessful GitHub Actions attempt: whether GitHub's own job record (a check run's id is its job's) shows it
+    // ending before any of the workflow's own steps ran. Only that ever counts as the runner's failure; unreadable is no.
+    for (const one of runs) {
+        if (one.app !== "github-actions" || one.status !== "completed" || one.conclusion === "success" || one.conclusion === "skipped" || one.conclusion === "neutral")
+            continue;
+        one.beforeTests = await readJobBeforeTests(run, gh, repo, one.id);
+    }
     return runs.sort((a, b) => a.id - b.id);
 }
+/**
+ * Whether a finished, unsuccessful job ended before any of the workflow's own steps ran: every step after GitHub's own
+ * first one ("Set up job", always number 1) never ran (no conclusion, or skipped) — leaving out only GitHub's own
+ * closing "Complete job" when it is the last step. Step numbers and outcomes are the runner's records; nothing the
+ * candidate prints is read. A job with no steps never reached one. Anything else (a step that ran, even the checkout)
+ * is not confirmed infrastructure.
+ */
+export function failedBeforeTests(job) {
+    if (job.status !== "completed" || job.conclusion === "success" || job.conclusion === null)
+        return false;
+    const steps = [...job.steps].sort((a, b) => a.number - b.number);
+    if (new Set(steps.map(one => one.number)).size !== steps.length)
+        return false;
+    const last = steps.at(-1);
+    const own = steps.filter(one => one.number > 1 && !(one === last && one.name === "Complete job" && steps.length > 1));
+    return own.every(one => one.status !== "in_progress" && (one.conclusion === null || one.conclusion === "skipped"));
+}
+/** GitHub's job record for one check run (its job), read strictly: null when it can't be read whole. */
+export async function readJobBeforeTests(run, gh, repo, id) {
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || !Number.isSafeInteger(id) || id <= 0)
+        return null;
+    let out;
+    try {
+        out = await run(gh, ["api", "--hostname", "github.com", `repos/${repo}/actions/jobs/${id}`, "--jq", "{id, status, conclusion, steps: [(.steps // [])[] | {number, name, status, conclusion}]}"], { cwd: "/", env: ciEnv() });
+    }
+    catch {
+        return null;
+    }
+    if (out.code !== 0)
+        return null;
+    let job;
+    try {
+        job = object(JSON.parse(out.stdout));
+    }
+    catch {
+        return null;
+    }
+    const steps = Array.isArray(job["steps"]) ? job["steps"].map(object) : null;
+    if (job["id"] !== id || typeof job["status"] !== "string" || steps === null)
+        return null;
+    if (steps.some(one => !Number.isSafeInteger(one["number"]) || typeof one["status"] !== "string" || typeof one["name"] !== "string"))
+        return null;
+    return failedBeforeTests({ id, status: String(job["status"]), conclusion: textOr(job["conclusion"]),
+        steps: steps.map(one => ({ number: Number(one["number"]), name: String(one["name"]), status: String(one["status"]), conclusion: textOr(one["conclusion"]) })) });
+}
 /** GitHub lists check runs from at most the latest 1000 check suites of a commit: the history is whole only below that. */
 export const CHECK_SUITE_CEILING = 1000;
 export async function readSuitesComplete(run, gh, repo, sha) {
@@ -903,3 +1137,194 @@ export async function readMergeBase(run, gh, repo, base, sha) {
         throw new Error("GitHub named no merge base");
     return out;
 }
+/**
+ * Main's head as GitHub has it now (eval-harness review 1, finding 4): read by the plane's own gh from GitHub's API,
+ * never from a ref in a checkout a build can write.
+ */
+export async function readMainHead(run, gh, repo, branch = "main") {
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || !/^[A-Za-z0-9._/-]+$/.test(branch) || branch.includes(".."))
+        throw new Error("not a repository and branch GitHub can be asked about");
+    const out = (await must(run(gh, ["api", "--hostname", "github.com", `repos/${repo}/git/ref/heads/${branch}`, "--jq", ".object.type + \" \" + .object.sha"], { cwd: "/", env: ciEnv() }), "gh api git/ref")).trim();
+    const match = /^commit ([0-9a-f]{40})$/.exec(out);
+    if (match === null)
+        throw new Error(`GitHub named no commit for ${branch}`);
+    return match[1];
+}
+/** Whether `sha` already holds `ancestor` (GitHub's compare: `sha` is not behind it), as GitHub answers now. */
+export async function readContains(run, gh, repo, sha, ancestor) {
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || !/^[0-9a-f]{40}$/.test(sha) || !/^[0-9a-f]{40}$/.test(ancestor))
+        throw new Error("not a repository and commits GitHub can be asked about");
+    const out = (await must(run(gh, ["api", "--hostname", "github.com", `repos/${repo}/compare/${ancestor}...${sha}`, "--jq", "[.status, .behind_by] | @json"], { cwd: "/", env: ciEnv() }), "gh api compare")).trim();
+    let answer;
+    try {
+        answer = JSON.parse(out);
+    }
+    catch {
+        throw new Error("GitHub's comparison couldn't be read");
+    }
+    if (!Array.isArray(answer) || typeof answer[0] !== "string" || !Number.isSafeInteger(answer[1]))
+        throw new Error("GitHub's comparison couldn't be read");
+    return answer[1] === 0 && (answer[0] === "ahead" || answer[0] === "identical");
+}
+/**
+ * Main's protection, judged for the principal that merges (eval-harness review 2, finding 1; review 1, finding 4): the
+ * plane's own gh, which merges as the same account. A layer holds only when it requires branches to be up to date, names
+ * a non-empty set of required checks covering PROTECTION_MINIMUM_CHECKS, bound to GitHub Actions (app 15368), and
+ * 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.
+ */
+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;
+    const judge = (where, strict, checks, bound, bypass) => {
+        const own = [];
+        if (!strict)
+            own.push(`${where}: "Require branches to be up to date before merging" is off`);
+        if (checks.length === 0)
+            own.push(`${where}: no required status checks`);
+        else {
+            const lacking = PROTECTION_MINIMUM_CHECKS.filter(name => !checks.includes(name));
+            if (lacking.length > 0)
+                own.push(`${where}: required checks lack ${lacking.join(", ")}`);
+            const unbound = PROTECTION_MINIMUM_CHECKS.filter(name => checks.includes(name) && !bound.includes(name));
+            if (unbound.length > 0)
+                own.push(`${where}: required checks must require GitHub Actions (app 15368) as their source: ${unbound.join(", ")}`);
+        }
+        own.push(...bypass.map(why => `${where}: ${why}`));
+        if (own.length === 0)
+            held.push(bound);
+        else
+            missing.push(...own);
+    };
+    const notProtected = (out) => /HTTP 404|Not Found|not protected|not enabled/i.test(`${out.stderr}\n${out.stdout}`);
+    const names = (list, key) => {
+        if (!Array.isArray(list))
+            return null;
+        const out = [];
+        for (const one of list) {
+            const name = key === "" ? one : object(one)[key];
+            if (typeof name !== "string" || name === "")
+                return null;
+            out.push(name);
+        }
+        return out;
+    };
+    const actionsChecks = (list, appKey) => Array.isArray(list)
+        ? list.flatMap(one => { const check = object(one); return check[appKey] === 15368 && typeof check["context"] === "string" ? [check["context"]] : []; }) : [];
+    // Classic branch protection, read whole. Context names alone allow an arbitrary writer to supply their status.
+    const classic = await run(gh, ["api", "--hostname", "github.com", `repos/${repo}/branches/${branch}/protection`], { cwd: "/", env: ciEnv() });
+    if (classic.code === 0) {
+        let answer = null;
+        try {
+            answer = JSON.parse(classic.stdout);
+        }
+        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++;
+            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"];
+            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");
+            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");
+    // 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");
+    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");
+                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");
+                continue;
+            }
+            const where = `ruleset ${id}`;
+            const got = await run(gh, ["api", "--hostname", "github.com", `repos/${repo}/rulesets/${id}`, "--jq", "{enforcement, target, current_user_can_bypass, bypass_actors} | @json"], { cwd: "/", env: ciEnv() });
+            let set = null;
+            try {
+                if (got.code === 0)
+                    set = object(JSON.parse(got.stdout));
+            }
+            catch {
+                set = null;
+            }
+            if (set === null) {
+                missing.push(`${where}: its settings couldn't be read`);
+                continue;
+            }
+            const bypass = [];
+            if (set["enforcement"] !== "active")
+                bypass.push("it isn't active");
+            if (set["target"] !== "branch")
+                bypass.push("it doesn't target branches");
+            if (set["current_user_can_bypass"] !== "never")
+                bypass.push(typeof set["current_user_can_bypass"] === "string"
+                    ? `the account that merges can bypass it (${set["current_user_can_bypass"]})` : "whether the account that merges can bypass it couldn't be read");
+            const actors = set["bypass_actors"];
+            if (!Array.isArray(actors))
+                bypass.push("its bypass list couldn't be read");
+            // Only a deploy key never merges as this account; a role, team, app or organization admin might.
+            else if (actors.some(one => object(one)["actor_type"] !== "DeployKey"))
+                bypass.push("its bypass list names a role, team, app or organization admin");
+            judge(where, params["strict_required_status_checks_policy"] === true, checks, actionsChecks(params["required_status_checks"], "integration_id"), bypass);
+        }
+    }
+    if (held.length > 0) {
+        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 (missing.length === 0)
+        missing.push("main has no branch protection or ruleset requiring status checks");
+    return { effective: false, missing, notYetRequired: [] };
+}
+/** 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);
+    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"] : [];
+    if (run["event"] === "push")
+        return run["branch"] === "main";
+    if (run["event"] === "pull_request")
+        return bases.length > 0 && bases.every(base => base === "main");
+    return false;
+}

package/dist/release-authority.js

@@ -143,11 +143,15 @@ export const AUTO_EVIDENCE_ACTION = "release auto-approved";
 /** An automatic seal taken back for good (the setting lowered, a refusal): its outcome names the seal's `auto:<id>`, and
  * that evidence never stands again. */
 export const AUTO_WITHDRAWN_ACTION = "release auto-approval withdrawn";
+/** The setting rows (no task; this action) through the ledger's (task_id, action, …) index: a seek to the few rows every
+ * project has written, never a walk down the project's whole ledger. The approval predicate reads this once per task row
+ * (SQLite evaluates every operand of an OR in a result column), so a walk made each Needs you count ~10x slower (0.9.76). */
+const SETTING_INDEX = "INDEXED BY work_completion";
 /** Read live at every use. Fail closed: a missing, unreadable or unknown row is `ask`. */
 export function releaseApprovalSetting(store, repo) {
     let row;
     try {
-        row = store.handle.prepare("SELECT actor, at, outcome FROM action_ledger WHERE repo = ? AND task_id IS NULL AND action = ? ORDER BY id DESC LIMIT 1").get(repo, RELEASE_APPROVAL_ACTION);
+        row = store.handle.prepare(`SELECT actor, at, outcome FROM action_ledger ${SETTING_INDEX} WHERE task_id IS NULL AND action = ? AND repo = ? ORDER BY id DESC LIMIT 1`).get(RELEASE_APPROVAL_ACTION, repo);
     }
     catch {
         return { auto: false, setBy: null, at: null };
@@ -158,7 +162,7 @@ export function releaseApprovalSetting(store, repo) {
 }
 export const releaseAutoApproves = (store, repo) => releaseApprovalSetting(store, repo).auto;
 /** SQL: the newest setting row for `repo` (an SQL expression) says `auto`. */
-export const releaseAutoSql = (repo) => `COALESCE((SELECT ra_set.outcome = 'auto' FROM action_ledger ra_set WHERE ra_set.repo = ${repo} AND ra_set.task_id IS NULL
+export const releaseAutoSql = (repo) => `COALESCE((SELECT ra_set.outcome = 'auto' FROM action_ledger ra_set ${SETTING_INDEX} WHERE ra_set.repo = ${repo} AND ra_set.task_id IS NULL
       AND ra_set.action = '${RELEASE_APPROVAL_ACTION}' ORDER BY ra_set.id DESC LIMIT 1), 0)`;
 /**
  * SQL over a `task_scope` alias: its automatic seal (`auto-check` or `auto-green`) stands on its own evidence row — this