toolroll 0.9.76 → 0.9.78

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,33 +82,45 @@ 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 = {}) {
-    const json = args.includes("--json");
+    // 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).
+    const bare = new Set(args.filter(one => BARE_FLAGS.has(one)));
+    const json = bare.has("--json");
     const refuse = (reason, message, code) => {
         write(json ? checkedEnvelopeJson({ ok: false, command: "release", reason, message }) : message);
         return code;
     };
     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 arg = args[i];
-        if (BARE_FLAGS.has(arg))
+        const raw = args[i];
+        if (BARE_FLAGS.has(raw))
             continue;
+        // `--flag=value` for every value flag; a secret (--token) is also the next argument even when it starts with "--".
+        const equals = raw.startsWith("--") ? raw.indexOf("=") : -1;
+        const arg = equals === -1 ? raw : raw.slice(0, equals);
         if (VALUE_FLAGS.has(arg)) {
-            const value = args[i + 1];
-            if (value === undefined || value.startsWith("--"))
+            const value = equals === -1 ? args[i + 1] : raw.slice(equals + 1);
+            // A secret may start with "--"; it is the value unless it is exactly one of this command's flags (never swallowed).
+            const namesFlag = value !== undefined && (BARE_FLAGS.has(value) || VALUE_FLAGS.has(value.split("=")[0]));
+            if (value === undefined || (equals === -1 && value.startsWith("--") && (arg !== "--token" || namesFlag)))
                 return refuse("usage", `${arg} takes a value.`, 2);
-            i += 1;
+            if (equals === -1)
+                i += 1;
             if (arg === "--repo")
                 repo = value;
             else if (arg === "--to")
@@ -117,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)
@@ -125,23 +147,30 @@ export async function runReleaseCommand(args, write, deps = {}) {
             }
             continue;
         }
-        if (arg.startsWith("--"))
+        if (raw.startsWith("--"))
             return refuse("usage", `Unknown option ${arg}.\n${RELEASE_HELP}`, 2);
         positional.push(arg);
     }
-    if (args.includes("--help")) {
+    if (bare.has("--help")) {
         write(RELEASE_HELP);
         return 0;
     }
     if (gate !== undefined) {
         if (positional.length > 0 || args.some(arg => ["--repo", "--limit", "--tap", "--new"].includes(arg)))
             return refuse("usage", "--release-gate <id> takes no branch or release options.", 2);
-        return runGateRelease(gate, args.includes("--yes"), write, json, deps.gateWorld ?? installedGateWorld());
+        return runGateRelease(gate, bare.has("--yes"), write, json, deps.gateWorld ?? installedGateWorld());
     }
-    if (args.includes("--yes"))
-        return refuse("usage", "--yes goes with --release-gate <id>; a release needs no confirmation beyond the owner's approval.", 2);
+    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> 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: args.includes("--start") }, write, json, deps);
+        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) {
         return runAuthorityCommand(positional[0], positional[1], { to, request, as, token, repo: repo === undefined ? undefined : resolve(deps.cwd ?? process.cwd(), repo) }, write, json, deps);
     }
@@ -169,7 +198,7 @@ export async function runReleaseCommand(args, write, deps = {}) {
     const adapters = deps.adapters === undefined
         ? releaseAdapters({ checkout, say, ...(tap === undefined ? {} : { tap }), ...(limits["deploy"] === undefined ? {} : { deployMinutes: limits["deploy"] }) })
         : { ...deps.adapters, say };
-    const outcome = await runRelease({ branch, checkout, stateDir, limits, fresh: args.includes("--new"), noCarry: args.includes("--no-carry") }, adapters);
+    const outcome = await runRelease({ branch, checkout, stateDir, limits, fresh: bare.has("--new"), noCarry: bare.has("--no-carry") }, adapters);
     return report(outcome, write, json, lines);
 }
 function report(outcome, write, json, lines) {
@@ -208,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-coverage.js

@@ -4,7 +4,7 @@
  * existing records and Git; nothing is written back, so no proof, receipt,
  * scope digest or schema changes. Fails closed: a receipt that can't be read,
  * a missing commit or any Git error leaves the result uncovered. */
-import { execFileSync } from "node:child_process";
+import { viewedGitSync } from "./teardown-git.js";
 import { verificationEvidence } from "./verification-evidence.js";
 import { runCheckLevel } from "./check-levels.js";
 /** How many of the newest passing release checks one read considers. */
@@ -25,7 +25,10 @@ export const gitIsAncestor = (repo, ancestor, descendant) => {
         return known;
     let answer;
     try {
-        execFileSync("git", ["-C", repo, "--no-lazy-fetch", "--no-optional-locks", "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", "merge-base", "--is-ancestor", ancestor, descendant], { stdio: "ignore", timeout: 5_000 });
+        // Every git version through a frozen read view, bounded (eval-harness review 1, finding 7).
+        const status = viewedGitSync(repo, ["merge-base", "--is-ancestor", ancestor, descendant], { timeoutMs: 5_000 }).status;
+        if (status !== 0)
+            throw Object.assign(new Error("git merge-base"), { status });
         answer = true;
     }
     catch (error) {

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.d.ts

@@ -72,7 +72,7 @@ export declare function planTargetedRecheck(store: Store, root: string, input: {
     now: Date;
 }): RecheckDecision;
 /** Coverage of a check: full, composed from A, partial (never passes), or identity-removed (asks again). */
-export type Coverage = "full" | "composed" | "partial" | "identity-removed";
+export type Coverage = "full" | "composed" | "partial" | "identity-removed" | "no-result";
 /**
  * Whether a targeted run B, with A's sealed evidence, its plan and snapshot, covers every item of B's inventory
  * (coverage conservation), and every required identity passed — re-derived from sealed values only.

package/dist/release-recheck.js

@@ -20,12 +20,12 @@
  * Coverage trusts test code (Alex, 2026-10-25): these results protect against accidental damage, not a hostile test.
  * Authority never reads them; the release's own records do.
  */
-import { CHECK_CONTEXT_CAPTURE, CHECK_INVENTORY_CAPTURE, CHECK_REPORT_CAPTURE, OBLIGATION_SNAPSHOT_CAPTURE, TARGETED_PLAN_CAPTURE, checkContextOf, isUnitFile, payloadDigest, projectGitDir, readSealedJson, treeFactsOf } from "./check-report.js";
+import { CHECK_CONTEXT_CAPTURE, CHECK_INVENTORY_CAPTURE, CHECK_REPORT_CAPTURE, OBLIGATION_SNAPSHOT_CAPTURE, TARGETED_PLAN_CAPTURE, checkContextOf, fullCheckProblem, isUnitFile, payloadDigest, projectGitDir, readSealedJson, treeFactsOf } from "./check-report.js";
 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"]);
@@ -483,6 +483,12 @@ export function settleCoverage(store, root, input, gateOf) {
             if (removedProtected(b.report, b.inventory, protectedIdentities(store, root, b.attempt.authority, input.runId)))
                 return removed();
         }
+        // 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.
+        // 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 };
     }
     if (b.plan === null || b.snapshot === null || b.attempt.baseRun === null || b.attempt.authority === null)

package/dist/release.d.ts

@@ -34,9 +34,34 @@
  */
 /** 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"];
-/** 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"];
+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";
+/**
+ * The pull-request checks main's GitHub protection is not yet required to name (eval-harness review 2, finding 1): the
+ * git lanes join main's protection once they have run there, so a protection without them is reported, never refused.
+ * A later release empties this list; from then on main's protection must name every REQUIRED_PR_CHECKS check.
+ */
+export declare const PROTECTION_REPORT_ONLY_CHECKS: readonly string[];
+/** The checks main's protection must require at minimum: every required check that isn't report-only. */
+export declare const PROTECTION_MINIMUM_CHECKS: readonly string[];
+/**
+ * Main's protection as the plane's gh reads it (release-adapters.ts readMainProtection): `effective` only when one layer
+ * (classic protection or one active ruleset) requires up-to-date branches, binds every PROTECTION_MINIMUM_CHECKS check to GitHub Actions,
+ * and nobody merging as this gh can bypass it. `missing` names each absent property; `notYetRequired` the report-only
+ * checks the effective layer doesn't name.
+ */
+export type MainProtection = {
+    effective: boolean;
+    missing: string[];
+    notYetRequired: string[];
+};
+/** 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";
@@ -55,10 +80,20 @@ export type CheckRun = {
     head?: string | null;
     /** The workflow (its id, from GitHub's workflow-run API) that this check's suite is a run of, when known. */
     workflow?: number | null;
+    /** That workflow's file in the repository (GitHub's workflow-run `path`), when known. */
+    workflowPath?: string | null;
+    /** GitHub's own job record (its steps, read by the plane's gh) shows this unsuccessful attempt ended before any of the
+     * workflow's own steps ran: the runner failed, not the tests. Absent or false: nothing shows that. */
+    beforeTests?: boolean | null;
 };
-/** How many failed attempts of one CI check, and failed release-check runs, an automatic approval tolerates (flakes on a
- * pinned commit and digest), before a person decides (auto-approve-green.md). */
-export declare const AUTO_FLAKE_CAP = 2;
+/**
+ * Failure classes replace a flat flake allowance (docs/plans/eval-harness.md; check-failure.ts says the classes): only a
+ * failure the plane itself confirmed as infrastructure is ever run again under the same approval — at most once per
+ * incident and twice per candidate — for a release check and for a GitHub CI job alike. A failing test, a typecheck, an
+ * attack test, a migration: none tolerated. An unexplained failure blocks, and a person decides.
+ */
+export declare const INFRA_RERUNS_PER_INCIDENT = 1;
+export declare const INFRA_RERUNS_PER_CANDIDATE = 2;
 /** One failed attempt that a later attempt of the same job passed. */
 export type CheckFailure = {
     id: number;
@@ -138,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";
 } | {
@@ -146,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;
@@ -168,6 +212,18 @@ export type AuthorityView = {
     landed: LandedCommit[];
 };
 export type ReleaseAction = "dispatch" | "deploy" | "merge" | "complete";
+/** The plane's answer after a failed release check: rerun (confirmed infrastructure), already rerunning, or stop. */
+export type FailureClassName = "deterministic" | "infrastructure" | "unknown" | "agent-behaviour";
+export type RecheckView = {
+    action: "rerun";
+    why: string;
+} | {
+    action: "pending";
+} | {
+    action: "stop";
+    class: FailureClassName | null;
+    why: string;
+};
 export type OperationView = {
     id: string;
     kind: "deploy" | "merge";
@@ -231,6 +287,20 @@ export type ReleaseAuthorityAdapter = {
      * the authority could not be stopped (a stale epoch, a merge already reserved): the coordinator fails closed. */
     needsApproval(authority: number, reason: string, epoch: number): Promise<boolean>;
     operations(authority: number): Promise<OperationView[]>;
+    /** After a failed release check (check-failure.ts): the plane classifies it from its own records and, only for
+     * confirmed infrastructure within its limits, runs the check again on the same candidate under the same approval.
+     * Absent on an older plane: a failed check stops as before. */
+    recheck?(taskId: string): Promise<RecheckView>;
+    /** Whether a passing check stands given every earlier attempt on the same commit (an earlier failure that wasn't
+     * confirmed infrastructure isn't erased by a pass), and what passed only on a retry. */
+    standing?(taskId: string, run: number): Promise<{
+        ok: true;
+        retried: string[] | null;
+    } | {
+        ok: false;
+        why: string;
+        retried: string[] | null;
+    }>;
     /** Releases that approve themselves when green (docs/plans/auto-approve-green.md): the plane's own seals, each proven
      * again inside the plane. Absent: a plane that can't, and every release asks a person as before. */
     auto?: AutoReleaseAdapter;
@@ -279,6 +349,17 @@ export type AutoReleaseAdapter = {
     }>;
     /** The automatic road ended without a release: the task asks a person, and the owner is told why. */
     giveUp(taskId: string, why: string): Promise<void>;
+    /** The task is filed while CI still runs on `candidate` (recorded in the plane before the task is filed): its approval
+     * card says so until the plane reads CI passing. It holds nothing (Alex, 2026-10-29: a person may approve during CI). */
+    ciRunning?(taskId: string, candidate: string): Promise<void>;
+    /** The plane reads CI on `candidate` itself and, when every required check passed, ends the "CI still running" note
+     * (and lifts a hold an older coordinator placed); `ask` tells the owner of a held release it needs them now. */
+    ciPassed?(taskId: string, candidate: string, ask: boolean): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        why: string;
+    }>;
     /** The release check failed while checking automatically: the owner is told; the commit may be checked again (a
      * regate of the same commit and digest, within the plane's cap on failed runs). */
     checkFailed(taskId: string, why: string): Promise<void>;
@@ -306,10 +387,6 @@ export type ReleaseAdapters = {
         deleteBranch(branch: string, head: string): Promise<void>;
         tree(sha: string): Promise<string>;
         fileAt(sha: string, path: string): Promise<string | null>;
-        /** origin/main as the last sync fetched it. */
-        mainHead(): Promise<string>;
-        /** Whether `ancestor` is in `sha`'s history. */
-        contains(sha: string, ancestor: string): Promise<boolean>;
     };
     toolroll: {
         /** Which runtime each launchd service and each CLI name (`toolroll`, `standing-orders`) runs from. */
@@ -377,11 +454,21 @@ 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>;
         merge(repo: string, pr: number, head: string, message?: string): Promise<string>;
+        /** main's head as GitHub's API answers now (never a local ref a build could move). */
+        mainHead(repo: string): Promise<string>;
+        /** Whether `sha` already holds `ancestor`, by GitHub's own comparison. */
+        contains(repo: string, sha: string, ancestor: string): Promise<boolean>;
+        /** Whether GitHub refuses to merge a branch that is behind main ("Require branches to be up to date before
+         * merging"); null when it can't be read. Read only. */
+        upToDateRequired(repo: string): Promise<MainProtection | null>;
         tag(repo: string, tag: string): Promise<string | null>;
         createTag(repo: string, tag: string, sha: string): Promise<void>;
         release(repo: string, tag: string): Promise<boolean>;
@@ -400,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>;
     };
 };
@@ -466,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?: {
@@ -490,6 +588,13 @@ export type ReleaseJournal = {
         why?: string;
         ci?: number[];
     } | null;
+    /** The gate filed the task while the pull request's checks still ran (pipeline-speed.md, D2 and "Decision: a person's
+     * release asks during CI"): the release check runs beside CI. A person may approve meanwhile; the plane's automatic
+     * approval waits for every check to pass, and nothing deploys, merges, tags or publishes before they do. */
+    ciAhead?: boolean;
+    /** Set with ciAhead and never cleared for this commit: a person's release reads CI again, fresh, right before the
+     * deploy, whatever was seen while asking (a green CI may have a newer attempt failing since). */
+    ciBeforeDeploy?: boolean;
     /** When each step was about to change something outside this machine: what a resume must look for before acting. */
     intents: Partial<Record<ReleaseStep, string>>;
     stopped: {
@@ -556,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. */
@@ -565,11 +677,14 @@ export declare function transientNetworkError(error: unknown): boolean;
  * each reported attempt must be filed under `head` with a check-run id; a required check counts only from GitHub
  * Actions (an app that names a check alike can't stand in for it); attempts are grouped by the job they belong to — the
  * app, its check suite (a workflow run, whose re-runs stay in it) and the name — and every group is judged by its
- * latest attempt; every required check needs a group. With `cap`, a group whose earlier attempts failed more than `cap`
- * times fails too (an automatic approval's flake allowance); the failures it tolerated are returned.
+ * latest attempt; every required check needs a group. With `auto` (an automatic approval), every other failed attempt on
+ * the commit — an earlier attempt, or a job a newer run renamed or dropped — must be one GitHub's own job record shows ending before any workflow step ran (`beforeTests`: confirmed
+ * infrastructure), and at most INFRA_RERUNS_PER_CANDIDATE of them on the commit; any other earlier failure — a test,
+ * a typecheck, or one nothing explains — fails the verdict, so a person decides. The failures it tolerated are returned.
  */
 export declare function prChecksVerdict(runs: readonly CheckRun[], head: string, required: readonly string[], options?: {
-    cap?: number;
+    auto?: true;
+    workflow?: string;
 }): {
     state: "passed";
     failures: CheckFailure[];
@@ -580,4 +695,19 @@ export declare function prChecksVerdict(runs: readonly CheckRun[], head: string,
     state: "failed";
     failed: string[];
 };
+/**
+ * What a failed release check means and what happens next, by its class (check-failure.ts), in words. Only confirmed
+ * infrastructure reruns on its own; nothing else is rerun to pass.
+ */
+export declare function checkFailedWords(input: {
+    sha: string;
+    run: number;
+    class: FailureClassName | null;
+    why: string;
+    branch: string;
+    checkout: string;
+    taskId: string;
+}): string;
+/** Whether GitHub's workflow-run `path` names exactly `file` (it may carry the ref it ran from, after an `@`). */
+export declare function workflowIs(path: string | null | undefined, file: string): boolean;
 export {};