toolroll 0.9.103 → 0.9.105

package/dist/release.d.ts

@@ -1,806 +0,0 @@
-/**
- * `toolroll release <branch>` (D10): the whole release of Toolroll itself as one resumable command. The owner's
- * approval of the release scope is the only human step; everything else runs headless, each waiting step with a time
- * limit:
- *
- *   gate → approval → check → complete → quiet → deploy → link → ci → merge → tree → tag → publish → homebrew → done
- *
- * gate, before filing a task for that commit, looks at the pull request's required checks on it: one that failed stops
- * the release before anything is filed or sent for approval; it waits, naming them, for checks not started or still
- * running, and stops if they don't finish within its limit (a task already filed is not looked at again; ci checks
- * once more before merging). It then files a prepared-candidate task pinned to the branch's exact commit, with the full
- * release check. approval
- * waits for an active approver's yes to that exact scope (never a mode's, an AI's or the lead's). check requires a Full
- * result of that commit: a failed check stops the release and stays visible, nothing reruns it. complete marks that
- * exact result Complete through the task's own authorization. quiet waits until nothing builds. deploy runs the
- * candidate's own deploy (scripts/deploy-browser.mjs: drain, backup, rehearsal, swap, health) and keeps the runtime its
- * final JSON names; an interrupted one is recovered from its saved stage (--phase recover) before anything else. link
- * points both CLI names at that runtime's bin.js, putting them back if either doesn't answer, and goes on only when
- * the console, worker and both names run the gated commit. ci waits for every
- * reported pull-request check on that same commit to pass, with every required check present: pending, missing,
- * skipped or failed never merges. merge
- * squash-merges with the head pinned to the gated commit, tree proves main's new commit has exactly the gated tree,
- * and only then tag pushes the version tag, whose macOS matrix must pass before npm publication (publish.yml). publish
- * waits for npm, the GitHub release and the macOS checks; homebrew updates the tap's formula and merges it (after its checks, when the tap runs any).
- *
- * A private journal (mode 0600, written whole then renamed) records what each step is about to do before it does
- * anything outside this machine, and what it saw after. A stop — a time limit, a failure, a crash, Ctrl-C — leaves the
- * journal at its step; running the same command again finds what already happened (the task, the completion, the
- * merge, the tag, the package, the tap change) instead of doing it twice, and continues from the first unfinished
- * step. A branch, pull request or tag that no longer matches what was gated stops the release rather than guess.
- *
- * 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 (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: 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).
- * 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. */
-export declare const PROTECTION_MINIMUM_CHECKS: readonly string[];
-/**
- * Pull-request checks a release never waits for or fails on, by exact name and the workflow file that defines them:
- * youiyoux's UI drift check (src/design/KIT.md), which fails a pull request that adds design drift but says nothing
- * about whether a build is safe to release, and the scripted journeys on a pull request (journeys.yml,
- * docs/plans/ci-speed.md item 4), advisory while they settle in CI: the release check runs every journey itself. Only a
- * GitHub Actions run of that name from that workflow is left out; the same name from anywhere else is judged like any
- * other check. Never a required check.
- */
-export declare const ADVISORY_PR_CHECKS: Readonly<Record<string, string>>;
-/**
- * Main's protection as the plane's gh reads it (release-adapters.ts readMainProtection): `effective` only when one layer
- * (classic protection or one active ruleset) requires up-to-date branches, binds every PROTECTION_MINIMUM_CHECKS check to GitHub Actions,
- * and nobody merging as this gh can bypass it. `missing` names each absent property; `notYetRequired` the report-only
- * checks the effective layer doesn't name.
- */
-export type MainProtection = {
-    effective: boolean;
-    missing: string[];
-    notYetRequired: string[];
-};
-/** The checks a release's publication waits for on its tag (.github/workflows/publish.yml, 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];
-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). The
- * check's covers the first attempt and the two same-commit reruns the plane may give it, each of which a busy machine
- * may stretch to two hours (check-load.ts). */
-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; `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;
-    state: "open" | "closed" | "merged";
-    head: string;
-    base: string;
-    mergeCommit: string | null;
-};
-/** The release task as Toolroll records it (`task show --json`). */
-export type GateState = {
-    exists: boolean;
-    candidate: string | null;
-    scopeDigest: string | null;
-    /** The current approval of the scope: by whom, of which digest, and how (`password` or `chat` is a person's yes). */
-    approval: {
-        by: string;
-        at: string;
-        digest: string;
-        basis: string | null;
-        role: string | null;
-        active: boolean;
-        /** The plane's own answer to "did a person give this approval, with a person's proof recorded?" (approval policy
-         * §1.5). Absent from a plane too old to say, which is no person's approval. */
-        person?: {
-            ok: true;
-            method: string;
-        } | {
-            ok: false;
-            why: string;
-        };
-    } | null;
-    /** The newest finished build of the task: its sealed result and check. */
-    result: {
-        run: number;
-        head: string | null;
-        check: string;
-        level: string | null;
-        receipt: string;
-        worktree: string | null;
-    } | null;
-    /** A finished build that left no result to complete (it failed before the check), in words. */
-    failed: string | null;
-    /** A newer attempt is queued or running (`task regate` after a failed check): the result shown is the one before it.
-     * Absent from a plane too old to say. */
-    pending?: boolean;
-    completion: {
-        actor: string;
-        at: string;
-        digest: string;
-    } | null;
-};
-export type Installed = {
-    services: string[];
-    clis: {
-        name: string;
-        runtime: string | null;
-    }[];
-};
-/** A CLI name's link on PATH and where it pointed before the release moved it (release-links.ts). */
-export type SavedLink = {
-    name: string;
-    path: string;
-    before: string | null;
-    foreign?: true;
-};
-/** A deployment that stopped and couldn't recover. `gate`: the update pause it left, when its journal is before the swap. */
-export type DeployStop = {
-    ok: false;
-    message: string;
-    gate?: {
-        id: string;
-        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";
-} | {
-    kind: "proposed";
-    pr: number;
-    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;
-    files: {
-        path: string;
-        added: number;
-        deleted: number;
-    }[];
-};
-/** A release's authority record as the coordinator reads it (store.ts release_authority). */
-export type AuthorityView = {
-    id: number;
-    generation: number;
-    state: string;
-    tipSha: string;
-    tipTask: string;
-    version: string;
-    pr: number;
-    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";
-    state: "reserved" | "running" | "succeeded" | "failed" | "unknown";
-    candidate: string;
-    externalRef: string | null;
-    reservedAt: string;
-    /** Reserved by a person's own deploy run (deploy-browser.mjs), not a coordinator. */
-    direct: boolean;
-    /** Whether the process that issued it is proven gone (store.ts releaseIssuerGone): read when the view is made. */
-    issuerGone: boolean;
-    /** A direct deploy's staging folder. */
-    stage: string | null;
-};
-/** The release's authority record, through the plane's store (release-once.md). Absent: a plane too old to carry, and
- * every commit asks for a person as before. */
-export type ReleaseAuthorityAdapter = {
-    authority(taskId: string): Promise<AuthorityView | null>;
-    live(taskId: string, action: ReleaseAction): Promise<{
-        applies: boolean;
-        ok: boolean;
-        why: string | null;
-    }>;
-    lease(authority: number, owner: string): Promise<{
-        ok: true;
-        epoch: number;
-    } | {
-        ok: false;
-        why: string;
-    }>;
-    renew(authority: number, owner: string, epoch: number): Promise<boolean>;
-    carry(authority: number, to: string, requestId: string, epoch: number): Promise<{
-        ok: true;
-        taskId: string;
-    } | {
-        ok: false;
-        message: string;
-    }>;
-    /** `secret`: proves a deploy run is this reservation's (handed to deploy-browser on stdin). */
-    reserve(input: {
-        authority: number;
-        kind: "deploy" | "merge";
-        taskId: string;
-        candidate: string;
-        epoch: number;
-    }): Promise<{
-        ok: true;
-        operation: string;
-        secret?: string;
-    } | {
-        ok: false;
-        why: string;
-    }>;
-    start(operation: string, epoch: number): Promise<boolean>;
-    /** Settle an operation at the epoch this coordinator holds; false: it no longer holds the release. */
-    finish(operation: string, outcome: "succeeded" | "failed" | "unknown", facts: {
-        detail?: string | null;
-        externalRef?: string | null;
-    }, epoch: number): Promise<boolean>;
-    /** A CI failure after the deploy (Alex's decision): the release stops and needs a person's fresh approval. False when
-     * 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;
-    /** GitHub's nightly lane debt (nightly-github.ts, docs/plans/evals-nightly.md part A) right before a deploy, the merge
-     * and the tag: one bounded read of GitHub (20 s), this candidate's exemptions read again, then the plane's stored
-     * debt. A warning never holds; a hold stops the release. Absent: a plane that can't read it. */
-    nightly?(input: {
-        taskId: string;
-        candidate: string;
-        pr: number;
-        phase: "deploy" | "merge" | "tag";
-    }): Promise<{
-        ok: true;
-        warning: string | null;
-    } | {
-        ok: false;
-        why: string;
-        warning: string | null;
-    }>;
-    /** Whether a sandboxed Full check's skipped cases are covered (fenced-check-coverage.ts, H3). Run `run`'s stamped level
-     * decides: an unsandboxed check answers at once. Absent: a plane that can't say, as for every older one. */
-    fencedCoverage?(taskId: string, run: number, candidate: string): Promise<{
-        ok: true;
-        covered: number;
-    } | {
-        ok: false;
-        why: string;
-    }>;
-    /** One-tap release approval (docs/plans/trusted-release-reports.md, slice A): what the plane tells a person and
-     * keeps for the approval sheet. Best effort: a failure here never changes the release. Absent on an older plane. */
-    ready?: ReleaseReadyAdapter;
-};
-/** What the coordinator tells the plane for a person's release (release-approval.ts). Ids and its own readings only. */
-export type ReleaseReadyAdapter = {
-    /** The approval step was entered (a fresh filing or a resumed one): one notification per task and scope digest. */
-    asked(taskId: string): Promise<void>;
-    /** The pull request's required checks on the candidate, as this coordinator just read them. */
-    ci(input: {
-        taskId: string;
-        candidate: string;
-        state: "passed" | "running" | "failed";
-        failed: readonly string[];
-        runs: readonly CheckRun[];
-    }): Promise<void>;
-    /** A person's release stopped: one attention notification per task, step and reason. */
-    stopped(input: {
-        taskId: string;
-        step: string;
-        reason: string;
-        message: string;
-    }): Promise<void>;
-    /** Main's merge commit was proved to hold the approved tree: the plane checks it again and keeps the release's record. */
-    verified(input: {
-        taskId: string;
-        merge: string;
-    }): Promise<void>;
-};
-/** 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. */
-    release?: ReleaseAuthorityAdapter;
-    /** Where each step's start, end and outcome are recorded (store.ts release_step, v146) for the Release view and
-     * `toolroll release status`. Best effort: a failure here never stops or changes the release. */
-    progress?: (entry: {
-        taskId: string;
-        tag: string;
-        version: string;
-        pr: number | null;
-        step: ReleaseStep;
-        state: "running" | "done" | "failed" | "waiting";
-        at: Date;
-        detail?: string | null;
-    }) => void;
-    now(): Date;
-    sleep(ms: number): Promise<void>;
-    say(line: string): void;
-    repo: {
-        /** owner/name of the gate checkout's origin. */
-        github(): Promise<string>;
-        /** Fetch the branch and main into the gate checkout (main fast-forwarded), so the gate diffs from today's main. */
-        sync(branch: string): Promise<void>;
-        remoteHead(branch: string): Promise<string | null>;
-        /** Delete only this exact branch head, with a lease; an already absent branch is finished. */
-        deleteBranch(branch: string, head: string): Promise<void>;
-        tree(sha: string): Promise<string>;
-        fileAt(sha: string, path: string): Promise<string | null>;
-    };
-    toolroll: {
-        /** Which runtime each launchd service and each CLI name (`toolroll`, `standing-orders`) runs from. */
-        installed(): Promise<Installed>;
-        /** The exact commit recorded in the deployment's runtime/package.json. */
-        runtimeCommit(runtime: string): Promise<string | null>;
-        gate(taskId: string): Promise<GateState>;
-        fileGate(input: {
-            taskId: string;
-            title: string;
-            checkout: string;
-            candidate: string;
-            goal: string;
-            acceptance: string;
-            /** Release terms to file with the scope (task scope --release): the version, pull request and branch. */
-            release?: {
-                version: string;
-                pr: number;
-                branch: string;
-                noCarry: boolean;
-            };
-        }): Promise<{
-            scopeDigest: string;
-        }>;
-        /** `reason` "stopping": Toolroll is still proving the check's build stopped (stop-proof.ts); it clears on its own. */
-        complete(taskId: string, receipt: string): Promise<{
-            ok: true;
-        } | {
-            ok: false;
-            message: string;
-            reason?: string;
-        }>;
-        busy(): Promise<{
-            running: number;
-            tasks: string[];
-        }>;
-        /** scripts/deploy-browser.mjs --run --stage --yes from the builder's checkout; runtime is its final JSON's `runtime`. */
-        deploy(input: {
-            run: number;
-            worktree: string;
-            stage: string;
-            operation?: {
-                id: string;
-                secret: string;
-            };
-        }): Promise<{
-            ok: true;
-            runtime: string;
-        } | DeployStop>;
-        /** scripts/deploy-browser.mjs --stage --phase recover for a stage that was launched; a stage never prepared is ok. */
-        recoverDeploy(input: {
-            run: number;
-            worktree: string;
-            stage: string;
-        }): Promise<{
-            ok: true;
-        } | DeployStop>;
-        /** Whether no deployment is at work or half done: no deploy-browser process, no update pause held, and `stage`'s
-         * journal (when given) unlocked and at a phase that changed nothing or finished. Null stage: unknown, so false. */
-        deploymentIdle(stage: string | null): Promise<boolean>;
-        /** Where both CLI names are on PATH now. */
-        cliLinks(): Promise<SavedLink[]>;
-        /** Point every saved link at `bin` and check each answers `version`; on any failure every link goes back to its
-         * saved `before` and this throws. */
-        switchLinks(links: readonly SavedLink[], bin: string, version: string): Promise<void>;
-    };
-    github: {
-        authenticated(): Promise<boolean>;
-        pullRequest(repo: string, branch: string): Promise<PullRequest | null>;
-        /** `tag`: a release tag's push binds its workflow file too (only that exact tag's push). */
-        checks(repo: string, sha: string, options?: {
-            tag?: string;
-        }): Promise<CheckRun[]>;
-        /** Whether GitHub's check history of this commit can be read whole (fewer check suites than the check-runs
-         * endpoint's ceiling). Absent or false: an automatic release fails closed; a person's is unaffected. */
-        complete?(repo: string, sha: string): Promise<boolean>;
-        merge(repo: string, pr: number, head: string, message?: string): Promise<string>;
-        /** main's head as GitHub's API answers now (never a local ref a build could move). */
-        mainHead(repo: string): Promise<string>;
-        /** Whether `sha` already holds `ancestor`, by GitHub's own comparison. */
-        contains(repo: string, sha: string, ancestor: string): Promise<boolean>;
-        /** Bring a pull request's branch up to main, only while its head is `expectedHead` (GitHub's own compare-and-swap: a
-         * push that got there first refuses). Absent: a behind branch stops, for a person to update. */
-        updateBranch?(repo: string, pr: number, expectedHead: string): Promise<{
-            ok: true;
-        } | {
-            ok: false;
-            why: string;
-        }>;
-        /** 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>;
-    };
-    registry: {
-        published(name: string, version: string): Promise<boolean>;
-    };
-    homebrew: {
-        repo: string;
-        /** Whether any of the tap's workflows, at the change or its base, runs on a change; if none does, no checks are owed. */
-        checked(head: string): Promise<boolean>;
-        /** The change's commit statuses, as check runs oldest first. */
-        statuses(head: string): Promise<CheckRun[]>;
-        state(version: string): Promise<HomebrewState>;
-        propose(version: string): Promise<{
-            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>;
-    };
-};
-export type ReleaseJournal = {
-    version: 1;
-    id: string;
-    github: string;
-    checkout: string;
-    branch: string;
-    candidate: {
-        sha: string;
-        tree: string;
-    };
-    packageName: string;
-    packageVersion: string;
-    tag: string;
-    pr: number;
-    step: ReleaseStep;
-    task: {
-        id: string;
-        scopeDigest: string | null;
-    };
-    approval: {
-        by: string;
-        at: string;
-    } | null;
-    /** The passing result: its run, receipt and checkout, and the commit it built (`head`), which a prepared candidate
-     * records as a commit of its own with exactly the candidate's tree (absent in a journal from before that was known). */
-    check: {
-        run: number;
-        receipt: string;
-        worktree: string;
-        head?: string;
-    } | null;
-    completion: {
-        actor: string;
-        at: string;
-    } | null;
-    deploy: {
-        runtime: string;
-        at: string;
-    } | null;
-    /** Saved before launching deploy, so a killed coordinator can recover that exact attempt first. */
-    deployAttempt?: {
-        stage: string;
-    } | null;
-    /** Where both CLI names pointed before link moved them: saved first, so a resumed or failed relink can put them back. */
-    links?: SavedLink[] | null;
-    ci: {
-        checks: string[];
-        at: string;
-    } | null;
-    merge: {
-        sha: string;
-        tree: string | null;
-    } | null;
-    tagged: {
-        sha: string;
-    } | null;
-    published: {
-        at: string;
-    } | null;
-    homebrew: {
-        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?: {
-        id: number;
-        generation: number;
-    } | null;
-    /** Commits that landed after the approval, carried under it: each with its files and line counts. */
-    landed?: LandedCommit[];
-    /** The deploy and merge operations this coordinator reserved (store.ts release_operation). */
-    operations?: {
-        deploy?: string;
-        merge?: string;
-    };
-    /** A pull request check failed after the deploy: nothing continues until a person approves again (--new). */
-    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: {
-        step: ReleaseStep;
-        reason: string;
-        message: string;
-        at: string;
-    } | null;
-    createdAt: string;
-    updatedAt: string;
-};
-export type ReleaseOutcome = {
-    ok: true;
-    journal: ReleaseJournal;
-    file: string;
-} | {
-    ok: false;
-    reason: string;
-    message: string;
-    step: ReleaseStep | "preflight";
-    journal: ReleaseJournal | null;
-    file: string;
-    resume: string;
-};
-export type ReleaseOptions = {
-    branch: string;
-    /** The gate checkout: a clone of the repository the release check runs in. */
-    checkout: string;
-    /** Where journals live (the installation's state folder). */
-    stateDir: string;
-    limits?: Partial<Record<WaitingStep, number>>;
-    /** Start over for a new commit on the branch, keeping the old journal aside. Refused once merging began. */
-    fresh?: boolean;
-    pollMs?: number;
-    /** File the release without carrying later commits: each one asks again. */
-    noCarry?: boolean;
-};
-/** Every commit that landed after the approval, in words: the summary and the merge message list them all. */
-export declare function landedWords(landed: readonly LandedCommit[]): string[];
-export declare const journalFile: (stateDir: string, branch: string) => string;
-export declare const resumeCommand: (branch: string, checkout: string) => string;
-/** Whole or not at all: a private temp file, synced, renamed into place, its folder synced. */
-export declare function writeJournal(file: string, journal: ReleaseJournal): void;
-export declare function readJournal(file: string): ReleaseJournal | null;
-/** The release task's id: one per exact commit, so a rerun finds the task it filed instead of filing another. */
-export declare const gateTaskId: (version: string, sha: string) => string;
-/** Whether the scope's approval is the owner's own yes to these exact bytes: a person through the password (or
- * identity) ceremony or a chat confirmation — never a mode's coverage, an AI teammate, a routine or the lead. */
-export declare function ownerApproval(gate: GateState, digest: string | null): {
-    ok: true;
-    by: string;
-    at: string;
-} | {
-    ok: false;
-    why: string;
-};
-/** Every required check present, and every reported check's newest attempt completed successfully. */
-export declare function checksVerdict(runs: readonly CheckRun[], required: readonly string[]): {
-    state: "passed";
-} | {
-    state: "pending";
-    waiting: string[];
-} | {
-    state: "failed";
-    failed: string[];
-};
-/**
- * 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 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):
- * 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 | Readonly<Record<string, 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;
-/** How a person names this branch to `toolroll release` again. */
-export declare function releaseBranchArg(branch: string): string;
-export {};