toolroll 0.9.79 → 0.9.82

package/dist/release-auto.js

@@ -17,6 +17,7 @@ import { fullCheckProblem, projectGitDir } from "./check-report.js";
 import { sealedRun } from "./release-recheck.js";
 import { runCheckLevel } from "./check-levels.js";
 import { readVerifiedCommit, verifiedBlobs, verifiedTreeDiff, verifiedTreeEntries } from "./commit-extract.js";
+import { EVAL_HOOK_FILES, evalHookProblem, storeRewriteProblem } from "./eval-hooks.js";
 import { mightName, testInfrastructure } from "./test-infra.js";
 import { chatControlHref } from "./chat-controls.js";
 import { INFRA_RERUNS_PER_CANDIDATE, REQUIRED_PR_CHECKS, REQUIRED_PR_CHECKS_WORKFLOW, prChecksVerdict } from "./release.js";
@@ -27,6 +28,7 @@ import { autoReleaseApprovalOf, personApprovalOf } from "./scope.js";
 import { releaseOperations, revokeRelease } from "./store.js";
 import { RELEASE_CI_HELD_ACTION, RELEASE_CI_PASSED_ACTION, RELEASE_CI_RUNNING_WORDS, releaseCiHoldOf, releaseCiRunningOf } from "./release-ci-hold.js";
 import { verificationEvidence } from "./verification-evidence.js";
+import { nightlyDebtHold } from "./nightly-github.js";
 export { RELEASE_APPROVAL_ACTION, releaseApprovalSetting, releaseAutoApproves };
 /** The setting's words, one place. */
 export const RELEASE_APPROVAL_WORDS = { ask: "Ask me", auto: "Approve automatically when checks pass" };
@@ -177,6 +179,11 @@ export function authorizeAutoCheck(store, input) {
 const SRC_TEST_INFRA = /^src\/(fixtures\/|(.*\/)?(test-[^/]*|[^/]*-test-support[^/]*|[^/]*fixtures?[^/]*)\.[cm]?[jt]sx?$)/;
 /** A test file (normalized path): `*.test.ts`, never inside a fixtures folder. */
 const TEST_FILE = /^(?!.*(^|\/)fixtures?\/)[^]*\.test\.ts$/;
+/** The eval set's and GitHub nightly's policy code (docs/plans/evals-nightly.md, part C, finding 10): the cases and
+ * oracles, the evaluator, its gate, hooks and world, reviewer scoring, nightly ingestion, their contracts, and the
+ * accounting readings evals trust (reported-usage.ts, run-efficiency.ts). Where they are called from, and the store's
+ * accounting reads, are held by eval-hooks.ts instead (evalHookProblem). */
+const EVAL_POLICY = /^(evals\/|src\/evals[^/]*\.ts$|src\/eval-[^/]*\.ts$|src\/reviewer-evals\.ts$|src\/nightly-github\.ts$|src\/contracts\/evals[^/]*\.ts$|src\/reported-usage\.ts$|src\/run-efficiency\.ts$)/;
 /** Build or type configuration anywhere: a person approves it. */
 const BUILD_CONFIG = /(^|\/)(tsconfig[^/]*\.json|[^/]*\.config\.[cm]?[jt]s|\.npmrc|\.nvmrc|\.node-version)$/;
 /**
@@ -201,6 +208,8 @@ export function autoPathProblem(path) {
     }
     // Test files under test/ carry the same trust as src's (Alex: test authors are trusted) — only the `.test.ts` files
     // themselves, never a helper, fixture, setup or config file beside them, nor one inside a fixtures folder.
+    if (EVAL_POLICY.test(normal))
+        return "it's eval or nightly policy code";
     if (testUnderTest)
         return null;
     if (BUILD_CONFIG.test(normal))
@@ -312,6 +321,19 @@ function changeProblem(repo, base, candidate) {
         scans.push(found);
     }
     const infra = new Set(scans.flatMap(one => [...one.infra]));
+    // The eval and nightly enforcement calls the base holds must all still be in place at the candidate (eval-hooks.ts).
+    // One verified read of every listed file per tree (an unreadable tree reads as every file missing: a person decides).
+    const blobAt = (tree) => { const blobs = verifiedBlobs(gitDir, tree, EVAL_HOOK_FILES); return (file) => blobs.ok ? blobs.value.get(file)?.bytes ?? null : null; };
+    const hooks = evalHookProblem(blobAt(after.value.tree), blobAt(before.value.tree));
+    if (hooks !== null)
+        return `${hooks}: a person decides`;
+    // No changed file may write over a pinned Store method from outside store.ts (eval-hooks.ts storeRewriteProblem).
+    const changed = diff.value.filter(change => change.after !== null).map(change => change.path);
+    // A failed read is no reader at all (a person decides), never files that read as absent.
+    const changedAt = (tree) => { const blobs = verifiedBlobs(gitDir, tree, changed); return blobs.ok ? (file) => blobs.value.get(file)?.bytes ?? null : null; };
+    const rewrites = storeRewriteProblem(changed, changedAt(after.value.tree), changedAt(before.value.tree));
+    if (rewrites !== null)
+        return `${rewrites}: a person decides`;
     for (const change of diff.value) {
         const modes = [change.before?.mode, change.after?.mode].filter((one) => one !== undefined);
         if (modes.includes("120000") || modes.includes("160000"))
@@ -461,6 +483,10 @@ export function sealAutoGreen(store, input) {
         if (changed !== null)
             return refuse(changed);
         // GitHub CI, as the plane's own gh saw it moments ago, on exactly this commit.
+        // GitHub's nightly lane debt (evals-nightly.md, part A2): dormant while automatic approval is refused, held here too.
+        const nightly = nightlyDebtHold(store, { repo: facts.repo, taskId: input.taskId, candidate: input.candidate, phase: "auto", release: true, now: input.now });
+        if (nightly !== null)
+            return refuse(nightly.why);
         const ci = ciVerdict(input.ci, input.candidate, input.now);
         if (!ci.ok)
             return refuse(`CI: ${ci.problem}`);

package/dist/release-card.js

@@ -27,6 +27,7 @@ import { routeFromJson } from "./phase-routing.js";
 import { projectName } from "./project.js";
 import { RELEASE_CI_RUNNING_WORDS, releaseCiRunningOf } from "./release-ci-hold.js";
 import { RELEASE_PATH, releaseConfigProblem, releaseGitEnv, releaseRemote, releaseTools } from "./release-git.js";
+import { nightlyReleaseLines } from "./nightly-github.js";
 const NONE = "none";
 /** A budget in dollars from integer micro-dollars, in integer arithmetic: cents when it is whole cents, else every digit. */
 const money = (micro) => {
@@ -258,6 +259,8 @@ export function releaseCardOf(store, scope, formDigest, words) {
         ...(terms !== null && terms.policy.carry && terms.access !== "sandboxed" ? ["This project's checks don't run in the sandbox: later test-only commits will run outside the sandbox without being shown to you first."] : []),
         // Filed while CI runs (Alex, 2026-10-29): a person may approve now, and is told plainly what still waits.
         ...(releaseCiRunningOf(store, scope.taskId) === null ? [] : [RELEASE_CI_RUNNING_WORDS]),
+        // GitHub's nightly (nightly-github.ts): what holds this release, or why it can't be read. Not a signed term.
+        ...(terms === null ? [] : nightlyReleaseLines(store, { repo: terms.repo, taskId: scope.taskId, candidate: scope.candidate ?? null, now: new Date() })),
         "",
         ...changeWords(changes, terms, 5),
         "",

package/dist/release-cli.js

@@ -21,6 +21,7 @@ import { carryRefusalWords, proveCarry, setAskEveryReleaseCommit, setUnsandboxed
 import { authenticateApprover, machineActing, personProof, proveCredential } from "./scope.js";
 import { allowAutoPublish, setReleaseApproval } from "./release-auto.js";
 import { createNightlyCheckFlow } from "./nightly-check.js";
+import { aliasNightlyLane, optInGithubNightly, retireNightlyLane } from "./nightly-github.js";
 import { parseSchedule } from "./flow-schedule.js";
 export const RELEASE_HELP = `toolroll release <branch> — release Toolroll itself, from a pushed branch with an open pull request
 
@@ -58,6 +59,12 @@ toolroll release nightly --repo <path> --as <you> --token <password> [--schedule
   — the full release check of main's head every night, approved once with your password; it never deploys,
   merges or completes, and a failure tells you and holds composed releases until a full check passes
 
+toolroll release nightly --github --repo <path> --as <you> --token <password> — read GitHub's Nightly runs on main
+  for this project (its recorded GitHub remote): a lane that fails its tests holds every deploy of the project, a
+  release's merge and its tag until a later nightly passes it, or the release's own CI re-ran it after the failure and
+  passed. --lane-alias <lane-id> <new name> says a renamed job is the same lane; --lane-retire <lane-id> retires a
+  lane no required check names any more (both with your password)
+
 toolroll release ask-every-commit on|off --repo <path> [--as <you> --token <password>] — this project's releases ask
   for every later commit (on), or carry test-only commits again (off: your password, never the lead's token)
 
@@ -91,8 +98,8 @@ A runner's lease is returned with \`toolroll worker release <lease>\`.`;
 /** A runner lease id (claim.ts mints randomUUID()). */
 export const LEASE_SHAPED = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export const LEASE_DEPRECATION = "`toolroll release <lease>` is now `toolroll worker release <lease>`; the old form goes in the next minor version.";
-const VALUE_FLAGS = new Set(["--repo", "--limit", "--tap", "--release-gate", "--to", "--request", "--as", "--token", "--schedule", "--stage"]);
-const BARE_FLAGS = new Set(["--new", "--json", "--help", "--yes", "--no-carry", "--start", "--recover-deploy"]);
+const VALUE_FLAGS = new Set(["--repo", "--limit", "--tap", "--release-gate", "--to", "--request", "--as", "--token", "--schedule", "--stage", "--lane-retire"]);
+const BARE_FLAGS = new Set(["--new", "--json", "--help", "--yes", "--no-carry", "--start", "--recover-deploy", "--github"]);
 export async function runReleaseCommand(args, write, deps = {}) {
     // The flag, not a secret's value that happens to read "--json".
     // A secret is never exactly one of these names (the loop below refuses that as a missing value).
@@ -104,12 +111,21 @@ export async function runReleaseCommand(args, write, deps = {}) {
     };
     const positional = [];
     const limits = {};
-    let stage;
+    let stage, laneRetire, laneAlias;
     let repo, tap, gate, to, request, as, token, scheduleFlag;
     for (let i = 0; i < args.length; i += 1) {
         const raw = args[i];
         if (BARE_FLAGS.has(raw))
             continue;
+        // `--lane-alias <lane-id> <new name>`: two values, neither a flag of this command.
+        if (raw === "--lane-alias") {
+            const [id, name] = [args[i + 1], args[i + 2]];
+            if (id === undefined || name === undefined || id.startsWith("--") || name.startsWith("--"))
+                return refuse("usage", "--lane-alias takes <lane-id> <new name>.", 2);
+            laneAlias = [id, name];
+            i += 2;
+            continue;
+        }
         // `--flag=value` for every value flag; a secret (--token) is also the next argument even when it starts with "--".
         const equals = raw.startsWith("--") ? raw.indexOf("=") : -1;
         const arg = equals === -1 ? raw : raw.slice(0, equals);
@@ -139,6 +155,8 @@ export async function runReleaseCommand(args, write, deps = {}) {
                 gate = value;
             else if (arg === "--stage")
                 stage = value;
+            else if (arg === "--lane-retire")
+                laneRetire = value;
             else {
                 const match = /^([a-z]+)=([0-9]+)$/.exec(value);
                 if (match === null || !(match[1] in RELEASE_LIMITS) || Number(match[2]) < 1)
@@ -169,6 +187,13 @@ export async function runReleaseCommand(args, write, deps = {}) {
         return refuse("usage", "--stage goes with --recover-deploy.", 2);
     if (bare.has("--yes"))
         return refuse("usage", "--yes goes with --release-gate <id> or --recover-deploy; a release needs no confirmation beyond the owner's approval.", 2);
+    if (bare.has("--github") || laneAlias !== undefined || laneRetire !== undefined) {
+        if (positional[0] !== "nightly" || positional.length !== 1)
+            return refuse("usage", "--github, --lane-alias and --lane-retire go with `toolroll release nightly`.", 2);
+        if ([bare.has("--github"), laneAlias !== undefined, laneRetire !== undefined].filter(Boolean).length !== 1 || scheduleFlag !== undefined || bare.has("--start"))
+            return refuse("usage", "Use one of --github, --lane-alias or --lane-retire, without --schedule or --start.", 2);
+        return runGithubNightlyCommand({ repo: repo === undefined ? undefined : resolve(deps.cwd ?? process.cwd(), repo), as, token, alias: laneAlias, retire: laneRetire }, write, json, deps);
+    }
     if (positional[0] === "nightly" && positional.length === 1)
         return runNightlyCommand({ repo: repo === undefined ? undefined : resolve(deps.cwd ?? process.cwd(), repo), as, token, schedule: scheduleFlag, start: bare.has("--start") }, write, json, deps);
     if (["carry", "revoke", "ask-every-commit", "unsandboxed-carry", "auto-approve", "publish-ok"].includes(positional[0] ?? "") && positional.length === 2) {
@@ -463,3 +488,34 @@ async function runNightlyCommand(flags, write, json, deps) {
         store.close();
     }
 }
+/** `toolroll release nightly --github | --lane-alias | --lane-retire`: GitHub's nightly as release debt
+ * (nightly-github.ts), each a person's step proved with their password now. */
+async function runGithubNightlyCommand(flags, write, json, deps) {
+    const answer = (ok, fields, words, code) => { write(json ? checkedEnvelopeJson({ ok, command: "release nightly", ...fields }) : words); return code; };
+    if (flags.repo === undefined)
+        return answer(false, { reason: "usage", message: "Name the project with --repo <path>." }, "Name the project with --repo <path>.", 2);
+    if (flags.as === undefined || flags.token === undefined)
+        return answer(false, { reason: "usage", message: "This needs your password: add --as <you> --token <password>." }, "This needs your password: add --as <you> --token <password>.", 2);
+    if (machineActing() || process.env["TOOLROLL_LEAD_TOKEN"] !== undefined || process.env["TOOLROLL_REMOTE_TOKEN"] !== undefined)
+        return answer(false, { reason: "person-only", message: "Only a person changes how GitHub's nightly holds releases." }, "Only a person changes how GitHub's nightly holds releases.", 1);
+    const store = openStore(deps.database ?? databasePath(process.env, homedir()));
+    const now = (deps.now ?? (() => new Date()))();
+    try {
+        if (flags.alias !== undefined) {
+            const [laneId, name] = flags.alias;
+            const done = aliasNightlyLane(store, { repo: flags.repo, laneId, name, as: flags.as, token: flags.token }, now);
+            return done.ok ? answer(true, { lane: laneId, name }, `Jobs named "${name}" now count for lane ${laneId}.`, 0) : answer(false, { reason: "refused", message: done.message }, done.message, 1);
+        }
+        if (flags.retire !== undefined) {
+            const done = retireNightlyLane(store, { repo: flags.repo, laneId: flags.retire, as: flags.as, token: flags.token }, now);
+            return done.ok ? answer(true, { lane: flags.retire, closed: done.closed }, `Retired lane ${flags.retire}${done.closed > 0 ? `; ${done.closed} open failure${done.closed === 1 ? "" : "s"} closed` : ""}.`, 0)
+                : answer(false, { reason: "refused", message: done.message }, done.message, 1);
+        }
+        const made = optInGithubNightly(store, { repo: flags.repo, as: flags.as, token: flags.token }, now);
+        return made.ok ? answer(true, { github: made.slug, lanes: made.lanes }, `GitHub's nightly for ${made.slug} now holds this project's deploys, release merges and tags while a lane fails (${made.lanes} lanes).`, 0)
+            : answer(false, { reason: "refused", message: made.message }, made.message, 1);
+    }
+    finally {
+        store.close();
+    }
+}

package/dist/release-view.d.ts

@@ -30,5 +30,8 @@ export type ReleaseView = {
         outcome: string | null;
     } | null;
     openMainFailures: number;
+    /** GitHub's nightly (nightly-github.ts): each open lane failure, held or exempted for this release's tip, and a
+     * warning when it couldn't be read or hasn't run lately. */
+    githubNightly: string[];
 };
 export declare function releaseViewOf(store: Store, taskId: string, now: Date, obligations?: (authority: number) => string[]): ReleaseView | null;

package/dist/release-view.js

@@ -4,6 +4,7 @@
  * main; for a carried task, whose release approval it was carried from. Read-only, from the store.
  */
 import { liveReleaseOf } from "./scope.js";
+import { nightlyReleaseLines } from "./nightly-github.js";
 import { releaseAuthorityOfTask, releaseCarries } from "./store.js";
 export function releaseViewOf(store, taskId, now, obligations = () => []) {
     const found = releaseAuthorityOfTask(store, taskId);
@@ -23,5 +24,6 @@ export function releaseViewOf(store, taskId, now, obligations = () => []) {
         obligations: obligations(a.id),
         nightly: nightly === undefined ? null : { at: String(nightly["at"]), sha: String(nightly["sha"]), outcome: nightly["outcome"] == null ? null : String(nightly["outcome"]) },
         openMainFailures: open,
+        githubNightly: nightlyReleaseLines(store, { repo: a.repo, taskId: a.tipTask, candidate: a.tipSha, now }),
     };
 }

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];
@@ -304,6 +307,22 @@ export type ReleaseAuthorityAdapter = {
     /** 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;
+    }>;
 };
 /** 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`). */
@@ -662,10 +681,10 @@ 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. */
@@ -686,7 +705,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

@@ -38,37 +38,54 @@ 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";
 import { transientFailure } from "./release-net.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. */
+/** 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). */
@@ -192,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;
@@ -553,6 +570,16 @@ export async function runRelease(options, adapters) {
             if (held !== null)
                 throw new Stop("approval", `${held}. It was merged; nothing more is tagged, published or sent to Homebrew until a person lets it go on: \`toolroll release publish-ok ${j.task.id} --as <you> --token <password>\`, then rerun.`);
         };
+        /** GitHub's nightly lane debt before a deploy, the merge or the tag (evals-nightly.md, part A2). */
+        const nightlyHolds = async (phase) => {
+            if (rel?.nightly === undefined)
+                return;
+            const answer = await rel.nightly({ taskId: j.task.id, candidate: j.candidate.sha, pr: j.pr, phase });
+            if (answer.warning !== null)
+                say(`  ${answer.warning}`);
+            if (!answer.ok)
+                throw new Stop("nightly-debt", `${answer.why} Nothing was ${phase === "deploy" ? "deployed" : phase === "merge" ? "merged" : "tagged or published"}; rerun the release once it passes.`);
+        };
         /** identity(), on a plane that keeps release authority; a legacy plane keeps the old rules. */
         const watch = async (action) => { if (rel !== undefined)
             await identity(action, true); };
@@ -983,6 +1010,7 @@ export async function runRelease(options, adapters) {
                                 await watch("deploy");
                                 // Every deploy reservation, whatever the journal saved: CI must still be green on the exact commit.
                                 await autoCiHolds("the deploy");
+                                await nightlyHolds("deploy");
                                 const reserved = await rel.reserve({ authority: j.authority.id, kind: "deploy", taskId: j.task.id, candidate: j.candidate.sha, epoch });
                                 if (!reserved.ok)
                                     throw new Stop("release", `The deploy couldn't be reserved: ${reserved.why}`);
@@ -1000,6 +1028,7 @@ export async function runRelease(options, adapters) {
                             await pinned();
                             // Every deploy issued, whatever the journal saved (a retry after a rollback included): CI still green.
                             await autoCiHolds("the deploy");
+                            await nightlyHolds("deploy");
                             let operation, secret = "";
                             if (rel !== undefined && j.authority && epoch !== null) {
                                 const reserved = await rel.reserve({ authority: j.authority.id, kind: "deploy", taskId: j.task.id, candidate: j.candidate.sha, epoch });
@@ -1093,6 +1122,9 @@ export async function runRelease(options, adapters) {
                             const verdict = prChecksVerdict(await adapters.github.checks(j.github, j.candidate.sha), j.candidate.sha, REQUIRED_PR_CHECKS, { ...autoCap(), workflow: REQUIRED_PR_CHECKS_WORKFLOW });
                             if (verdict.state !== "passed")
                                 await ciFailedAfterDeploy(`Pull request checks are no longer all passing on ${j.candidate.sha.slice(0, 7)}`);
+                            // GitHub's nightly lane debt (a bounded read), before main's last read so it doesn't widen that window; the
+                            // reservation below checks the stored debt again in its own transaction.
+                            await nightlyHolds("merge");
                             // Main once more, from GitHub, the last thing before the merge is reserved: moved since the comparison, it
                             // stops here (finding 4). GitHub's own up-to-date rule refuses the rest of the window.
                             const now = await adapters.github.mainHead(j.github);
@@ -1149,6 +1181,7 @@ export async function runRelease(options, adapters) {
                             throw new Stop("conflict", `${j.tag} already points at ${at.slice(0, 7)}, not the merge ${merge.sha.slice(0, 7)}.`);
                         if (at === null) {
                             await autoCiHolds("the tag");
+                            await nightlyHolds("tag");
                             intend("tag");
                             await adapters.github.createTag(j.github, j.tag, merge.sha);
                         }
@@ -1422,9 +1455,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)`);
@@ -1468,6 +1504,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;
@@ -1525,5 +1568,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/reported-usage.d.ts

@@ -0,0 +1,69 @@
+import type { Billing } from "./spend.js";
+/** Several reported models are kept as their sorted ids joined by this (it has spaces, so no one id can equal it):
+ * a run whose calls ran different models never reads as any one of them. */
+export declare const MODELS_JOIN = " + ";
+export declare function reportedModelOf(value: unknown): string | null;
+/** The one model a Claude result's `modelUsage` names; null when it names none, several, or anything malformed. */
+export declare function soleReportedModel(modelUsage: unknown): string | null;
+/** Two reports of the same piece of work (a resumed turn, a second init): unknown if either is, the model when they
+ * agree, otherwise every model named, sorted (never one chosen). */
+export declare function combineReportedModels(a: string | null, b: string | null): string | null;
+export declare function providerTurnsOf(value: unknown): number | null;
+export declare function reportedCostUsdOf(value: unknown): number | null;
+/** One provider call's own report. `tokensIn` is everything the model read (cached included) when the provider
+ * reported every part of it (run-efficiency.ts usageOf), else null. */
+export type ProviderReport = {
+    modelReported: string | null;
+    providerTurns: number | null;
+    reportedCostUsd: number | null;
+    tokensIn: number | null;
+    cacheReadTokens: number | null;
+    cacheWriteTokens: number | null;
+};
+/** What the session's own `system`/`init` events named: the one model they agree on, or that they disagree. */
+export type ClaudeInitModel = {
+    model: string | null;
+    conflict: boolean;
+};
+/** A Claude primary `result` (streamed or buffered `--output-format json`), with what the session's inits named. The
+ * init's model is the session's own; inits that disagree leave it unknown; with no init naming one, the result's
+ * `modelUsage` counts only when it names exactly one model. */
+export declare function claudeResultReport(result: Record<string, unknown>, init?: ClaudeInitModel): ProviderReport;
+/** Codex's `turn.completed` usage: its input already counts what came from cache; it reports no cache writes, no
+ * model and no cost in `exec --json`, so those stay unknown. */
+export declare function codexUsageReport(usage: unknown): ProviderReport;
+/** One of the three amounts, never added to another. */
+export type ReportedAmount = {
+    kind: "api";
+    microusd: number;
+}
+/** The provider's own reported cost of work a subscription covers: usage, not billed (null: it reported none). */
+ | {
+    kind: "subscription";
+    reportedUsd: number | null;
+} | {
+    kind: "unknown";
+};
+/** A run's amount, from its fixed billing and its priced spend (run_spend). Subscription work reads its provider's
+ * reported cost as usage, never as dollars; billed work without a reported or priced cost is unknown. v141 (Codex
+ * round 1 #4, #10): billing this computer's default guessed (`basis` not evidence) is unknown, and so is a run whose
+ * cost the provider never reported (its `cost_usd` then holds a conservative charge, never a measurement). */
+export declare function runAmountOf(run: {
+    billing: Billing | null;
+    spendMicrousd: number | null;
+    costUsd: number | null;
+    basis?: "evidence" | "default" | null;
+    costUnknown?: boolean;
+}): ReportedAmount;
+/** A chat request's amount: a subscription chat's reported cost is usage; an API chat's settled charge is dollars,
+ * unless its spend is unknown (then the amount is, whatever was settled against the reservation). v141 (Codex round 1
+ * #4): a subscription harness's request is subscription usage only when its own events said it was billed to the plan
+ * (`billingReported`); one they said used a key is API dollars at its reported cost; one they said nothing of is
+ * unknown. Absent `billingReported` keeps the older reading for callers that predate it. */
+export declare function chatTurnAmountOf(turn: {
+    provider: string;
+    settledMicrousd: number | null;
+    unknownSpend: boolean;
+    reportedCostUsd: number | null;
+    billingReported?: "subscription" | "api-key" | null;
+}): ReportedAmount;