toolroll 0.9.93 → 0.9.95

package/dist/dispose.js

@@ -1,4 +1,8 @@
 // Assignment tracking grants no repair authority or attempts.
+import { STORAGE_HOLD_PREFIX } from "./needs-you.js";
+import { blockAfterSignedOut } from "./fallback.js";
+import { authorizeCheckOnly } from "./check-only.js";
+import { proposeNewRoute } from "./route-change.js";
 import { originalTaskBase, focusedTestCommandSupported } from "./observations.js";
 /**
  * The build disposition service (Parity II Phase 2, v4 Q2 / v6 W1): the
@@ -18,6 +22,7 @@ import { bodyHashOf, publicationBody } from "./publish.js";
 import { modeTermsFromJson } from "./modes.js";
 import { evidenceRoot, readVerifiedArtifact, writeEvidenceFile } from "./evidence.js";
 import { queueBuildReview } from "./build-review.js";
+import { followBuiltRun } from "./check-repair.js";
 import { homedir } from "node:os";
 import { nightlyTaskRef, releaseTaskRef } from "./store.js";
 import {} from "./proof.js";
@@ -158,6 +163,8 @@ function disposeBuildOutcomeLocked(context, result) {
             });
             // A stated no-change publishes nothing.
             if (result.noChange !== true && result.committed) {
+                // The approval that built this commit allows one automatic recheck of it, should its verdict go missing.
+                authorizeCheckOnly(store, runId, clock());
                 const grant = store.publicationGrantFor(repo);
                 const headSha = store.getRun(runId)?.headRevision ?? null;
                 if (grant !== null &&
@@ -198,6 +205,7 @@ function disposeBuildOutcomeLocked(context, result) {
             store.resetStrikes(taskRef);
             store.clearQuota(runner, provider, model ?? "");
             maybeRequestAutoReview(store, repo, runId, result.committed, result.noChange === true, clock(), context.evidenceRoot);
+            followBuiltRun(store, repo, context.evidenceRoot ?? evidenceRoot(homedir()), runId, worktreePath, clock());
             return { kind: "built", committed: result.committed, noChange: result.noChange === true };
         }
         store.transact(() => {
@@ -327,11 +335,26 @@ function disposeBuildOutcomeLocked(context, result) {
             sealed: sealed.ok,
         };
     }
+    if (result.reason === "protected-storage") {
+        // The storage check couldn't finish (protected-storage.ts): nothing spent,
+        // no strike. The words are kept on the run, the task holds and tries
+        // again on its own, and a person reads why and which program to allow.
+        if (leaseId !== undefined)
+            release(store, leaseId, clock());
+        if (result.message.trim() !== "")
+            store.recordOutcomeFacts(runId, { handoff: result.message });
+        store.finishRun(runId, { outcome: "refused", reason: "protected-storage", now: clock() });
+        holdForStorage(store, { taskRef, taskId, message: result.message }, clock());
+        return { kind: "skipped", reason: "protected-storage" };
+    }
     // no-claim, not-yours, not-leased, protected-branch, wrong-branch:
     // invariants the dispatcher was supposed to uphold.
     if (leaseId !== undefined)
         release(store, leaseId, clock());
     store.finishRun(runId, { outcome: "refused", reason: result.reason, now: clock() });
+    // A fallback agent not signed in to its plan: the task waits for a person's retry, never loops (fallback.ts).
+    if (result.reason === "auth-mode" && blockAfterSignedOut(store, runId, clock()))
+        return { kind: "skipped", reason: "fallback-signed-out" };
     if (result.reason === "stale-approval") {
         // A deterministic refusal (setup review): the approval no longer
         // matches the routing, and nothing about the next pass changes that.
@@ -347,6 +370,27 @@ function disposeBuildOutcomeLocked(context, result) {
     }
     return { kind: "invariant", reason: result.reason };
 }
+/** How long a task waits after the storage check couldn't finish before it tries again on its own. */
+export const STORAGE_RETRY_MS = 10 * 60_000;
+export { STORAGE_HOLD_PREFIX };
+/**
+ * The storage HOLD: the check couldn't finish, so no launch can be fenced
+ * now. The task waits STORAGE_RETRY_MS and tries again on its own (a person
+ * who allowed access in Privacy & Security needn't do more), and "Try again"
+ * (unhold) lifts it at once. One message per task an hour, with the words.
+ */
+export function holdForStorage(store, args, now) {
+    store.holdOwned({ taskRef: args.taskRef, ownerKind: "backoff", ownerId: `storage:${args.taskRef}`, reason: `${STORAGE_HOLD_PREFIX}${args.message}`, until: new Date(now.getTime() + STORAGE_RETRY_MS) }, now);
+    store.enqueueNotification({
+        source: { taskRef: args.taskRef },
+        dedupeKey: `protected-storage:${args.taskRef}:${now.toISOString().slice(0, 13)}`,
+        kind: "protected-storage",
+        pushClass: "attention",
+        link: `/t/${encodeURIComponent(args.taskId)}`,
+        subject: `${args.taskId}: waiting for macOS permission`,
+        body: `${args.message}\nIt tries again on its own in ${STORAGE_RETRY_MS / 60_000} minutes.`,
+    }, now);
+}
 /**
  * The stale-approval HOLD, shared by the post-build disposition above and
  * the tick's pre-admission refusal (v48 integrity): a pre-routing row
@@ -357,6 +401,8 @@ function disposeBuildOutcomeLocked(context, result) {
  */
 export function holdStaleApproval(store, args, now) {
     const scope = store.getScope(args.taskId);
+    // Toolroll proposes the new exact route itself (route-change.ts): the person's one act is Approve, on one line.
+    const proposed = proposeNewRoute(store, args.taskRef, args.taskId, now);
     store.holdOwned({
         taskRef: args.taskRef,
         ownerKind: "backoff",
@@ -370,8 +416,8 @@ export function holdStaleApproval(store, args, now) {
         kind: "stale-approval",
         pushClass: "attention",
         link: `/t/${encodeURIComponent(args.taskId)}`,
-        subject: `${args.taskId}: its approval no longer matches the build routing — approve it again`,
-        body: `${args.message}\nNothing runs on it until the scope is approved again; the hold lifts with the yes.`,
+        subject: `${args.taskId}: its agents changed — approve it again`,
+        body: `${proposed?.words ?? args.message}\nNothing runs on it until it's approved again.`,
     }, now);
 }
 // ---- the bounded repair loop (v40, evidence-review-v1) --------------------
@@ -538,9 +584,9 @@ export function regateTask(store, taskId, now, approval) {
 export function maybeTriggerRepair(store, repo, evidenceRoot, sourceRunId, verdict, now, cause = "review", automatic = false) {
     if (verdict !== "short" && verdict !== "refuted")
         return { kind: "none" };
-    // Findings go to the lead. Explicit repair/revision actions remain available.
-    // Historical mode signatures remain intact; no automatic follow-up spends.
-    if (automatic)
+    // A review's findings go to the lead, and a person asks for their repair. A failed check is the one automatic road
+    // (check-repair.ts), and only under a mode a person signed for it, checked below.
+    if (automatic && cause !== "verification")
         return { kind: "none" };
     // One attempt per source run, ever (source_run UNIQUE) — checked first so
     // a re-fired trigger is a silent no-op, never a duplicate.
@@ -598,9 +644,9 @@ export function maybeTriggerRepair(store, repo, evidenceRoot, sourceRunId, verdi
     const terms = mode === null ? null : modeTermsFromJson(mode.termsJson);
     let verification;
     if (cause === "verification") {
-        // A signed repair mode is required for this automatic producer. The
-        // existing review/manual road continues to offer unapproved drafts.
-        if (terms?.repairAuto !== true || run.finishedAt === null || !run.headRevision ||
+        // A signed repair mode is required for this automatic producer. A person
+        // asking (check-repair.ts startCheckRepair) gets an unapproved draft instead.
+        if ((automatic && terms?.repairAuto !== true) || run.finishedAt === null || !run.headRevision ||
             (run.outcome !== "built" && run.outcome !== "no-change"))
             return { kind: "none" };
         const owner = store.refForId(run.taskRef);
@@ -633,7 +679,7 @@ export function maybeTriggerRepair(store, repo, evidenceRoot, sourceRunId, verdi
                         subject: unrelated.kind === "gate-timed-out" ? "The project check ran out of time; running it once more" : "A slow test outside this change failed the check; running it once more",
                         body: `${gateFailureSummary(unrelated)} The check runs again once on the same commit ${run.headRevision.slice(0, 7)}, with no agent. If it fails again, a person decides.`,
                         link: `/t/${encodeURIComponent(taskId)}` }, now);
-                    return { kind: "none" };
+                    return { kind: "rerun" };
                 }
             }
             store.enqueueNotification({ source: { run: sourceRunId }, dedupeKey: `repair-unrelated:${sourceRunId}`, kind: "repair-evidence", pushClass: "attention",

package/dist/easy-start.js

@@ -284,9 +284,8 @@ export function defaultEasyStartSeams(options) {
             }
         },
         findRepo: async (dir) => {
-            const { run } = await import("./exec.js");
-            const top = await run("git", ["rev-parse", "--show-toplevel"], { cwd: dir, timeoutMs: 10_000 });
-            return top.code === 0 ? top.stdout.trim() : null;
+            const { checkoutTop } = await import("./teardown-git.js");
+            return checkoutTop(dir);
         },
         enrolled: async (repo) => {
             const { loadRepos } = await import("./repos.js");

package/dist/eval-oracle.js

@@ -19,6 +19,7 @@
  * The build's code never runs in the oracle's own process, and nothing the build wrote (a result file, a verdict) is
  * ever read as one: the verdict travels from the oracle to the runner over the oracle's own pipe.
  */
+import { prepareProtectedStorage } from "./protected-storage.js";
 import { spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { closeSync, constants, lstatSync, mkdirSync, mkdtempSync, openSync, realpathSync, rmSync, writeSync } from "node:fs";
@@ -55,10 +56,12 @@ export function canonical(value) {
 export const fencedGradeRunner = async ({ cwd, stdin, timeoutMs, deny }) => {
     if (!macosFenceAvailable() && !linuxFenceAvailable())
         throw new Error("this machine can't fence the graded program");
+    // The storage check, awaited off this thread (protected-storage.ts); a refusal keeps its words.
+    const storage = await prepareProtectedStorage();
     const egress = await startEgressProxy({ hosts: [] });
     try {
         const network = { mode: "allowlist", proxyPort: egress.port, brokerPorts: [], loopback: "proxy-only", socketRoots: [cwd], token: egress.secret };
-        const launch = fenceFor("check", { databaseFile: null, worktree: cwd, boundary: null, binding: null, runFolders: runFolders(null), poolRoots: [], extra: [...deny],
+        const launch = fenceFor("check", { databaseFile: null, worktree: cwd, boundary: null, binding: null, runFolders: runFolders(null), poolRoots: [], storage, extra: [...deny],
             writes: { writes: { subpaths: [cwd], prefixes: [] }, readOnly: [] }, network });
         const result = await run(process.execPath, ["probe.mjs"], { cwd, stdin, timeoutMs, maxBuffer: ORACLE_OUTPUT_BYTES, processGroup: true, envAllowlist: ["PATH"],
             env: { ...proxyEnv(egress, "proxy-only"), HOME: cwd, TMPDIR: cwd }, fence: launch.fence, fenceGrants: launch.fenceGrants, confinement: "required" });

package/dist/evals.js

@@ -27,6 +27,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { closeSync, constants, lstatSync, mkdirSync, mkdtempSync, openSync, readdirSync, realpathSync, rmSync, writeSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
 import { homedir, hostname } from "node:os";
+import { sameMachineHost } from "./machine-identity.js";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { readVerifiedCommit, verifiedBlobs } from "./commit-extract.js";
@@ -840,7 +841,7 @@ export function recoverEvalCampaigns(store, now, options = {}) {
     const out = [];
     for (const campaign of store.handle.prepare("SELECT id, runner_host, runner_pid, runner_started FROM eval_campaign WHERE state = 'running' ORDER BY admitted_at").all()) {
         const id = String(campaign["id"]);
-        if (String(campaign["runner_host"]) !== host) {
+        if (!sameMachineHost(String(campaign["runner_host"]), host)) {
             out.push({ id, recovered: false, why: `its runner is on ${String(campaign["runner_host"])}` });
             continue;
         }

package/dist/evidence-pair.d.ts

@@ -0,0 +1,53 @@
+import type { Store } from "./store.js";
+export type EvidenceReading = "failing" | "fixed" | "still-failing" | "check-changed" | "out-of-date";
+export type EvidenceSide = {
+    run: number;
+    head: string;
+    status: "passed" | "failed";
+    via: "build" | "follow-up";
+    screenshots: number[];
+};
+export type EvidencePair = {
+    id: number;
+    familyRoot: string;
+    before: EvidenceSide;
+    receiptDigest: string;
+    commandDigest: string | null;
+    savedBy: string;
+    savedAt: string;
+    after: EvidenceSide | null;
+    latestHead: string | null;
+    latestRun: number | null;
+    reading: EvidenceReading;
+};
+export declare function evidencePairsOf(store: Store, root: string, taskId: string, now: Date): EvidencePair[];
+export type SavePair = {
+    ok: true;
+    id: number;
+    existing: boolean;
+} | {
+    ok: false;
+    reason: "unknown" | "not-on-task" | "no-failed-check";
+    message: string;
+};
+/** Save a run's failed check as the before side. Only a sealed failure can be saved: there's nothing else to compare. */
+export declare function saveEvidencePair(store: Store, root: string, input: {
+    taskId: string;
+    runId?: number;
+    by: string;
+}, now: Date): SavePair;
+export type RerunPair = {
+    ok: true;
+    run: number;
+    head: string;
+    request: number;
+    existing: boolean;
+} | {
+    ok: false;
+    message: string;
+};
+/** Ask for the same check on the latest commit. Its level is the one the saved failure ran at. The caller proves the person. */
+export declare function rerunEvidence(store: Store, taskId: string, actor: string, now: Date): RerunPair;
+/** How a pair reads, in one sentence. */
+export declare function evidenceWords(pair: EvidencePair): string;
+export { askFailingFirst, dropFailingFirst, FAILING_FIRST_FILE, failingFirstOf, failingFirstReportSchema, failingFirstWords, saveFailingFirstReport, type FailingFirst } from "./failing-first.js";

package/dist/evidence-pair.js

@@ -0,0 +1,128 @@
+/**
+ * Before-and-after evidence (docs/plans/fleet-follow-through.md, part 4), and a bug fix's optional failing test first.
+ *
+ * The before side is saved from a sealed failed check: its run, commit, receipt digest and command digest. The after
+ * side is never stored. It is read each time from the family's newest result, so a newer commit reads as out of date
+ * without anything having to notice. Rerunning uses the follow-up check road (result-follow-ups.ts): the same approved
+ * command, in a fresh checkout, on the latest commit, with no agent.
+ *
+ * A failing-test-first report is the agent's own words, shown as that. It is not a check Toolroll ran.
+ */
+import { readVerificationView } from "./contracts/verification-view.js";
+import { followUpChecksOf, requestFollowUpChecks } from "./result-follow-ups.js";
+import { readingFleet } from "./fleet-schema.js";
+import { cleanFindingText, familyRootOf, NOT_ON_TASK, runOnTask } from "./findings.js";
+import { runCheckLevel } from "./check-levels.js";
+import { failedVerificationEvidence, verificationEvidence } from "./verification-evidence.js";
+/** The family's builder runs that finished with a commit, newest first. */
+function familyRuns(store, taskId) {
+    const family = store.taskFamilyOf(taskId, null, true);
+    const ids = family === null || family.problem !== null ? [taskId] : family.versions.map(one => one.id);
+    return ids.flatMap(id => {
+        const ref = store.lookupRef(id);
+        return ref === null ? [] : store.runsFor(ref.id).filter(one => one.role === "builder" && one.finishedAt !== null && one.headRevision !== null);
+    }).sort((a, b) => b.id - a.id);
+}
+const screenshotsOf = (store, runId) => store.artifactsFor(runId).filter(one => one.kind === "screenshot").map(one => one.id);
+/** The command a run's sealed receipt ran, and whether it passed. Null when it has no readable receipt. */
+function sealedCheck(store, root, runId) {
+    const gate = verificationEvidence(store, root, runId);
+    if (!gate.ok || gate.bytes === null)
+        return null;
+    const view = readVerificationView(gate.bytes);
+    if (!view.ok)
+        return null;
+    const result = view.value.result;
+    return { digest: view.value.command.digest, passed: result.configured && result.ran === true && result.exitCode === 0 };
+}
+/** The newest result of the family that ran `digest`, by the build's own check or a follow-up check on its commit. */
+function afterSide(store, root, runs, beforeRun, digest, now) {
+    let otherCommand = false;
+    for (const run of runs) {
+        if (run.id < beforeRun)
+            break;
+        const follow = followUpChecksOf(store, run.id, now).filter(one => (one.state === "passed" || one.state === "failed") && one.head === run.headRevision).at(-1);
+        if (follow !== undefined && (digest === null || follow.digest === digest))
+            return { run: run.id, head: follow.head, status: follow.state, via: "follow-up", screenshots: screenshotsOf(store, run.id) };
+        if (follow !== undefined)
+            otherCommand = true;
+        if (run.id === beforeRun)
+            continue;
+        const own = sealedCheck(store, root, run.id);
+        if (own === null)
+            continue;
+        if (digest !== null && own.digest !== digest) {
+            otherCommand = true;
+            continue;
+        }
+        return { run: run.id, head: run.headRevision, status: own.passed ? "passed" : "failed", via: "build", screenshots: screenshotsOf(store, run.id) };
+    }
+    return otherCommand ? "check-changed" : null;
+}
+function pairOf(store, root, row, taskId, now) {
+    const runs = familyRuns(store, taskId);
+    const beforeRun = Number(row["before_run"]);
+    const commandDigest = row["command_digest"] === null ? null : String(row["command_digest"]);
+    const found = afterSide(store, root, runs, beforeRun, commandDigest, now);
+    const latest = runs[0] ?? null;
+    const after = found === "check-changed" ? null : found;
+    const reading = found === "check-changed" ? "check-changed"
+        : after === null ? latest !== null && latest.headRevision !== String(row["before_head"]) ? "out-of-date" : "failing"
+            : after.head !== latest?.headRevision ? "out-of-date"
+                : after.status === "passed" ? "fixed" : "still-failing";
+    return {
+        id: Number(row["id"]), familyRoot: String(row["family_root"]),
+        before: { run: beforeRun, head: String(row["before_head"]), status: "failed", via: "build", screenshots: screenshotsOf(store, beforeRun) },
+        receiptDigest: String(row["receipt_digest"]), commandDigest, savedBy: String(row["saved_by"]), savedAt: String(row["saved_at"]),
+        after, latestHead: latest?.headRevision ?? null, latestRun: latest?.id ?? null, reading,
+    };
+}
+export function evidencePairsOf(store, root, taskId, now) {
+    return readingFleet(() => store.handle.prepare("SELECT * FROM evidence_pair WHERE family_root = ? ORDER BY id DESC").all(familyRootOf(store, taskId)).map(row => pairOf(store, root, row, taskId, now)), []);
+}
+/** Save a run's failed check as the before side. Only a sealed failure can be saved: there's nothing else to compare. */
+export function saveEvidencePair(store, root, input, now) {
+    const ref = store.lookupRef(input.taskId);
+    if (ref === null)
+        return { ok: false, reason: "unknown", message: `no task \`${input.taskId}\`` };
+    // A run named by a caller is checked first, and said plainly: every road (the CLI's --run, the console's form) comes here.
+    if (input.runId !== undefined && !runOnTask(store, input.runId, input.taskId))
+        return { ok: false, reason: "not-on-task", message: NOT_ON_TASK };
+    const runId = input.runId ?? familyRuns(store, input.taskId)[0]?.id;
+    const run = runId === undefined ? null : store.getRun(runId);
+    const root1 = familyRootOf(store, input.taskId);
+    if (run === null || run.headRevision === null)
+        return { ok: false, reason: "no-failed-check", message: `${input.taskId} has no finished attempt to save.` };
+    const failure = failedVerificationEvidence(store, root, run.id);
+    if (failure.kind !== "failed")
+        return { ok: false, reason: "no-failed-check", message: `Attempt #${run.id} has no failed check to save.` };
+    const view = readVerificationView(failure.receipt);
+    const made = store.handle.prepare(`INSERT INTO evidence_pair (family_root, repo, before_run, before_head, receipt_digest, command_digest, saved_by, saved_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT (family_root, before_run) DO NOTHING`).run(root1, ref.repo, run.id, run.headRevision, failure.digest, view.ok ? view.value.command.digest : null, input.by, now.toISOString());
+    if (Number(made.changes) === 1)
+        return { ok: true, id: Number(made.lastInsertRowid), existing: false };
+    const row = store.handle.prepare("SELECT id FROM evidence_pair WHERE family_root = ? AND before_run = ?").get(root1, run.id);
+    return { ok: true, id: Number(row?.["id"]), existing: true };
+}
+/** Ask for the same check on the latest commit. Its level is the one the saved failure ran at. The caller proves the person. */
+export function rerunEvidence(store, taskId, actor, now) {
+    const latest = familyRuns(store, taskId)[0];
+    if (latest === undefined)
+        return { ok: false, message: `${taskId} has no finished attempt to check.` };
+    const level = runCheckLevel(store, latest.id);
+    const asked = requestFollowUpChecks(store, { runId: latest.id, level: (level === "off" || level === null ? "full" : level), actor }, now);
+    return asked.ok ? { ok: true, run: latest.id, head: latest.headRevision, request: asked.request, existing: asked.existing } : { ok: false, message: asked.message };
+}
+const short = (head) => head === null ? "no commit" : head.slice(0, 7);
+/** How a pair reads, in one sentence. */
+export function evidenceWords(pair) {
+    const before = `Failed on ${short(pair.before.head)} (build #${pair.before.run})`;
+    switch (pair.reading) {
+        case "failing": return `${before}. Not checked since.`;
+        case "fixed": return `${before}, passes on ${short(pair.after.head)} (build #${pair.after.run}).`;
+        case "still-failing": return `${before}, still fails on ${short(pair.after.head)} (build #${pair.after.run}).`;
+        case "check-changed": return `${before}. The project's check changed since, so the two can't be compared.`;
+        case "out-of-date": return `${before}. Out of date: the code is now at ${short(pair.latestHead)}${pair.after === null ? "" : `, and the last check ran on ${short(pair.after.head)}`}.`;
+    }
+}
+export { askFailingFirst, dropFailingFirst, FAILING_FIRST_FILE, failingFirstOf, failingFirstReportSchema, failingFirstWords, saveFailingFirstReport } from "./failing-first.js";

package/dist/exhaustion.d.ts

@@ -6,9 +6,11 @@
  * someone signs in, instead of burning attempts. Everything else is the
  * ordinary failure road.
  *
- * `usage-exhausted`, `credits-depleted` and `transient-throttle` are only
- * ever read from older runs' records (they were stamped by a removed
- * feature); this build never produces them.
+ * `usage-exhausted` moves the work to the next agent a person approved
+ * (fallback.ts), so it comes only from a recogniser below, and a recogniser
+ * comes only from a real run (docs/plans/fallback-chains.md). A provider with
+ * none never reads as exhausted. `credits-depleted` and `transient-throttle`
+ * are only ever read from older runs' records.
  */
 export type TerminalClass = "usage-exhausted" | "credits-depleted" | "transient-throttle"
 /** The provider's sign-in or API key no longer works — no retry:
@@ -31,15 +33,26 @@ export type StructuralTerminal = {
     code: string | null;
 };
 /** Classify a finished attempt: a sign-in that no longer works first, for
- * any provider or version; then a structural failure terminal is
+ * any provider or version; then a recognised plan limit, on the exact provider,
+ * auth mode and CLI line it was seen on; then a structural failure terminal is
  * `not-exhausted`, and anything else `unknown`. */
 export declare function classifyTerminal(args: {
     terminal: StructuralTerminal | null;
+    /** The run's own provider, its auth mode, and the version the installed CLI reports to the gateway: never the checkout's word. */
+    run?: {
+        provider: string;
+        authMode: string;
+        version: string | null;
+    };
     /** What a run that failed within seconds, having produced nothing, said
      * on its way out (stderr and unstructured stdout) — read ONLY for the
      * sign-in signal: a CLI that is not logged in often exits before its
      * structured stream begins. */
     earlyExit?: string | null;
 }): TerminalClass;
+/** Whether a terminal reads as a limit for this provider and auth mode, before its CLI version is asked. */
+export declare function terminalMatchesLimit(provider: string, authMode: string, terminal: StructuralTerminal | null): boolean;
+/** Whether Toolroll can recognise this agent running out at all: the words every surface shows beside an entry. */
+export declare function limitRecognised(provider: string, authMode: string): boolean;
 /** Whether a provider's own words say its sign-in or key no longer works. */
 export declare function isAuthFailure(text: string): boolean;

package/dist/exhaustion.js

@@ -6,12 +6,15 @@
  * someone signs in, instead of burning attempts. Everything else is the
  * ordinary failure road.
  *
- * `usage-exhausted`, `credits-depleted` and `transient-throttle` are only
- * ever read from older runs' records (they were stamped by a removed
- * feature); this build never produces them.
+ * `usage-exhausted` moves the work to the next agent a person approved
+ * (fallback.ts), so it comes only from a recogniser below, and a recogniser
+ * comes only from a real run (docs/plans/fallback-chains.md). A provider with
+ * none never reads as exhausted. `credits-depleted` and `transient-throttle`
+ * are only ever read from older runs' records.
  */
 /** Classify a finished attempt: a sign-in that no longer works first, for
- * any provider or version; then a structural failure terminal is
+ * any provider or version; then a recognised plan limit, on the exact provider,
+ * auth mode and CLI line it was seen on; then a structural failure terminal is
  * `not-exhausted`, and anything else `unknown`. */
 export function classifyTerminal(args) {
     const { terminal } = args;
@@ -21,8 +24,45 @@ export function classifyTerminal(args) {
         return "auth-expired";
     if (terminal === null || terminal.failed !== true)
         return "unknown";
+    if (args.run !== undefined && terminal.text !== null && planLimitReached(args.run, terminal.text))
+        return "usage-exhausted";
     return "not-exhausted";
 }
+const RECOGNISERS = Object.freeze([
+    {
+        provider: "claude", authMode: "subscription", from: [2, 1, 290], below: [2, 2, 0],
+        terminal: /^You've hit your (?:session|weekly|Opus|Sonnet) limit · resets [^\n]{1,64}$/,
+    },
+]);
+function versionOf(version) {
+    const parts = version === null ? null : /^(\d{1,6})\.(\d{1,6})\.(\d{1,6})(?:\s|$)/.exec(version);
+    return parts === null ? null : [Number(parts[1]), Number(parts[2]), Number(parts[3])];
+}
+function before(a, b) {
+    for (let at = 0; at < 3; at++)
+        if (a[at] !== b[at])
+            return a[at] < b[at];
+    return false;
+}
+function planLimitReached(run, text) {
+    const version = versionOf(run.version);
+    if (version === null)
+        return false;
+    const words = text.trim();
+    return RECOGNISERS.some(one => one.provider === run.provider && one.authMode === run.authMode
+        && !before(version, one.from) && before(version, one.below) && one.terminal.test(words));
+}
+/** Whether a terminal reads as a limit for this provider and auth mode, before its CLI version is asked. */
+export function terminalMatchesLimit(provider, authMode, terminal) {
+    if (terminal === null || terminal.failed !== true || terminal.text === null)
+        return false;
+    const words = terminal.text.trim();
+    return RECOGNISERS.some(one => one.provider === provider && one.authMode === authMode && one.terminal.test(words));
+}
+/** Whether Toolroll can recognise this agent running out at all: the words every surface shows beside an entry. */
+export function limitRecognised(provider, authMode) {
+    return RECOGNISERS.some(one => one.provider === provider && one.authMode === authMode);
+}
 /**
  * The sign-in signals, provider-neutral: Claude's expired or unrefreshable
  * OAuth session and its "Please run /login", an API key the provider calls

package/dist/export.js

@@ -57,7 +57,7 @@ export function categoryOf(table) {
         [/^(flow|workflow_)/, "flows"],
         [/^(chat_|lead_|team_|notification|push_)/, "chats"],
         [/^(approver|credential$|invite|sso_identity|coordinator_|oauth_)/, "people"],
-        [/^(run|artifact|claim|worktree$|execution_slot|criterion_review|diff_comment|proof_|review_request|repair_chain|incident|publication$|merge_|side_spend|knowledge_snapshot|learning_snapshot|skill_snapshot)/, "runs"],
+        [/^(run|artifact|claim|worktree$|execution_slot|criterion_review|diff_comment|proof_|review_request|repair_chain|check_repair|evidence_pair|failing_first|finding|provider_capture|incident|publication$|merge_|side_spend|knowledge_snapshot|learning_snapshot|skill_snapshot)/, "runs"],
         [/^(task|hold$|plan_|scope_|tool_seal|decision|external_|skill_test)/, "tasks"],
         [/^(project|approval_policy|capability|verify_command|worktree_setup|backend_grant|intake_grant|publication_grant|operating_mode|knowledge_|learning_|memory_|skill_)/, "projects"],
         [/(_config|_default|_defaults)$|^(budget|model_|provider_|installation_fact|runtime_check|monitoring_status|integration_check|quota|mode_rail|schema_version)/, "settings"],

package/dist/failing-first.d.ts

@@ -0,0 +1,31 @@
+/** Failing test first (docs/plans/fleet-follow-through.md), on its own so the steering mailbox can read it. Evidence pairs
+ * reach the builder through follow-up checks, and the mailbox loads with the provider table: importing them from there
+ * is a cycle that fails at load in every built command. */
+import { z } from "zod";
+import type { Store } from "./store.js";
+export declare const FAILING_FIRST_OUTPUT_LIMIT = 2000;
+/** Where the agent writes its report, in the attempt's own mailbox folder. */
+export declare const FAILING_FIRST_FILE = "failing-first.json";
+export declare const failingFirstReportSchema: z.ZodObject<{
+    key: z.ZodString;
+    test: z.ZodString;
+    output: z.ZodString;
+}, z.core.$strict>;
+export type FailingFirst = {
+    askedBy: string;
+    askedAt: string;
+    reportRun: number | null;
+    test: string | null;
+    output: string | null;
+    reportedAt: string | null;
+};
+export declare function failingFirstOf(store: Store, taskId: string): FailingFirst | null;
+export declare function askFailingFirst(store: Store, taskId: string, by: string, now: Date): boolean;
+export declare function dropFailingFirst(store: Store, taskId: string): void;
+/** The agent's report, as data. Only a task that asked takes one. */
+export declare function saveFailingFirstReport(store: Store, taskRef: number, runId: number, report: {
+    test: string;
+    output: string;
+}, now: Date): boolean;
+/** How the step stands, or null when this task didn't ask for it. */
+export declare function failingFirstWords(step: FailingFirst | null): string | null;

package/dist/failing-first.js

@@ -0,0 +1,44 @@
+/** Failing test first (docs/plans/fleet-follow-through.md), on its own so the steering mailbox can read it. Evidence pairs
+ * reach the builder through follow-up checks, and the mailbox loads with the provider table: importing them from there
+ * is a cycle that fails at load in every built command. */
+import { z } from "zod";
+import { readingFleet } from "./fleet-schema.js";
+import { cleanFindingText, familyRootOf } from "./findings.js";
+export const FAILING_FIRST_OUTPUT_LIMIT = 2_000;
+/** Where the agent writes its report, in the attempt's own mailbox folder. */
+export const FAILING_FIRST_FILE = "failing-first.json";
+export const failingFirstReportSchema = z.strictObject({ key: z.string().min(1).max(64), test: z.string().min(1).max(300), output: z.string().min(1).max(FAILING_FIRST_OUTPUT_LIMIT) });
+export function failingFirstOf(store, taskId) {
+    return readingFleet(() => {
+        const row = store.handle.prepare("SELECT * FROM failing_first WHERE family_root = ?").get(familyRootOf(store, taskId));
+        if (row === undefined)
+            return null;
+        const text = (key) => row[key] === null ? null : String(row[key]);
+        return { askedBy: String(row["asked_by"]), askedAt: String(row["asked_at"]), reportRun: row["report_run"] === null ? null : Number(row["report_run"]), test: text("test"), output: text("output"), reportedAt: text("reported_at") };
+    }, null);
+}
+export function askFailingFirst(store, taskId, by, now) {
+    const ref = store.lookupRef(taskId);
+    if (ref === null)
+        return false;
+    store.handle.prepare("INSERT INTO failing_first (family_root, repo, asked_by, asked_at) VALUES (?, ?, ?, ?) ON CONFLICT (family_root) DO NOTHING").run(familyRootOf(store, taskId), ref.repo, by, now.toISOString());
+    return true;
+}
+export function dropFailingFirst(store, taskId) {
+    store.handle.prepare("DELETE FROM failing_first WHERE family_root = ?").run(familyRootOf(store, taskId));
+}
+/** The agent's report, as data. Only a task that asked takes one. */
+export function saveFailingFirstReport(store, taskRef, runId, report, now) {
+    const taskId = store.refById(taskRef)?.externalId;
+    if (taskId === undefined)
+        return false;
+    const saved = store.handle.prepare("UPDATE failing_first SET report_run = ?, test = ?, output = ?, reported_at = ? WHERE family_root = ?")
+        .run(runId, cleanFindingText(report.test, 300), cleanFindingText(report.output, FAILING_FIRST_OUTPUT_LIMIT), now.toISOString(), familyRootOf(store, taskId));
+    return Number(saved.changes) === 1;
+}
+/** How the step stands, or null when this task didn't ask for it. */
+export function failingFirstWords(step) {
+    if (step === null)
+        return null;
+    return step.reportedAt === null ? "Failing test first was asked for. No report yet." : `The agent reports it wrote ${step.test ?? "a test"} first and saw it fail. Toolroll didn't run this itself.`;
+}

package/dist/fallback-schema.d.ts

@@ -0,0 +1,8 @@
+/**
+ * v156: fallback chains (docs/plans/fallback-chains.md). New tables only, so a saved row reads as it did. Their names
+ * differ from the tables v115 dropped: nothing old comes back under an old name. Kept beside nothing else so the update
+ * road can read the list without loading the store.
+ */
+export declare const V156_SCHEMA = "\nCREATE TABLE IF NOT EXISTS fallback_setting (\n  repo            TEXT PRIMARY KEY,\n  entries_json    TEXT NOT NULL,\n  paid_granted_by TEXT,\n  paid_granted_at TEXT,\n  updated_by      TEXT NOT NULL,\n  updated_at      TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS fallback_walk (\n  id            INTEGER PRIMARY KEY AUTOINCREMENT,\n  task_ref      INTEGER NOT NULL,\n  scope_digest  TEXT NOT NULL,\n  chain_digest  TEXT NOT NULL,\n  cursor        INTEGER NOT NULL DEFAULT 0,\n  tail_run      INTEGER NOT NULL,\n  state         TEXT NOT NULL DEFAULT 'open' CHECK (state IN ('open','closed')),\n  closed_reason TEXT,\n  opened_at     TEXT NOT NULL,\n  closed_at     TEXT\n);\nCREATE UNIQUE INDEX IF NOT EXISTS fallback_walk_one_open ON fallback_walk (task_ref) WHERE state = 'open';\nCREATE TABLE IF NOT EXISTS fallback_move (\n  walk           INTEGER NOT NULL REFERENCES fallback_walk(id),\n  to_index       INTEGER NOT NULL,\n  from_run       INTEGER NOT NULL UNIQUE,\n  to_run         INTEGER UNIQUE,\n  terminal_class TEXT NOT NULL,\n  paid           INTEGER NOT NULL DEFAULT 0,\n  moved_at       TEXT NOT NULL,\n  PRIMARY KEY (walk, to_index)\n);\n";
+export declare const V156_TABLES: readonly ["fallback_setting", "fallback_walk", "fallback_move"];
+export declare const V156_STEPS: readonly ["fallback-tables"];

package/dist/fallback-schema.js

@@ -0,0 +1,40 @@
+/**
+ * v156: fallback chains (docs/plans/fallback-chains.md). New tables only, so a saved row reads as it did. Their names
+ * differ from the tables v115 dropped: nothing old comes back under an old name. Kept beside nothing else so the update
+ * road can read the list without loading the store.
+ */
+export const V156_SCHEMA = `
+CREATE TABLE IF NOT EXISTS fallback_setting (
+  repo            TEXT PRIMARY KEY,
+  entries_json    TEXT NOT NULL,
+  paid_granted_by TEXT,
+  paid_granted_at TEXT,
+  updated_by      TEXT NOT NULL,
+  updated_at      TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS fallback_walk (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  task_ref      INTEGER NOT NULL,
+  scope_digest  TEXT NOT NULL,
+  chain_digest  TEXT NOT NULL,
+  cursor        INTEGER NOT NULL DEFAULT 0,
+  tail_run      INTEGER NOT NULL,
+  state         TEXT NOT NULL DEFAULT 'open' CHECK (state IN ('open','closed')),
+  closed_reason TEXT,
+  opened_at     TEXT NOT NULL,
+  closed_at     TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS fallback_walk_one_open ON fallback_walk (task_ref) WHERE state = 'open';
+CREATE TABLE IF NOT EXISTS fallback_move (
+  walk           INTEGER NOT NULL REFERENCES fallback_walk(id),
+  to_index       INTEGER NOT NULL,
+  from_run       INTEGER NOT NULL UNIQUE,
+  to_run         INTEGER UNIQUE,
+  terminal_class TEXT NOT NULL,
+  paid           INTEGER NOT NULL DEFAULT 0,
+  moved_at       TEXT NOT NULL,
+  PRIMARY KEY (walk, to_index)
+);
+`;
+export const V156_TABLES = Object.freeze(["fallback_setting", "fallback_walk", "fallback_move"]);
+export const V156_STEPS = Object.freeze(["fallback-tables"]);