toolroll 0.9.78 → 0.9.81

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

@@ -32,16 +32,18 @@
  * Everything outside this module is an adapter (release-adapters.ts), so the state machine is tested without git,
  * GitHub, npm or a running Toolroll.
  */
-/** 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", "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
+/** The pull-request checks a release waits for, by exact job name (docs/plans/test-matrix.md). Every one must have
+ * concluded `success` — executed, never skipped — on the gated commit; src/ci-workflow.test.ts holds the workflows to
+ * this list, and publish.yml's release proof to the same list. */
+export declare const REQUIRED_PR_CHECKS: readonly ["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 24 · macos-latest", "node 22 · ubuntu-latest", "node 22 · macos-latest"];
+/** The workflow file each 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";
+export declare const REQUIRED_PR_CHECKS_WORKFLOW: Readonly<Record<typeof REQUIRED_PR_CHECKS[number], string>>;
 /**
- * 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.
+ * The pull-request checks main's GitHub protection is not yet required to name (eval-harness review 2, finding 1).
+ * Empty since the test matrix (docs/plans/test-matrix.md): publication's release proof trusts what main's protection
+ * required at the merge, so main's protection must name every REQUIRED_PR_CHECKS check, and a release refuses to merge
+ * (and so to publish) until it does.
  */
 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. */
@@ -57,10 +59,11 @@ export type MainProtection = {
     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"];
+/** The checks a release's publication waits for on its tag (.github/workflows/publish.yml, docs/plans/test-matrix.md):
+ * the release proof (the tagged tree passed every REQUIRED_PR_CHECKS check on its pull request, read from GitHub) and
+ * the publish job that needs it. The tag runs no tests again. Nothing else reported on the merge commit (main-push.yml)
+ * holds publication. */
+export declare const RELEASE_TAG_CHECKS: readonly ["release proof", "publish"];
 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];
@@ -662,15 +665,17 @@ export declare function checksVerdict(runs: readonly CheckRun[], required: reado
     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.
+ * Publication's verdict on the tag commit (test-matrix.md): 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
+ * push run — is not waited for: the candidate's checks already passed on its exact head before the merge, the merged
+ * tree was proved equal to it, and publish.yml's release proof checks both again from GitHub's record.
  */
 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):
@@ -684,7 +689,7 @@ export declare function transientNetworkError(error: unknown): boolean;
  */
 export declare function prChecksVerdict(runs: readonly CheckRun[], head: string, required: readonly string[], options?: {
     auto?: true;
-    workflow?: string;
+    workflow?: string | Readonly<Record<string, string>>;
 }): {
     state: "passed";
     failures: CheckFailure[];

package/dist/release.js

@@ -37,37 +37,55 @@ import { randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
 import { personProof } from "./person-proof.js";
 import { RELEASE_CI_RUNNING_WORDS as CI_RUNNING_WORDS } from "./release-ci-hold.js";
-/** 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. */
+import { transientFailure } from "./release-net.js";
+/** The pull-request checks a release waits for, by exact job name (docs/plans/test-matrix.md). Every one must have
+ * concluded `success` — executed, never skipped — on the gated commit; src/ci-workflow.test.ts holds the workflows to
+ * this list, and publish.yml's release proof to the same list. */
 export const REQUIRED_PR_CHECKS = [
-    "node 22 · ubuntu-latest",
+    // The unit suite on Node 24 (ci.yml "test-shard" and "test"), on every pull request.
     "node 24 · ubuntu-latest",
+    // The area lanes (ci.yml), on every pull request except a documentation-only one (scripts/ci-scope.mjs), where they
+    // are skipped; a release's pull request runs them.
     "linux native containment · delegated cgroup v2",
     "linux fence · sandbox-runtime",
     "Windows Job Object containment",
     // The git lanes (ci.yml job "git"): the declared floor (git-floor.ts) and Debian trixie's 2.47.
     "git 2.41 · debian trixie",
     "git 2.47 · debian trixie",
-    // The unit suite on macOS (ci.yml jobs "macos-shard" and "macos"; pipeline-speed.md, item 3a): tested on the candidate
-    // before it merges, no longer only on the tag after.
-    "node 22 · macos-latest",
+    // The unit suite on macOS (ci.yml jobs "macos-shard" and "macos"; pipeline-speed.md, item 3a), Node 24.
     "node 24 · macos-latest",
+    // Node 22, the engines floor, on Linux and macOS (release-candidate.yml): on a release-* branch's pull request,
+    // skipped on every other pull request.
+    "node 22 · ubuntu-latest",
+    "node 22 · macos-latest",
 ];
-/** The workflow file every REQUIRED_PR_CHECKS job belongs to: a job of that name from any other workflow (a lookalike
+/** The workflow file each 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 const REQUIRED_PR_CHECKS_WORKFLOW = ".github/workflows/ci.yml";
+export const REQUIRED_PR_CHECKS_WORKFLOW = {
+    "node 24 · ubuntu-latest": ".github/workflows/ci.yml",
+    "linux native containment · delegated cgroup v2": ".github/workflows/ci.yml",
+    "linux fence · sandbox-runtime": ".github/workflows/ci.yml",
+    "Windows Job Object containment": ".github/workflows/ci.yml",
+    "git 2.41 · debian trixie": ".github/workflows/ci.yml",
+    "git 2.47 · debian trixie": ".github/workflows/ci.yml",
+    "node 24 · macos-latest": ".github/workflows/ci.yml",
+    "node 22 · ubuntu-latest": ".github/workflows/release-candidate.yml",
+    "node 22 · macos-latest": ".github/workflows/release-candidate.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.
+ * The pull-request checks main's GitHub protection is not yet required to name (eval-harness review 2, finding 1).
+ * Empty since the test matrix (docs/plans/test-matrix.md): publication's release proof trusts what main's protection
+ * required at the merge, so main's protection must name every REQUIRED_PR_CHECKS check, and a release refuses to merge
+ * (and so to publish) until it does.
  */
-export const PROTECTION_REPORT_ONLY_CHECKS = ["git 2.41 · debian trixie", "git 2.47 · debian trixie", "node 22 · macos-latest", "node 24 · macos-latest"];
+export const PROTECTION_REPORT_ONLY_CHECKS = [];
 /** The checks main's protection must require at minimum: every required check that isn't report-only. */
 export const PROTECTION_MINIMUM_CHECKS = REQUIRED_PR_CHECKS.filter(name => !PROTECTION_REPORT_ONLY_CHECKS.includes(name));
-/** 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 const RELEASE_TAG_CHECKS = ["publish", "tag macOS · node 22", "tag macOS · node 24"];
+/** The checks a release's publication waits for on its tag (.github/workflows/publish.yml, docs/plans/test-matrix.md):
+ * the release proof (the tagged tree passed every REQUIRED_PR_CHECKS check on its pull request, read from GitHub) and
+ * the publish job that needs it. The tag runs no tests again. Nothing else reported on the merge commit (main-push.yml)
+ * holds publication. */
+export const RELEASE_TAG_CHECKS = ["release proof", "publish"];
 export const RELEASE_TAG_WORKFLOW = ".github/workflows/publish.yml";
 export const RELEASE_STEPS = ["gate", "approval", "check", "complete", "quiet", "deploy", "link", "ci", "merge", "tree", "tag", "publish", "homebrew", "done"];
 /** How long each waiting step may take, in minutes, before the release stops there (rerunning continues from it). */
@@ -191,10 +209,10 @@ export function checksVerdict(runs, required) {
     return waiting.length > 0 ? { state: "pending", waiting } : { state: "passed" };
 }
 /**
- * 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.
+ * Publication's verdict on the tag commit (test-matrix.md): 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
+ * push run — is not waited for: the candidate's checks already passed on its exact head before the merge, the merged
+ * tree was proved equal to it, and publish.yml's release proof checks both again from GitHub's record.
  */
 export function tagChecksVerdict(runs) {
     const names = RELEASE_TAG_CHECKS;
@@ -1318,20 +1336,24 @@ async function containsMain(adapters, j, nothing) {
  * cannot make the final main read and merge atomic, so absent or unreadable protection stops that release too.
  */
 async function mainProtection(adapters, j, auto, nothing) {
-    let protection;
+    let protection, unread = null;
+    // Couldn't read (after the adapter's network retries) is its own stop, never "doesn't hold" and never "holds".
     try {
         protection = await adapters.github.upToDateRequired(j.github);
     }
-    catch {
+    catch (error) {
         protection = null;
+        unread = String(error?.message ?? error).slice(0, 400);
     }
     // The git lanes main's protection doesn't name yet are said, never refused (PROTECTION_REPORT_ONLY_CHECKS).
     if (protection !== null && protection.notYetRequired.length > 0)
         adapters.say(`  Note: main's protection doesn't require ${protection.notYetRequired.join(", ")} yet; add ${protection.notYetRequired.length === 1 ? "it" : "them"} to its required checks.`);
     if (protection?.effective === true)
         return;
-    const lacking = protection === null ? "GitHub's branch protection for main couldn't be read" : `main's protection doesn't hold: ${protection.missing.join("; ")}`;
-    throw new Stop("base-unprotected", `${lacking}, so this release can't merge${auto ? " automatically" : ""}. ${nothing}. Restore effective main protection and try again.`);
+    if (protection === null) {
+        throw new Stop("github-unreadable", `Couldn't read GitHub's branch protection for main${unread === null ? "" : ` (${unread.replace(/^couldn't read GitHub's branch protection for main: /, "")})`}, so this release can't merge${auto ? " automatically" : ""}. ${nothing}. Run the release again once GitHub answers.`);
+    }
+    throw new Stop("base-unprotected", `main's protection doesn't hold: ${protection.missing.join("; ")}, so this release can't merge${auto ? " automatically" : ""}. ${nothing}. Restore effective main protection and try again.`);
 }
 /**
  * Wait for every required pull request check on the candidate to pass; stop on one that failed. `pendingIsEnough` (the
@@ -1377,17 +1399,17 @@ async function earlyChecks(adapters, j, wait, options = {}) {
         throw new Stop("ci-missing", `Pull request checks on ${sha} didn't all finish in time${named === "" ? (unread ? " (GitHub didn't answer)" : "") : `: ${named}`}. ${nothing}. Start or rerun them on GitHub, then run this command again.`);
     }
 }
-/** The network failures a release's waits ride out: git or gh timing out (or cut off) on the way to GitHub. */
-const TRANSIENT_NETWORK = /Recv failure: (?:Operation timed out|Connection reset by peer)|TLS handshake timeout|Operation timed out|Connection timed out|i\/o timeout|Connection reset by peer|Failed to connect to [^\s]*github\.com port \d+/i;
-/** 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 function transientNetworkError(error) {
     if (error instanceof Stop || error instanceof Restart)
         return false;
-    return TRANSIENT_NETWORK.test(String(error?.message ?? error));
+    return transientFailure(String(error?.message ?? error)) !== null;
 }
 /** The part of a network failure worth saying: its matching phrase. */
 function networkWords(error) {
-    return TRANSIENT_NETWORK.exec(String(error?.message ?? error))?.[0] ?? "a network failure";
+    return transientFailure(String(error?.message ?? error))?.words ?? "a network failure";
 }
 /**
  * The pull request's checks on exactly `head`, every attempt (the adapter asks GitHub for all of them, filter=all):
@@ -1417,9 +1439,12 @@ export function prChecksVerdict(runs, head, required, options = {}) {
         }
         // A required name counts only from the workflow that defines it: a job of the same name in another workflow (or
         // one whose workflow GitHub doesn't name) fails the verdict rather than stand in for it.
-        if (options.workflow !== undefined && required.includes(run.name) && !workflowIs(run.workflowPath, options.workflow)) {
-            failed.push(`${run.name} (from ${run.workflowPath ?? "a workflow GitHub doesn't name"}, not ${options.workflow})`);
-            continue;
+        if (options.workflow !== undefined && required.includes(run.name)) {
+            const want = typeof options.workflow === "string" ? options.workflow : options.workflow[run.name];
+            if (want === undefined || !workflowIs(run.workflowPath, want)) {
+                failed.push(`${run.name} (from ${run.workflowPath ?? "a workflow GitHub doesn't name"}, not ${want ?? "a workflow this release knows for it"})`);
+                continue;
+            }
         }
         if (run.app === "github-actions" && (typeof run.suite !== "number" || !Number.isSafeInteger(run.suite))) {
             failed.push(`${run.name} (no workflow run)`);
@@ -1463,6 +1488,13 @@ export function prChecksVerdict(runs, head, required, options = {}) {
             waiting.push(`${name} (${latest.status})`);
             continue;
         }
+        // Skipped is never success (test-matrix.md): GitHub's protection reads a skipped job as passing a merge, a release
+        // never does. A documentation-only pull request skips the area lanes, and any pull request but a release-* branch's
+        // skips Node 22, so a release needs every lane executed on its exact head.
+        if (latest.conclusion === "skipped" && required.includes(name)) {
+            failed.push(`${name} (skipped: a release needs it run on this exact commit; release from a branch named release-*, whose pull request runs every lane)`);
+            continue;
+        }
         if (latest.conclusion !== "success") {
             failed.push(`${name} (${latest.conclusion ?? "no conclusion"})`);
             continue;
@@ -1520,5 +1552,12 @@ export function checkFailedWords(input) {
 }
 /** Whether GitHub's workflow-run `path` names exactly `file` (it may carry the ref it ran from, after an `@`). */
 export function workflowIs(path, file) {
-    return typeof path === "string" && (path === file || path.startsWith(`${file}@`));
+    if (typeof path !== "string")
+        return false;
+    if (path === file)
+        return true;
+    // GitHub may append @ref, but ci.yml@evil.yml is also a valid *different* workflow filename. Multiple @ signs
+    // likewise cannot distinguish that filename from a ref. Refuse ambiguous suffixes instead of granting its checks.
+    const ref = path.startsWith(`${file}@`) ? path.slice(file.length + 1) : "";
+    return /^[A-Za-z0-9._+/-]+$/.test(ref) && !/\.ya?ml$/i.test(ref);
 }

package/dist/teardown-git.d.ts

@@ -23,7 +23,7 @@ export declare function refusal(result: ExecResult): string | null;
  * target is bound to the same repository as the folder it is removed from. A removal without --force runs under the
  * target's own view (its own config.worktree folded in), so git's last check of whether it is clean reads it as the
  * target itself would. `binding.repo`: the project's main checkout, from the plane's records, when the caller has it. */
-export declare function teardownGit(runner?: Runner, binding?: GitBinding): Git;
+export declare function teardownGit(runner?: Runner, binding?: GitBinding, lockTimeoutMs?: number, gitFile?: string): Git;
 /**
  * Git on a build's checkout, as the plane runs it outside every fence (staging, committing and inspecting the build's
  * work): the same fixed hardening as teardown (no hooks, fsmonitor, ext transport, credential helpers or automatic