toolroll 0.9.79 → 0.9.82

package/dist/exec.js

@@ -1847,6 +1847,11 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
         let initLine = null;
         let initIdentityLine = null;
         let conflictingInitLine = null;
+        /** v140: the first init's model, and the first top-level init naming another (the parser reads them as a conflict:
+         * unknown, never one of them). Kept even within one session id. */
+        let initModel = null;
+        let initModelLine = null;
+        let modelConflictLine = null;
         let initSessionId = null;
         let resultLine = null;
         let resultOverflowed = false;
@@ -1955,6 +1960,15 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
             if (type === "system" && String(event["subtype"] ?? "") === "init" && topLevelEvent(event)) {
                 if (initLine === null)
                     initLine = line;
+                const model = typeof event["model"] === "string" ? event["model"] : null;
+                if (model !== null) {
+                    if (initModel === null) {
+                        initModel = model;
+                        initModelLine = line;
+                    }
+                    else if (model !== initModel && modelConflictLine === null)
+                        modelConflictLine = line;
+                }
                 const id = transportSessionId(event["session_id"]);
                 let identityWitness = false;
                 if (id !== null) {
@@ -2052,7 +2066,7 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
             liveProviders.delete(child);
             framing.finish();
             live?.detach();
-            const lines = [initLine, initIdentityLine, conflictingInitLine, accountedResultLine(), overflowLine]
+            const lines = [initLine, initIdentityLine, conflictingInitLine, initModelLine, modelConflictLine, accountedResultLine(), overflowLine]
                 .filter((one) => one !== null)
                 .filter((line, index, all) => all.indexOf(line) === index);
             const settlement = container === null ? Promise.resolve(null) : settleContainer(container, options);

package/dist/flow-draft.js

@@ -7,6 +7,7 @@
  * nothing is sent: a later zone shows it to a person, and a later step posts
  * it ({{stage.<id>}}).
  */
+import { inEvalWorld } from "./eval-gate.js";
 import { redactSecretLines, scanForSecrets } from "./evidence.js";
 import { run } from "./exec.js";
 import { CLAUDE_NO_TOOLS_ARGS, CLAUDE_SIGNED_OUT, claudeJsonBody, claudeModelArgs, inScratchDir } from "./claude-print.js";
@@ -59,6 +60,9 @@ export function keptDraft(text) {
 /** The production runner: Claude through the sign-in on this computer, with no tools, no MCP servers and no repository. */
 export function claudeDraftRunner(runner = run) {
     return request => inScratchDir("standing-orders-draft-", async (dir) => {
+        // An eval world makes no provider call it can't cap and record (eval-gate.ts).
+        if (inEvalWorld())
+            return { ok: false, said: "Drafts aren't written in an eval world." };
         const started = Date.now();
         const result = await runner("claude", [
             "-p", "--output-format", "json", ...CLAUDE_NO_TOOLS_ARGS, ...claudeModelArgs(request.model),

package/dist/flow-sort.js

@@ -7,6 +7,7 @@
  * second, with how sure it is. It never writes text, so nothing it returns
  * is instructions: an answer is only ever one of the zone's own options.
  */
+import { inEvalWorld } from "./eval-gate.js";
 import { redactSecretLines, scanForSecrets } from "./evidence.js";
 import { SORT_ROUTE_KEY, sortKeyOf, sortNoteKeyOf } from "./contracts/flow.js";
 import { readJevReply } from "./contracts/sort-answer.js";
@@ -51,6 +52,9 @@ export function sortRequest(sort, state) {
 }
 /** Ask Jev through OpenRouter. Trouble reaching it (or a refused key, or no credit) is a reason to try again, in words. */
 export async function askJev(fetcher, key, request) {
+    // An eval world makes no provider call it can't gate and record (eval-gate.ts), so nothing is sent.
+    if (inEvalWorld())
+        return { ok: false, said: "An eval world makes no Jev call." };
     const started = Date.now();
     let response;
     try {

package/dist/github-jobs.d.ts

@@ -0,0 +1,25 @@
+/**
+ * GitHub's own job records, read by the plane's gh (release-adapters.ts for a release's checks, nightly-github.ts for
+ * GitHub's nightly): what each step of a finished job did. Step numbers and outcomes are the runner's records; nothing
+ * the tested code prints is read.
+ */
+/** One job's step outcomes as GitHub's Actions API reports them. */
+export type JobRecord = {
+    id: number;
+    status: string;
+    conclusion: string | null;
+    steps: {
+        number: number;
+        name: string;
+        status: string;
+        conclusion: string | null;
+    }[];
+};
+/**
+ * Whether a finished, unsuccessful job ended before any of the workflow's own steps ran: every step after GitHub's own
+ * first one ("Set up job", always number 1) never ran (no conclusion, or skipped) — leaving out only GitHub's own
+ * closing "Complete job" when it is the last step. Step numbers and outcomes are the runner's records; nothing the
+ * candidate prints is read. A job with no steps never reached one. Anything else (a step that ran, even the checkout)
+ * is not confirmed infrastructure.
+ */
+export declare function failedBeforeTests(job: JobRecord): boolean;

package/dist/github-jobs.js

@@ -0,0 +1,22 @@
+/**
+ * GitHub's own job records, read by the plane's gh (release-adapters.ts for a release's checks, nightly-github.ts for
+ * GitHub's nightly): what each step of a finished job did. Step numbers and outcomes are the runner's records; nothing
+ * the tested code prints is read.
+ */
+/**
+ * Whether a finished, unsuccessful job ended before any of the workflow's own steps ran: every step after GitHub's own
+ * first one ("Set up job", always number 1) never ran (no conclusion, or skipped) — leaving out only GitHub's own
+ * closing "Complete job" when it is the last step. Step numbers and outcomes are the runner's records; nothing the
+ * candidate prints is read. A job with no steps never reached one. Anything else (a step that ran, even the checkout)
+ * is not confirmed infrastructure.
+ */
+export function failedBeforeTests(job) {
+    if (job.status !== "completed" || job.conclusion === "success" || job.conclusion === null)
+        return false;
+    const steps = [...job.steps].sort((a, b) => a.number - b.number);
+    if (new Set(steps.map(one => one.number)).size !== steps.length)
+        return false;
+    const last = steps.at(-1);
+    const own = steps.filter(one => one.number > 1 && !(one === last && one.name === "Complete job" && steps.length > 1));
+    return own.every(one => one.status !== "in_progress" && (one.conclusion === null || one.conclusion === "skipped"));
+}

package/dist/guides.js

@@ -473,20 +473,23 @@ with a time limit.
    saved first; if either name doesn't answer as the new build, both go
    back. It goes on only when the console, worker and both names run the
    gated commit. A rerun relinks without deploying again.
-8. **ci**: waits for every pull-request check on the gated commit:
-   Ubuntu on Node 22 and 24, Linux and Windows containment. Pending,
-   missing, skipped, cancelled or failed never merges.
+8. **ci**: waits for every pull-request check on the gated commit: Node 24
+   on Ubuntu and macOS, the area lanes (Linux cgroup and fence, Windows,
+   git 2.41 and 2.47), and Node 22 on Ubuntu and macOS, which runs on a
+   release-* branch's pull request.
+   Pending, missing, skipped, cancelled or failed never merges, and main's
+   protection must require every one of them.
 9. **merge**: squash-merges with the head pinned to the gated commit,
    once main has nothing the branch lacks, then deletes the remote branch
    only if its head still matches. A resumed merge also finishes this cleanup.
 10. **tree**: main's merge commit must have exactly the gated tree, or
    nothing is tagged.
-11. **tag**: pushes \`v<version>\` on that merge commit. In publish.yml,
-    macOS Node 22 and 24 must both pass before npm and GitHub publication
-    (the candidate's macOS checks already passed in ci.yml before the merge).
-    macos.yml keeps the nightly matrix.
-12. **publish**: waits for npm, the GitHub release and the tag's publish
-    job (which needs the macOS legs); not main's own CI on the merge commit.
+11. **tag**: pushes \`v<version>\` on that merge commit. The tag runs no
+    tests again: publish.yml's release proof reads GitHub's record that the
+    tagged tree is the merged pull request's head tree and passed every
+    required check there, and npm and GitHub publication need it.
+12. **publish**: waits for npm, the GitHub release and the tag's release
+    proof and publish jobs; not main's own push run on the merge commit.
 13. **homebrew**: the release is published once npm and the GitHub release
     are verified. It proposes the tap's formula change (checksum from npm's
     tarball) and looks at its checks once: \`Published; Homebrew pending\`

package/dist/invoke.d.ts

@@ -18,7 +18,7 @@
  */
 import { type AgentSpec, type Invocation, type ProviderRunner, type AgentEnding } from "./provider.js";
 import { type VersionProbe } from "./attest.js";
-import type { Store } from "./store.js";
+import { type Store } from "./store.js";
 import type { RunOptions } from "./exec.js";
 import type { Runner } from "./worktree.js";
 import { type NetworkFence, type SignInGrants } from "./agent-fence.js";

package/dist/invoke.js

@@ -16,6 +16,7 @@
  * (`adapterFor`), and only builder, planner, reviewer, and scout import
  * `invokeAgent`.
  */
+import { takeEvalDispatch } from "./eval-gate.js";
 import { adapterFor, auditOf, claudePluginEnv, isolationUnsupported, ALL_CREDENTIAL_ENV } from "./provider.js";
 import { readProviderKey, readAuthModeStrict, PROVIDER_KEY_ENV, OWN_KEY_ENV } from "./keys.js";
 import { ACP_AGENTS, isAcpProvider, isKeyedProvider } from "./acp-agents.js";
@@ -26,6 +27,7 @@ import { attestProvider } from "./attest.js";
 import { run as runCommand, runOwnerTag, streamsInput } from "./exec.js";
 import { spawnSync } from "node:child_process";
 import { currentContainment } from "./containment.js";
+import { recordRunBillingBasis, recordRunCostUnknown, recordRunModelReported } from "./store.js";
 import { witnessedRunner } from "./process-custody.js";
 import { underStopWatch } from "./task-control.js";
 import { childDatabaseEnv, isolatedChildDatabase, removeChildDatabase as removeAgentDatabase } from "./child-database.js";
@@ -153,6 +155,12 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     if (recordedSessionId !== null && requestedResumeSessionId === null && startSessionId !== recordedSessionId) {
         throw new Error(`run ${runId} already records session ${recordedSessionId} but this invocation neither resumes nor starts under it`);
     }
+    // An eval world (eval-gate.ts, docs/plans/evals-nightly.md part C): every dispatch takes one of the attempt's slots,
+    // named for this run so the runner can match it to the run's record; past the case's limit nothing spawns. Outside
+    // an eval world this changes nothing.
+    const evalSlot = takeEvalDispatch(`run:${runId}`);
+    if (evalSlot.active && !evalSlot.ok)
+        return { kind: "refused", reason: "containment", providerVersion: null, diagnostic: evalSlot.why };
     const adapter = adapterFor(spec.provider);
     const { startSessionId: _untrustedStartSessionId, streamInput: _untrustedStreamInput, ...invocationWithoutStart } = invocation;
     // Live input (live-input.ts): only Claude's builds, only through a transport that keeps stdin open. The brief is
@@ -715,6 +723,8 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     // An ACP run bills as its admission stamp says (store.acpBillingOfRun): its agent's own plan, or metered.
     const acpBilling = isAcpProvider(spec.provider) ? (store.acpBillingOfRun(runId)?.kind === "plan" ? "subscription" : "api-key") : null;
     store.fixRunBilling(runId, acpBilling ?? (authMode === "api-key" ? "api-key" : evidence ?? billingOf(spec.provider, store.handle)), new Date());
+    // v141: whether that billing is this run's own evidence or this computer's default (a guess: unknown money).
+    recordRunBillingBasis(store, runId, acpBilling !== null || authMode === "api-key" || evidence !== null ? "evidence" : "default");
     const envelope = adapter.parse(result.stdout);
     store.stampAgentReportedUsage(runId, envelope.agentReportedUsage ?? null);
     // An installed CLI too old for a build's own setup refuses its flags
@@ -765,6 +775,10 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         // How many agent turns it took, where the provider reports it (docs/plans/run-efficiency.md); unknown stays NULL.
         ...(envelope.ending?.turns == null ? {} : { agentTurns: envelope.ending.turns + (options.accumulateUsage ? run.agentTurns ?? 0 : 0) }),
     });
+    // v141: a turn whose cost wasn't reported leaves the run's money unknown for good (a sticky column, never the note).
+    recordRunCostUnknown(store, runId, envelope.costUnknown === true);
+    // v140: the exact model the provider's own events named (null: not reported); a resumed turn adds its own to the run's.
+    recordRunModelReported(store, runId, envelope.modelReported ?? null, options.accumulateUsage === true);
     // How the attempt ended, classified HERE where the structural terminal
     // still exists; a sign-in that no longer works pauses its provider.
     // A run that failed within seconds having produced nothing is read for

package/dist/lead.js

@@ -509,7 +509,10 @@ export async function runLeadTurn(input) {
             return fail("over-reservation", LEAD_FAILURE_COPY.overReserved, true);
         }
         finishStep({ state: "answered", tokensIn: answer.tokensIn, tokensOut: answer.tokensOut, settledMicrousd: stepSettled, replyBytes: Buffer.byteLength(answer.text, "utf8"),
-            cacheReadTokens: answer.cacheReadTokens ?? null, cacheWriteTokens: answer.cacheWriteTokens ?? null });
+            cacheReadTokens: answer.cacheReadTokens ?? null, cacheWriteTokens: answer.cacheWriteTokens ?? null,
+            // v140: what the provider itself reported for this request (absent: unreported, kept NULL).
+            modelReported: answer.modelReported ?? null, providerTurns: answer.providerTurns ?? null, reportedCostUsd: answer.reportedCostUsd ?? null,
+            billingReported: answer.billingReported ?? null });
         tokensIn += answer.tokensIn;
         tokensOut += answer.tokensOut;
         if (answer.cacheReadTokens === undefined)

package/dist/memory-pass.js

@@ -10,6 +10,7 @@
  * is the one writer, and it writes through the ordinary knowledge and
  * decision stores so every edit keeps its revision.
  */
+import { inEvalWorld } from './eval-gate.js';
 import { createHash } from 'node:crypto';
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -188,6 +189,9 @@ export function analysisPrompt(surface, openGaps) {
 /** The production analyser: one call through the configured chat provider, no tools, no history. */
 export function defaultAnalyzer(store, options) {
     return async (input) => {
+        // An eval world makes no provider call it can't record (eval-gate.ts, Codex round 1 #3): the backward pass waits.
+        if (inEvalWorld())
+            return { ok: false, problem: 'The backward pass makes no provider call in an eval world.' };
         const config = store.getChatConfig();
         if (config === null)
             return { ok: false, problem: 'Chat is not configured; the backward pass uses the chat model.' };

package/dist/nightly-check.d.ts

@@ -18,6 +18,8 @@ export declare const NIGHTLY_ACCEPTANCE: readonly {
 }[];
 /** The ledger act that records a person's approval of a nightly check, keyed by its trigger. */
 export declare const NIGHTLY_APPROVED = "nightly check approved";
+/** The ledger act that records a person turning GitHub's nightly into release debt for a project (nightly-github.ts). */
+export declare const GITHUB_NIGHTLY_ON = "github nightly debt on";
 /** The digest a person's approval of the nightly signs: the trigger, the project, the schedule, the check-only terms
  * and the fixed words each firing files. */
 export declare function nightlyDigestOf(trigger: number, repo: string, schedule: string, check: MainCheck): string;
@@ -44,7 +46,8 @@ export declare const TRUSTED_MAIN_CLEAR_MS: number;
  * last read failed, or when the read was of another remote than the one recorded now (review round 2).
  */
 export declare function trustedMainOf(store: Store, repo: string, now: Date, maxAgeMs: number): string | null;
-/** The watch loop's read of each project's recorded remote main that the nightly check or main's debt needs, at most
+/** The watch loop's read of each project's recorded remote main that the nightly check, GitHub's nightly (its runs count
+ * only at commits on main's history) or main's debt needs, at most
  * every 30 minutes. Each read is a fresh fetch into a private directory. A failed read forgets the last one. A good
  * one hands its verified objects to the project's Git store (hardened git, content-addressed: git checks every object
  * against its hash, and filing verifies the commit again), so the nightly can check a merge the checkout never pulled. */

package/dist/nightly-check.js

@@ -36,6 +36,8 @@ export const NIGHTLY_NOT = "Changing anything: this is a check only.";
 export const NIGHTLY_ACCEPTANCE = Object.freeze([{ id: "c1", statement: "The full release check passes on main", how: null, evidence: ["check"] }]);
 /** The ledger act that records a person's approval of a nightly check, keyed by its trigger. */
 export const NIGHTLY_APPROVED = "nightly check approved";
+/** The ledger act that records a person turning GitHub's nightly into release debt for a project (nightly-github.ts). */
+export const GITHUB_NIGHTLY_ON = "github nightly debt on";
 /** The digest a person's approval of the nightly signs: the trigger, the project, the schedule, the check-only terms
  * and the fixed words each firing files. */
 export function nightlyDigestOf(trigger, repo, schedule, check) {
@@ -91,14 +93,15 @@ export function trustedMainOf(store, repo, now, maxAgeMs) {
     }
     return sha;
 }
-/** The watch loop's read of each project's recorded remote main that the nightly check or main's debt needs, at most
+/** The watch loop's read of each project's recorded remote main that the nightly check, GitHub's nightly (its runs count
+ * only at commits on main's history) or main's debt needs, at most
  * every 30 minutes. Each read is a fresh fetch into a private directory. A failed read forgets the last one. A good
  * one hands its verified objects to the project's Git store (hardened git, content-addressed: git checks every object
  * against its hash, and filing verifies the commit again), so the nightly can check a merge the checkout never pulled. */
 export async function refreshTrustedMains(store, root, now, runner = run) {
     const repos = new Set([
         ...store.handle.prepare("SELECT DISTINCT repo FROM main_check_failure WHERE cleared_at IS NULL").all().map(row => String(row["repo"])),
-        ...store.handle.prepare("SELECT DISTINCT repo FROM action_ledger WHERE action = ?").all(NIGHTLY_APPROVED).map(row => String(row["repo"])),
+        ...store.handle.prepare("SELECT DISTINCT repo FROM action_ledger WHERE action IN (?, ?) AND repo IS NOT NULL").all(NIGHTLY_APPROVED, GITHUB_NIGHTLY_ON).map(row => String(row["repo"])),
     ]);
     let read = 0;
     const remotes = new RemoteMains(store, runner, root);

package/dist/nightly-github.d.ts

@@ -0,0 +1,316 @@
+import { GITHUB_NIGHTLY_ON } from "./nightly-check.js";
+import { type Store } from "./store.js";
+export { GITHUB_NIGHTLY_ON };
+/** The one workflow file whose runs count: exactly this path, never one with an `@` suffix or another folder's. */
+export declare const NIGHTLY_WORKFLOW_PATH = ".github/workflows/nightly.yml";
+/** GitHub's re-run horizon: a counted run is read again for new attempts for this long. */
+export declare const NIGHTLY_WATCH_MS: number;
+/** Listing never goes further back than this: no run older than it can still be unfinished. */
+export declare const NIGHTLY_LIST_HORIZON_MS: number;
+/** Pages of runs one read lists at most; a longer backlog resumes on the next read. */
+export declare const NIGHTLY_PAGES_PER_READ = 10;
+/** A boundary's one bounded read (deploy, merge, pre-tag), and the background read's overall deadline. */
+export declare const NIGHTLY_BOUNDARY_READ_MS = 20000;
+export declare const NIGHTLY_BACKGROUND_READ_MS = 60000;
+/** How often the watch loop reads each opted-in project's nightly. */
+export declare const NIGHTLY_BACKGROUND_EVERY_MS: number;
+export declare const SHARDS_PASSED_STEP = "Every shard passed";
+export declare const SHARDS_COVERED_STEP = "Every shard ran the whole suite";
+/** One GitHub REST read through the plane's own gh (release-adapters.ts githubReads), bounded by `timeoutMs`. */
+export type GhRead = (path: string, timeoutMs: number) => Promise<{
+    ok: true;
+    body: unknown;
+} | {
+    ok: false;
+    why: string;
+}>;
+/** Main as the plane read it from the recorded remote: whether a commit is on its first-parent history ("unknown" when
+ * main hasn't been read lately, the commit isn't here yet, or the read of main is older than `since` — a run created
+ * after main was read may be on a main that read hasn't seen), and whether one main commit contains another. */
+export type MainHistory = {
+    /** `deadline`: wall-clock milliseconds by which the local history work stops ("unknown" then). */
+    onMain(sha: string, since: string, deadline: number): "yes" | "no" | "unknown";
+    /** Three-state, like onMain: "unknown" when history couldn't be read whole or the deadline passed. */
+    mainContains(sha: string, ancestor: string, deadline: number): "yes" | "no" | "unknown";
+};
+export type NightlyDeps = MainHistory & {
+    gh: GhRead;
+    now: () => Date;
+};
+/** One read inside a read's deadline. */
+type Get = (path: string) => Promise<{
+    ok: true;
+    body: unknown;
+} | {
+    ok: false;
+    why: string;
+}>;
+/** Whether a project opted in, as the plane recorded a person's step: the newest such ledger row, read strictly. */
+export declare function githubNightlyOf(store: Store, repo: string): {
+    slug: string;
+    url: string;
+    record: number;
+    by: string;
+    at: string;
+} | null;
+/** Every project that ever opted in (a broken or superseded record still counts here: its debt still holds). */
+export declare function githubNightlyRepos(store: Store): string[];
+/** A lane's stable id: its workflow file and the required check's name when it was seeded. */
+export declare const laneIdOf: (workflow: string, name: string) => string;
+/** One lane per required check whose name no lane (by its name or an alias) answers to yet. A retired lane whose name
+ * is required again opens again. */
+export declare function seedLanes(store: Store, repo: string, now: Date): void;
+/** The live lane a job of `workflow` named `name` belongs to: a person's alias first (the newest for that name), then
+ * the lane seeded under it. Never a guess: anything else is no lane. */
+export declare function resolveLane(store: Store, repo: string, workflow: string, name: string): string | null;
+/** The name a lane is shown by: its newest alias, else the name it was seeded under. */
+export declare function laneName(store: Store, repo: string, laneId: string): string;
+/** `toolroll release nightly --github`: a person turns GitHub's nightly into release debt for this project. The
+ * repository is the project's recorded remote's, never the checkout's. */
+export declare function optInGithubNightly(store: Store, input: {
+    repo: string;
+    as: string;
+    token: string;
+}, now: Date): {
+    ok: true;
+    slug: string;
+    lanes: number;
+} | {
+    ok: false;
+    message: string;
+};
+/** `--lane-alias <old-id> <new name>`: a person says a renamed job is the same lane. Open debt goes with the lane. */
+export declare function aliasNightlyLane(store: Store, input: {
+    repo: string;
+    laneId: string;
+    name: string;
+    as: string;
+    token: string;
+}, now: Date): {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/** `--lane-retire <lane-id>`: a person retires a lane no required check names any more; its open debt closes,
+ * recorded as theirs. */
+export declare function retireNightlyLane(store: Store, input: {
+    repo: string;
+    laneId: string;
+    as: string;
+    token: string;
+}, now: Date): {
+    ok: true;
+    closed: number;
+} | {
+    ok: false;
+    message: string;
+};
+type GhRun = {
+    id: number;
+    path: string;
+    repository: string | null;
+    headRepository: string | null;
+    headBranch: string | null;
+    headSha: string;
+    event: string;
+    status: string;
+    runAttempt: number;
+    createdAt: string;
+};
+type GhStep = {
+    number: number;
+    name: string;
+    status: string;
+    conclusion: string | null;
+};
+export type GhJob = {
+    id: number;
+    name: string;
+    status: string;
+    conclusion: string | null;
+    startedAt: string | null;
+    completedAt: string | null;
+    headSha: string;
+    runId: number;
+    runAttempt: number | null;
+    steps: GhStep[] | null;
+};
+/** Whether a run is one of the project's own nightly runs on main (everything but main's history, checked apart). */
+export declare function nightlyRunBinds(run: Pick<GhRun, "path" | "repository" | "headRepository" | "headBranch" | "event" | "headSha">, slug: string): boolean;
+export type Cause = "passed" | "test-failure" | "runner-failure" | "not-run";
+/**
+ * Why a completed lane job ended as it did, from GitHub's own job and step records in the same attempt
+ * (evals-nightly.md, "Cause of a failure"). Fails closed: anything not positively the runner's is a test failure.
+ */
+export declare function causeOf(job: GhJob, attempt: readonly GhJob[]): Cause;
+export type NightlyRead = {
+    ok: true;
+    listed: number;
+    checked: number;
+    complete: boolean;
+} | {
+    ok: false;
+    why: string;
+};
+/**
+ * One read of the project's GitHub nightly within `budgetMs`: list runs from the cursor, re-read the watch list (new
+ * and unfinished runs first, then the oldest-checked), record every completed lane job, open and clear failures. A
+ * failed call stops where it is; what was recorded stays, and the cursor never moves past a page it couldn't read.
+ */
+export declare function readGithubNightly(store: Store, repo: string, deps: NightlyDeps, budgetMs: number): Promise<NightlyRead>;
+/** Every job of one exact attempt of one run, every page, each GitHub's record of that run, attempt and commit. Null
+ * when any page can't be read whole. */
+export declare function readAttemptJobs(get: Get, slug: string, run: number, attempt: number, sha: string): Promise<GhJob[] | null>;
+/** A recorded open failure of a lane. */
+export type LaneFailure = {
+    id: number;
+    repo: string;
+    laneId: string;
+    ghRun: number;
+    attempt: number;
+    jobId: number;
+    sha: string;
+    completedAt: string;
+    openedAt: string;
+};
+export declare function openFailures(store: Store, repo: string): LaneFailure[];
+/**
+ * Clear each open failure that a later counted nightly run passed: a run created after the failed run (a rerun of an
+ * older run never clears newer debt; Codex round 1, finding 2), the same lane, a job started after the failed one
+ * completed, on a commit that contains the failed one. A re-run inside the same run never clears. Local history work
+ * stops at `wall` (wall-clock ms); what is left is settled on a later read.
+ */
+export declare function settleGithubNightly(store: Store, repo: string, history: Pick<MainHistory, "mainContains">, now: Date, wall?: number): {
+    cleared: number;
+    complete: boolean;
+    unresolved: string | null;
+};
+/** Main's history as the plane read it from the project's recorded remote (nightly-check.ts trustedMainOf), from the
+ * verified objects in the project's own Git store; never a ref a build could move. */
+export declare function mainHistoryOf(store: Store, repo: string, now: Date): MainHistory;
+/**
+ * The watch loop's background read (operate.ts refreshGithubNightlies): each opted-in project at most every
+ * NIGHTLY_BACKGROUND_EVERY_MS, claimed in the store so two processes don't both read, within one overall deadline.
+ */
+export declare function readGithubNightlies(store: Store, deps: {
+    gh: GhRead;
+    now: () => Date;
+    history?: (repo: string, now: Date) => MainHistory;
+}, budgetMs?: number): Promise<number>;
+/** What a hold stops: a deploy, the merge, the tag (pre-tag authorization), or an automatic approval (sealAutoGreen). */
+export type NightlyPhase = "deploy" | "merge" | "tag" | "auto";
+/** How long a boundary's re-read of a candidate's exemption stands for the stored checks inside the reservation, the
+ * deployment gate and the installed runtime's deploy check after it. */
+export declare const EXEMPTION_FRESH_MS: number;
+/** "Oct 30, 06:17 UTC". */
+export declare const nightlyStamp: (iso: string) => string;
+/** The words of a nightly hold: the first open failure, how many more, and the way out at this point. */
+export declare function nightlyDebtWords(store: Store, held: readonly LaneFailure[], phase: NightlyPhase, release: boolean): string;
+/**
+ * The stored check every boundary makes, inside the caller's own transaction where it has one (the deployment gate, the
+ * deploy and merge reservations, the pre-tag step, an automatic approval): the project's open lane failures, less those
+ * this exact task and candidate hold a fresh exemption for. Null when nothing holds. A project that never opted in has
+ * no lane failures.
+ */
+export declare function nightlyDebtHold(store: Store, input: {
+    repo: string;
+    taskId: string | null;
+    candidate: string | null;
+    phase: NightlyPhase;
+    release: boolean;
+    now: Date;
+}): {
+    why: string;
+    failures: LaneFailure[];
+} | null;
+/** How the project's GitHub nightly stands: whether it is on, when it was last read (and why not), when it last ran. */
+export type NightlyStatus = {
+    on: boolean;
+    lastOkAt: string | null;
+    lastWhy: string | null;
+    lastRunAt: string | null;
+    stale: boolean;
+};
+/** No nightly run seen for this long reads "hasn't run since". */
+export declare const NIGHTLY_STALE_MS: number;
+export declare function githubNightlyStatus(store: Store, repo: string, now: Date): NightlyStatus;
+/** A warning that never holds anything (Decision 1): GitHub couldn't be read, or the nightly hasn't run lately. */
+export declare function nightlyWarning(status: NightlyStatus, now: Date): string | null;
+/** One workflow's newest pull-request run on a candidate head, as an exemption reads it. */
+export type LaneJobs = {
+    run: number;
+    attempt: number;
+    status: string;
+    jobs: GhJob[];
+};
+/**
+ * A release candidate's own pull-request CI, as an exemption needs it (modelled on scripts/release-proof.mjs): for each
+ * workflow, the newest run on `head` from that pull request's `pull_request` event, that run's latest attempt's jobs
+ * with their times, then the run read again. The newest run is chosen first: one that doesn't bind to this pull
+ * request never lets an older run stand. `null` for a workflow with no such run; "unreadable" when anything can't be
+ * read whole or changed during the read.
+ */
+export declare function readLaneJobs(get: Get, slug: string, pr: number, head: string, workflows: readonly string[]): Promise<Map<string, LaneJobs | null> | "unreadable">;
+/** The files a lane's job runs that the candidate could otherwise rewrite to make a job of that name pass: its workflow
+ * file and the CI scripts the workflows call. An exemption stands only when each is byte-identical (the same Git
+ * blob) on the candidate and at the failed commit. The tests themselves are the candidate's, as for every required
+ * check (the trust the required-checks gate already places in them). */
+export declare const LANE_PINNED_FILES: readonly ["scripts/ci-shards.mjs", "scripts/ci-scope.mjs", "scripts/ci-git.sh", "scripts/ci-no-skips.mjs"];
+export type NightlyBoundary = {
+    ok: true;
+    warning: string | null;
+} | {
+    ok: false;
+    why: string;
+    warning: string | null;
+};
+/**
+ * A boundary (the coordinator's deploy, merge and pre-tag steps): one bounded read of GitHub's nightly, then this
+ * candidate's exemptions read again from its own pull-request CI — minted only before the merge (`deploy`, `merge`);
+ * at the tag an exemption obtained before the merge is re-read, never made — then the stored debt. A read that fails is
+ * a warning and the stored debt still holds; an exemption that can't be re-read is no exemption here.
+ */
+export declare function nightlyBoundary(store: Store, input: {
+    repo: string;
+    taskId: string;
+    candidate: string;
+    pr: number;
+    phase: Exclude<NightlyPhase, "auto">;
+}, deps: NightlyDeps, budgetMs?: number): Promise<NightlyBoundary>;
+/** One project-level Needs-you item: an open GitHub nightly lane failure, or a nightly check of main that failed. */
+export type NightlyNeed = {
+    key: string;
+    repo: string;
+    title: string;
+    reason: string;
+    href: string;
+    since: string;
+};
+/**
+ * Needs you, for the projects `shown` admits: one item per open GitHub nightly lane failure (linking to its job on
+ * GitHub, under the opted-in repository the plane recorded), and one per nightly check of main with open failures
+ * (linking to its task). Oldest first.
+ */
+export declare function nightlyNeedsYou(store: Store, shown: (repo: string) => boolean): NightlyNeed[];
+/** The release card's GitHub nightly lines: each open lane failure (held, or exempted for this candidate), then a
+ * warning when GitHub couldn't be read or the nightly hasn't run lately. Empty when there is nothing to say. */
+export declare function nightlyReleaseLines(store: Store, input: {
+    repo: string;
+    taskId: string;
+    candidate: string | null;
+    now: Date;
+}): string[];
+/**
+ * A deploy run's own boundary (scripts/deploy-browser.mjs, through the installed runtime; Codex round 1, finding 3):
+ * the same bounded read as the coordinator's — GitHub's nightly, then this candidate's exemptions re-read — before the
+ * stored check, so a deploy started by hand neither misses a new failure nor rides an exemption its CI no longer
+ * supports. A task no release covers has no exemption to re-read; its nightly is still read. Anything that fails here
+ * takes away the candidate's stored exemptions; the stored check that follows decides.
+ */
+export declare function refreshNightlyForDeploy(store: Store, input: {
+    runId: number;
+    now: () => Date;
+    gh?: GhRead;
+    budgetMs?: number;
+}): Promise<NightlyBoundary | null>;