toolroll 0.9.93 → 0.9.95

package/dist/route-change.js

@@ -0,0 +1,89 @@
+/**
+ * One step to approve a new route (docs/plans/plain-toolroll.md P2.5). There are no route classes: an approval stays
+ * bound to its exact route, and dispatch runs on no other bytes. When the route a task would dispatch on differs from the
+ * sealed one, Toolroll files the same words again on today's route (nothing is sealed) and keeps one "what changed" line,
+ * bound to that route's digest, for the one Approve. A legacy row with no route gets the same.
+ *
+ * approve() reads routeChangeProblem: a line that doesn't describe the route being approved refuses "changed".
+ */
+import { providerName } from "./provider-auth.js";
+import { legOf, routeDigestOf, routeFromJson } from "./phase-routing.js";
+import { deployGateScope, releaseCheckScope } from "./scope.js";
+import { BUILT_IN } from "./store.js";
+const ROLE = { plan: "planner", build: "builder", repair: "repair agent", review: "reviewer" };
+const named = (one) => `${providerName(one.provider)} ${one.model ?? "(its default model)"}`;
+const billing = (mode) => mode === "api-key" ? "API key" : mode === "subscription" ? "subscription" : null;
+/** The sentence for what changed between the seal and the proposal. */
+export function routeChangeWords(sealed, next) {
+    const changes = [];
+    for (const phase of ["build", "plan", "repair", "review"]) {
+        const now = legOf(next.route, phase);
+        const was = sealed.route !== null ? legOf(sealed.route, phase) : phase === "build" && sealed.profile != null ? { provider: sealed.profile.provider, model: "model" in sealed.profile ? (sealed.profile.model ?? null) : null } : null;
+        if (was === null) {
+            if (phase === "build")
+                changes.push(`The builder is ${named(now)}`);
+            continue;
+        }
+        if (was.provider === now.provider && was.model === now.model)
+            continue;
+        const line = `changes from ${named(was)} to ${named(now)}`;
+        // The repair agent is the builder's usual twin: one change is one sentence.
+        if (changes.some(one => one.endsWith(line)))
+            continue;
+        changes.push(`${changes.length === 0 ? "The" : "the"} ${ROLE[phase]} ${line}`);
+    }
+    const from = billing(sealed.authMode), to = billing(next.authMode);
+    const paid = from !== null && to !== null && from !== to ? ` (${from} → ${to})` : "";
+    if (changes.length === 0)
+        return "The agents' settings changed since you approved this. Approve to continue.";
+    return `${changes.join("; ")}${paid}. Approve to continue.`;
+}
+/** File the same words on today's route, and keep the line. Null: nothing to propose (a release, nothing changed, or no
+ * route Toolroll can name), and the task stays as it is. It seals nothing. */
+export function proposeNewRoute(store, taskRef, taskId, now) {
+    return store.transact(() => {
+        const before = store.getScope(taskId);
+        if (before === null || deployGateScope(before) || releaseCheckScope(before))
+            return null;
+        const sealedRoute = routeFromJson(before.approvedRouteJson ?? null);
+        const refiled = store.refileScope(taskId, now);
+        if (refiled === null || refiled.profileState === "unresolved")
+            return null;
+        const route = routeFromJson(refiled.proposedRouteJson ?? null);
+        if (route === null)
+            return null;
+        if (refiled.approvedDigest === refiled.digest)
+            return null;
+        // How the last attempt billed, against how the new builder would: said when they differ.
+        const lastBilled = store.runsFor(taskRef).find(one => one.role === "builder")?.authMode ?? null;
+        const billed = store.agentsFor([legOf(route, "build").provider])[0]?.billing ?? null;
+        const words = routeChangeWords({ route: sealedRoute, profile: before.approvedProfile ?? null, authMode: lastBilled }, { route, authMode: billed });
+        store.handle.prepare(`INSERT INTO route_change (task_ref, scope_digest, to_route_digest, words, created_at) VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT (task_ref) DO UPDATE SET scope_digest = excluded.scope_digest, to_route_digest = excluded.to_route_digest, words = excluded.words, created_at = excluded.created_at`)
+            .run(taskRef, refiled.digest, routeDigestOf(route), words, now.toISOString());
+        return { words };
+    });
+}
+/** The line for this task's waiting plan, or null. Only while it describes exactly the plan up for approval. */
+export function routeChangeOf(store, taskId) {
+    const ref = store.lookupRef(taskId);
+    if (ref === null)
+        return null;
+    const row = store.handle.prepare("SELECT scope_digest, to_route_digest, words FROM route_change WHERE task_ref = ?").get(ref.id);
+    const scope = store.getScope(taskId);
+    if (row === undefined || scope === null || scope.digest !== row["scope_digest"] || scope.approvedDigest === scope.digest)
+        return null;
+    const route = routeFromJson(scope.proposedRouteJson ?? null);
+    return route !== null && routeDigestOf(route) === row["to_route_digest"] ? String(row["words"]) : null;
+}
+/** Each sweep: an unapproved row from before routing gets its route, and the same one Approve. A standing old approval
+ * is left alone (the stale check reaches it if its route ever differs). */
+export function routeLegacyPlans(store, now) {
+    const rows = store.handle.prepare(`SELECT r.id AS ref, r.external_id AS task FROM task_scope s JOIN task_ref r ON r.external_id = s.task_id AND r.backend = ? JOIN task t ON t.id = r.external_id
+    WHERE s.route_era IS NULL AND t.state = 'queued' AND (s.approved_digest IS NULL OR s.approved_digest <> s.digest) LIMIT 20`).all(BUILT_IN);
+    let routed = 0;
+    for (const row of rows)
+        if (proposeNewRoute(store, Number(row["ref"]), String(row["task"]), now) !== null)
+            routed++;
+    return routed;
+}

package/dist/route-hooks.js

@@ -80,8 +80,9 @@ const VERB = String.raw `(?:INSERT(?:\s+OR\s+\w+)?\s+INTO|REPLACE\s+INTO|UPDATE(
 const writes = (tables) => new RegExp(String.raw `\b${VERB}\s+(?:main\s*\.\s*)?["\`\[]?(?:${tables.join("|")})["\`\]]?(?![\w])`, "i");
 const ROUTING_WRITE = writes([...ROUTING_TABLES, "route_rule_one_winner"]);
 const MODELS_WRITE = writes(MODELS_TABLES);
-/** The two columns only route-store.ts writes: any write statement that names one. */
-const COLUMN_WRITE = /\b(?:INSERT|REPLACE|UPDATE)\b[^]*\b(?:exec_class|revision_origin)\b/i;
+/** The two columns only route-store.ts writes: any write statement that names one. A lesson note keeps its own copy of
+ * how a revision was asked for: that one INSERT into its own table is not this column, and only it is left out. */
+const COLUMN_WRITE = /\b(?:INSERT(?!\s+INTO\s+lesson_note\b)|REPLACE|UPDATE)\b[^]*\b(?:exec_class|revision_origin)\b/i;
 /** Each string or template text in the file that writes a protected row, with the function it's in ("" at the top
  * level): `Class#method`, or the top-level function. */
 export function protectedWrites(file, source) {

package/dist/route-results.d.ts

@@ -1,5 +1,5 @@
 import { INELIGIBLE_REASONS, type RecordReason, type RecordState, type ResultRecordView, type Selection } from "./contracts/route-results.js";
-import { type Store } from "./store.js";
+import { type Run, type Store } from "./store.js";
 export { cohortOf, EXEC_CLASS_OF_REASON, execClassOf, type CohortInput, type CohortRow } from "./route-store.js";
 /** How long an accepted result waits before it counts, and how long a result may wait for an answer. */
 export declare const MATURE_AFTER_MS: number;
@@ -39,6 +39,11 @@ export type RecordValue = {
     /** The family is quiet, or past ACCUMULATE_FOR_MS: with a final verdict, the record closes. */
     accumulationEnded: boolean;
 };
+/** Whether the first built run among `runs` passed its own check; null when none is recorded. The code map's report reads
+ * this too, so the two never disagree on what a first check is. */
+export declare function firstCheckPassedOf(store: Store, runs: readonly Pick<Run, "id" | "outcome">[]): boolean | null;
+/** How many of these task versions are a person's revision. */
+export declare function personRevisionsOf(store: Store, refs: readonly number[]): number;
 /**
  * A task family's record, evaluated now from its rows (null: no code-writing run, or a family whose lineage can't be
  * proved). The order is the plan's: what can't be attributed to one model and one cohort first, then a live attempt

package/dist/route-results.js

@@ -54,6 +54,17 @@ function classOfRun(run, kept) {
     return "model";
 }
 const FAILED_OUTCOMES = new Set(["failed", "interrupted"]);
+/** Whether the first built run among `runs` passed its own check; null when none is recorded. The code map's report reads
+ * this too, so the two never disagree on what a first check is. */
+export function firstCheckPassedOf(store, runs) {
+    const first = runs.find(run => run.outcome === "built");
+    const status = first === undefined ? null : store.runCheckFor(first.id)?.status ?? null;
+    return status === "passed" ? true : status === "failed" ? false : null;
+}
+/** How many of these task versions are a person's revision. */
+export function personRevisionsOf(store, refs) {
+    return Number(store.handle.prepare("SELECT COUNT(*) AS n FROM task_ref WHERE id IN (SELECT value FROM json_each(?)) AND revision_origin = 'person'").get(JSON.stringify(refs))?.["n"] ?? 0);
+}
 /**
  * A task family's record, evaluated now from its rows (null: no code-writing run, or a family whose lineage can't be
  * proved). The order is the plan's: what can't be attributed to one model and one cohort first, then a live attempt
@@ -106,10 +117,8 @@ export function evaluateFamily(store, rootTaskId, evidenceRoot, now) {
         else
             agentTurns += run.agentTurns;
     }
-    const firstBuilt = runs.find(run => run.outcome === "built");
-    const firstCheck = firstBuilt === undefined ? null : store.runCheckFor(firstBuilt.id)?.status ?? null;
-    const personRevisions = store.handle.prepare("SELECT COUNT(*) AS n FROM task_ref WHERE id IN (SELECT value FROM json_each(?)) AND revision_origin = 'person'")
-        .get(JSON.stringify(family.versions.filter(one => one.id !== family.root.id).map(one => one.refId)))?.["n"];
+    const firstCheck = firstCheckPassedOf(store, runs);
+    const personRevisions = personRevisionsOf(store, family.versions.filter(one => one.id !== family.root.id).map(one => one.refId));
     const quiet = family.versions.every(one => one.state === "done" || one.state === "cancelled" || one.state === "failed") && runs.every(run => run.outcome !== null);
     let modelFailures = 0, infraFailures = 0;
     for (const run of runs) {
@@ -129,7 +138,7 @@ export function evaluateFamily(store, rootTaskId, evidenceRoot, now) {
         firstStartedAt: first?.startedAt ?? runs[0].startedAt, acceptedAt: null, decidedAt: null, modelFailures, infraFailures,
         apiMicrousd, subscriptionRuns, subscriptionTokens, unknownRuns, remediationRuns,
         selections: attributed.map(one => one.selection).filter((one) => one !== null), settled: false,
-        personRevisions: Number(personRevisions ?? 0), firstCheckPassed: firstCheck === "passed" ? true : firstCheck === "failed" ? false : null,
+        personRevisions, firstCheckPassed: firstCheck,
         agentTurns, turnsUnknownRuns,
         accumulationEnded: quiet || now.getTime() >= Date.parse(first?.startedAt ?? runs[0].startedAt) + ACCUMULATE_FOR_MS,
     };

package/dist/run-closeout.d.ts

@@ -1,4 +1,4 @@
-import type { Store, WorktreeRow } from "./store.js";
+import { type Store, type WorktreeRow } from "./store.js";
 /** How long a process has after SIGTERM before SIGKILL. */
 export declare const STOP_GRACE_MS = 10000;
 export type ProcessRow = {

package/dist/run-closeout.js

@@ -15,9 +15,9 @@
  */
 import { execFileSync } from "node:child_process";
 import { existsSync, readdirSync, readlinkSync, realpathSync } from "node:fs";
-import { hostname } from "node:os";
 import { basename, sep } from "node:path";
 import { ownedProcessCount, runOwnerTag } from "./exec.js";
+import { localWitnessSql } from "./store.js";
 import { sleep as defaultSleep } from "./sleep.js";
 /** How long a process has after SIGTERM before SIGKILL. */
 export const STOP_GRACE_MS = 10_000;
@@ -138,10 +138,11 @@ export async function closeOutRuns(store, clock, options = {}) {
     if (process.platform === "win32")
         return [];
     const db = store.handle;
+    const local = localWitnessSql(db, "p"), mine = localWitnessSql(db);
     const runs = db.prepare(`SELECT DISTINCT p.run AS run FROM run_process p JOIN run r ON r.id = p.run JOIN task_ref t ON t.id = r.task_ref
-    WHERE p.exited_at IS NULL AND p.pid IS NOT NULL AND p.containment IS NULL AND p.container IS NULL AND p.host = ?
+    WHERE p.exited_at IS NULL AND p.pid IS NOT NULL AND p.containment IS NULL AND p.container IS NULL AND ${local.sql}
       AND r.outcome IS NOT NULL${options.repo === undefined ? "" : " AND t.repo = ?"} ORDER BY p.run`)
-        .all(...[hostname(), ...(options.repo === undefined ? [] : [options.repo])]).map(row => Number(row["run"]));
+        .all(...[...local.params, ...(options.repo === undefined ? [] : [options.repo])]).map(row => Number(row["run"]));
     const out = [];
     if (runs.length === 0)
         return out;
@@ -151,7 +152,7 @@ export async function closeOutRuns(store, clock, options = {}) {
         if (ownedProcessCount(runOwnerTag(store, runId)) > 0)
             continue;
         const witnesses = db.prepare(`SELECT pid, process_group, observed_at FROM run_process
-      WHERE run = ? AND exited_at IS NULL AND pid IS NOT NULL AND containment IS NULL AND container IS NULL AND host = ?`).all(runId, hostname())
+      WHERE run = ? AND exited_at IS NULL AND pid IS NOT NULL AND containment IS NULL AND container IS NULL AND ${mine.sql}`).all(runId, ...mine.params)
             .map(row => ({ pid: Number(row["pid"]), group: Number(row["process_group"]) === 1, observedAt: Date.parse(String(row["observed_at"])) }))
             .filter(one => Number.isFinite(one.observedAt));
         if (witnesses.length === 0)
@@ -252,8 +253,9 @@ export function checkoutTargets(census, inside, roots, guard) {
 function finishedRunProcesses(store, census) {
     const byPid = new Map(census.map(row => [row.pid, row]));
     const roots = new Set();
+    const local = localWitnessSql(store.handle, "p");
     const rows = store.handle.prepare(`SELECT p.pid AS pid, p.observed_at AS observed_at FROM run_process p JOIN run r ON r.id = p.run
-    WHERE p.exited_at IS NULL AND p.pid IS NOT NULL AND p.host = ? AND r.outcome IS NOT NULL`).all(hostname());
+    WHERE p.exited_at IS NULL AND p.pid IS NOT NULL AND ${local.sql} AND r.outcome IS NOT NULL`).all(...local.params);
     for (const row of rows) {
         const now = byPid.get(Number(row["pid"]));
         const observedAt = Date.parse(String(row["observed_at"]));

package/dist/runner-process.js

@@ -13,6 +13,7 @@
  * The record is the plane's own state (the folder that holds the database). It grants nothing by itself: it can
  * only let a name whose every recorded holder has exited be taken over early.
  */
+import { sameMachineHost } from "./machine-identity.js";
 import { createHash, createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { closeSync, fstatSync, lstatSync, mkdirSync, openSync, readSync, realpathSync, renameSync, rmSync, writeFileSync, fsyncSync, constants } from "node:fs";
@@ -195,7 +196,7 @@ export function holderProvedGone(record, holder, host, probe = realProcessProbe)
     if (typeof record.signature !== "string" || !/^[a-f0-9]{64}$/.test(record.signature)
         || !timingSafeEqual(Buffer.from(record.signature, "hex"), Buffer.from(expected, "hex")))
         return { gone: false, why: "its process record is not authenticated" };
-    if (record.runner !== holder.runner.name || record.host !== holder.runner.host || record.host !== host)
+    if (record.runner !== holder.runner.name || record.host !== holder.runner.host || !sameMachineHost(record.host, host))
         return { gone: false, why: "its record is for another worker or machine" };
     if (record.registeredAt !== holder.runner.registeredAt || record.credential !== credentialDigest(holder.credentialHash))
         return { gone: false, why: "its record is from an earlier start" };
@@ -229,7 +230,7 @@ export function recordStandsFor(record, holder, host) {
     if (typeof record.signature !== "string" || !/^[a-f0-9]{64}$/.test(record.signature)
         || !timingSafeEqual(Buffer.from(record.signature, "hex"), Buffer.from(expected, "hex")))
         return "its process record is not authenticated";
-    if (record.runner !== holder.runner.name || record.host !== holder.runner.host || record.host !== host)
+    if (record.runner !== holder.runner.name || record.host !== holder.runner.host || !sameMachineHost(record.host, host))
         return "its record is for another worker or machine";
     if (record.registeredAt !== holder.runner.registeredAt || record.credential !== credentialDigest(holder.credentialHash))
         return "its record is from an earlier start";

package/dist/runner.js

@@ -380,7 +380,8 @@ export function recoverDead(store, now, livenessMs = DEFAULT_LIVENESS_MS) {
             const claims = store.releaseClaimsOf(candidate.name, now, requeued);
             const worktrees = store.releaseWorktreesOf(candidate.name, now);
             const settled = store.recoverRunnerWork(candidate.name, now);
-            return { runner: candidate.name, claims, worktrees, runs: settled.runs, requeued: [...new Set([...requeued, ...settled.requeued])] };
+            // Only what recovery left in the queue: a vanished build it stopped for a person isn't requeued (vanished-retry.ts).
+            return { runner: candidate.name, claims, worktrees, runs: settled.runs, requeued: [...new Set([...requeued, ...settled.requeued])].filter(id => store.getTask(id)?.state === "queued") };
         });
         if (recovery !== null)
             recovered.push(recovery);

package/dist/scope.d.ts

@@ -205,6 +205,7 @@ export declare function canonicalProfileJson(profile: ExecutionProfile): string;
  * same 128 bits every other safety digest here uses (finding 21). */
 export declare function profileDigestOf(profile: ExecutionProfile): string;
 export declare const CHAIN_DIGEST_VERSION = 1;
+export declare const LIVE_CHAIN_VERSION = 2;
 /** One entry of an approved fallback chain: the WHOLE execution profile
  * (so a claude->codex switch cannot inherit one provider's repair config)
  * and the auth mode it runs under. Order is authority. */
@@ -214,15 +215,15 @@ export type ChainEntry = {
 };
 /** The stored snapshot bytes for a chain: the version rides IN the
  * snapshot, exactly like a single profile's. */
-export declare function canonicalChainJson(entries: readonly ChainEntry[]): string;
+export declare function canonicalChainJson(entries: readonly ChainEntry[], version?: number): string;
 /** sha256 over a domain-separated canonical chain encoding — a DIFFERENT
  * domain from a single profile ("standing-orders:chain:" vs
  * ":profile:"), so a chain digest can never collide with a profile
  * digest, truncated to the same 128 bits. */
-export declare function chainDigestOf(entries: readonly ChainEntry[]): string;
+export declare function chainDigestOf(entries: readonly ChainEntry[], version?: number): string;
 /** Strict re-hydration of a stored chain — every entry proved through the
  * single-profile rehydrator; anything unexpected is null. */
-export declare function chainFromJson(json: string | null): ChainEntry[] | null;
+export declare function chainFromJson(json: string | null, version?: number): ChainEntry[] | null;
 /**
  * THE STRICT RAW TERMS READ (raw authority repair): the stored columns of
  * a scope or a standing order, proved EXACTLY — a JSON list is a list of
@@ -499,6 +500,7 @@ export declare function digestOf(scope: Pick<Scope, "goal" | "outOfScope" | "tou
     releaseCheck?: ReleaseCheckPurpose | null;
 }, target?: ExecutionProfile | null | {
     chain: readonly ChainEntry[];
+    version?: number;
 }, route?: PhaseRoute | null): string;
 export declare function propose(store: Store, input: ScopeInput): Scope;
 export type GuardedProposeResult = {
@@ -793,7 +795,23 @@ export declare function fileAndSealUnderMode(store: Store, input: ScopeInput & {
     reason: "no-mode" | "not-signer" | "not-covered" | "coordinator-filed" | "acceptance-required" | "profile-unresolved";
     detail?: string;
 };
-export declare function approve(store: Store, taskId: string, by: string, now: Date, sawDigest: string, token: string, mutation?: Mutation): ApproveResult;
+export declare function approve(store: Store, taskId: string, by: string, now: Date, sawDigest: string, token: string, mutation?: Mutation, 
+/** A fast start (fast-start.ts): Build is this same yes, with its marker in the proof. Only that road passes it. */
+fastStart?: {
+    rule: string;
+    at: string;
+}, 
+/** A person's own yes in chat (owner's decision, docs/plans/toolroll-cards.md): their tap or signed-in click stands in
+ * for a password, so `token` is unused. Every rule below still applies. The caller has proved the person is the one
+ * tapping. `shown` is what a card that showed its terms whole showed: those words, and the digest kept when it was
+ * made. Null when the card showed less: the seal then opens none of the walls a person's reading opens. */
+chat?: {
+    modeDigest: string;
+    shown: {
+        expect: string;
+        terms: string;
+    } | null;
+}): ApproveResult;
 /** The ledger act that records how an approval's person was proved (password-now, sso-now, fresh-password, fresh-sso). */
 export declare const APPROVAL_PROOF = "approval proved";
 /** The proof row's detail: when the person was proved, the generation, and the exact digest they said yes to. */
@@ -835,6 +853,7 @@ export type ScopeAuthority = {
     route: PhaseRoute;
     digest: string;
     authMode: AuthMode | null;
+    chain?: ChainEntry[];
 } | {
     ok: false;
     reason: "terms" | "unrouted" | "unresolved" | "profile" | "chain" | "route" | "parity" | "digest" | "auth-mode";
@@ -1031,3 +1050,8 @@ export declare function localApprovalEligible(store: Store, by: string, taskId:
     reason: LocalApprovalRefusal;
     message: string;
 };
+/** A chain that may dispatch: version 2, a base and at least one fallback. An older chain is history, never this. */
+export declare function liveChainFromJson(json: string | null): ChainEntry[] | null;
+/** The chain in full, the words a yes agrees to: order, agent, model, how it bills, what it may do, and whether Toolroll
+ * can see it run out. Every approval surface shows these lines; empty for a scope with no chain. */
+export declare function chainTermsLines(scope: Pick<Scope, "proposedChainJson">): string[];

package/dist/scope.js

@@ -1,7 +1,10 @@
 // The rubric's vocabulary loads before anything that reaches the plan contract (see contracts/acceptance-terms.ts).
 export { ACCEPTANCE_LIMITS, EVIDENCE_KINDS } from "./contracts/acceptance-terms.js";
+import { cardShowsScope, cardTermsDigest } from "./chat-terms.js";
 import { mintSecret } from "./secret-mint.js";
 import { passwordlessOn } from "./passwordless.js";
+import { routeChangeProblem } from "./route-change-check.js";
+import { issueImported } from "./task-source.js";
 import { currentPasswordSource, passwordGuardOf, provenPasswordAccount } from "./sign-in-guard.js";
 import { validateScopeText } from "./task-text.js";
 import { contractChangesOf } from "./contract-changes.js";
@@ -152,29 +155,30 @@ export function profileDigestOf(profile) {
         .digest("hex")
         .slice(0, 32);
 }
-// ---- fallback chains (v30-v114; removed in v115) --------------------------
-// History only: an approval sealed over a fallback chain still decodes and
-// its digest still re-derives, so old tasks verify and render. Nothing
-// files, seals, or dispatches a chain any more.
+// ---- fallback chains (fallback.ts, docs/plans/fallback-chains.md) ----------
+// Version 1 is history (v30-v114): an old approval still decodes and its digest
+// still re-derives, so old tasks verify and render, and it holds no authority.
+// Version 2 is what filing writes now: only it dispatches.
 export const CHAIN_DIGEST_VERSION = 1;
+export const LIVE_CHAIN_VERSION = 2;
 /** The stored snapshot bytes for a chain: the version rides IN the
  * snapshot, exactly like a single profile's. */
-export function canonicalChainJson(entries) {
-    return canonicalJson({ digestVersion: CHAIN_DIGEST_VERSION, chain: entries });
+export function canonicalChainJson(entries, version = CHAIN_DIGEST_VERSION) {
+    return canonicalJson({ digestVersion: version, chain: entries });
 }
 /** sha256 over a domain-separated canonical chain encoding — a DIFFERENT
  * domain from a single profile ("standing-orders:chain:" vs
  * ":profile:"), so a chain digest can never collide with a profile
  * digest, truncated to the same 128 bits. */
-export function chainDigestOf(entries) {
+export function chainDigestOf(entries, version = CHAIN_DIGEST_VERSION) {
     return createHash("sha256")
-        .update(`standing-orders:chain:v${CHAIN_DIGEST_VERSION}:${canonicalChainJson(entries)}`, "utf8")
+        .update(`standing-orders:chain:v${version}:${canonicalChainJson(entries, version)}`, "utf8")
         .digest("hex")
         .slice(0, 32);
 }
 /** Strict re-hydration of a stored chain — every entry proved through the
  * single-profile rehydrator; anything unexpected is null. */
-export function chainFromJson(json) {
+export function chainFromJson(json, version = CHAIN_DIGEST_VERSION) {
     if (json === null)
         return null;
     let parsed;
@@ -187,7 +191,7 @@ export function chainFromJson(json) {
     if (parsed === null || typeof parsed !== "object")
         return null;
     const wrapper = parsed;
-    if (wrapper.digestVersion !== CHAIN_DIGEST_VERSION)
+    if (wrapper.digestVersion !== version)
         return null;
     // Exact keys on the wrapper and on every entry (v48 integrity): a
     // snapshot carrying anything this code never writes is not one it wrote.
@@ -600,7 +604,7 @@ route) {
     const innerDigest = target == null
         ? null
         : "chain" in target
-            ? chainDigestOf(target.chain)
+            ? chainDigestOf(target.chain, target.version)
             : profileDigestOf(target);
     return createHash("sha256")
         .update(JSON.stringify({
@@ -1070,7 +1074,14 @@ export function fileAndSealUnderMode(store, input) {
         return { ok: true, scope: store.getScope(input.taskId), basis: "mode" };
     });
 }
-export function approve(store, taskId, by, now, sawDigest, token, mutation = {}) {
+export function approve(store, taskId, by, now, sawDigest, token, mutation = {}, 
+/** A fast start (fast-start.ts): Build is this same yes, with its marker in the proof. Only that road passes it. */
+fastStart, 
+/** A person's own yes in chat (owner's decision, docs/plans/toolroll-cards.md): their tap or signed-in click stands in
+ * for a password, so `token` is unused. Every rule below still applies. The caller has proved the person is the one
+ * tapping. `shown` is what a card that showed its terms whole showed: those words, and the digest kept when it was
+ * made. Null when the card showed less: the seal then opens none of the walls a person's reading opens. */
+chat) {
     // Read and write in one transaction, re-reading inside it — the credential
     // check included, so a token rotated between authentication and the write
     // cannot leave an approval signed by an authority that no longer exists.
@@ -1078,7 +1089,14 @@ export function approve(store, taskId, by, now, sawDigest, token, mutation = {})
     // this approval — which would resurrect the old wording *and* mark it
     // agreed, the precise opposite of what the digest is for.
     return store.transact(() => {
-        const authenticated = authenticateApprover(store, by, token, store.lookupRef(taskId)?.repo ?? null);
+        const repoNow = store.lookupRef(taskId)?.repo ?? null;
+        const account = chat === undefined ? null : store.accountOf(by);
+        // A machine never reaches this road, and the person's role and reach are read here, in the seal's transaction.
+        if (chat !== undefined && machineActing())
+            return { ok: false, reason: "machine-proof" };
+        if (chat !== undefined && (account === null || account.revokedAt !== null || account.role !== "approver" || repoNow === null || !store.accountCanAccess(by, repoNow)))
+            return { ok: false, reason: "not-an-approver" };
+        const authenticated = chat !== undefined ? { ok: true, method: "chat", at: now.getTime() } : authenticateApprover(store, by, token, repoNow);
         if (!authenticated.ok)
             return authenticated;
         // ONLY A PERSON APPROVES (docs/plans/approval-policy.md, phase 1): a lead token or a remote API token proves the
@@ -1089,7 +1107,7 @@ export function approve(store, taskId, by, now, sawDigest, token, mutation = {})
         // localApprovalEligible, read again here inside the seal's transaction).
         const local = authenticated.method === "local-owner" ? currentLocalOwner() : null;
         if (authenticated.method === "local-owner") {
-            if (local === null || local.act !== "approve-plan")
+            if (local === null || (local.act !== "approve-plan" && !(local.act === "build-now" && fastStart !== undefined)))
                 return { ok: false, reason: "policy", message: localOwnerRefusal(store.accountOf(by)?.passwordSet === true, "/").message };
             const eligible = localApprovalEligible(store, by, taskId);
             if (!eligible.ok)
@@ -1106,6 +1124,16 @@ export function approve(store, taskId, by, now, sawDigest, token, mutation = {})
         // the new one in silence — which is the whole failure this guards.
         if (sawDigest !== scope.digest)
             return { ok: false, reason: "changed" };
+        // What the card showed when it was made is what this yes is to: other words, or words leaving out a widening, aren't.
+        const shown = chat?.shown ?? null;
+        if (shown !== null && (cardTermsDigest(shown.terms) !== shown.expect || !cardShowsScope(scope, shown.terms)))
+            return { ok: false, reason: "changed" };
+        // The "what changed" line a person read describes this exact route, or this yes isn't to what they read (route-change.ts).
+        if (routeChangeProblem(store, taskId, scope))
+            return { ok: false, reason: "changed" };
+        // A fast start is never a task from outside (github-import.ts): that takes the ordinary ceremony.
+        if (fastStart !== undefined && issueImported(store, taskId))
+            return { ok: false, reason: "policy", message: "A task from outside takes the ordinary approval." };
         // An unresolved scope cannot say exactly what would run, so nobody can
         // agree to it (foundations finding 16) — restatement is the road.
         if (scope.profileState === "unresolved") {
@@ -1144,7 +1172,7 @@ export function approve(store, taskId, by, now, sawDigest, token, mutation = {})
         // How the person was proved, beside every yes they give (a vote kept for protected work, or the seal): a password
         // typed now, a re-check now, or a remembered one — with when, the credential generation and the exact digest.
         const proved = () => store.recordAction({ at: now.toISOString(), actor: by, repo: store.lookupRef(taskId)?.repo ?? null, taskId, runId: null, action: APPROVAL_PROOF,
-            outcome: authenticated.method, source: "work", detail: approvalProofDetail(authenticated.at, store.accountOf(by)?.generation ?? 0, scope.digest, local === null ? undefined : { generation: local.localGeneration, transport: local.transport }) });
+            outcome: authenticated.method, source: "work", detail: (fastStart === undefined ? approvalProofDetail : fastProofDetail(fastStart))(authenticated.at, store.accountOf(by)?.generation ?? 0, scope.digest, local === null ? undefined : { generation: local.localGeneration, transport: local.transport }) });
         if (gate.verdict === "vote") {
             // The same person again adds nothing: no new vote, no proof row (and the approval roads refund a re-check).
             if (gate.already)
@@ -1164,7 +1192,8 @@ export function approve(store, taskId, by, now, sawDigest, token, mutation = {})
                 // profile — the exact bytes the digest the approver signed was bound
                 // to. Routing saveScope here would re-run resolution and could sign a
                 // profile nobody saw.
-                const sealed = store.sealScopeApproval(taskId, by, now, mutation);
+                const sealed = chat === undefined ? store.sealScopeApproval(taskId, by, now, mutation)
+                    : store.sealScopeApproval(taskId, by, now, mutation, { kind: "chat", modeDigest: chat.modeDigest, ...(shown === null ? {} : { card: "shown", cardDigest: shown.expect, shownTerms: shown.terms }) }, "person");
                 const approved = sealed ? store.getScope(taskId) : null;
                 if (!sealed || approved === null) {
                     refused.result = { ok: false, reason: sealed ? "no-scope" : "changed" };
@@ -1185,6 +1214,9 @@ export function approve(store, taskId, by, now, sawDigest, token, mutation = {})
 export const APPROVAL_PROOF = "approval proved";
 /** The proof row's detail: when the person was proved, the generation, and the exact digest they said yes to. */
 export const approvalProofDetail = (at, generation, digest, local) => `${new Date(at).toISOString()} · generation ${generation}${local === undefined ? "" : ` · local ${local.generation} ${local.transport}`} · digest ${digest}`;
+/** A fast start's proof: the v1 record proofDetailOf reads, with the marker. `local` keeps the legacy words
+ * localSealStandsSql reads, so a local owner's seal stands on the same rule. */
+const fastProofDetail = (fastStart) => (at, generation, digest, local) => JSON.stringify({ v: 1, at: new Date(at).toISOString(), generation, digest, fastStart, ...(local === undefined ? {} : { local: `proof · local ${local.generation} ${local.transport} · seal` }) });
 /** The proof of THIS approval: the approver's own row for these exact bytes (never another approval's words). */
 export function approvalProofOf(store, taskId, by, digest) {
     const rows = store.handle.prepare("SELECT outcome, detail FROM action_ledger WHERE task_id = ? AND action = ? AND actor = ? ORDER BY id DESC LIMIT 50").all(taskId, APPROVAL_PROOF, by);
@@ -1281,10 +1313,11 @@ export function scopeAuthorityOf(scope, env = {}) {
     if (profile === null) {
         return { ok: false, reason: "profile", problem: profileJson === null ? "the scope carries no agent profile" : "the scope's agent profile cannot be read exactly (unknown keys, an unsafe number, or a clock no timer can hold)" };
     }
-    // A scope filed with fallback agents (v30-v114) holds no authority now
-    // that fallback chains are gone: saving it again chooses its agents.
-    if (scope.proposedChainJson != null) {
-        return { ok: false, reason: "chain", problem: "this scope named fallback agents, which Toolroll no longer uses — save the scope again to choose its agents" };
+    // Fallback agents: a current chain whose base IS this profile. An older
+    // chain (v30-v114) holds no authority: saving the scope again re-files it.
+    const chain = scope.proposedChainJson == null ? null : liveChainFromJson(scope.proposedChainJson);
+    if (scope.proposedChainJson != null && (chain === null || profileDigestOf(chain[0].profile) !== profileDigestOf(profile))) {
+        return { ok: false, reason: "chain", problem: "this scope named fallback agents from an older version, or they can't be read — save the scope again to choose its agents" };
     }
     const routeJson = scope.proposedRouteJson ?? null;
     const route = routeFromJson(routeJson);
@@ -1294,7 +1327,7 @@ export function scopeAuthorityOf(scope, env = {}) {
     const parity = routeParityProblem(route, profile, { riskLevel: scope.riskLevel ?? "routine", qualityMode: scope.qualityMode ?? "default" });
     if (parity !== null)
         return { ok: false, reason: "parity", problem: parity };
-    const digest = digestOf({ goal: scope.goal, outOfScope: scope.outOfScope, touches: scope.touches, budgetMicrousd: scope.budgetMicrousd, acceptance: scope.acceptance, candidate: scope.candidate ?? null, qualityMode: scope.qualityMode ?? "default", releaseTerms: scope.releaseTerms ?? null, releaseCheck: scope.releaseCheck ?? null }, profile, route);
+    const digest = digestOf({ goal: scope.goal, outOfScope: scope.outOfScope, touches: scope.touches, budgetMicrousd: scope.budgetMicrousd, acceptance: scope.acceptance, candidate: scope.candidate ?? null, qualityMode: scope.qualityMode ?? "default", releaseTerms: scope.releaseTerms ?? null, releaseCheck: scope.releaseCheck ?? null }, chain === null ? profile : { chain, version: LIVE_CHAIN_VERSION }, route);
     if (digest !== scope.digest) {
         return { ok: false, reason: "digest", problem: "the scope's reference does not re-derive from its own terms, agents, and route — file it again" };
     }
@@ -1310,8 +1343,11 @@ export function scopeAuthorityOf(scope, env = {}) {
         if (!read.ok)
             return { ok: false, reason: "auth-mode", problem: read.problem };
         authMode = read.mode;
+        // The base was filed under one credential; a yes on another isn't a yes to these terms.
+        if (chain !== null && chain[0].authMode !== authMode)
+            return { ok: false, reason: "auth-mode", problem: "the agent's sign-in changed since this was filed — save the scope again" };
     }
-    return { ok: true, profile, route, digest, authMode };
+    return { ok: true, profile, route, digest, authMode, ...(chain === null ? {} : { chain }) };
 }
 /** The rubric's approval-card lines (v39): one per criterion, the id in
  * front (the exact string a proof must answer by) and its required
@@ -1321,8 +1357,8 @@ export function acceptanceWords(criteria) {
     if (criteria.length === 0)
         return [];
     return [
-        `  acceptance   ${criteria[0].id}: ${criteria[0].statement} [requires: ${criteria[0].evidence.join(", ")}]`,
-        ...criteria.slice(1).map(c => `               ${c.id}: ${c.statement} [requires: ${c.evidence.join(", ")}]`),
+        `  done when    ${criteria[0].id}: ${criteria[0].statement} [shown by: ${criteria[0].evidence.join(", ")}]`,
+        ...criteria.slice(1).map(c => `               ${c.id}: ${c.statement} [shown by: ${c.evidence.join(", ")}]`),
     ];
 }
 /** The route's approval-card lines (v47): the WORKING route the digest
@@ -1340,8 +1376,8 @@ evidence = null) {
     return [
         `  goal         ${scope.goal}`,
         ...(scope.outOfScope === null ? [] : [`  not this     ${scope.outOfScope}`]),
-        ...(scope.candidate ? [`  candidate    ${scope.candidate} — checked out by the machine, no agent runs`] : []),
-        ...(scope.touches.length === 0 ? [] : [`  touches      ${scope.touches.join(", ")}`]),
+        ...(scope.candidate ? [`  commit       ${scope.candidate.slice(0, 7)} — checked out by Toolroll, no agent runs`] : []),
+        ...(scope.touches.length === 0 ? [] : [`  files        ${scope.touches.join(", ")}`]),
         ...acceptanceWords(scope.acceptance),
         ...(scope.budgetMicrousd === null
             ? []
@@ -1350,6 +1386,7 @@ evidence = null) {
         // leg with its reason and readiness — before anyone signs.
         ...scopeRouteWords(scope, readiness),
         ...(evidence === null ? [] : [`  why model    ${evidence.replace(/^Why this model: /, "")}`]),
+        ...chainTermsLines(scope).map((line, at) => at === 0 ? `  fallback     ${line}` : `               ${line}`),
         // What the build may reach (egress.ts), part of what the yes agrees to.
         ...(scope.profile === null || scope.profile === undefined ? [] : [`  network      ${networkWords(scope.profile.network ?? null).replace(/^Network: /, "")}`]),
         ...(scope.profile === null || scope.profile === undefined ? [] : [`  writes       ${writesWords(scope.profile.writes)}`]),
@@ -1358,7 +1395,7 @@ evidence = null) {
         ...(scope.profile === null || scope.profile === undefined ? [] : ((terms) => [`  reads        ${terms.reads}`, ...(terms.mach === null ? [] : [`  services     ${terms.mach}`])])(sandboxTermsWords(scope.profile))),
         ...releaseTermsWords(scope.releaseTerms ?? null),
         ...(scope.releaseCheck == null ? [] : [`  release      ${releaseCheckSentence(scope.releaseCheck)}`]),
-        `  reference    ${scope.digest}`,
+        `  version      ${scope.digest.slice(0, 8)} (the full plan version is in --json)`,
         `  approved     ${describeApproval(approval)}`,
     ];
 }
@@ -1394,13 +1431,16 @@ function describeApproval(approval) {
     if (approval.approved)
         return `yes, by ${approval.by} at ${approval.at}`;
     if (approval.reason === "changed") {
-        return "no — it was approved, then the scope was rewritten; approve it again";
+        return "no — edited after approval; approve it again";
     }
     return "no — nothing will build this until somebody agrees to it";
 }
 // ---- Only a person approves (docs/plans/approval-policy.md, phase 1). Kept last: the freshness tripwire pins places.
 export { personProof } from "./person-proof.js";
 import { personProof } from "./person-proof.js";
+import { permissionPlainWords } from "./chat-terms.js";
+import { limitRecognised } from "./exhaustion.js";
+import { SUBSCRIPTION_CAPABLE } from "./keys.js";
 import { releaseCheckPurposeDigest, releaseTermsDigest } from "./contracts/release-terms.js";
 import { CHECK_ACCESS_WIDTH, autoEvidenceOf, carriesUnsandboxed, newestReleaseGeneration, releaseAuthorityOfTask, releaseAutoApproves, releaseSealProblem } from "./release-authority.js";
 /** Whether the command running now is a machine's: the lead (its token) or a remote API run. Trusted context only. */
@@ -1690,3 +1730,27 @@ export function localApprovalEligible(store, by, taskId) {
         return no("unsandboxed");
     return { ok: true };
 }
+// ---- Fallback chains (fallback.ts). Kept last too.
+/** A chain that may dispatch: version 2, a base and at least one fallback. An older chain is history, never this. */
+export function liveChainFromJson(json) {
+    const chain = chainFromJson(json, LIVE_CHAIN_VERSION);
+    return chain === null || chain.length < 2 ? null : chain;
+}
+// The chain's four providers by name, here rather than provider-auth.ts: this file sits under the contracts, and that one
+// loads every adapter.
+const CHAIN_AGENT_NAMES = { claude: "Claude", codex: "Codex", gemini: "Gemini", openrouter: "OpenRouter" };
+/** The chain in full, the words a yes agrees to: order, agent, model, how it bills, what it may do, and whether Toolroll
+ * can see it run out. Every approval surface shows these lines; empty for a scope with no chain. */
+export function chainTermsLines(scope) {
+    const chain = liveChainFromJson(scope.proposedChainJson ?? null);
+    if (chain === null)
+        return [];
+    return [
+        "If an agent runs out of its plan, the work moves to the next one here:",
+        ...chain.map((entry, at) => {
+            const paid = entry.authMode === "api-key" || SUBSCRIPTION_CAPABLE[entry.profile.provider] !== true;
+            const last = at === chain.length - 1;
+            return `${at + 1}. ${CHAIN_AGENT_NAMES[entry.profile.provider] ?? entry.profile.provider} ${entry.profile.model}, ${paid ? "on an API key, which spends money, and only while the project allows paid fallback" : "its plan"}; ${permissionPlainWords(entry.profile) ?? "agent permissions not known"}. ${last ? "Last in the chain." : limitRecognised(entry.profile.provider, entry.authMode) ? "Moves on when its plan runs out." : "Won't move on: Toolroll can't yet recognise this agent running out."}`;
+        }),
+    ];
+}

package/dist/scout.d.ts

@@ -2,7 +2,7 @@ import type { ProviderId } from "./contracts/provider.js";
 import type { Store } from "./store.js";
 import { type ParsedDecision, type Problem } from "./decision.js";
 import { type ParsedReport, type ReportProblem } from "./scout-report.js";
-import type { Runner } from "./builder.js";
+import { type Runner } from "./builder.js";
 import * as browserCheck from "./scout-browser.js";
 /** The scout's own headless browser: the pinned Playwright tool, saving its
  * screenshots straight into the run's image folder. */