toolroll 0.9.91 → 0.9.93

package/dist/needs-you.d.ts

@@ -6,11 +6,11 @@
  * The words never name the machine's internals; `plainSentence` keeps a
  * recorded reason only when it is free of them. */
 /** What a person is asked for. */
-export type NeedKey = "approval" | "card" | "answer" | "questions" | "sign-in" | "confirm-stopped" | "check-stopped" | "hold" | "choose-project" | "define-task" | "fix-request" | "choose-agent" | "fix-dependency" | "add-requirement" | "connect-builder" | "start-builder" | "vanished" | "review-result" | "rebuild" | "replan" | "earlier-version" | "other";
+export type NeedKey = "approval" | "card" | "answer" | "questions" | "sign-in" | "stop-unproven" | "hold" | "choose-project" | "define-task" | "fix-request" | "choose-agent" | "fix-dependency" | "add-requirement" | "connect-builder" | "start-builder" | "vanished" | "review-result" | "rebuild" | "replan" | "earlier-version" | "other";
 /** What the work waits for when no person can act. */
-export type WaitKey = "build-stopping" | "build-finishing" | "other-computer" | "card-reply" | "card-time" | "card-ci";
+export type WaitKey = "build-stopping" | "build-finishing" | "build-checking" | "other-computer" | "card-reply" | "card-time" | "card-ci";
 /** The action's code: the WorkAction that owns the act, or one of the acts a surface renders itself. */
-export type NeedActionCode = "approve-scope" | "approve-card" | "answer-decision" | "inspect-decisions" | "sign-in" | "confirm-stopped" | "inspect-hold" | "place-task" | "write-scope" | "select-agent" | "repair-dependency" | "repair-capability" | "start-worker" | "reconcile-run" | "open-result" | "retry-task" | "inspect-task";
+export type NeedActionCode = "approve-scope" | "approve-card" | "answer-decision" | "inspect-decisions" | "sign-in" | "recheck-stopped" | "inspect-hold" | "place-task" | "write-scope" | "select-agent" | "repair-dependency" | "repair-capability" | "start-worker" | "reconcile-run" | "open-result" | "retry-task" | "inspect-task";
 export type NeedAction = {
     code: NeedActionCode;
     label: string;
@@ -76,14 +76,14 @@ export declare const hasInternalWords: (text: string) => boolean;
  * it reads plainly, otherwise the need's own words. */
 export declare function needSentence(key: NeedKey, reason: string | null, context?: NeedContext): string;
 export declare function waitSentence(key: WaitKey | undefined, reason: string | null, context?: NeedContext): string;
-/** A finished run Toolroll can't prove stopped (store.stopQuiescenceFact):
- * a person can confirm it only when nothing of it may still be running.
- * `unknown`: Toolroll can't check, so the person confirms they checked. */
+/** A finished run Toolroll can't yet prove stopped (store.stopQuiescenceFact). Nobody is asked to confirm it:
+ * `unprovable` is Toolroll's own check still to run (stop-proof.ts), which settles by itself; `unknown` is that this
+ * computer can't look, or something Toolroll didn't start is in the build's folder — held, with nothing to vouch for. */
 export declare function processNeedOf(fact: {
     run: number;
     kind: "open" | "alive" | "elsewhere" | "unprovable" | "unknown" | "settling";
 } | null): {
-    need: "confirm-stopped" | "check-stopped";
+    need: "stop-unproven";
     build: number;
 } | {
     wait: WaitKey;

package/dist/needs-you.js

@@ -22,9 +22,10 @@ export const NEEDS = {
     answer: { sentence: () => "Answer the question so the work can continue.", action: { code: "answer-decision", label: "Answer the question" }, useReason: always },
     questions: { sentence: () => "Too many questions are open. Answer one so this task can start.", action: { code: "inspect-decisions", label: "Answer questions" } },
     "sign-in": { sentence: context => `${context.provider ?? "Your agent"} needs you to sign in again. The task starts on its own after.`, action: { code: "sign-in", label: "Sign in again" }, useReason: reason => /sign in|API key/i.test(reason) },
-    "confirm-stopped": { sentence: context => `Toolroll can't confirm ${build(context)} stopped. Nothing from it is running.`, action: { code: "confirm-stopped", label: "Confirm it stopped" } },
-    // Toolroll can't look at all: never "nothing is running"; the person checks, says so, then confirms.
-    "check-stopped": { sentence: context => `Toolroll can't check whether ${build(context)} stopped. Make sure nothing from it is running, then confirm.`, action: { code: "confirm-stopped", label: "Confirm it stopped" } },
+    // Toolroll proves a build stopped itself (stop-proof.ts); nobody is asked to vouch for it. Only when this computer
+    // can't look, or something Toolroll didn't start is using the build's folder, is the work held: the person can close
+    // what's theirs and have it look again, nothing more.
+    "stop-unproven": { sentence: context => `Toolroll can't prove ${build(context)} stopped from this computer, so the work is held. Close anything of yours that is using its folder, then check again.`, action: { code: "recheck-stopped", label: "Check again" } },
     hold: { sentence: () => "A hold is keeping this task from starting. Review it to release it.", action: { code: "inspect-hold", label: "Review hold" } },
     "choose-project": { sentence: () => "Choose a project so a builder can start.", action: { code: "place-task", label: "Choose a project" } },
     "define-task": { sentence: () => "Say what the task should do so it can be planned.", action: { code: "write-scope", label: "Define the task" } },
@@ -70,7 +71,7 @@ export function askChipOf(read) {
         return "Question";
     if (read.need === "hold")
         return "On hold";
-    if (read.need === "vanished" || read.need === "confirm-stopped" || read.need === "check-stopped")
+    if (read.need === "vanished" || read.need === "stop-unproven")
         return "Stopped";
     if (read.need === "sign-in")
         return "Sign in";
@@ -100,11 +101,12 @@ export const NEED_ASK = {
     approval: "decide", card: "decide", answer: "decide", questions: "decide", "choose-project": "decide", "define-task": "decide",
     "fix-request": "decide", "choose-agent": "decide",
     "review-result": "review", rebuild: "review", replan: "decide",
-    "sign-in": "unblock", "confirm-stopped": "unblock", "check-stopped": "unblock", hold: "unblock", "fix-dependency": "unblock",
+    "sign-in": "unblock", "stop-unproven": "unblock", hold: "unblock", "fix-dependency": "unblock",
     "add-requirement": "unblock", "connect-builder": "unblock", "start-builder": "unblock", vanished: "unblock", "earlier-version": "unblock", other: "unblock",
 };
 export const WAITS = {
     "build-finishing": () => "Finishing up; this clears on its own.",
+    "build-checking": context => `Making sure ${build(context)} stopped. This clears on its own.`,
     "build-stopping": context => `Waiting for ${build(context)} to stop. Nothing is needed from you.`,
     "other-computer": context => `Waiting for the computer that ran ${build(context)} to confirm it stopped.`,
     "card-reply": () => "Waiting for a reply.",
@@ -130,18 +132,18 @@ export function waitSentence(key, reason, context = {}) {
     const plain = reason?.trim() || null;
     return plain !== null && !hasInternalWords(plain) ? plain : "Waiting for the work to continue on its own.";
 }
-/** A finished run Toolroll can't prove stopped (store.stopQuiescenceFact):
- * a person can confirm it only when nothing of it may still be running.
- * `unknown`: Toolroll can't check, so the person confirms they checked. */
+/** A finished run Toolroll can't yet prove stopped (store.stopQuiescenceFact). Nobody is asked to confirm it:
+ * `unprovable` is Toolroll's own check still to run (stop-proof.ts), which settles by itself; `unknown` is that this
+ * computer can't look, or something Toolroll didn't start is in the build's folder — held, with nothing to vouch for. */
 export function processNeedOf(fact) {
     if (fact === null)
         return null;
     if (fact.kind === "settling")
         return { wait: "build-finishing", build: fact.run };
     if (fact.kind === "unprovable")
-        return { need: "confirm-stopped", build: fact.run };
+        return { wait: "build-checking", build: fact.run };
     if (fact.kind === "unknown")
-        return { need: "check-stopped", build: fact.run };
+        return { need: "stop-unproven", build: fact.run };
     return { wait: fact.kind === "elsewhere" ? "other-computer" : "build-stopping", build: fact.run };
 }
 /** Dispatch and work-index codes that wait on a person, as their need. */

package/dist/operate-remote-arguments.js

@@ -57,10 +57,10 @@ export const REMOTE_ARGUMENTS = new Map([
     ['template show', args('name')],
     ...['search', 'impact'].map(action => [`knowledge ${action}`, args('query', 'base')]),
     ['knowledge refresh', args('', 'base')],
-    // Decision reads and supersession are already project-bound in project-memory.ts. Proposal IDs are
-    // accepted only by memory apply (step-up), never by the listing commands below.
-    ...['search', 'decisions', 'show', 'decide', 'retire', 'review', 'status'].map(action => [`memory ${action}`,
-        args(['search', 'decide'].includes(action) ? 'query*' : ['show', 'retire'].includes(action) ? 'query' : '', 'why reason supersedes source all decision sessions no-local')]),
+    // Decision reads are already project-bound in project-memory.ts. Memory writes (decide, retire, apply) are a person's
+    // step-up, never a token's act, so none is listed here.
+    ...['search', 'decisions', 'show', 'review', 'status'].map(action => [`memory ${action}`,
+        args(action === 'search' ? 'query*' : action === 'show' ? 'query' : '', 'why reason supersedes source all decision sessions no-local')]),
     ['flows list', args()],
     ['flows show', args('flow:flow')], ['flows export', args('flow:flow')],
     ['flows create', args('', 'yes name template', { steps: 'steps' })],

package/dist/operate-remote.js

@@ -50,7 +50,7 @@ export const REMOTE_SCOPES = new Map([
     // The person's own remote actions, or everyone's within their projects for an approver (remote-audit.ts).
     ["audit", self],
     ["knowledge search", repo], ["knowledge impact", repo], ["knowledge refresh", repo],
-    ...["search", "decisions", "show", "decide", "retire", "review", "status"].map(action => [`memory ${action}`, self]),
+    ...["search", "decisions", "show", "review", "status"].map(action => [`memory ${action}`, self]),
     ...["list", "show", "export", "create", "edit", "trigger add", "trigger pause", "trigger resume", "trigger remove", "card add", "archive"]
         .map(action => [`flows ${action}`, self]),
     ["models status", global], ["models list", global],

package/dist/operate.js

@@ -33,6 +33,7 @@ import { personProof } from "./person-proof.js";
 import { RemoteMains } from "./remote-main.js";
 import { checkoutPlan, cleanCheckouts, discardCheckout, finishedCheckouts, slimKeptCheckouts, whyWords } from "./checkout-cleanup.js";
 import { closeOutCheckouts, closeOutRuns, stoppedWords } from "./run-closeout.js";
+import { proveFinishedRunsStopped, proveRunStopped } from "./stop-proof.js";
 import { MIN_DAYS, RETENTION_KINDS, countWords, dailyRetention, isRetentionKind, lastSweepAt, parsePeriod, periodLabel, periodWords, retentionPlan, sweepWords } from "./retention.js";
 import { checkPolicy, parseList, policyParts } from "./policy.js";
 import { billingOf, budgetHoldWords, budgetLabel, budgetStates, monthNamed, monthOf, spendItems, subagentNames, usd as spendUsd } from "./spend.js";
@@ -50,6 +51,7 @@ import { startLiveBackups } from "./live-backup.js";
 import { pushLimitSink } from "./provider-limits.js";
 import { heuristicSizing, installFilingSizer, ownerSizer, refineFiledSizing, settleSizings } from "./task-sizing.js";
 import { tierLines, tierReport } from "./tier-report.js";
+import { savingsLines, savingsReportOrError } from "./route-savings.js";
 import { limitsView } from "./limits-ui.js";
 import { startCodexLimits } from "./codex-limits.js";
 import { packageVersion, startMonitoring, targetOf } from "./monitoring.js";
@@ -62,6 +64,8 @@ import { sendSubagentSummaries } from "./subagent-admin.js";
 import { runRequestedUndos, sendSubagentWeeklies } from "./subagent-week.js";
 import { refreshConnections } from "./mcp-connect.js";
 import { releaseCheckPurposeFor, releaseTermsFor } from "./release-carry.js";
+import { approveReleaseCard, journalMatchesPlane, releaseApprovalCard, releaseCardLines, releaseTaskOf, waitingJournals } from "./release-approval.js";
+import { journalFile } from "./release.js";
 import { refreshTrustedMains, settleReleaseChecks } from "./nightly-check.js";
 import { githubNightlyRepos, readGithubNightlies } from "./nightly-github.js";
 import { exec as releaseExec, githubReads } from "./release-adapters.js";
@@ -262,6 +266,9 @@ import { latestRelease, newerRelease, notifySecurityRelease, notifyVersionLive,
 import { installMethod } from "./install-method.js";
 import { PACKAGE_VERSION } from "./version.js";
 import { machineActing } from "./scope.js";
+import { reevaluateResultRecords } from "./route-results.js";
+import { holdRuleOff, routeRulesPass, taskEvidenceWords } from "./route-rules.js";
+import { ruleHoldOf } from "./route-store.js";
 import { loginFileOf, migrateLegacyLogin, savedLoginFile, writableLoginFile } from "./login-secrets.js";
 /**
  * 0 done · 1 broke · 2 bad usage · 3 ran fine, the answer is no.
@@ -1211,6 +1218,9 @@ async function dispatch(command, positional, flags, context) {
     switch (command) {
         case "status":
             return statusCommand(positional, flags, context);
+        // `toolroll release approve` (cli.ts routes only this verb here; every other `release` form is release-cli.ts).
+        case "release":
+            return releaseApproveCommand(positional, flags, context);
         case "evals":
             return evalsCommand(positional, flags, context);
         case "ready":
@@ -1296,14 +1306,25 @@ async function dispatch(command, positional, flags, context) {
             return runKnowledgeApply(flags, { ...context, now: context.clock(), actor: verified !== null && verified.ok ? acting.name : null });
         }
         case "models": {
-            const acting = await askCredentials(flags, context);
+            // A local owner's lowering act (models turn-off / dismiss, through the terminal UI) asks for no credential: the
+            // rule door re-checks the owner and its exact act itself.
+            const localOnly = currentLocalOwner() !== null && !flags.has("as") && !flags.has("token") && ["turn-off", "dismiss", "suggestions", "stop"].includes(positional[0] ?? "");
+            const acting = localOnly ? null : await askCredentials(flags, context);
+            // The credential generation the proof is checked against, read BEFORE it (as `config set` does): a rotation in
+            // between makes the rule door refuse, never borrow the new generation.
+            const provedGeneration = acting === null ? -1 : context.store.accountOf(acting.name)?.generation ?? -1;
             const verified = acting === null ? null : authenticateApprover(context.store, acting.name, acting.token);
-            return runModelsCommand(positional, flags, { store: context.store, write: context.write, json: context.json, now: context.clock(), actor: verified !== null && verified.ok ? acting.name : null });
+            const proof = verified !== null && verified.ok ? { actor: acting.name, generation: provedGeneration, method: verified.method } : null;
+            return runModelsCommand(positional, flags, { store: context.store, write: context.write, json: context.json, now: context.clock(), actor: proof?.actor ?? null, proof });
         }
         case "memory": {
             // The remembered local login (or --as/--token) names the person; reads
-            // and writes both record who asked.
+            // and writes both record who asked. Writes are a person's: never the lead's token or chain (like knowledge apply).
+            if (memoryWriteVerb(positional) && currentActor()?.lead === true)
+                return fail(context.write, context.json, `memory ${positional[0]}`, "unauthenticated", MEMORY_WRITE_REFUSAL, EXIT.refused);
             const acting = await askCredentials(flags, context);
+            if (memoryWriteVerb(positional) && acting !== null && parseLeadToken(acting.token) !== null)
+                return fail(context.write, context.json, `memory ${positional[0]}`, "unauthenticated", MEMORY_WRITE_REFUSAL, EXIT.refused);
             const verified = acting === null ? null : verifyApproverByPassword(context.store, acting.name, acting.token, context.store.knownRepos().filter(repo => context.store.accountCanAccess(acting.name, repo)));
             const who = verified !== null && verified.ok ? verified.who : null;
             return runMemoryCommand(positional, flags, { store: context.store, write: context.write, json: context.json, now: context.clock(), actor: who?.name ?? null, repos: who?.repos ?? [], configDir: dirname(context.databaseFile), ...(context.evidenceRoot === undefined ? {} : { evidenceRoot: context.evidenceRoot }) });
@@ -2703,6 +2724,17 @@ async function tickCommand(flags, context) {
                 continue;
             }
         }
+        // THE RULE HOLD, before any claim or row (results routing, route v3): a task approved under an earned rule that
+        // then switched itself off on its sealed trigger never starts on that model. Nothing opens, so nothing strikes;
+        // the task is held, in words, until a person approves it again (the hold goes with that yes).
+        if (!wantsPlan && !wantsScout) {
+            const ruleHeld = ruleHoldOf(store, id);
+            if (ruleHeld !== null) {
+                holdRuleOff(store, ref.id, id, ruleHeld.model, clock());
+                dispatched.push({ id, outcome: "skipped", reason: "rule-switched-off", detail: `${id}: results for ${ruleHeld.model} dropped after this was approved — approve it again or re-file it` });
+                continue;
+            }
+        }
         // THE READINESS HALT (v47): a provider THIS runner has reported
         // unavailable never claims and never spends — no substitution, no
         // second-best; the skip names the observation and the ways out.
@@ -3550,6 +3582,9 @@ async function reconcileCommand(flags, context) {
     // A witness reserved for a spawn that never made a process (a crash or a
     // thrown spawn) settles once its run's process groups are proven gone.
     store.settleUnspawnedWitnesses(clock());
+    // What no record proves stopped, Toolroll proves itself from this computer's processes (stop-proof.ts): nobody is
+    // asked to confirm a build stopped, so a release waiting on its check moves on by itself.
+    await proveFinishedRunsStopped(store, clock);
     store.settleQuiescentStops(clock());
     // An update whose updater ended while letting work finish must not leave new work paused.
     try {
@@ -3630,6 +3665,18 @@ async function reconcileCommand(flags, context) {
         tidied = runTidy(store, clock(), releaseFactsFor(context.databaseFile), TIDY_PASS_LIMIT, { principal: "operator", repos: [repo], includeUnplaced: false });
     }
     catch { /* the next pass tries again */ }
+    // Result records (results-routing.md, slice 1): each finished family's record is evaluated again from its rows —
+    // a completion, a follow-up check, a revision, a proof, a merge or the task ending each change what it says.
+    try {
+        reevaluateResultRecords(store, canonicalProject(repo) ?? resolve(repo), context.evidenceRoot, clock());
+    }
+    catch { /* the next pass tries again */ }
+    // Earned rules (results-routing.md, slice 2): each live rule checked against its sealed terms on the records just
+    // evaluated; tasks approved under one that switched itself off are held for a new approval.
+    try {
+        routeRulesPass(store, canonicalProject(repo) ?? resolve(repo), clock());
+    }
+    catch { /* the next pass tries again */ }
     // Checkout cleanup (Settings → Storage): finished work's clean checkouts go as the setting says (by default when
     // the task is complete or cancelled); their branches stay. Each removal is in the ledger.
     // Completing or cancelling a task stops anything still running from its checkout first.
@@ -9321,7 +9368,7 @@ function showTask(positional, context) {
         ...(detail.automaticReview === null ? reviewStatusLines(detail.review, latestFinished?.id ?? null) : buildReviewLines(detail.automaticReview)),
         ...(scope === null
             ? ["  no scope — nothing will build this until one is written and approved"]
-            : describeScope(scope, readiness)),
+            : describeScope(scope, readiness, taskEvidenceWords(store, task.id, now))),
         ...planContractLines(store, context.evidenceRoot, id),
         // The route's standing (v47): sealed, proposed, legacy, or unreadable —
         // the projection itself is in describeScope's lines above.
@@ -10752,43 +10799,47 @@ async function resumeTaskCommand(positional, flags, context) {
     ]);
 }
 /**
- * `toolroll run settle <id> --why "<text>" --as <you> --token <t>`: an
- * approver's last resort for a finished run whose process witnesses can be
- * proven neither exited nor alive (a spawn interrupted before its pid was
- * written). Refuses while anything of the run is alive; the reason is kept
- * in the ledger against the approver's name. Signals nothing.
+ * `toolroll run settle <id> --as <you> --token <t>`: have Toolroll check again whether a finished run stopped. Nobody
+ * vouches that a build stopped (a person can't see whether a process exited): this runs Toolroll's own look at this
+ * computer's processes (stop-proof.ts), the one the worker makes on its own, and settles the run when none of them is
+ * the run's. A leftover proven the run's is stopped; anything else is left alone. `--why` is still accepted from older
+ * scripts and ignored.
  */
 async function runCommand(positional, flags, context) {
     const { store, write, json, clock } = context;
     const [action, id, ...extra] = positional;
     const command = "run settle";
-    const usage = "`toolroll run settle <run-id> --why \"<reason>\" --as <you> --token <t>`";
+    const usage = "`toolroll run settle <run-id>`";
     if (action !== "settle")
         return fail(write, json, "run", "usage", usage, EXIT.usage);
     const runId = Number(id ?? "");
-    const why = text(flags, "why")?.trim();
     if (id === undefined || extra.length > 0 || !/^[1-9]\d*$/.test(id) || !Number.isSafeInteger(runId))
         return fail(write, json, command, "usage", usage, EXIT.usage);
-    if (why === undefined || why === "" || why.length > 300 || /[\x00-\x1f\x7f]/.test(why))
-        return fail(write, json, command, "usage", "say why in one line with --why (at most 300 characters) — it is kept in the ledger", EXIT.usage);
     const run = store.getRun(runId);
     if (run === null)
         return fail(write, json, command, "unknown-run", `no run #${runId}`, EXIT.refused);
     const acting = await askCredentials(flags, context);
     if (acting === null)
-        return fail(write, json, command, "usage", "settling takes `--as <you> --token <t>` — it is an approver's act and is recorded against your name", EXIT.usage);
+        return fail(write, json, command, "usage", "checking a run again takes `--as <you> --token <t>` (or your sign-in from `toolroll up`)", EXIT.usage);
     const authenticated = authenticateApprover(store, acting.name, acting.token);
     const repo = store.refById(run.taskRef)?.repo ?? null;
     if (!authenticated.ok || !store.accountCanAccess(acting.name, repo))
         return fail(write, json, command, "not-an-approver", "that is not an approver for this run's project, or the token does not match", EXIT.refused);
-    const settled = store.settleRunWitnessesByApprover({ runId, by: acting.name, why }, clock());
-    if (!settled.ok)
-        return fail(write, json, command, settled.reason, settled.detail, EXIT.refused, { run: runId });
-    return succeed(write, json, command, { run: runId, witnesses: settled.witnesses, repeated: settled.repeated }, () => [
-        settled.repeated
-            ? `Run #${runId} has no unsettled process witness; nothing changed.`
-            : `Settled run #${runId}: ${settled.witnesses.length} process witness${settled.witnesses.length === 1 ? "" : "es"} recorded as ended, with your reason in the ledger.`,
-    ]);
+    if (run.outcome === null)
+        return fail(write, json, command, "still-running", `run #${runId} is still open`, EXIT.refused, { run: runId });
+    const proved = await proveRunStopped(store, runId, clock);
+    const stopped = store.stopQuiescenceFact(runId);
+    if (stopped === null) {
+        return succeed(write, json, command, { run: runId, outcome: proved.outcome === "skipped" ? "already-stopped" : "stopped", stoppedProcesses: proved.stopped ?? 0 }, () => [
+            proved.outcome === "skipped" ? `Run #${runId} had already stopped; nothing changed.`
+                : `Run #${runId} stopped: Toolroll checked this computer's processes and none of them is the run's${proved.stopped ? ` (it stopped ${proved.stopped} the run left running)` : ""}. The check is in the ledger.`,
+        ]);
+    }
+    const reason = proved.outcome === "blocked" ? "unproven" : stopped.kind === "alive" ? "alive" : "waiting";
+    const words = proved.outcome === "blocked" ? `Run #${proved.run} ${proved.words}.`
+        : stopped.kind === "alive" ? `Something of run #${stopped.run} is still running; Toolroll stops what is proven the run's on its own.`
+            : `Toolroll is still making sure run #${stopped.run} stopped. This clears on its own.`;
+    return fail(write, json, command, reason, words, EXIT.refused, { run: runId });
 }
 // ---- shared ---------------------------------------------------------------
 /**
@@ -11132,12 +11183,15 @@ function spendCommand(flags, context) {
     const windows = limitsView(limits, [], { project: repo => basename(repo), subagent: id => String(id) }, context.clock())?.tiles ?? [];
     // Sized routing: each tier's tasks, time to a result and plan use, and what the tiers saved.
     const tiers = tierReport(context.store.handle, month.from, month.to, items);
-    return succeed(context.write, context.json, command, { month: month.name, totalMicrousd: total, unpriced, items: items.length, budgets, limits, tiers: { rows: tiers.rows, saved: tiers.saved } }, () => [
+    // Suggestions and rules (results-routing slice 4): what each rule, trial and suggestion observed, over 90 days a side.
+    const suggestions = savingsReportOrError(context.store, context.store.knownRepos(), context.clock());
+    return succeed(context.write, context.json, command, { month: month.name, totalMicrousd: total, unpriced, items: items.length, budgets, limits, tiers: { rows: tiers.rows, saved: tiers.saved }, suggestions }, () => [
         `${month.name}: ${spendUsd(total)} (${items.length} pieces of work${unpriced > 0 ? `, ${unpriced} unpriced` : ""}; subscription work is $0)`,
         ...windows.map(tile => `  ${`${tile.name} ${tile.window}`.padEnd(24)} ${tile.value}% · ${tile.detail}`),
         ...[...byProject.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10).map(([repo, microusd]) => `  ${basename(repo).padEnd(24)} ${spendUsd(microusd)}`),
         ...budgets.map(one => `  budget ${budgetLabel(one, names.get(Number(one.key))).replace(/'s$/, "").padEnd(24)} ${spendUsd(one.spentMicrousd)} of ${spendUsd(one.limitMicrousd)} (${one.percent}%)${one.hardStop ? "" : " alerts only"}`),
         ...tierLines(tiers, spendUsd),
+        ...savingsLines(suggestions),
     ]);
 }
 /** `backup now | list` (sprint 8): back the database up now, or list backups and how the latest ones went. */
@@ -13418,3 +13472,117 @@ export function upLaptopPortCandidates(store, fromSeam) {
         return [range[0] ?? 4180];
     return [...range];
 }
+/** The memory verbs that change project memory (memory-cli.ts), and `propose`, which files the proposals a person then
+ * applies: a person's act, never the lead's. The reads stay as they are. */
+const MEMORY_WRITE_VERBS = new Set(["decide", "retire", "apply", "propose"]);
+function memoryWriteVerb(positional) {
+    return MEMORY_WRITE_VERBS.has(positional[0] ?? "");
+}
+const MEMORY_WRITE_REFUSAL = "Project memory is changed by a person with their own sign-in, not the lead. The lead proposes decisions in chat for you to confirm.";
+/**
+ * `toolroll release approve [<branch>] [--repo <path>]` (docs/plans/trusted-release-reports.md, slice A, A8): approve
+ * the release waiting for a person from this terminal, without copying a task id or a digest. The release journals are
+ * discovery only, read strictly; the plane's sealed release identity decides which release this is. The card prints
+ * control-free; the person is asked through `askCredentials` (or its remembered login, under its existing conditions);
+ * the card is built again AFTER that prompt and anything changed refuses; then the shared card wrapper hands the
+ * snapshot's scope digest to the unchanged approve(). `--json` never prompts.
+ */
+async function releaseApproveCommand(positional, flags, context) {
+    const { store, write, json } = context;
+    const command = "release approve";
+    const usage = "`toolroll release approve [<branch>] [--repo <path>]` (with --json: --as <you> --token <password> --digest <card digest>)";
+    const branchFlag = text(flags, "branch");
+    if (positional[0] !== "approve" || positional.length > 2 || (branchFlag !== undefined && positional.length > 1))
+        return fail(write, json, command, "usage", usage, EXIT.usage);
+    const branch = branchFlag ?? positional[1];
+    if (branch !== undefined && (!/^[A-Za-z0-9._/-]{1,255}$/.test(branch) || branch.startsWith("-") || branch.includes("..")))
+        return fail(write, json, command, "usage", `${branch} is not a branch name this command takes.`, EXIT.usage);
+    const repoFlag = text(flags, "repo");
+    const repo = repoFlag === undefined ? null : resolve(repoFlag);
+    const stateDir = dirname(context.databaseFile);
+    const { journals, unreadable } = waitingJournals(stateDir, name => journalFile(stateDir, name));
+    // The exact branch asked for, never another that shares its file name (feature/foo and feature_foo).
+    const named = branch === undefined ? journals : journals.filter(one => one.branch === branch);
+    if (branch !== undefined && named.length === 0 && unreadable.includes(basename(journalFile(stateDir, branch)))) {
+        return fail(write, json, command, "unreadable", `${branch}'s release journal can't be read as one; nothing was approved. Run \`toolroll release ${branch}\` again.`, EXIT.refused);
+    }
+    const matches = [], refusals = [];
+    for (const one of named) {
+        if (releaseTaskOf(store, one.taskId) !== null && approvalOf(store.getScope(one.taskId)).approved)
+            continue;
+        const proved = journalMatchesPlane(store, one, repo);
+        if (proved.ok)
+            matches.push(one);
+        else
+            refusals.push(proved.why);
+    }
+    if (matches.length === 0) {
+        const why = refusals.length > 0 ? `${refusals[0]}; nothing was approved` : branch === undefined ? "No release is waiting for your approval" : `No release of ${branch} is waiting for your approval`;
+        return fail(write, json, command, refusals.length > 0 ? "mismatch" : "none", `${why}.`, EXIT.refused);
+    }
+    if (matches.length > 1) {
+        return fail(write, json, command, "ambiguous", `More than one release is waiting: ${matches.map(one => `${one.branch} (${one.version})`).join(", ")}. Name the branch: \`toolroll release approve <branch>\`.`, EXIT.refused, { releases: matches.map(one => ({ branch: one.branch, version: one.version, task: one.taskId })) });
+    }
+    const chosen = matches[0];
+    const built = releaseApprovalCard(store, chosen.taskId);
+    if (!built.ok)
+        return fail(write, json, command, "none", built.why, EXIT.refused);
+    const shown = built.card;
+    const cardData = { task: shown.taskId, version: shown.seal.identity.packageVersion, branch: shown.seal.identity.branch, candidate: shown.seal.identity.approvedSha, digest: shown.digest, ci: shown.ci?.state ?? null };
+    if (shown.approved !== null)
+        return fail(write, json, command, "approved", `Release ${cardData.version} is already approved by ${shown.approved.by}.`, EXIT.refused, { release: cardData });
+    if (shown.refusal !== null) {
+        if (!json)
+            for (const line of releaseCardLines(shown))
+                write(line);
+        return fail(write, json, command, "refused", `Can't approve now: ${shown.refusal}`, EXIT.refused, { release: cardData });
+    }
+    let name, token;
+    if (json) {
+        const given = credentialsFrom(flags, context);
+        if (given.name === undefined || given.token === undefined || given.name === "" || given.token === "")
+            return fail(write, json, command, "credentials", "Approving a release needs who is agreeing: --as <you> --token <password>. Nothing was approved.", EXIT.usage, { release: cardData });
+        if (text(flags, "digest") !== shown.digest)
+            return fail(write, json, command, "unconfirmed", "Name the card you read: --digest <card digest>. Nothing was approved.", EXIT.refused, { release: cardData });
+        name = given.name;
+        token = given.token;
+    }
+    else {
+        for (const line of releaseCardLines(shown))
+            write(line);
+        write("");
+        if (interactive()) {
+            if (!await confirm(`Approve release ${cardData.version}?`)) {
+                write("Nothing approved.");
+                return EXIT.refused;
+            }
+        }
+        else if (!flags.has("yes") || text(flags, "digest") !== shown.digest) {
+            write(`Nothing has been approved. Agree to exactly this card with: toolroll release approve ${chosen.branch} --yes --digest ${shown.digest} --as <you> --token <your password>`);
+            return EXIT.refused;
+        }
+        const acting = await askCredentials(flags, context);
+        if (acting === null)
+            return fail(write, json, command, "credentials", "Approving a release needs who is agreeing. Nothing was approved.", EXIT.usage);
+        name = acting.name;
+        token = acting.token;
+    }
+    // After the prompt: the card again, from the plane. A change refuses; it is never approved in place of what was shown.
+    const again = releaseApprovalCard(store, chosen.taskId);
+    if (!again.ok || again.card.digest !== shown.digest)
+        return fail(write, json, command, "changed", "This release changed while you were being asked; nothing was approved. Run the command again to read it.", EXIT.refused);
+    const now = context.clock();
+    const answer = approveReleaseCard(store, { taskId: chosen.taskId, cardDigest: shown.digest, approveNow: scopeDigest => approve(store, chosen.taskId, name, now, scopeDigest, token, mutationFrom(flags, now)) });
+    if (!answer.ok) {
+        if (answer.reason !== "approve")
+            return fail(write, json, command, answer.reason, `${answer.message} Nothing was approved.`, EXIT.refused);
+        const refused = answer.result;
+        if (refused.reason === "policy")
+            return fail(write, json, command, "policy", `${chosen.taskId}: ${refused.message}`, EXIT.refused);
+        return fail(write, json, command, refused.reason, describeApproveFailure(refused.reason, chosen.taskId), EXIT.refused);
+    }
+    return succeed(write, json, command, { release: cardData }, () => [
+        `Approved release ${cardData.version} (${cardData.candidate.slice(0, 7)}). The release check runs next; it deploys, merges and publishes once GitHub CI and the check pass.`,
+        ...(shown.stopped === null ? [] : [`The release isn't running: run \`toolroll release ${chosen.branch}\` to go on.`]),
+    ]);
+}

package/dist/phase-routing.d.ts

@@ -49,7 +49,7 @@
  * a legacy approval governed by its sealed profile alone.
  */
 import type { EvidenceKind } from "./contracts/acceptance-terms.js";
-import { MODEL_ID_SHAPE, RISKS, ROUTE_VERSION, type PhaseRoute, type RouteLeg, type RouteOverride, type RouteVersion, type TaskSizing } from "./contracts/route.js";
+import { MODEL_ID_SHAPE, PLAIN_ROUTE_VERSION, RISKS, ROUTE_VERSION, type PhaseRoute, type RouteLeg, type RouteOverride, type RouteVersion, type TaskSizing } from "./contracts/route.js";
 import type { Phase, ProviderId } from "./provider.js";
 import type { QualityMode } from "./quality.js";
 /** The sealed route's shape is its contract (contracts/route.ts); these are its types. */
@@ -62,7 +62,7 @@ export declare function exactModelId(v: unknown): v is string;
 /** v2 adds the task's size (small / medium / large, risky or not), the
  * light tier, and plan headroom. A v1 route — sealed before sizing — still
  * reads back exactly and keeps its own digest domain. */
-export { ROUTE_VERSION };
+export { PLAIN_ROUTE_VERSION, ROUTE_VERSION };
 /** The durable route ERA a scope row carries once it was filed under this
  * policy: NULL on a row proven to predate v47 (legacy — the sealed profile
  * alone governs), this value on every row filed since. A row with an era
@@ -191,6 +191,37 @@ export type RouteInput = {
      * candidates on more than one provider, the one with more room runs; a
      * provider past its limits gives way even to a stronger tier. */
     headroom?: readonly ProviderRoom[];
+    /** Results routing (route v3, docs/plans/results-routing.md slice 2): the project's live earned rules, and the two
+     * eligibility facts the route itself doesn't carry (a release or candidate task; declared paths that touch the
+     * project's protected paths). Absent or null: no rule applies. */
+    earned?: EarnedInput | null;
+};
+/** One live earned rule, as routing reads it: which project-size cohort it covers, the exact Claude model it builds
+ * on, and the configured builder it was earned against (a configuration change pauses the rule; a mismatch here
+ * skips it all the same). */
+export type EarnedRule = {
+    id: number;
+    generation: number;
+    cohortSize: "small" | "medium";
+    provider: ProviderId;
+    model: string;
+    configured: {
+        provider: string;
+        model: string | null;
+    };
+};
+/** A live trial (results routing slice 3): try a cheaper Claude model on the next `limit` eligible tasks of one
+ * cohort, each still approved by a person. `reservation` is this filing's place in it (route-store.ts
+ * reserveTrialPlace): its id, or null when every place is taken, so the configured builder runs it. */
+export type EarnedTrial = EarnedRule & {
+    limit: number;
+    reservation: number | null;
+};
+export type EarnedInput = {
+    rules: readonly EarnedRule[];
+    release: boolean;
+    protected: boolean;
+    trial?: EarnedTrial | null;
 };
 export declare function specWords(spec: {
     provider: string;
@@ -203,6 +234,55 @@ export declare function specWords(spec: {
  * guess.
  */
 export declare function recommendRoute(input: RouteInput): PhaseRoute;
+/**
+ * THE BUILD LEG'S ONE PRECEDENCE ORDER (results routing, docs/plans/results-routing.md slice 2), pure:
+ *
+ *   pin > person override > trial > earned rule > configured row (light / routine / strong by size)
+ *   > headroom move
+ *
+ * Headroom moves only a configured leg, never a rule's or a trial's: their evidence is about one exact model. A rule
+ * or trial whose provider is past the headroom limits is skipped for this filing, and its reason says so. A trial
+ * applies only with a place reserved for this task (slice 3). A rule or trial applies only to an
+ * eligible task — small or medium, not risky, default quality, no screenshot or manual-review evidence, not a
+ * merging mode, not a release or candidate, nothing protected declared — and only over the configured builder it was
+ * earned against. Its leg says how it was selected (`selection`), so the route seals as version 3 and every later
+ * check reads the sealed selection, never the current rules or the reason text.
+ */
+export declare function selectBuildLeg(input: RouteInput, configured: {
+    spec: RouteCandidate;
+    tier: CandidateTier;
+    reasons: string[];
+}): {
+    leg: RouteLeg;
+    moved: boolean;
+};
+/** The earned rule this task's build takes (pure): null when none could apply (no rule for its size, or the task
+ * isn't eligible), or a rule skipped for this filing with the words why. */
+export declare function earnedRuleFor(input: RouteInput, configured: {
+    spec: RouteCandidate;
+    tier: CandidateTier;
+}): {
+    kind: "rule";
+    rule: EarnedRule;
+} | {
+    kind: "skipped";
+    reason: string;
+} | null;
+/** The trial this task's build takes (pure, results routing slice 3): null when none could apply (no live trial for
+ * its size, or the task isn't eligible: the same facts an earned rule needs), a trial with this task's place, or a
+ * trial skipped for this filing with the words why (another configured builder, no place left, no headroom). */
+export declare function trialFor(input: RouteInput, configured: {
+    spec: RouteCandidate;
+    tier: CandidateTier;
+}): {
+    kind: "trial";
+    trial: EarnedTrial & {
+        reservation: number;
+    };
+} | {
+    kind: "skipped";
+    reason: string;
+} | null;
 export declare function legOf(route: PhaseRoute, phase: Phase): RouteLeg;
 /** Every stated problem on the route, in phase order — a non-empty list
  * means the scope files unresolved with these words. */