toolroll 0.9.79 → 0.9.82

package/dist/operate.d.ts

@@ -2,6 +2,7 @@ import { type IntegrationIo } from "./integrations.js";
 import { type OnboardIo } from "./agent-onboard.js";
 import { type Sizer } from "./task-sizing.js";
 import { type TriggerIo } from "./flow-triggers.js";
+import { type GhRead } from "./nightly-github.js";
 import type { StepIo } from "./flow-steps.js";
 import type { FetchLike } from "./flow-share.js";
 import { type Store } from "./store.js";
@@ -9,7 +10,7 @@ import { type DispatchAdapter } from "./sync.js";
 import { type RolePort, type UpRoleStart } from "./up-processes.js";
 import { type TelegramTransport } from "./telegram.js";
 import { type LeadCliSeams } from "./lead-cli.js";
-import { type Principal, type RemoteSource } from "./operate-remote.js";
+import { type Principal, type RemoteRun, type RemoteSource } from "./operate-remote.js";
 import { type PublishExec } from "./publish.js";
 import { type Runner as CommandRunner } from "./builder.js";
 import { type ReleaseIo } from "./releases.js";
@@ -150,6 +151,79 @@ export declare function runOperateAs(argv: string[], opts: {
     tool?: string;
     options?: OperateOptions;
 }): Promise<number>;
+type Context = {
+    /** A remote run's person (runOperateAs): every credential check resolves to them. Absent for every local command. */
+    principal?: RemoteRun;
+    /** The lead token this command runs under: it signs in as its owner. */
+    leadToken?: string;
+    desktopIdentity?: string;
+    /** A desktop service directory is state, never an implicitly enrolled project. */
+    inferProjectFromCwd?: boolean;
+    /** Exact additions approved by the native project picker, independent of the enrollment registry. */
+    additionalProjectRepos?: () => readonly string[];
+    store: Store;
+    write: Write;
+    json: boolean;
+    /** Every --repo occurrence in order (arc 2) — only `up` reads it. */
+    repoList?: string[];
+    now: Date;
+    clock: () => Date;
+    evidenceRoot: string;
+    /** The directory holding the database — where credential files live. */
+    databaseFile: string;
+    /** Where `storage` looks for leftover test temp folders; default the temp folder and /tmp. */
+    tempRoots?: readonly string[];
+    /** The long-lived service's token: only a pass carrying it may start the automatic storage sweep. */
+    sweepOwner?: object;
+    telegramTokenFile: string;
+    agentRunner?: CommandRunner;
+    gitRunner?: CommandRunner;
+    telegramTransport?: TelegramTransport;
+    telegramEnv?: Record<string, string | undefined>;
+    /** Injected by tests: what `publish` runs for git and gh. */
+    publishExec?: PublishExec;
+    leadSeams?: LeadCliSeams;
+    /** Injected by tests: the external-dispatch gh surface. */
+    dispatchAdapter?: DispatchAdapter;
+    /** Injected by tests: how flow triggers reach GitHub (gh) and Linear (fetch), and where their secrets live. */
+    flowTriggerIo?: Partial<TriggerIo>;
+    /** Injected by tests: how flow check and update steps run commands and reach GitHub and Linear. */
+    flowStepIo?: Partial<StepIo>;
+    /** Injected by tests: how often a worker's flow passes run beside its builds (default FLOW_EVERY_MS). */
+    flowEveryMs?: number;
+    /** Injected by tests: the operating system this runs on (default process.platform). */
+    platform?: NodeJS.Platform;
+    /** Injected by tests: whether this machine has an OS fence for checks (default: probed). */
+    fenceAvailable?: () => boolean;
+    /** Injected by tests: how `flows import` fetches a flow file's address. */
+    flowFetch?: FetchLike;
+    integrationIo?: Partial<IntegrationIo>;
+    /**
+     * The stop fence (Codex M5-M8 audit, IV-1): set by the watch when a
+     * signal lands. A pass that sees true admits NOTHING more — no schedule
+     * fires, no claim, no run, no spawn. The in-flight build finishes under
+     * its own bounds (or the grace kill); admission is what stops.
+     */
+    shouldStop?: () => boolean;
+    /** A failed recovery pass pauses new admissions without stopping an owned build. */
+    shouldPauseAdmission?: () => boolean;
+    /** Test seam for task wait; production uses a timer. */
+    waitSleep?: (milliseconds: number) => Promise<void>;
+    releaseIo?: ReleaseIo;
+    installBin?: string;
+    onboardSeams?: OnboardSeams;
+    upSeams?: {
+        terminal?: boolean;
+        env?: Record<string, string | undefined>;
+        openBrowser?: (url: string) => void;
+    };
+    /** This process is one role of a `toolroll up`, started by it (never from the command line). */
+    upRole?: UpRoleHost;
+    /** In-memory seams a child process can't receive: `up` runs its console and worker in this one process. */
+    upOneProcess?: boolean;
+    /** Test seam: this computer's tailnet names (production asks `tailscale status`). */
+    tailnetNames?: () => Promise<readonly string[]>;
+};
 /** Durably create the login file BEFORE the bootstrap commits (arc 2
  * finding 27): exclusive, 0600, fsynced — file and directory both — so the
  * row only ever follows a durable secret. Throws on any failure. */
@@ -181,3 +255,19 @@ export type UpRoleHost = {
 /** A role child's whole run (up-role-child.ts): the ordinary command prelude (containment, secrets, limits), then the
  * role itself. Only a process started by `up` gets here; no command line selects a role. */
 export declare function runUpRole(start: UpRoleStart, port: RolePort): Promise<number>;
+/** GitHub's nightly as release debt (docs/plans/evals-nightly.md, part A): the watch loop's background read of each
+ * opted-in project's nightly runs, at most every 30 minutes, within a 60 s overall deadline, through the plane's own gh
+ * (release-adapters.ts githubReads). Nothing is read for a project that never opted in. */
+export declare function refreshGithubNightlies(store: Store, now: () => Date, reads?: GhRead): Promise<number>;
+/**
+ * `toolroll evals run | attempt | cases | recover` (docs/plans/evals-nightly.md, part C).
+ *
+ * - `run [--diagnostic] [--case a,b] [--k n] --as <you> --token <password>`: admit a campaign (a person's proof, the
+ *   no release busy) and run it to its end from this installed plane. With no flags it is canonical,
+ *   refused while any case is a draft. Each attempt is a child process: `evals attempt`.
+ * - `attempt <campaign> <case> <n> --world <dir> --db <world db>`: one attempt's world (eval-world.ts). Only under its
+ *   runner's dispatch gate, and only on the world's own database.
+ * - `cases`: each installed case, its version, its pin, and whether a person has validated it yet.
+ * - `recover [--abandon <campaign>]`: settle campaigns whose runner stopped; with --abandon, a person ends a stuck one.
+ */
+export declare function evalsCommand(positional: readonly string[], flags: Map<string, string | true>, context: Context): Promise<number>;

package/dist/operate.js

@@ -60,6 +60,9 @@ import { runRequestedUndos, sendSubagentWeeklies } from "./subagent-week.js";
 import { refreshConnections } from "./mcp-connect.js";
 import { releaseCheckPurposeFor, releaseTermsFor } from "./release-carry.js";
 import { refreshTrustedMains, settleReleaseChecks } from "./nightly-check.js";
+import { githubNightlyRepos, readGithubNightlies } from "./nightly-github.js";
+import { exec as releaseExec, githubReads } from "./release-adapters.js";
+import { releaseTools } from "./release-git.js";
 import { SECRETS_FIRST, startToolSecrets, toolSecretStorage } from "./project-tools.js";
 import { followDiscord } from "./discord.js";
 import { followTeams } from "./teams.js";
@@ -99,7 +102,7 @@ import { taskReviewBrief, renderReviewBrief } from "./task-review-brief.js";
  * **Nothing ever prompts.** There is no terminal on the other end at 3am.
  */
 import { homedir, hostname } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { releaseStalledUpdate, waitingUpdate } from "./toolroll-update.js";
 import { openStore, openStoreNoMigrate, CONCURRENT_WRITER_WAIT_MS, isDatabaseBusy, databasePath, BUILT_IN, parseCapabilityKey, verifiedAuthor, isDigestTime, predecessorWatches, RESULT_SCREENSHOTS, lifecycleOf, reportLifecycle, beatLifecycle, } from "./store.js";
 import { createHash, randomBytes, randomInt, randomUUID } from "node:crypto";
@@ -247,6 +250,7 @@ import { installationStatus, renderInstallationStatus, renderTaskWait, repairSta
 import { latestRelease, newerRelease, notifySecurityRelease, notifyVersionLive, recordRunnerVersion, startUpdateChecks, updateLine } from "./releases.js";
 import { installMethod } from "./install-method.js";
 import { PACKAGE_VERSION } from "./version.js";
+import { machineActing } from "./scope.js";
 /**
  * 0 done · 1 broke · 2 bad usage · 3 ran fine, the answer is no.
  *
@@ -676,6 +680,9 @@ export const OPERATE_VALUE_FLAGS = new Set([
     "choose", "note", "max-open-decisions", "name", "days", "publication", "auto-approve", "review-auto", "port", "host", "allow-host",
     "for", "tick-every", "bridge-every", "reconcile-every", "incarnation",
     "say", "ceiling-usd", "cap-usd",
+    // evals: the cases a diagnostic campaign runs, its k, an attempt's world and what its builds may not read, and the
+    // stuck campaign a person ends (recover --abandon).
+    "case", "k", "world", "deny", "abandon",
     "token-file", "bin", "poll", "github", "remote", "head-prefix", "password",
     // v102: project rules.
     "not-requester", "protect", "protect-paths",
@@ -714,6 +721,8 @@ export const OPERATE_VALUE_FLAGS = new Set([
     "release",
 ]);
 export const OPERATE_BOOLEAN_FLAGS = new Set([
+    // evals run: a report-only campaign; keep each attempt's world for a look afterwards.
+    "diagnostic", "keep",
     // task scope --release ... --no-carry: every later commit asks again.
     "no-carry",
     "json", "yes", "all", "brief", "local", "history", "latest-watch", "dry-run", "file",
@@ -1147,6 +1156,8 @@ async function dispatch(command, positional, flags, context) {
     switch (command) {
         case "status":
             return statusCommand(positional, flags, context);
+        case "evals":
+            return evalsCommand(positional, flags, context);
         case "ready":
             return readyCommand(flags, context);
         case "task":
@@ -6279,6 +6290,10 @@ async function runWatchLoop(args) {
             const settledChecks = settleReleaseChecks(store, context.evidenceRoot, context.clock());
             if (settledChecks > 0)
                 progress(`watch: settled ${settledChecks} release check(s)`);
+            // GitHub's nightly as release debt (nightly-github.ts): each opted-in project at most every 30 minutes, 60 s in
+            // all. A test's injected agent runner means a test: no real gh.
+            if (context.agentRunner === undefined)
+                await refreshGithubNightlies(store, context.clock);
             // A finished check may send a build's card down its failure path: now, not on the next beat.
             if (ran + batched > 0)
                 moveCards(store, repo, context.clock(), context.evidenceRoot);
@@ -12373,3 +12388,145 @@ async function runUpWorkerRole(context, config, port, build) {
     }
     return EXIT.ok;
 }
+/** GitHub's nightly as release debt (docs/plans/evals-nightly.md, part A): the watch loop's background read of each
+ * opted-in project's nightly runs, at most every 30 minutes, within a 60 s overall deadline, through the plane's own gh
+ * (release-adapters.ts githubReads). Nothing is read for a project that never opted in. */
+export async function refreshGithubNightlies(store, now, reads) {
+    if (githubNightlyRepos(store).length === 0)
+        return 0;
+    return readGithubNightlies(store, { gh: reads ?? githubReads(releaseExec, releaseTools().gh, { retry: true }), now });
+}
+/**
+ * `toolroll evals run | attempt | cases | recover` (docs/plans/evals-nightly.md, part C).
+ *
+ * - `run [--diagnostic] [--case a,b] [--k n] --as <you> --token <password>`: admit a campaign (a person's proof, the
+ *   no release busy) and run it to its end from this installed plane. With no flags it is canonical,
+ *   refused while any case is a draft. Each attempt is a child process: `evals attempt`.
+ * - `attempt <campaign> <case> <n> --world <dir> --db <world db>`: one attempt's world (eval-world.ts). Only under its
+ *   runner's dispatch gate, and only on the world's own database.
+ * - `cases`: each installed case, its version, its pin, and whether a person has validated it yet.
+ * - `recover [--abandon <campaign>]`: settle campaigns whose runner stopped; with --abandon, a person ends a stuck one.
+ */
+export async function evalsCommand(positional, flags, context) {
+    const { write, json } = context;
+    // Loaded when an eval command runs, so no other command (nor the console's bundle) pays for the eval runner.
+    const { admitEvalCampaign, campaignSpending, EVALS_ROOT, installedBuildDigest, loadEvalSet, planCampaign, recoverEvalCampaigns, runEvalCampaign } = await import("./evals.js");
+    const { inEvalWorld } = await import("./eval-gate.js");
+    const { evalCliEntry, runEvalWorld } = await import("./eval-world.js");
+    const action = positional[0];
+    const command = `evals${action === undefined ? "" : ` ${action}`}`;
+    const usage = "Use: toolroll evals run [--diagnostic] [--case <ids>] [--k <n>] --as <you> --token <password> | toolroll evals cases | toolroll evals recover [--abandon <campaign> --as <you> --token <password>]";
+    if (action === "recover" && flags.has("abandon"))
+        return evalsAbandonCommand(flags, context);
+    if (action === "recover") {
+        // A campaign whose runner stopped: its unfinished attempts recorded as interrupted, then it ends incomplete.
+        const recovered = recoverEvalCampaigns(context.store, context.clock());
+        return succeed(write, json, command, { campaigns: recovered }, () => recovered.length === 0 ? ["No campaign is running."] : recovered.map(one => `${one.id}: ${one.recovered ? "recovered" : "left running"} (${one.why})`));
+    }
+    if (action === "cases") {
+        const set = loadEvalSet();
+        if (!set.ok)
+            return fail(write, json, command, "unreadable", set.problem, EXIT.failed);
+        const cases = set.cases.map(one => ({ id: one.id, kind: one.kind, version: one.version, pin: one.pin, validatedBy: one.validatedBy, draft: one.validatedBy === null }));
+        return succeed(write, json, command, { manifestDigest: set.manifestDigest, cases }, () => cases.map(one => `${one.id} (${one.kind}) ${one.version.slice(0, 12)} on ${one.pin.model}: ${one.draft ? "draft, awaiting a person's validation" : `validated by ${one.validatedBy}`}`));
+    }
+    if (action === "attempt") {
+        // Only its campaign's runner starts an attempt: under the runner's dispatch gate, on the world's own database.
+        if (!inEvalWorld())
+            return fail(write, json, command, "refused", "An eval attempt runs only from its campaign's runner.", EXIT.refused);
+        const [, campaign, caseId, n] = positional;
+        const world = text(flags, "world");
+        if (campaign === undefined || caseId === undefined || n === undefined || !/^[1-9][0-9]?$/.test(n) || world === undefined)
+            return fail(write, json, command, "usage", "Use: toolroll evals attempt <campaign> <case> <n> --world <dir> --db <world>/toolroll/orders.db", EXIT.usage);
+        let worldDir;
+        try {
+            worldDir = realpathSync(world);
+        }
+        catch {
+            return fail(write, json, command, "refused", "The world's folder can't be read.", EXIT.refused);
+        }
+        if (resolve(context.databaseFile) !== join(worldDir, "toolroll", "orders.db"))
+            return fail(write, json, command, "refused", "An eval attempt runs only on its world's own database.", EXIT.refused);
+        const set = loadEvalSet();
+        const one = set.ok ? set.cases.find(item => item.id === caseId) : undefined;
+        if (one === undefined)
+            return fail(write, json, command, "refused", set.ok ? `No case is named ${caseId}.` : set.problem, EXIT.refused);
+        const deny = (text(flags, "deny") ?? "").split(",").filter(path => path !== "" && isAbsolute(path));
+        const report = await runEvalWorld(one, { worldDir, databaseFile: context.databaseFile, deny, timeoutMs: one.timeoutMinutes * 60_000 });
+        return succeed(write, json, command, { ...report }, () => [JSON.stringify(report)]);
+    }
+    if (action !== "run" || positional.length !== 1)
+        return fail(write, json, command, "usage", usage, EXIT.usage);
+    if (inEvalWorld())
+        return fail(write, json, command, "refused", "An eval world doesn't start campaigns of its own.", EXIT.refused);
+    if (machineActing() || process.env["TOOLROLL_LEAD_TOKEN"] !== undefined)
+        return fail(write, json, command, "person-only", "Only a person starts an eval campaign: it spends money.", EXIT.refused);
+    const k = text(flags, "k");
+    const cases = text(flags, "case");
+    const set = loadEvalSet();
+    if (!set.ok)
+        return fail(write, json, command, "unreadable", set.problem, EXIT.failed);
+    const planned = planCampaign(set, { ...(cases === undefined ? {} : { cases: cases.split(",").filter(Boolean) }), ...(k === undefined ? {} : { k: Number(k) }), diagnostic: flag(flags, "diagnostic") });
+    if (!planned.ok)
+        return fail(write, json, command, "refused", planned.problem, EXIT.refused);
+    const acting = await askCredentials(flags, context);
+    if (acting === null)
+        return fail(write, json, command, "usage", "An eval campaign is started with your password: add --as <you> --token <password>.", EXIT.usage);
+    const { plan } = planned;
+    const buildDigest = () => installedBuildDigest(PACKAGE_VERSION);
+    const sealed = { cases: plan.cases.map(one => ({ id: one.id, version: one.version, pin: one.pin, maxDispatches: one.maxDispatches })), k: plan.k, baseline: null, evals: EVALS_ROOT };
+    // A campaign whose runner stopped no longer holds its place.
+    recoverEvalCampaigns(context.store, context.clock());
+    const admitted = admitEvalCampaign(context.store, { kind: "eval", canonical: plan.canonical, manifestDigest: set.manifestDigest, buildDigest: buildDigest(), version: PACKAGE_VERSION, k: plan.k,
+        sealed, as: acting.name, token: acting.token, now: context.clock() });
+    if (!admitted.ok)
+        return fail(write, json, command, admitted.reason, admitted.message, EXIT.refused);
+    const stateDir = dirname(context.databaseFile);
+    const entry = evalCliEntry();
+    const keep = ["PATH", "HOME", "USER", "LOGNAME", "LANG", "SHELL", "TMPDIR"];
+    const ended = await runEvalCampaign(context.store, admitted.id, plan.cases, {
+        // Beside the plane's state folder, never inside it: a world's builds read-deny the plane's state.
+        workRoot: join(dirname(stateDir), "toolroll-eval-worlds", admitted.id),
+        buildDigest,
+        keepWorlds: flag(flags, "keep"),
+        now: context.clock,
+        command: input => ({ file: entry.file, args: [...entry.args, "evals", "attempt", input.campaign, input.caseId, String(input.n), "--world", input.worldDir, "--deny", stateDir, "--db", input.databaseFile, "--json"],
+            env: { ...Object.fromEntries(keep.flatMap(name => process.env[name] === undefined ? [] : [[name, process.env[name]]])), XDG_CONFIG_HOME: join(input.worldDir, "config") } }),
+    });
+    const rows = context.store.handle.prepare("SELECT case_id, n, replaces, outcome, error_why, api_microusd, subscription_microusd, usage_unknown FROM eval_attempt WHERE campaign = ? ORDER BY case_id, n, replaces").all(admitted.id);
+    const nullable = (value) => value === null || value === undefined ? null : Number(value);
+    const attempts = rows.map(row => ({ case: String(row["case_id"]), n: Number(row["n"]), replaces: Number(row["replaces"]), outcome: row["outcome"] === null ? null : String(row["outcome"]),
+        why: row["error_why"] === null ? null : String(row["error_why"]), apiMicrousd: nullable(row["api_microusd"]), subscriptionMicrousd: nullable(row["subscription_microusd"]), usageUnknown: Number(row["usage_unknown"]) === 1 }));
+    // What was actually spent, as recorded: API dollars and subscription usage apart, unknown never shown as measured.
+    const spent = campaignSpending(context.store, admitted.id);
+    const dollars = (micro, unknown) => micro === null ? `unknown (${unknown} attempt${unknown === 1 ? "" : "s"} with unknown spending)` : `$${(micro / 1_000_000).toFixed(2)}`;
+    return succeed(write, json, command, { campaign: admitted.id, canonical: plan.canonical, state: ended.state, why: ended.why, attempts, spending: spent }, () => [
+        `Campaign ${admitted.id} (${plan.canonical ? "canonical" : "diagnostic"}) is ${ended.state}${ended.why === null ? "" : `: ${ended.why}`}.`,
+        ...attempts.map(one => `${one.case} #${one.n}${one.replaces === 0 ? "" : " (replacement)"}: ${one.outcome ?? "not finished"}${one.why === null ? "" : ` — ${one.why}`}`),
+        `API dollars: ${dollars(spent.apiMicrousd, spent.unknownAttempts)}. Subscription usage, not billed: ${dollars(spent.subscriptionMicrousd, spent.unknownAttempts)}.`,
+    ]);
+}
+/**
+ * `toolroll evals recover --abandon <campaign> --as <you> --token <password>` (PR #263 review): a person ends a campaign
+ * recovery can't settle (its runner or a world's processes can't be proven gone). Its unfinished attempts are recorded
+ * as errors and its spending as unknown, and it ends incomplete; nothing is signalled and no world is removed. A lead
+ * token, a machine or an eval world is refused; the password is checked inside the write (evals.ts abandonEvalCampaign).
+ */
+async function evalsAbandonCommand(flags, context) {
+    const { write, json } = context;
+    const command = "evals recover";
+    const { abandonEvalCampaign } = await import("./evals.js");
+    const { inEvalWorld } = await import("./eval-gate.js");
+    const id = text(flags, "abandon");
+    if (id === undefined || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(id))
+        return fail(write, json, command, "usage", "Use: toolroll evals recover --abandon <campaign> --as <you> --token <password>", EXIT.usage);
+    if (inEvalWorld() || machineActing() || process.env["TOOLROLL_LEAD_TOKEN"] !== undefined)
+        return fail(write, json, command, "person-only", "Only a person abandons an eval campaign.", EXIT.refused);
+    const acting = await askCredentials(flags, context);
+    if (acting === null)
+        return fail(write, json, command, "usage", "A campaign is abandoned with your password: add --as <you> --token <password>.", EXIT.usage);
+    const ended = abandonEvalCampaign(context.store, { id, as: acting.name, token: acting.token, now: context.clock() });
+    if (!ended.ok)
+        return fail(write, json, command, ended.reason, ended.message, EXIT.refused);
+    return succeed(write, json, command, { campaign: id, state: "incomplete", attempts: ended.attempts, spending: "unknown" }, () => [`Campaign ${id} ended incomplete. ${ended.attempts} unfinished attempt${ended.attempts === 1 ? "" : "s"} recorded as errors; what it spent is unknown. Nothing was stopped: check for its processes yourself.`]);
+}

package/dist/project-knowledge.d.ts

@@ -23,18 +23,18 @@ export declare function knowledgeVersion(store: Store, repo: string, actor: stri
 /** Chat reads only an admitted project. Keep the full source in the project UI. */
 export declare function conversationKnowledge(store: Store, repo: string, actor: string, reference?: string, decision?: number): {
     title?: never;
+    content?: never;
     history?: never;
     revision: number;
     stale: boolean;
     notice: string;
     decision?: never;
-    content?: never;
     instructions?: never;
     references?: never;
     decisions?: never;
 } | {
     title?: never;
-    revision?: never;
+    content?: never;
     history?: never;
     stale?: never;
     decision: {
@@ -52,7 +52,7 @@ export declare function conversationKnowledge(store: Store, repo: string, actor:
         id: number;
     };
     notice: string;
-    content?: never;
+    revision?: never;
     instructions?: never;
     references?: never;
     decisions?: never;
@@ -69,9 +69,9 @@ export declare function conversationKnowledge(store: Store, repo: string, actor:
     decisions?: never;
 } | {
     title?: never;
+    content?: never;
     stale?: never;
     decision?: never;
-    content?: never;
     revision: number;
     history: {
         revision: number;

package/dist/provider.d.ts

@@ -177,6 +177,9 @@ export type ParsedEnvelope = {
     structuralTerminal: import("./exhaustion.js").StructuralTerminal | null;
     /** What an ACP agent itself reported it used — kept on the run, never priced. Absent for every other dialect. */
     agentReportedUsage?: string | null;
+    /** v140: the exact model the provider itself reported for this turn (Claude: its session's init, or a buffered
+     * result's one `modelUsage` model). Absent or null: not reported — every other dialect today. */
+    modelReported?: string | null;
     /** An ACP conversation's facts the conformance check reads (acp-client.ts AcpEnvelope): nothing else does. */
     acp?: {
         offered: string[];

package/dist/provider.js

@@ -30,6 +30,7 @@ import { ACP_AGENTS, isAcpProvider, withAcp } from "./acp-agents.js";
 import { acpParse } from "./acp-client.js";
 import { agentSpecSchema, MODEL_ID, modelIdSchema, PROVIDER_ID_VALUES, providerIdSchema } from "./contracts/provider.js";
 import { primaryResultEvent, topLevelEvent } from "./stream-scope.js";
+import { claudeResultReport, reportedModelOf } from "./reported-usage.js";
 export const PROVIDER_IDS = PROVIDER_ID_VALUES;
 export function isProviderId(value) {
     return providerIdSchema.safeParse(value).success;
@@ -293,7 +294,7 @@ function claudeFinalMessage(result) {
     }
     return typeof result.result === "string" ? result.result : null;
 }
-function claudeEnvelopeOf(result, sessionFromInit, initObserved, initSessionConflict = false) {
+function claudeEnvelopeOf(result, sessionFromInit, initObserved, initSessionConflict = false, initModel = { model: null, conflict: false }) {
     const input = result?.usage?.input_tokens;
     const output = result?.usage?.output_tokens;
     const cost = result?.total_cost_usd;
@@ -322,6 +323,8 @@ function claudeEnvelopeOf(result, sessionFromInit, initObserved, initSessionConf
         costUsd: typeof cost === "number" && cost >= 0 ? cost : null,
         ...(result !== null && result[CLAUDE_COST_UNKNOWN] === true ? { costUnknown: true } : {}),
         usageRaw: result?.usage === undefined ? null : JSON.stringify(result.usage).slice(0, USAGE_JSON_CAP),
+        // The model only when the session's own events name it (never the agent's words); no result, no report.
+        modelReported: result === null ? (initModel.conflict ? null : initModel.model) : claudeResultReport(result, initModel).modelReported,
         initObserved,
         // Structural, never prose (finding 15): consumed means the primary
         // result says SUCCESS. An error result keeps its text as diagnostics
@@ -354,6 +357,7 @@ function claudeParse(stdout) {
     let initSeen = false;
     let sessionFromInit = null;
     let initSessionConflict = false;
+    const initModels = new Set();
     let primary = null;
     let transportFailure = null;
     for (const line of stdout.split("\n")) {
@@ -379,6 +383,9 @@ function claudeParse(stdout) {
         }
         if (String(type) === "system" && String(event["subtype"] ?? "") === "init") {
             initSeen = true;
+            const model = reportedModelOf(event["model"]);
+            if (model !== null)
+                initModels.add(model);
             const id = sessionIdOf(event["session_id"]);
             if (id !== null) {
                 if (sessionFromInit === null)
@@ -402,7 +409,7 @@ function claudeParse(stdout) {
                 primary = result;
         }
     }
-    const envelope = claudeEnvelopeOf(primary, sessionFromInit, initSeen, initSessionConflict);
+    const envelope = claudeEnvelopeOf(primary, sessionFromInit, initSeen, initSessionConflict, { model: initModels.size === 1 ? [...initModels][0] : null, conflict: initModels.size > 1 });
     if (transportFailure === null)
         return envelope;
     return {

package/dist/release-adapters.d.ts

@@ -8,6 +8,8 @@ import type { CheckRun, GateState, Installed, MainProtection, ReleaseAdapters }
 import { Store } from "./store.js";
 import { type CiObservation } from "./release-auto.js";
 import { type BuildRunner } from "./release-carry.js";
+import { type GhRead } from "./nightly-github.js";
+export { failedBeforeTests, type JobRecord } from "./github-jobs.js";
 import { type ReleaseRepo, type ReleaseTools } from "./release-git.js";
 export { RELEASE_PATH, RELEASE_REMOTE, releaseConfigProblem, releaseGitArgs, releaseGitEnv, releaseRemote, releaseTools, type ReleaseRepo, type ReleaseTools } from "./release-git.js";
 export type Exec = (command: string, args: readonly string[], options?: {
@@ -112,7 +114,10 @@ export declare function bumpFormula(text: string, url: string, sha256: string):
 export declare function storeReleaseAdapter(open: () => Store, done: (store: Store) => void, now: () => Date, runner?: BuildRunner, 
 /** Releases that approve themselves (auto-approve-green.md): the plane's own look at CI on a commit, and where the
  * check receipts are kept. Absent: no automatic approval, every release asks a person. */
-auto?: AutoObservers): NonNullable<ReleaseAdapters["release"]>;
+auto?: AutoObservers, 
+/** GitHub's nightly (nightly-github.ts): the plane's own gh reads for a boundary's one bounded read. Absent: nothing
+ * is read at the boundary, and the stored debt still holds inside every reservation. */
+nightlyReads?: GhRead): NonNullable<ReleaseAdapters["release"]>;
 /** What the plane itself reads for an automatic release approval. */
 export type AutoObservers = {
     /** The plane's executor policy, never a report field or project setting. Unknown refuses. Production currently
@@ -135,28 +140,23 @@ export declare function readCheckRuns(run: Exec, gh: string, repo: string, sha:
 options?: {
     tag?: string;
 }): Promise<CheckRun[]>;
-/** 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;
 /** GitHub's job record for one check run (its job), read strictly: null when it can't be read whole. */
 export declare function readJobBeforeTests(run: Exec, gh: string, repo: string, id: number): Promise<boolean | null>;
+/**
+ * GitHub's REST API as GitHub's nightly reads it (nightly-github.ts): GET only, github.com only, a repository path, the
+ * plane's own gh with the allowlisted environment, each call bounded by its caller's deadline. A background read rides
+ * out a short network failure (release-net.ts, within that call's own share of the deadline); a boundary's read is
+ * plain exec. Never an answer that isn't GitHub's whole JSON.
+ */
+export declare function githubReads(run: Exec, gh: string, options?: {
+    retry?: boolean;
+}): (path: string, timeoutMs: number) => Promise<{
+    ok: true;
+    body: unknown;
+} | {
+    ok: false;
+    why: string;
+}>;
 /** GitHub lists check runs from at most the latest 1000 check suites of a commit: the history is whole only below that. */
 export declare const CHECK_SUITE_CEILING = 1000;
 export declare function readSuitesComplete(run: Exec, gh: string, repo: string, sha: string): Promise<boolean>;

package/dist/release-adapters.js

@@ -28,6 +28,9 @@ import { autoPublishHeld, holdAutoPublish, liftCiHold, authorizeAutoCheck, giveU
 import { proveCarry } from "./release-carry.js";
 import { randomBytes, randomUUID } from "node:crypto";
 import { deploymentGate } from "./deploy-gate.js";
+import { failedBeforeTests } from "./github-jobs.js";
+import { mainHistoryOf, nightlyBoundary } from "./nightly-github.js";
+export { failedBeforeTests } from "./github-jobs.js";
 import { extractCommit } from "./commit-extract.js";
 import { teardownGit, refusal as gitRefusal } from "./teardown-git.js";
 import { RELEASE_REMOTE, releaseConfigProblem, releaseGitArgs, releaseGitEnv, releaseRemote, releaseTools } from "./release-git.js";
@@ -422,7 +425,9 @@ export function releaseAdapters(options) {
         upToDateRequired: () => readUpToDateRequired(reads, ciGh, releaseRepo().slug), evidenceRoot: join(dirname(database), "evidence"),
         // A successful Actions job authenticates the job, not the candidate-writable JSON it uploads. Until the
         // executor protects that reporting channel, production releases must take the person's approval road.
-        reportsProtected: false });
+        reportsProtected: false }, 
+    // A boundary's one bounded read of GitHub's nightly: plain exec, never the release's long retries (20 s in all).
+    githubReads(run, ciGh));
     return {
         ...(existsSync(database) ? { release } : {}),
         now: options.now ?? (() => new Date()),
@@ -925,7 +930,10 @@ function personAnswerOf(value) {
 export function storeReleaseAdapter(open, done, now, runner, 
 /** Releases that approve themselves (auto-approve-green.md): the plane's own look at CI on a commit, and where the
  * check receipts are kept. Absent: no automatic approval, every release asks a person. */
-auto) {
+auto, 
+/** GitHub's nightly (nightly-github.ts): the plane's own gh reads for a boundary's one bounded read. Absent: nothing
+ * is read at the boundary, and the stored debt still holds inside every reservation. */
+nightlyReads) {
     const withStore = (body) => { const store = open(); try {
         return body(store);
     }
@@ -962,6 +970,20 @@ auto) {
         async live(taskId, action) {
             return withStore(store => { const live = liveReleaseOf(store, taskId, action, now()); return live.applies ? { applies: true, ok: live.ok, why: live.ok ? null : live.why } : { applies: false, ok: false, why: null }; });
         },
+        ...(nightlyReads === undefined ? {} : {
+            async nightly(input) {
+                const store = open();
+                try {
+                    const repo = store.lookupRef(input.taskId)?.repo ?? null;
+                    if (repo === null)
+                        return { ok: false, why: `Task ${input.taskId} is in no project, so GitHub's nightly debt can't be read for it.`, warning: null };
+                    return await nightlyBoundary(store, { repo, taskId: input.taskId, candidate: input.candidate, pr: input.pr, phase: input.phase }, { ...mainHistoryOf(store, repo, now()), gh: nightlyReads, now });
+                }
+                finally {
+                    done(store);
+                }
+            },
+        }),
         async lease(authority, owner) { return withStore(store => takeReleaseLease(store, authority, owner, now())); },
         async renew(authority, owner, epoch) { return withStore(store => renewReleaseLease(store, authority, owner, epoch, now())); },
         async carry(authority, to, requestId, epoch) {
@@ -1169,23 +1191,6 @@ options = {}) {
     }
     return runs.sort((a, b) => a.id - b.id);
 }
-/**
- * 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"));
-}
 /** GitHub's job record for one check run (its job), read strictly: null when it can't be read whole. */
 export async function readJobBeforeTests(run, gh, repo, id) {
     if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || !Number.isSafeInteger(id) || id <= 0)
@@ -1214,6 +1219,34 @@ export async function readJobBeforeTests(run, gh, repo, id) {
     return failedBeforeTests({ id, status: String(job["status"]), conclusion: textOr(job["conclusion"]),
         steps: steps.map(one => ({ number: Number(one["number"]), name: String(one["name"]), status: String(one["status"]), conclusion: textOr(one["conclusion"]) })) });
 }
+/**
+ * GitHub's REST API as GitHub's nightly reads it (nightly-github.ts): GET only, github.com only, a repository path, the
+ * plane's own gh with the allowlisted environment, each call bounded by its caller's deadline. A background read rides
+ * out a short network failure (release-net.ts, within that call's own share of the deadline); a boundary's read is
+ * plain exec. Never an answer that isn't GitHub's whole JSON.
+ */
+export function githubReads(run, gh, options = {}) {
+    return async (path, timeoutMs) => {
+        if (!/^repos\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_./?&=%-]+$/.test(path) || timeoutMs <= 0)
+            return { ok: false, why: "not a read this makes" };
+        const exec = options.retry === true ? retryingExec(run, { say: () => { }, sleep, budgetMs: timeoutMs }) : run;
+        let result;
+        try {
+            result = await exec(gh, ["api", "--hostname", "github.com", "--method", "GET", path], { cwd: "/", env: ciEnv(), timeoutMs });
+        }
+        catch (error) {
+            return { ok: false, why: String(error?.message ?? error).slice(0, 200) };
+        }
+        if (result.code !== 0)
+            return { ok: false, why: result.code === 124 ? "GitHub didn't answer in time" : result.code === 127 ? "gh isn't installed" : (result.stderr || result.stdout).trim().split("\n").slice(-1)[0].slice(0, 200) || `gh exited ${result.code}` };
+        try {
+            return { ok: true, body: JSON.parse(result.stdout) };
+        }
+        catch {
+            return { ok: false, why: "GitHub's answer couldn't be read" };
+        }
+    };
+}
 /** GitHub lists check runs from at most the latest 1000 check suites of a commit: the history is whole only below that. */
 export const CHECK_SUITE_CEILING = 1000;
 export async function readSuitesComplete(run, gh, repo, sha) {
@@ -1290,7 +1323,7 @@ export async function readMainProtection(run, gh, repo, branch = "main") {
         else {
             const lacking = PROTECTION_MINIMUM_CHECKS.filter(name => !checks.includes(name));
             if (lacking.length > 0)
-                own.push(`${where}: required checks lack ${lacking.join(", ")}`);
+                own.push(`${where}: required checks lack ${lacking.join(", ")} (add ${lacking.length === 1 ? "it" : "them"} to main's required status checks: a release's proof trusts what main required)`);
             const unbound = PROTECTION_MINIMUM_CHECKS.filter(name => checks.includes(name) && !bound.includes(name));
             if (unbound.length > 0)
                 own.push(`${where}: required checks must require GitHub Actions (app 15368) as their source: ${unbound.join(", ")}`);

package/dist/release-auto.d.ts

@@ -19,7 +19,7 @@ export type ObservedCheckRun = {
     suite?: number | null;
     head?: string | null;
     workflow?: number | null;
-    /** The workflow's file (GitHub's workflow-run `path`): a required check counts only from ci.yml. */
+    /** The workflow's file (GitHub's workflow-run `path`): a required check counts only from its own (REQUIRED_PR_CHECKS_WORKFLOW). */
     workflowPath?: string | null;
     /** GitHub's job record shows this unsuccessful attempt ended before any workflow step ran (release-adapters.ts). */
     beforeTests?: boolean | null;