toolroll 0.9.77 → 0.9.79

package/dist/release-cli.d.ts

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

package/dist/release-cli.js

@@ -14,7 +14,8 @@ const sqlite = () => createRequire(import.meta.url)("node:sqlite");
 import { checkedEnvelopeJson } from "./contracts/cli.js";
 import { RELEASE_LIMITS, runRelease } from "./release.js";
 import { processes, releaseAdapters } from "./release-adapters.js";
-import { releaseGate } from "./release-gate.js";
+import { journals, releaseGate } from "./release-gate.js";
+import { rescueDeployment } from "./deploy-rescue.js";
 import { databasePath, openStore, revokeRelease } from "./store.js";
 import { carryRefusalWords, proveCarry, setAskEveryReleaseCommit, setUnsandboxedCarry } from "./release-carry.js";
 import { authenticateApprover, machineActing, personProof, proveCredential } from "./scope.js";
@@ -39,6 +40,13 @@ toolroll release --release-gate <id> [--yes] — lift the update pause a deploym
   database, service definition and running service are all still the previous build's. --yes lifts that one pause.
   Any missing or contradicting evidence refuses and leaves the pause in place.
 
+toolroll release --recover-deploy [--stage <dir>] [--yes] — put back a deployment that stopped half way
+
+  Finds the one unfinished deployment (or the stage named) and shows what its recovery will do; --yes does it. When
+  the old service isn't proved stopped, it boots the service out and stops what it left running, but only processes
+  proved, by exact runtime path and arguments, to be that deployment's own; then it starts the previous service
+  again, waits for it, and lifts the update pause. Anything it can't prove refuses. Safe to run again.
+
 toolroll release carry <release> --to <commit> [--request <id>] — carry a person's release approval to a later commit
 
   Only tests, docs and the changelog may change after the approval, within the limits, with an identical production
@@ -74,15 +82,17 @@ Options
   --limit <step>=<min>   change one step's time limit (${Object.entries(RELEASE_LIMITS).map(([step, minutes]) => `${step} ${minutes}`).join(", ")})
   --tap <owner/name>     the Homebrew tap (default ap9000/homebrew-toolroll)
   --release-gate <id>    check (and with --yes, lift) one update pause left before a deployment's swap
-  --yes                  with --release-gate: lift the pause once it is proved safe
+  --yes                  with --release-gate: lift the pause once it is proved safe; with --recover-deploy: recover
+  --recover-deploy       recover the unfinished deployment (see above)
+  --stage <dir>          with --recover-deploy: the deployment's staging folder, when more than one is unfinished
   --json                 answer with one machine envelope
 
 A runner's lease is returned with \`toolroll worker release <lease>\`.`;
 /** A runner lease id (claim.ts mints randomUUID()). */
 export const LEASE_SHAPED = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export const LEASE_DEPRECATION = "`toolroll release <lease>` is now `toolroll worker release <lease>`; the old form goes in the next minor version.";
-const VALUE_FLAGS = new Set(["--repo", "--limit", "--tap", "--release-gate", "--to", "--request", "--as", "--token", "--schedule"]);
-const BARE_FLAGS = new Set(["--new", "--json", "--help", "--yes", "--no-carry", "--start"]);
+const VALUE_FLAGS = new Set(["--repo", "--limit", "--tap", "--release-gate", "--to", "--request", "--as", "--token", "--schedule", "--stage"]);
+const BARE_FLAGS = new Set(["--new", "--json", "--help", "--yes", "--no-carry", "--start", "--recover-deploy"]);
 export async function runReleaseCommand(args, write, deps = {}) {
     // The flag, not a secret's value that happens to read "--json".
     // A secret is never exactly one of these names (the loop below refuses that as a missing value).
@@ -94,6 +104,7 @@ export async function runReleaseCommand(args, write, deps = {}) {
     };
     const positional = [];
     const limits = {};
+    let stage;
     let repo, tap, gate, to, request, as, token, scheduleFlag;
     for (let i = 0; i < args.length; i += 1) {
         const raw = args[i];
@@ -126,6 +137,8 @@ export async function runReleaseCommand(args, write, deps = {}) {
                 tap = value;
             else if (arg === "--release-gate")
                 gate = value;
+            else if (arg === "--stage")
+                stage = value;
             else {
                 const match = /^([a-z]+)=([0-9]+)$/.exec(value);
                 if (match === null || !(match[1] in RELEASE_LIMITS) || Number(match[2]) < 1)
@@ -147,8 +160,15 @@ export async function runReleaseCommand(args, write, deps = {}) {
             return refuse("usage", "--release-gate <id> takes no branch or release options.", 2);
         return runGateRelease(gate, bare.has("--yes"), write, json, deps.gateWorld ?? installedGateWorld());
     }
+    if (bare.has("--recover-deploy")) {
+        if (positional.length > 0 || args.some(arg => ["--repo", "--limit", "--tap", "--new", "--release-gate"].includes(arg.split("=")[0])))
+            return refuse("usage", "--recover-deploy takes only --stage <dir>, --yes and --json.", 2);
+        return runRescue(stage, bare.has("--yes"), write, json, deps.rescueWorld ?? installedRescueWorld(deps.cwd ?? process.cwd()));
+    }
+    if (stage !== undefined)
+        return refuse("usage", "--stage goes with --recover-deploy.", 2);
     if (bare.has("--yes"))
-        return refuse("usage", "--yes goes with --release-gate <id>; a release needs no confirmation beyond the owner's approval.", 2);
+        return refuse("usage", "--yes goes with --release-gate <id> or --recover-deploy; a release needs no confirmation beyond the owner's approval.", 2);
     if (positional[0] === "nightly" && positional.length === 1)
         return runNightlyCommand({ repo: repo === undefined ? undefined : resolve(deps.cwd ?? process.cwd(), repo), as, token, schedule: scheduleFlag, start: bare.has("--start") }, write, json, deps);
     if (["carry", "revoke", "ask-every-commit", "unsandboxed-carry", "auto-approve", "publish-ok"].includes(positional[0] ?? "") && positional.length === 2) {
@@ -217,6 +237,55 @@ function installedGateWorld() {
             .filter(path => existsSync(path)).map(path => ({ path, text: readFileSync(path, "utf8") })),
     };
 }
+/** The installation's deployments, its plane's records and the release's own recovery road, for --recover-deploy. */
+function installedRescueWorld(cwd) {
+    const database = databasePath(process.env, homedir());
+    const stateDir = dirname(database);
+    const adapters = releaseAdapters({ checkout: cwd, say: line => process.stderr.write(`${line}\n`) });
+    return {
+        database, stateDir,
+        journals: () => journals(stateDir),
+        runWorktree: run => {
+            if (!existsSync(database))
+                return null;
+            const db = new (sqlite().DatabaseSync)(database, { readOnly: true });
+            try {
+                const row = db.prepare("SELECT worktree FROM run WHERE id = ?").get(run);
+                return typeof row?.["worktree"] === "string" && row["worktree"] !== "" ? row["worktree"] : null;
+            }
+            catch {
+                return null;
+            }
+            finally {
+                db.close();
+            }
+        },
+        recover: async (input) => {
+            const answer = await adapters.toolroll.recoverDeploy(input);
+            return answer.ok ? { ok: true } : { ok: false, message: answer.message };
+        },
+    };
+}
+async function runRescue(stage, yes, write, json, world) {
+    let outcome;
+    try {
+        outcome = await rescueDeployment(stage, yes, world);
+    }
+    catch (error) {
+        outcome = { ok: false, reason: "failed", message: `${error.message} Run \`toolroll release --recover-deploy --yes\` again once the cause is fixed.` };
+    }
+    if (!outcome.ok) {
+        write(json ? checkedEnvelopeJson({ ok: false, command: "release", reason: outcome.reason, message: outcome.message }) : `✗ ${outcome.message}`);
+        return outcome.reason === "usage" ? 2 : 3;
+    }
+    if (json) {
+        write(checkedEnvelopeJson({ ok: true, command: "release", recovery: { acted: outcome.acted, stage: outcome.stage, phase: outcome.phase, said: outcome.words } }));
+        return 0;
+    }
+    for (const line of outcome.words)
+        write(outcome.acted ? `✓ ${line}` : line);
+    return 0;
+}
 function runGateRelease(id, yes, write, json, world) {
     let outcome;
     try {

package/dist/release-gate.d.ts

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

package/dist/release-gate.js

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

package/dist/release-net.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The release tool's one way through a short network failure on the way to GitHub (git or gh): a read that failed for a
+ * transient reason — a connection refused or reset, a name that didn't resolve, a time limit, a 5xx, a truncated or
+ * unparseable answer, GitHub's secondary rate limit — is asked again with backoff for up to about three minutes, then
+ * fails with its original error. A definitive answer (404, 401/403, bad credentials, a missing program) is never asked
+ * again. Nothing here ever turns "couldn't read" into an answer: the caller still sees the failure and fails closed.
+ *
+ * Only a read is retried blindly. A call that changes something (a merge, a tag, a branch push, a release, a tap
+ * change) goes through `writeWithRecheck`: after a transient failure it re-reads GitHub to learn whether the write
+ * happened, and asks again only when it provably didn't.
+ */
+import type { Exec } from "./release-adapters.js";
+export type ExecResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+/** How long one call may keep asking, and how far apart. */
+export declare const NET_RETRY_BUDGET_MS = 180000;
+export declare const NET_RETRY_MAX_ATTEMPTS = 12;
+export declare const netBackoff: (retry: number) => number;
+type RetryBudget = {
+    remaining: () => number;
+    sleep: (ms: number) => Promise<void>;
+};
+declare const sharedBudget: unique symbol;
+export type RetryOptions = {
+    say: (line: string) => void;
+    sleep: (ms: number) => Promise<void>;
+    now?: () => Date;
+    budgetMs?: number;
+    maxAttempts?: number;
+    /** Recovery reads inherit their write's budget, including under an injected clock. */
+    [sharedBudget]?: RetryBudget;
+};
+/**
+ * Whether a failure (its words, and the exit code when it came from a program) is transient: the phrase worth saying,
+ * and how long GitHub asked to wait (Retry-After) when it said. Null for a definitive answer or anything unknown —
+ * an unknown failure is never retried.
+ */
+export declare function transientFailure(text: string, code?: number): {
+    words: string;
+    retryAfterMs: number | null;
+} | null;
+/** Whether one exec result failed transiently (exit 0 never did, unless its answer doesn't parse; see readOnlyCall). */
+export declare function transientResult(result: ExecResult): ReturnType<typeof transientFailure>;
+/**
+ * Whether a call only reads (and so may be asked again blindly): `git ls-remote` and `git fetch` (which only moves the
+ * coordinator's own remote-tracking refs); REST repository `gh api` reads with only the flags below (gh turns
+ * fields or input into a POST); `gh pr list|view|checks`, `gh release view`, `gh repo view`. Anything else is a write, or
+ * unknown, and is never retried by `retryingExec`.
+ */
+export declare function readOnlyCall(command: string, args: readonly string[]): {
+    kind: "git" | "gh-api" | "gh";
+    jsonBody: boolean;
+} | null;
+/** A short name for a call, said once when it is asked again: `gh api repos/…/check-runs`, `git ls-remote`. */
+export declare function callLabel(command: string, args: readonly string[]): string;
+/**
+ * An Exec that asks a read again after a transient failure, with backoff, for up to `budgetMs` (about three minutes)
+ * and `maxAttempts` calls; it says why once per call. When the budget runs out it answers the FIRST failure, exactly as
+ * the program gave it, so the caller stops with the original error. A definitive answer or a success is returned at
+ * once. A call that isn't provably a read (readOnlyCall) is passed straight through, never retried.
+ */
+export declare function retryingExec(run: Exec, options: RetryOptions): Exec;
+/** One read, asked again as retryingExec describes. `call` may do more than the read itself (the release's Git
+ * re-checks the checkout's config first); anything it throws ends the read at once. */
+export declare function retryCall(call: (remainingMs: number) => Promise<ExecResult>, label: string, options: RetryOptions, jsonBody?: boolean): Promise<ExecResult>;
+/**
+ * A write that may be asked again only once GitHub says it didn't happen (idempotency). `write` makes the call;
+ * `accept` reads a successful answer into the value (a SyntaxError there is an answer cut short: transient);
+ * `refuse` throws for a failure. After a transient failure, `recheck` reads the state (its own reads retried): `done`
+ * with the value when the write happened, `not-done` when it provably didn't (only then is it asked again), and
+ * anything else — or a recheck that can't read — stops with the write's original error.
+ */
+export declare function writeWithRecheck<T>(label: string, options: RetryOptions, steps: {
+    write: (remainingMs: number) => Promise<ExecResult>;
+    accept: (result: ExecResult) => T;
+    refuse: (result: ExecResult) => never;
+    recheck: (options: RetryOptions) => Promise<{
+        state: "done";
+        value: T;
+    } | {
+        state: "not-done";
+    } | {
+        state: "other";
+        why: string;
+    }>;
+}): Promise<T>;
+export {};

package/dist/release-net.js

@@ -0,0 +1,253 @@
+/** How long one call may keep asking, and how far apart. */
+export const NET_RETRY_BUDGET_MS = 180_000;
+export const NET_RETRY_MAX_ATTEMPTS = 12;
+const BACKOFF_MS = [2_000, 4_000, 8_000, 16_000, 30_000];
+export const netBackoff = (retry) => BACKOFF_MS[Math.min(retry, BACKOFF_MS.length - 1)];
+const sharedBudget = Symbol("release retry budget");
+function retryBudget(options) {
+    if (options[sharedBudget] !== undefined)
+        return options[sharedBudget];
+    const now = () => (options.now ?? (() => new Date()))().getTime();
+    let last = now(), left = Math.max(0, options.budgetMs ?? NET_RETRY_BUDGET_MS);
+    const remaining = () => {
+        const at = now();
+        left = Math.max(0, left - Math.max(0, at - last));
+        last = at;
+        return left;
+    };
+    return { remaining, sleep: async (ms) => {
+            const before = remaining();
+            await options.sleep(ms);
+            // A frozen/backward fake clock must not grant more backoff than a real clock.
+            const elapsed = before - remaining();
+            left = Math.max(0, left - Math.max(0, ms - elapsed));
+        } };
+}
+const exhausted = () => ({ code: 124, stdout: "", stderr: "the network retry budget ran out" });
+/** Secondary rate limit or 429: transient, and GitHub may say how long to wait. */
+const RATE_LIMITED = /secondary rate limit|abuse detection|HTTP 429|Too Many Requests/i;
+/** A definitive answer: GitHub (or git) answered, and the answer is no. Checked before the transient phrases. */
+const DEFINITIVE = /Toolroll won't run Git|Not Found|Unauthorized|Forbidden|Bad Request|Bad credentials|Requires authentication|authentication required|Authentication failed|Permission denied|Repository not found|Resource not accessible|Must have admin rights|could not read Username|not protected|not enabled|Reference already exists|Validation Failed|Head branch was modified|not mergeable|API rate limit exceeded|GH00[136]|protected branch update failed|\[rejected\]|updates were rejected|stale info|required status check|repository rule violations/i;
+/** Transport failures and server-side trouble: nothing was answered yet. */
+const TRANSIENT = new RegExp([
+    "error connecting to", "Could not resolve host", "no such host", "Temporary failure in name resolution", "nodename nor servname",
+    "Connection refused", "Connection reset", "connection reset by peer", "Failed to connect to", "Couldn't connect to server", "Network is unreachable", "No route to host",
+    "Recv failure", "Send failure", "TLS handshake timeout", "SSL_ERROR_SYSCALL", "SSL_read", "gnutls_handshake", "Operation timed out", "Connection timed out", "i/o timeout",
+    "timeout awaiting", "context deadline exceeded", "Client\\.Timeout", "unexpected EOF", "early EOF", "The remote end hung up unexpectedly", "RPC failed", "broken pipe",
+    "unexpected end of JSON input", "invalid character .{1,12} looking for beginning of value", "Unexpected end of JSON input",
+    "HTTP 5\\d\\d", "returned error: 5\\d\\d", "\\b50[0234] (?:Internal Server Error|Bad Gateway|Service Unavailable|Gateway Timeout)", "Server Error", "Bad Gateway", "Service Unavailable", "Gateway Timeout",
+].join("|"), "i");
+/**
+ * Whether a failure (its words, and the exit code when it came from a program) is transient: the phrase worth saying,
+ * and how long GitHub asked to wait (Retry-After) when it said. Null for a definitive answer or anything unknown —
+ * an unknown failure is never retried.
+ */
+export function transientFailure(text, code) {
+    if (code === 127)
+        return null;
+    if (DEFINITIVE.test(text))
+        return null;
+    const limited = RATE_LIMITED.exec(text);
+    // A rate-limit hint never overrides an independent refusal. Only 403/429 may
+    // describe a secondary limit; git prints HTTP errors differently from gh.
+    const statuses = [...text.matchAll(/(?:HTTP(?:\/[\d.]+)?\s+|returned error:\s*)(4\d\d)\b/gi)].map(match => Number(match[1]));
+    if (statuses.some(status => limited === null || (status !== 403 && status !== 429)))
+        return null;
+    if (limited !== null) {
+        const after = /Retry-After:\s*(\d{1,4})/i.exec(text) ?? /(?:try again|retry) in (\d{1,4}) ?s(?:econds?)?/i.exec(text);
+        return { words: limited[0], retryAfterMs: after === null ? null : Number(after[1]) * 1000 };
+    }
+    const found = TRANSIENT.exec(text);
+    // The phrase and the rest of its line ("Could not resolve host: github.com"), kept short.
+    if (found !== null)
+        return { words: text.slice(found.index).split("\n")[0].trim().slice(0, 80), retryAfterMs: null };
+    // The coordinator's own time limit on the child (exec answers 124 when it killed it).
+    if (code === 124)
+        return { words: "the call timed out", retryAfterMs: null };
+    return null;
+}
+const failureText = (result) => `${result.stderr}\n${result.stdout}`;
+/** Whether one exec result failed transiently (exit 0 never did, unless its answer doesn't parse; see readOnlyCall). */
+export function transientResult(result) {
+    return result.code === 0 ? null : transientFailure(failureText(result), result.code);
+}
+/** The git subcommand among the arguments: the first that isn't an option or an option's value. */
+function gitSubcommand(args) {
+    for (let at = 0; at < args.length; at++) {
+        const arg = args[at];
+        if (["-c", "-C", "--git-dir", "--work-tree", "--namespace", "--config-env"].includes(arg)) {
+            if (args[++at] === undefined)
+                return null;
+            continue;
+        }
+        if (/^-[cC]./.test(arg) || /^--(?:git-dir|work-tree|namespace|config-env|attr-source)=/.test(arg))
+            continue;
+        if (["--no-optional-locks", "--no-replace-objects", "--no-pager", "--no-lazy-fetch", "--literal-pathspecs"].includes(arg))
+            continue;
+        if (arg.startsWith("-"))
+            return null;
+        return arg;
+    }
+    return null;
+}
+/**
+ * Whether a call only reads (and so may be asked again blindly): `git ls-remote` and `git fetch` (which only moves the
+ * coordinator's own remote-tracking refs); REST repository `gh api` reads with only the flags below (gh turns
+ * fields or input into a POST); `gh pr list|view|checks`, `gh release view`, `gh repo view`. Anything else is a write, or
+ * unknown, and is never retried by `retryingExec`.
+ */
+export function readOnlyCall(command, args) {
+    const name = command.split("/").pop() ?? command;
+    if (name === "git") {
+        const sub = gitSubcommand(args);
+        return sub === "ls-remote" || sub === "fetch" ? { kind: "git", jsonBody: false } : null;
+    }
+    if (name !== "gh")
+        return null;
+    if (args[0] === "api") {
+        let endpoint = null, shaped = false;
+        for (let at = 1; at < args.length; at++) {
+            const arg = args[at];
+            // Parse only spellings we know. In particular, pflag accepts -iXPOST and -ifbody=...;
+            // a blacklist of tokens beginning with -X/-f cannot prove those calls read-only.
+            if (arg === "--paginate" || arg === "--slurp") {
+                shaped = true;
+                continue;
+            }
+            const flag = /^(--(?:method|hostname|jq|template))(?:=(.*))?$/.exec(arg) ?? /^(-[Xqt])(.*)$/.exec(arg);
+            if (flag !== null) {
+                const value = flag[2] || args[++at];
+                if (value === undefined || value.startsWith("-"))
+                    return null;
+                if (flag[1] === "-X" || flag[1] === "--method") {
+                    if (value !== "GET")
+                        return null;
+                }
+                else if (flag[1] !== "--hostname")
+                    shaped = true;
+                continue;
+            }
+            if (arg.startsWith("-") || endpoint !== null || !/^\/?repos\/[^\s]+$/.test(arg))
+                return null;
+            endpoint = arg;
+        }
+        return endpoint === null ? null : { kind: "gh-api", jsonBody: !shaped };
+    }
+    const pair = `${args[0] ?? ""} ${args[1] ?? ""}`;
+    if (!["pr list", "pr view", "pr checks", "release view", "repo view"].includes(pair))
+        return null;
+    const shaped = args.some(arg => arg === "--jq" || arg === "-q" || arg === "--template" || arg === "-t" || /^--(?:jq|template)=/.test(arg));
+    return { kind: "gh", jsonBody: !shaped && args.some(arg => arg === "--json" || arg.startsWith("--json=")) };
+}
+/** A short name for a call, said once when it is asked again: `gh api repos/…/check-runs`, `git ls-remote`. */
+export function callLabel(command, args) {
+    const name = command.split("/").pop() ?? command;
+    if (name === "git")
+        return `git ${gitSubcommand(args) ?? ""}`.trim();
+    if (args[0] === "api") {
+        const path = args.find(one => one.startsWith("repos/")) ?? args.find((one, at) => at > 0 && !one.startsWith("-")) ?? "";
+        return `gh api ${path.split("?")[0].replace(/[0-9a-f]{40}/g, sha => sha.slice(0, 7))}`.trim();
+    }
+    return `gh ${args.slice(0, 2).join(" ")}`;
+}
+/**
+ * An Exec that asks a read again after a transient failure, with backoff, for up to `budgetMs` (about three minutes)
+ * and `maxAttempts` calls; it says why once per call. When the budget runs out it answers the FIRST failure, exactly as
+ * the program gave it, so the caller stops with the original error. A definitive answer or a success is returned at
+ * once. A call that isn't provably a read (readOnlyCall) is passed straight through, never retried.
+ */
+export function retryingExec(run, options) {
+    return async (command, args, execOptions) => {
+        const read = readOnlyCall(command, args);
+        if (read === null)
+            return run(command, args, execOptions);
+        return retryCall(remainingMs => run(command, args, { ...execOptions,
+            timeoutMs: Math.min((execOptions?.timeoutMs ?? 0) > 0 ? execOptions.timeoutMs : 120_000, remainingMs),
+        }), callLabel(command, args), options, read.jsonBody);
+    };
+}
+/** Whether a 0-exit plain JSON body parses; a truncated one is a transient failure. */
+const bodyParses = (stdout) => { try {
+    JSON.parse(stdout);
+    return true;
+}
+catch {
+    return false;
+} };
+/** One read, asked again as retryingExec describes. `call` may do more than the read itself (the release's Git
+ * re-checks the checkout's config first); anything it throws ends the read at once. */
+export async function retryCall(call, label, options, jsonBody = false) {
+    const budget = retryBudget(options);
+    const maxAttempts = options.maxAttempts ?? NET_RETRY_MAX_ATTEMPTS;
+    let first = null;
+    for (let attempt = 0;; attempt++) {
+        const remaining = budget.remaining();
+        if (remaining <= 0)
+            return first ?? exhausted();
+        const result = await call(remaining);
+        let why = transientResult(result);
+        if (why === null && result.code === 0 && jsonBody && !bodyParses(result.stdout))
+            why = { words: "an answer cut short", retryAfterMs: null };
+        if (why === null)
+            return result;
+        // The original failure is what the caller sees; a truncated 0-exit body becomes an explicit failure.
+        first ??= result.code !== 0 ? result : { code: 1, stdout: result.stdout, stderr: "unexpected end of JSON input (GitHub's answer was cut short)" };
+        const wait = why.retryAfterMs ?? netBackoff(attempt);
+        if (attempt + 1 >= maxAttempts || wait >= budget.remaining())
+            return first;
+        if (attempt === 0)
+            options.say(`  GitHub didn't answer ${label} (${why.words}); asking again for up to ${Math.round((options.budgetMs ?? NET_RETRY_BUDGET_MS) / 60_000)} min.`);
+        await budget.sleep(wait);
+    }
+}
+/**
+ * A write that may be asked again only once GitHub says it didn't happen (idempotency). `write` makes the call;
+ * `accept` reads a successful answer into the value (a SyntaxError there is an answer cut short: transient);
+ * `refuse` throws for a failure. After a transient failure, `recheck` reads the state (its own reads retried): `done`
+ * with the value when the write happened, `not-done` when it provably didn't (only then is it asked again), and
+ * anything else — or a recheck that can't read — stops with the write's original error.
+ */
+export async function writeWithRecheck(label, options, steps) {
+    const budget = retryBudget(options);
+    const maxAttempts = options.maxAttempts ?? NET_RETRY_MAX_ATTEMPTS;
+    let first = null;
+    for (let attempt = 0;; attempt++) {
+        const remaining = budget.remaining();
+        if (remaining <= 0)
+            return steps.refuse(first ?? exhausted());
+        const result = await steps.write(remaining);
+        let why = transientResult(result);
+        if (result.code === 0) {
+            try {
+                return steps.accept(result);
+            }
+            catch (error) {
+                if (!(error instanceof SyntaxError))
+                    throw error;
+                why = { words: "an answer cut short", retryAfterMs: null };
+            }
+        }
+        if (why === null)
+            return steps.refuse(result);
+        first ??= result.code !== 0 ? result : { code: 1, stdout: result.stdout, stderr: "unexpected end of JSON input (GitHub's answer was cut short)" };
+        if (budget.remaining() <= 0)
+            return steps.refuse(first);
+        if (attempt === 0)
+            options.say(`  GitHub didn't answer ${label} (${why.words}); reading GitHub to learn whether it happened.`);
+        let state;
+        try {
+            state = await steps.recheck({ ...options, maxAttempts: NET_RETRY_MAX_ATTEMPTS, [sharedBudget]: budget });
+        }
+        catch (error) {
+            return steps.refuse({ ...first, stderr: `${first.stderr.trim()} (and whether it happened couldn't be read: ${String(error?.message ?? error).slice(0, 200)})` });
+        }
+        if (state.state === "done")
+            return state.value;
+        if (state.state === "other")
+            return steps.refuse({ ...first, stderr: `${first.stderr.trim()} (${state.why})` });
+        const wait = why.retryAfterMs ?? netBackoff(attempt);
+        if (attempt + 1 >= maxAttempts || wait >= budget.remaining())
+            return steps.refuse(first);
+        await budget.sleep(wait);
+    }
+}

package/dist/release-recheck.js

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

package/dist/release.d.ts

@@ -34,7 +34,7 @@
  */
 /** The pull-request checks a release waits for, by exact job name (.github/workflows/ci.yml). Every one must have
  * concluded `success` on the gated commit; src/ci-workflow.test.ts holds the workflow to this list. */
-export declare const REQUIRED_PR_CHECKS: readonly ["node 22 · ubuntu-latest", "node 24 · ubuntu-latest", "linux native containment · delegated cgroup v2", "linux fence · sandbox-runtime", "Windows Job Object containment", "git 2.41 · debian trixie", "git 2.47 · debian trixie"];
+export declare const REQUIRED_PR_CHECKS: readonly ["node 22 · ubuntu-latest", "node 24 · ubuntu-latest", "linux native containment · delegated cgroup v2", "linux fence · sandbox-runtime", "Windows Job Object containment", "git 2.41 · debian trixie", "git 2.47 · debian trixie", "node 22 · macos-latest", "node 24 · macos-latest"];
 /** The workflow file every REQUIRED_PR_CHECKS job belongs to: a job of that name from any other workflow (a lookalike
  * added beside it) never stands for it (Codex review round 1, inherited CI limitation). */
 export declare const REQUIRED_PR_CHECKS_WORKFLOW = ".github/workflows/ci.yml";
@@ -57,8 +57,11 @@ export type MainProtection = {
     missing: string[];
     notYetRequired: string[];
 };
-/** The checks a release tag runs (.github/workflows/publish.yml), awaited before Homebrew moves. */
-export declare const RELEASE_TAG_CHECKS: readonly ["node 22 · macos-latest", "node 24 · macos-latest", "publish"];
+/** The checks a release's publication waits for on its tag (.github/workflows/publish.yml, pipeline-speed.md item 3):
+ * the publish job and the macOS legs it needs, each named. Nothing else reported on the merge commit (main's own CI push
+ * run) holds publication. */
+export declare const RELEASE_TAG_CHECKS: readonly ["publish", "tag macOS · node 22", "tag macOS · node 24"];
+export declare const RELEASE_TAG_WORKFLOW = ".github/workflows/publish.yml";
 export declare const RELEASE_STEPS: readonly ["gate", "approval", "check", "complete", "quiet", "deploy", "link", "ci", "merge", "tree", "tag", "publish", "homebrew", "done"];
 export type ReleaseStep = typeof RELEASE_STEPS[number];
 type WaitingStep = "gate" | "approval" | "check" | "quiet" | "deploy" | "ci" | "publish" | "homebrew";
@@ -170,6 +173,8 @@ export type DeployStop = {
         phase: string;
     };
 };
+/** The tap's formula for a version: current, a proposal open, missing — or `newer`: the tap's default branch already
+ * names a later version, which an older release must never overwrite. */
 export type HomebrewState = {
     kind: "current";
 } | {
@@ -178,7 +183,14 @@ export type HomebrewState = {
     head: string;
 } | {
     kind: "missing";
+} | {
+    kind: "newer";
+    version: string;
 };
+/** Homebrew after publication (pipeline-speed.md, P1): its own durable state, finished by `toolroll release <branch>`.
+ * `pending`: a change proposed or its checks still running; `failed`: its checks failed (a later run reads them again);
+ * `current`: merged, or already on the tap; `superseded`: the tap already names a newer version, so nothing was changed. */
+export type HomebrewProgress = "pending" | "failed" | "current" | "superseded";
 /** One commit that landed after the approval, with its files and line counts (release_carry). */
 export type LandedCommit = {
     sha: string;
@@ -442,7 +454,10 @@ export type ReleaseAdapters = {
     github: {
         authenticated(): Promise<boolean>;
         pullRequest(repo: string, branch: string): Promise<PullRequest | null>;
-        checks(repo: string, sha: string): Promise<CheckRun[]>;
+        /** `tag`: a release tag's push binds its workflow file too (only that exact tag's push). */
+        checks(repo: string, sha: string, options?: {
+            tag?: string;
+        }): Promise<CheckRun[]>;
         /** Whether GitHub's check history of this commit can be read whole (fewer check suites than the check-runs
          * endpoint's ceiling). Absent or false: an automatic release fails closed; a person's is unaffected. */
         complete?(repo: string, sha: string): Promise<boolean>;
@@ -472,6 +487,14 @@ export type ReleaseAdapters = {
             pr: number;
             head: string;
         }>;
+        /** Right before the merge: the change is the tap's own open pull request at exactly `head`, and its formula is
+         * exactly the tap's formula with npm's published tarball for `version` and that tarball's own sha256. */
+        verified(pr: number, head: string, version: string): Promise<{
+            ok: true;
+        } | {
+            ok: false;
+            why: string;
+        }>;
         merge(pr: number, head: string): Promise<void>;
     };
 };
@@ -538,6 +561,9 @@ export type ReleaseJournal = {
         pr: number | null;
         head: string | null;
         merged: boolean;
+        /** Absent in a journal from before Homebrew was finished apart: read from `merged`. */
+        state?: HomebrewProgress;
+        why?: string | null;
     } | null;
     /** The release's authority record (release-once.md), once a person approved terms: the id and generation. */
     authority?: {
@@ -635,9 +661,18 @@ 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. */
+/** A probe's failure that is only the network to GitHub failing for now (release-net.ts transientFailure: a timeout, a
+ * connection or name failure, a 5xx, an answer cut short, a secondary rate limit), never a decision (a Stop), a
+ * definitive answer or another error. */
 export declare function transientNetworkError(error: unknown): boolean;
 /**
  * The pull request's checks on exactly `head`, every attempt (the adapter asks GitHub for all of them, filter=all):