toolroll 0.9.76 → 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"];
@@ -55,10 +77,20 @@ export type CheckRun = {
     head?: string | null;
     /** The workflow (its id, from GitHub's workflow-run API) that this check's suite is a run of, when known. */
     workflow?: number | null;
+    /** That workflow's file in the repository (GitHub's workflow-run `path`), when known. */
+    workflowPath?: string | null;
+    /** GitHub's own job record (its steps, read by the plane's gh) shows this unsuccessful attempt ended before any of the
+     * workflow's own steps ran: the runner failed, not the tests. Absent or false: nothing shows that. */
+    beforeTests?: boolean | null;
 };
-/** How many failed attempts of one CI check, and failed release-check runs, an automatic approval tolerates (flakes on a
- * pinned commit and digest), before a person decides (auto-approve-green.md). */
-export declare const AUTO_FLAKE_CAP = 2;
+/**
+ * Failure classes replace a flat flake allowance (docs/plans/eval-harness.md; check-failure.ts says the classes): only a
+ * failure the plane itself confirmed as infrastructure is ever run again under the same approval — at most once per
+ * incident and twice per candidate — for a release check and for a GitHub CI job alike. A failing test, a typecheck, an
+ * attack test, a migration: none tolerated. An unexplained failure blocks, and a person decides.
+ */
+export declare const INFRA_RERUNS_PER_INCIDENT = 1;
+export declare const INFRA_RERUNS_PER_CANDIDATE = 2;
 /** One failed attempt that a later attempt of the same job passed. */
 export type CheckFailure = {
     id: number;
@@ -168,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";
@@ -231,6 +275,20 @@ export type ReleaseAuthorityAdapter = {
      * the authority could not be stopped (a stale epoch, a merge already reserved): the coordinator fails closed. */
     needsApproval(authority: number, reason: string, epoch: number): Promise<boolean>;
     operations(authority: number): Promise<OperationView[]>;
+    /** After a failed release check (check-failure.ts): the plane classifies it from its own records and, only for
+     * confirmed infrastructure within its limits, runs the check again on the same candidate under the same approval.
+     * Absent on an older plane: a failed check stops as before. */
+    recheck?(taskId: string): Promise<RecheckView>;
+    /** Whether a passing check stands given every earlier attempt on the same commit (an earlier failure that wasn't
+     * confirmed infrastructure isn't erased by a pass), and what passed only on a retry. */
+    standing?(taskId: string, run: number): Promise<{
+        ok: true;
+        retried: string[] | null;
+    } | {
+        ok: false;
+        why: string;
+        retried: string[] | null;
+    }>;
     /** Releases that approve themselves when green (docs/plans/auto-approve-green.md): the plane's own seals, each proven
      * again inside the plane. Absent: a plane that can't, and every release asks a person as before. */
     auto?: AutoReleaseAdapter;
@@ -279,6 +337,17 @@ export type AutoReleaseAdapter = {
     }>;
     /** The automatic road ended without a release: the task asks a person, and the owner is told why. */
     giveUp(taskId: string, why: string): Promise<void>;
+    /** The task is filed while CI still runs on `candidate` (recorded in the plane before the task is filed): its approval
+     * card says so until the plane reads CI passing. It holds nothing (Alex, 2026-10-29: a person may approve during CI). */
+    ciRunning?(taskId: string, candidate: string): Promise<void>;
+    /** The plane reads CI on `candidate` itself and, when every required check passed, ends the "CI still running" note
+     * (and lifts a hold an older coordinator placed); `ask` tells the owner of a held release it needs them now. */
+    ciPassed?(taskId: string, candidate: string, ask: boolean): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        why: string;
+    }>;
     /** The release check failed while checking automatically: the owner is told; the commit may be checked again (a
      * regate of the same commit and digest, within the plane's cap on failed runs). */
     checkFailed(taskId: string, why: string): Promise<void>;
@@ -306,10 +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. */
@@ -382,6 +447,13 @@ export type ReleaseAdapters = {
          * 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>;
@@ -490,6 +562,13 @@ export type ReleaseJournal = {
         why?: string;
         ci?: number[];
     } | null;
+    /** The gate filed the task while the pull request's checks still ran (pipeline-speed.md, D2 and "Decision: a person's
+     * release asks during CI"): the release check runs beside CI. A person may approve meanwhile; the plane's automatic
+     * approval waits for every check to pass, and nothing deploys, merges, tags or publishes before they do. */
+    ciAhead?: boolean;
+    /** Set with ciAhead and never cleared for this commit: a person's release reads CI again, fresh, right before the
+     * deploy, whatever was seen while asking (a green CI may have a newer attempt failing since). */
+    ciBeforeDeploy?: boolean;
     /** When each step was about to change something outside this machine: what a resume must look for before acting. */
     intents: Partial<Record<ReleaseStep, string>>;
     stopped: {
@@ -565,11 +644,14 @@ export declare function transientNetworkError(error: unknown): boolean;
  * each reported attempt must be filed under `head` with a check-run id; a required check counts only from GitHub
  * Actions (an app that names a check alike can't stand in for it); attempts are grouped by the job they belong to — the
  * app, its check suite (a workflow run, whose re-runs stay in it) and the name — and every group is judged by its
- * latest attempt; every required check needs a group. With `cap`, a group whose earlier attempts failed more than `cap`
- * times fails too (an automatic approval's flake allowance); the failures it tolerated are returned.
+ * latest attempt; every required check needs a group. With `auto` (an automatic approval), every other failed attempt on
+ * the commit — an earlier attempt, or a job a newer run renamed or dropped — must be one GitHub's own job record shows ending before any workflow step ran (`beforeTests`: confirmed
+ * infrastructure), and at most INFRA_RERUNS_PER_CANDIDATE of them on the commit; any other earlier failure — a test,
+ * a typecheck, or one nothing explains — fails the verdict, so a person decides. The failures it tolerated are returned.
  */
 export declare function prChecksVerdict(runs: readonly CheckRun[], head: string, required: readonly string[], options?: {
-    cap?: number;
+    auto?: true;
+    workflow?: string;
 }): {
     state: "passed";
     failures: CheckFailure[];
@@ -580,4 +662,19 @@ export declare function prChecksVerdict(runs: readonly CheckRun[], head: string,
     state: "failed";
     failed: string[];
 };
+/**
+ * What a failed release check means and what happens next, by its class (check-failure.ts), in words. Only confirmed
+ * infrastructure reruns on its own; nothing else is rerun to pass.
+ */
+export declare function checkFailedWords(input: {
+    sha: string;
+    run: number;
+    class: FailureClassName | null;
+    why: string;
+    branch: string;
+    checkout: string;
+    taskId: string;
+}): string;
+/** Whether GitHub's workflow-run `path` names exactly `file` (it may carry the ref it ran from, after an `@`). */
+export declare function workflowIs(path: string | null | undefined, file: string): boolean;
 export {};