toolroll 0.9.94 → 0.9.95

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"]);

package/dist/fallback.d.ts

@@ -0,0 +1,138 @@
+import { type ChainEntry, type ExecutionProfile, type Scope } from "./scope.js";
+import type { Store } from "./store.js";
+export declare const MAX_FALLBACK_ENTRIES = 3;
+/** What a project's setting names: the rest of each entry's terms resolve at filing and seal with the approval. */
+export type FallbackEntry = {
+    provider: string;
+    model: string;
+    authMode: "subscription" | "api-key";
+};
+export type FallbackSetting = {
+    repo: string;
+    entries: FallbackEntry[];
+    paidGrant: {
+        by: string;
+        at: string;
+    } | null;
+    updatedBy: string;
+    updatedAt: string;
+};
+export declare function entryDigestOf(entry: ChainEntry): string;
+/** An entry in the words every surface uses. */
+export declare function entryWords(entry: FallbackEntry): string;
+/** Whether Toolroll can see this entry run out, in plain words: an entry it can't recognise ends the chain there. */
+export declare function entryMovesOnWords(entry: Pick<FallbackEntry, "provider" | "authMode">): string;
+/** Whether this entry spends money, by what it was pinned to: an API key, or a provider that only bills by use. A plan
+ * entry is never paid: where its login can't be proved to be that plan, it doesn't run (invoke.ts), it is never
+ * reinterpreted as a paid agent. */
+export declare function entryPaid(_store: Store, entry: Pick<FallbackEntry, "provider" | "authMode">): boolean;
+/** Parse `provider:model:plan|api-key`. The model is everything between the first and last colon, so ":free" ids work. */
+export declare function parseEntry(text: string): FallbackEntry | string;
+export declare function entriesProblem(entries: readonly FallbackEntry[]): string | null;
+export declare function fallbackSettingOf(store: Store, repo: string): FallbackSetting | null;
+export declare function setFallbackChain(store: Store, repo: string, entries: readonly FallbackEntry[], by: string, now: Date): {
+    ok: true;
+} | {
+    ok: false;
+    problem: string;
+};
+export declare function clearFallbackChain(store: Store, repo: string, by: string, now: Date): {
+    ok: true;
+} | {
+    ok: false;
+    problem: string;
+};
+/** The paid grant: the one explicit yes a paid entry spends under, read again at every money moment. */
+export declare function setPaidGrant(store: Store, repo: string, allowed: boolean, by: string, now: Date): {
+    ok: true;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * The chain a new scope files with: its base agent, then the project's entries. Null means no chain. A setting that can't
+ * resolve is a stated problem: the scope files unresolved in those words, and nothing runs on half a chain.
+ */
+export declare function chainForFiling(store: Store, repo: string | null, base: ExecutionProfile, baseAuth: string, lower: (profile: ExecutionProfile) => ExecutionProfile): {
+    ok: true;
+    chain: ChainEntry[] | null;
+} | {
+    ok: false;
+    problem: string;
+};
+export declare const chainJsonOf: (chain: readonly ChainEntry[]) => string;
+/**
+ * Why this chain can't seal on this yes, or null. A paid entry takes a person's own yes: the ceremony or their chat tap,
+ * never a mode, grant, schedule, lead or automatic seal, and no machine's credential. A chat tap is bound to the scope's
+ * digest, which covers the chain, and the card shows the chain in full (chainTermsLines).
+ */
+export declare function chainSealProblem(store: Store, scope: Scope, basis: {
+    kind: string;
+} | undefined): string | null;
+/** Each tick, before any dispatch: settle every open walk. */
+export declare function reconcileWalks(store: Store, now: Date): void;
+export type FallbackDispatch = {
+    index: number;
+    entry: ChainEntry;
+    paid: boolean;
+} | {
+    problem: string;
+} | null;
+/**
+ * Which entry the next build of this task runs as, read by the tick before anything is claimed: null is the ordinary
+ * road (no chain, or the base agent). A move whose paid grant has since gone closes here and says so: nothing runs on it.
+ */
+export declare function dispatchEntryOf(store: Store, taskRef: number, taskId: string, now: Date): FallbackDispatch;
+/** A route stamp for a fallback entry, checked against the sealed chain: the admission's proof of `fallback` provenance. */
+export declare function fallbackStampProblem(store: Store, taskRef: number, taskId: string, stamp: {
+    routeDigest: string;
+    phase: string;
+    provider: string;
+    model: string | null;
+}, parentRun: number | null): string | null;
+/**
+ * Inside the run's admission transaction: bind it to its walk, or say why not (the caller rolls the row back). A base run
+ * opens a walk; a pending entry consumes its edge exactly once, with the paid grant re-read; a parked tail hands custody to
+ * its resumption; a repair inherits its parent's binding verbatim. Nothing else opens on a chain approval.
+ */
+export declare function bindRunToWalk(store: Store, runId: number, now: Date): string | null;
+/** The pinned entry a bound run spends as, or null for a run with no binding. */
+export declare function pinnedEntryOf(store: Store, runId: number): {
+    index: number;
+    entry: ChainEntry;
+} | {
+    problem: string;
+} | null;
+/**
+ * THE LAST LOOK AT THE SPAWN: one read of every authority a chain run spends under. A builder or repair on a chain
+ * approval with no binding spends nothing; a bound run must hold the walk's current place, under the live approval, as its
+ * exact entry; a paid entry must still hold the live grant. Null means go.
+ */
+export declare function chainCustodyProblem(store: Store, runId: number): string | null;
+/** Whether this finished attempt is about to move on: it holds a walk's place and the gateway classed it exhausted. */
+export declare function ranOutOnChain(store: Store, runId: number): boolean;
+/** The gateway refused this bound run: its plan login isn't proved. The walk closes, a person is told, no strike. */
+export declare function closeWalkSignedOut(store: Store, runId: number, now: Date): void;
+/**
+ * After the dispatch road finished a refused run: when it was a fallback agent refused for not being signed in to its
+ * plan, the task stops and waits for a person (task state failed, the run's reason saying why), until they retry it.
+ * Nothing expires it. True when it did.
+ */
+export declare function blockAfterSignedOut(store: Store, runId: number, now: Date): boolean;
+export type MoveResult = {
+    moved: true;
+    to: FallbackEntry;
+    paid: boolean;
+} | null;
+/**
+ * THE MOVE, inside sealFailure's transaction (the claim is already released, the run still open): only the walk's own tail,
+ * started and classed exhausted by the gateway, on the exact entry it was pinned to. Null means the ordinary failure road
+ * runs, with the walk closed in words when it can't go on. The caller finishes the run either way; a walk that moved leaves
+ * no strike.
+ */
+export declare function moveOnIfExhausted(store: Store, runId: number, taskId: string, now: Date): MoveResult;
+/**
+ * What the next agent is told about the move, for its brief. The one place the handover note plugs in: once it merges, a
+ * fallback run gets that note here. Null for any run that isn't continuing another agent's work.
+ */
+export declare function fallbackBriefFor(store: Store, runId: number): string | null;