toolroll 0.9.75 → 0.9.77

package/dist/release.d.ts

@@ -34,7 +34,29 @@
  */
 /** 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"];
+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"];
+/** 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 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 RELEASE_STEPS: readonly ["gate", "approval", "check", "complete", "quiet", "deploy", "link", "ci", "merge", "tree", "tag", "publish", "homebrew", "done"];
@@ -42,12 +64,38 @@ export type ReleaseStep = typeof RELEASE_STEPS[number];
 type WaitingStep = "gate" | "approval" | "check" | "quiet" | "deploy" | "ci" | "publish" | "homebrew";
 /** How long each waiting step may take, in minutes, before the release stops there (rerunning continues from it). */
 export declare const RELEASE_LIMITS: Readonly<Record<WaitingStep, number>>;
-/** One check attempt; `app` is the GitHub App that made it (github-actions for a workflow), when known. */
+/** One check attempt; `app` is the GitHub App that made it (github-actions for a workflow), when known; `id` its check
+ * run id, `suite` its check suite (one workflow run: its re-runs stay in it) and `head` the commit GitHub filed it
+ * under, when known. */
 export type CheckRun = {
     name: string;
     status: string;
     conclusion: string | null;
     app?: string | null;
+    id?: number | null;
+    suite?: number | null;
+    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;
+};
+/**
+ * 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;
+    name: string;
+    conclusion: string | null;
 };
 export type PullRequest = {
     number: number;
@@ -152,6 +200,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";
@@ -215,6 +275,89 @@ 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;
+};
+/** The plane's automatic release approval, as the coordinator asks it. Every answer is the plane's own: the coordinator
+ * hands it ids, never evidence (the plane reads GitHub CI itself for `approve`). */
+export type AutoReleaseAdapter = {
+    /** The project's "Approve automatically when checks pass", read now (off when unreadable). */
+    setting(taskId: string): Promise<boolean>;
+    /** Seal `auto-check` so the release check runs before anyone approves. */
+    authorizeCheck(input: {
+        taskId: string;
+        digest: string;
+        candidate: string;
+    }): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        why: string;
+    }>;
+    /** Whether the `auto-check` seal still stands (the setting on, its evidence, the digest). */
+    checking(taskId: string): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        why: string;
+    }>;
+    /** Observe CI on the candidate and, when everything passed, seal `auto-green` (opening the release's authority). */
+    approve(input: {
+        taskId: string;
+        digest: string;
+        candidate: string;
+        run: number;
+        receipt: string;
+    }): Promise<{
+        ok: true;
+        by: string;
+        at: string;
+        ci: {
+            id: number;
+            name: string;
+        }[];
+    } | {
+        ok: false;
+        why: string;
+    }>;
+    /** 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>;
+    /** "Released 0.9.x automatically". */
+    released(taskId: string, tag: string): Promise<void>;
+    /** CI stopped passing after the merge of an automatic release: hold its tag, publication and Homebrew until a person
+     * lets it go on (`toolroll release publish-ok`). Durable, in the plane. */
+    holdPublish(taskId: string, why: string): Promise<void>;
+    /** Why the release's publication waits for a person, or null. Read from the plane, whatever the journal says. */
+    publishHeld(taskId: string): Promise<string | null>;
 };
 export type ReleaseAdapters = {
     /** One approval per release (release-once.md); absent on a plane that can't carry. */
@@ -232,10 +375,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. */
@@ -304,7 +443,17 @@ export type ReleaseAdapters = {
         authenticated(): Promise<boolean>;
         pullRequest(repo: string, branch: string): Promise<PullRequest | null>;
         checks(repo: string, sha: 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>;
@@ -406,6 +555,20 @@ export type ReleaseJournal = {
     needsApproval?: boolean;
     /** This journal's task was picked fresh after a CI failure after the deploy: an id that never existed, never another. */
     freshTask?: boolean;
+    /** The automatic road (auto-approve-green.md): `checking` once the plane sealed `auto-check`, `approved` once it sealed
+     * `auto-green`, `refused` (and why) when it wouldn't — then a person approves, as before. */
+    auto?: {
+        state: "checking" | "approved" | "refused";
+        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: {
@@ -476,4 +639,42 @@ export declare function checksVerdict(runs: readonly CheckRun[], required: reado
 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. */
 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):
+ * 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 `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?: {
+    auto?: true;
+    workflow?: string;
+}): {
+    state: "passed";
+    failures: CheckFailure[];
+} | {
+    state: "pending";
+    waiting: 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 {};