toolroll 0.9.91 → 0.9.92

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.9.92 — 2026-11-05
+
+- **Toolroll learns which cheaper models do the job.** Every task now gets a
+  result record (see it on the task page, or run `toolroll models results`).
+  Once a cheaper model has done well on a project's small or routine tasks,
+  Settings → Models suggests it, with the evidence. Accepting needs your
+  password and only affects that project's eligible tasks; if the cheaper
+  model then does badly, Toolroll switches back on its own and tells you.
+  Approvals show a line saying why a model was picked. Also in the terminal:
+  `toolroll models suggestions`, `accept`, `dismiss`, `turn-off`.
+- **Try a cheaper model on the next 10 tasks.** When a cheaper model has no
+  track record yet, Settings → Models offers a trial. Each trial task says
+  "trial 3 of 10" and must be approved by a person; Stop ends it any time
+  (`toolroll models try` / `stop`).
+- **See what it saved.** The Spend page and `toolroll spend` show cost per
+  task before and after each rule or trial — observed, not a promise, and
+  only once there are enough priced results.
+- **Project memory is changed by a person only.** A personal API token used
+  from the remote CLI could record or retire project decisions without a
+  password; now it can't, and neither can the lead. Reading memory works as
+  before.
+
 ## 0.9.91 — 2026-11-04
 
 - **A deploy checks your HTTPS console before it changes anything.** If the

package/dist/approval-authority.d.ts

@@ -1,7 +1,15 @@
 /** SQL over a `task_scope` alias and a repo expression: whether that row's approval authority stands at `now` (an SQL
  * expression, used exactly three times: the mode and grant clauses, and the release's expiry). It never asks whether the row is approved.
  * COALESCE: a NULL basis would make the OR chain NULL, and NOT NULL reads as "not dead"; NULL stands on nothing. */
-export declare const authorityStandsSql: (scope: string, repo: string, now: string) => string;
+export declare function authorityStandsSql(scope: string, repo: string, now: string): string;
+/**
+ * SQL, conjunctive with every alternative above (results routing slice 3): a task whose sealed route tries a cheaper
+ * model (its build leg's selection is a trial) stands only on a PERSON's own yes to these exact bytes — the ceremony
+ * (`password`) or their paired-chat tap (`chat`), with that person's proof at the seal's instant, and no machine's.
+ * A mode, a grant, a schedule, a carry, an automatic seal or the lead never stand for one, whatever else allows them.
+ * The route is matched as text, so a route that can't be read as JSON is held to it too (fail closed).
+ */
+export declare function trialSealStandsSql(scope: string): string;
 /**
  * SQL, conjunctive with every alternative above (easy-start plan C5): a seal a local owner gave (its proof row at the
  * seal's instant says `local-owner`) stands only while local mode is on, for that owner, at the local generation its

package/dist/approval-authority.js

@@ -20,7 +20,8 @@ const PERSON_PROOFS = "('password-now', 'sso-now', 'fresh-password', 'fresh-sso'
 /** SQL over a `task_scope` alias and a repo expression: whether that row's approval authority stands at `now` (an SQL
  * expression, used exactly three times: the mode and grant clauses, and the release's expiry). It never asks whether the row is approved.
  * COALESCE: a NULL basis would make the OR chain NULL, and NOT NULL reads as "not dead"; NULL stands on nothing. */
-export const authorityStandsSql = (scope, repo, now) => `COALESCE((((COALESCE(${scope}.approval_basis, '') IN ('password', 'chat') AND NOT ${machineSealSql(scope)}
+export function authorityStandsSql(scope, repo, now) {
+    return `COALESCE((((COALESCE(${scope}.approval_basis, '') IN ('password', 'chat') AND NOT ${machineSealSql(scope)}
         AND (${personSealSql(scope)} OR NOT ${automationSql(scope)} OR ${approverStandsSql(scope, repo)}))
     OR (${scope}.approval_basis = 'carried' AND ${carrySealSql(scope)})
     OR (${scope}.approval_basis = 'mode' AND EXISTS (SELECT 1 FROM operating_mode om
@@ -30,7 +31,19 @@ export const authorityStandsSql = (scope, repo, now) => `COALESCE((((COALESCE(${
     OR (${scope}.approval_basis = 'grant' AND ${grantStandsSql(`${scope}.mode_digest`, now, repo)})
     OR (${scope}.approval_basis = 'schedule' AND ${approverStandsSql(scope, repo)})
     OR (${scope}.approval_basis IN ('auto-check', 'auto-green') AND ${autoSealSql(scope, repo)} AND ${approverStandsSql(scope, repo)}))
-    AND ${releaseStandsSql(scope, now)} AND ${localSealStandsSql(scope, repo)}), 0)`;
+    AND ${releaseStandsSql(scope, now)} AND ${localSealStandsSql(scope, repo)}
+    AND (instr(COALESCE(${scope}.approved_route_json, ''), '"trial"') = 0 OR ${trialSealStandsSql(scope)})), 0)`;
+}
+/**
+ * SQL, conjunctive with every alternative above (results routing slice 3): a task whose sealed route tries a cheaper
+ * model (its build leg's selection is a trial) stands only on a PERSON's own yes to these exact bytes — the ceremony
+ * (`password`) or their paired-chat tap (`chat`), with that person's proof at the seal's instant, and no machine's.
+ * A mode, a grant, a schedule, a carry, an automatic seal or the lead never stand for one, whatever else allows them.
+ * The route is matched as text, so a route that can't be read as JSON is held to it too (fail closed).
+ */
+export function trialSealStandsSql(scope) {
+    return `(COALESCE(${scope}.approval_basis, '') IN ('password', 'chat') AND NOT ${machineSealSql(scope)} AND ${personSealSql(scope)})`;
+}
 /**
  * SQL, conjunctive with every alternative above (easy-start plan C5): a seal a local owner gave (its proof row at the
  * seal's instant says `local-owner`) stands only while local mode is on, for that owner, at the local generation its

package/dist/build-review.js

@@ -126,6 +126,8 @@ function sendBack(store, root, runId, taskId, repo, high, now) {
         run: runId, source: revisionSourceOf(store.getScope(taskId)?.digest ?? null), actor, repos: [repo], batch: "",
         note: revisionNoteOf(high), path: "", line: "",
         request: createHash("sha256").update(`build-review:${runId}`).digest("hex").slice(0, 32), allowMode: true,
+        // The automatic review's send-back, even when the mode's signer is its actor: never a person's act.
+        origin: "automatic-review",
     }, now);
     return revised.ok ? { ok: true, id: revised.id } : { ok: false, problem: revised.message };
 }

package/dist/chat-actions.d.ts

@@ -1,5 +1,3 @@
-/** Shared, exact-state actions. Models may prepare; only the existing human
- * confirmation door executes. Protected actions use a one-use review receipt. */
 import { type Authority } from "./local-owner.js";
 import { type Store } from "./store.js";
 import { type VerifiedApprover } from "./principal.js";
@@ -231,6 +229,16 @@ export declare const CHAT_ACTIONS: {
         readonly protected: false;
         readonly password: false;
     };
+    readonly suggestion_not_now: {
+        readonly label: "Not now";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly trial_stop: {
+        readonly label: "Stop trial";
+        readonly protected: false;
+        readonly password: false;
+    };
     readonly lead_about_you: {
         readonly label: "Remember";
         readonly protected: false;
@@ -279,7 +287,7 @@ export declare function sharedActionReviewPath(id: number): string;
 export declare function mintSharedActionReview(store: Store, who: VerifiedApprover, id: number, root: string, now: Date): {
     payload: {
         version: 1;
-        operation: "decision_record" | "decision_retire" | "flow_browser" | "flow_browser_off" | "flow_card_add" | "flow_card_approve" | "flow_card_assign" | "flow_card_cancel" | "flow_card_choose" | "flow_card_comment" | "flow_card_move" | "flow_card_send_back" | "flow_card_watch" | "flow_create" | "flow_edit" | "flow_script_save" | "flow_starter" | "flow_trigger_add" | "flow_trigger_pause" | "flow_trigger_remove" | "flow_trigger_resume" | "kit_setup" | "knowledge_instructions" | "knowledge_remove" | "knowledge_restore" | "knowledge_save" | "lead_about_you" | "result_accept" | "scope_approve" | "skill_disable" | "skill_enable" | "skill_import" | "skill_restore" | "skill_test" | "subagent_answer" | "subagent_ask" | "subagent_create" | "subagent_memory" | "subagent_note" | "subagent_routine" | "subagent_soul" | "subagent_state" | "subagent_tools" | "subagent_undo" | "sweep_cancel_rest" | "sweep_file" | "task_cancel" | "task_resume" | "tool_add" | "tool_remove";
+        operation: "decision_record" | "decision_retire" | "flow_browser" | "flow_browser_off" | "flow_card_add" | "flow_card_approve" | "flow_card_assign" | "flow_card_cancel" | "flow_card_choose" | "flow_card_comment" | "flow_card_move" | "flow_card_send_back" | "flow_card_watch" | "flow_create" | "flow_edit" | "flow_script_save" | "flow_starter" | "flow_trigger_add" | "flow_trigger_pause" | "flow_trigger_remove" | "flow_trigger_resume" | "kit_setup" | "knowledge_instructions" | "knowledge_remove" | "knowledge_restore" | "knowledge_save" | "lead_about_you" | "result_accept" | "scope_approve" | "skill_disable" | "skill_enable" | "skill_import" | "skill_restore" | "skill_test" | "subagent_answer" | "subagent_ask" | "subagent_create" | "subagent_memory" | "subagent_note" | "subagent_routine" | "subagent_soul" | "subagent_state" | "subagent_tools" | "subagent_undo" | "suggestion_not_now" | "sweep_cancel_rest" | "sweep_file" | "task_cancel" | "task_resume" | "tool_add" | "tool_remove" | "trial_stop";
         request: {
             [x: string]: unknown;
         };

package/dist/chat-actions.js

@@ -1,5 +1,6 @@
 /** Shared, exact-state actions. Models may prepare; only the existing human
  * confirmation door executes. Protected actions use a one-use review receipt. */
+import { dismissSuggestion, ruleById, stopTrial, suggestionsFor, suggestionWords, taskEvidenceWords, trialWords } from "./route-rules.js";
 import { CHAT_ACTION_LOCAL_ACTS, currentLocalOwner } from "./local-owner.js";
 import { fileTaskProposal } from "./proposal.js";
 import { heuristicSizing } from "./task-sizing.js";
@@ -128,6 +129,10 @@ export const CHAT_ACTIONS = {
     kit_setup: { label: "Set up kit", protected: false, password: false },
     decision_record: { label: "Record decision", protected: false, password: false },
     decision_retire: { label: "Retire decision", protected: false, password: false },
+    // Not now only takes a suggestion off the list for 30 days: nothing about which models run changes.
+    suggestion_not_now: { label: "Not now", protected: false, password: false },
+    // Stopping a trial only lowers: new tasks build on the configured model; approved ones keep theirs.
+    trial_stop: { label: "Stop trial", protected: false, password: false },
     // What the owner's own lead knows about them: theirs alone, in no project (lead-about.ts).
     lead_about_you: { label: "Remember", protected: false, password: false },
     scope_approve: { label: "Approve work", protected: true, password: true },
@@ -279,7 +284,7 @@ export function prepareSharedAction(store, who, operation, input, root, now = ne
         const stamp = hash({ operation, request, repo: "", state, terms, actor: who.name, generation: who.generation, ceiling: who.ceilingDigest });
         return { version: SHARED_ACTION_VERSION, operation, request, repo: "", title, terms, stamp, state };
     }
-    const task = operation.startsWith("skill_") || operation.startsWith("knowledge_") || operation.startsWith("decision_") || operation.startsWith("tool_") || operation.startsWith("flow_") || operation.startsWith("subagent_") || operation.startsWith("kit_") || operation.startsWith("sweep_")
+    const task = operation.startsWith("skill_") || operation.startsWith("knowledge_") || operation.startsWith("decision_") || operation.startsWith("tool_") || operation.startsWith("flow_") || operation.startsWith("subagent_") || operation.startsWith("kit_") || operation.startsWith("sweep_") || operation.startsWith("suggestion_") || operation.startsWith("trial_")
         ? null
         : text(input, "task", 64);
     const flowTarget = operation.startsWith("flow_") && operation !== "flow_create" && operation !== "flow_script_save" && operation !== "flow_starter" ? flowTargetOf(store, input) : null;
@@ -866,6 +871,26 @@ export function prepareSharedAction(store, who, operation, input, root, now = ne
             }
         }
     }
+    else if (operation === "suggestion_not_now") {
+        // Only a suggestion on offer now, by its exact id (which binds its evidence, prices and Models generations).
+        const asked = text(input, "suggestion", 200);
+        const offer = suggestionsFor(store, repo, now).find(one => one.id === asked);
+        if (offer === undefined)
+            throw Error("That suggestion isn't on offer any more. See Settings → Models.");
+        state = { suggestion: offer.id };
+        title = `Not now: ${offer.name} for ${offer.cohortSize === "small" ? "small" : "routine"} tasks`;
+        terms.push(suggestionWords(offer), "Keeps this suggestion quiet for 30 days. Nothing about which models run changes. To accept it instead, review it in Settings → Models.");
+    }
+    else if (operation === "trial_stop") {
+        // Only a live trial of this project, by its number; the card is stale once the trial moves.
+        const asked = integer(input, "trial");
+        const trial = Number.isSafeInteger(asked) ? ruleById(store, asked) : null;
+        if (trial === null || trial.kind !== "trial" || trial.repo !== repo || (trial.state !== "trialling" && trial.state !== "paused"))
+            throw Error("That trial isn't running any more. See Settings → Models.");
+        state = { trial: trial.id, generation: trial.generation };
+        title = "Stop trying a cheaper model";
+        terms.push(trialWords(store, trial), "New tasks build on the configured model again. Tasks a person already approved on the trial keep that model.");
+    }
     else if (operation.startsWith("decision_")) {
         // The staleness fence: the newest decision id and the active count, so a
         // card drafted before a subagent recorded or retired one is refused.
@@ -947,10 +972,11 @@ export function prepareSharedAction(store, who, operation, input, root, now = ne
             if (!authority.ok)
                 throw Error(authority.problem);
             state["authMode"] = authority.authMode;
-            terms.push(...describeScope(scope)
+            terms.push(...describeScope(scope, undefined, taskEvidenceWords(store, scope.taskId, now))
                 .filter((line) => !/^\s*(reference|approved)\s/.test(line))
                 .map((line) => line
                 .trimStart()
+                .replace(/^why model\s+/, "Why this model: ")
                 .replace(/^goal\s+/, "Work: ")
                 .replace(/^not this\s+/, "Excluded: ")
                 .replace(/^touches\s+/, "Allowed files: ")), `Agent permissions and limits\n${runtimeTerms(authority.profile)}\n${authority.authMode === "api-key" ? "Uses your API key; spend is charged to that account." : authority.authMode === "subscription" ? "Uses your subscription login." : ""}`);
@@ -1246,6 +1272,25 @@ export function executeSharedAction(store, who, id, payload, now, options) {
                 if (!removeToolFrom(store, repo, String(req["name"]), actor, now))
                     throw Error("That tool was already removed.");
             }
+            else if (payload.operation === "trial_stop") {
+                const door = currentLocalOwner() !== null ? { kind: "local-owner", actor } : { kind: "person", person: { actor: who.name, generation: who.generation, method: "session", live: () => true } };
+                const trial = ruleById(store, Number(payload.state["trial"]));
+                if (trial === null || trial.generation !== Number(payload.state["generation"]))
+                    throw Error("That trial changed since this card was made. See Settings → Models.");
+                const done = stopTrial(store, trial.id, door, now);
+                if (!done.ok)
+                    throw Error(done.problem);
+                return { ok: true, taskId: null, said: "Trial stopped. New tasks build on the configured model.", href: `/settings/models?scope=${encodeURIComponent(repo)}#models-suggested` };
+            }
+            else if (payload.operation === "suggestion_not_now") {
+                // The rule door (route-store.ts proveRuleDoor) re-proves who says it: this computer's local owner only inside
+                // its `dismiss-suggestion` act, or the confirming person.
+                const door = currentLocalOwner() !== null ? { kind: "local-owner", actor } : { kind: "person", person: { actor: who.name, generation: who.generation, method: "session", live: () => true } };
+                const done = dismissSuggestion(store, { repo, id: String(payload.state["suggestion"]) }, door, now);
+                if (!done.ok)
+                    throw Error(done.problem);
+                return { ok: true, taskId: null, said: "Not now: this suggestion stays quiet for 30 days.", href: `/settings/models?scope=${encodeURIComponent(repo)}#models-suggested` };
+            }
             else if (payload.operation === "decision_record")
                 recordDecision(store, { repo, actor, draft: { claim: String(req["claim"]), why: String(req["why"]), sourceKind: "conversation",
                         ...(req["source"] === undefined ? {} : { sourceRef: String(req["source"]) }), ...(payload.state["supersedes"] === undefined ? {} : { supersedes: Number(payload.state["supersedes"]) }) } }, now);

package/dist/chat-decide.js

@@ -972,6 +972,8 @@ export function applyDecideFeedback(store, seat, prompt, text, repos, root, now)
     const revised = requestResultChanges(store, root, {
         run: prompt.run, batch: "", source: prompt.digest, actor: verified.who.name, repos: verified.who.repos,
         note: text, path: "", line: "", request: sha(`chat-decide:${seat.channel}:${prompt.id}`).slice(0, 32), allowMode: true,
+        // The chat's own verified person, answering "What should change?" in their own words.
+        origin: "person",
     }, now);
     if (!revised.ok)
         return { said: `Your feedback wasn't sent: ${revised.message}`, link: null };

package/dist/chat-review.d.ts

@@ -1,3 +1,4 @@
+import type { RevisionOrigin } from "./contracts/route-results.js";
 import type { Store } from "./store.js";
 import type { VerifiedApprover } from "./principal.js";
 import { type FeedbackImage } from "./result-review.js";
@@ -41,7 +42,7 @@ export declare function reviewInputProblem(note: string | null, path: string | n
 /** Chat and the result form write the same comments and call the same revision service.
  * A failed combined note+revision rolls back the note too; no half-completed action.
  */
-export declare function applyChatReview(store: Store, who: VerifiedApprover, evidenceRoot: string, request: ReviewRequest, now: Date, allowMode: boolean): {
+export declare function applyChatReview(store: Store, who: VerifiedApprover, evidenceRoot: string, request: ReviewRequest, now: Date, allowMode: boolean, origin: RevisionOrigin): {
     ok: true;
     taskId: string;
     run: number;

package/dist/chat-review.js

@@ -48,7 +48,7 @@ export function reviewInputProblem(note, path, line) {
 /** Chat and the result form write the same comments and call the same revision service.
  * A failed combined note+revision rolls back the note too; no half-completed action.
  */
-export function applyChatReview(store, who, evidenceRoot, request, now, allowMode) {
+export function applyChatReview(store, who, evidenceRoot, request, now, allowMode, origin) {
     try {
         return store.transact(() => store.savepoint(() => {
             const fail = (message) => { throw new ReviewRefusal(message); };
@@ -86,7 +86,7 @@ export function applyChatReview(store, who, evidenceRoot, request, now, allowMod
             if (batch.length === 0)
                 return fail("Add feedback or select saved notes before requesting changes.");
             const result = createResultRevision(store, evidenceRoot, {
-                run: live.run, batch: batch.join(","), source: live.source, actor: who.name, repos: who.repos, allowMode,
+                run: live.run, batch: batch.join(","), source: live.source, actor: who.name, repos: who.repos, allowMode, origin,
             }, now);
             if (!result.ok)
                 return fail(result.message);

package/dist/contracts/chat-actions.d.ts

@@ -252,6 +252,14 @@ export declare const chatActionRequestSchemas: {
         decision: z.ZodInt;
         reason: z.ZodString;
     }, z.core.$strict>;
+    readonly suggestion_not_now: z.ZodObject<{
+        repo: z.ZodString;
+        suggestion: z.ZodString;
+    }, z.core.$strict>;
+    readonly trial_stop: z.ZodObject<{
+        repo: z.ZodString;
+        trial: z.ZodInt;
+    }, z.core.$strict>;
     /** The line, and (from 1) the line it replaces; 0 or none adds it. */
     readonly lead_about_you: z.ZodObject<{
         line: z.ZodString;
@@ -331,12 +339,14 @@ export declare const sharedActionSchema: z.ZodObject<{
         subagent_state: "subagent_state";
         subagent_tools: "subagent_tools";
         subagent_undo: "subagent_undo";
+        suggestion_not_now: "suggestion_not_now";
         sweep_cancel_rest: "sweep_cancel_rest";
         sweep_file: "sweep_file";
         task_cancel: "task_cancel";
         task_resume: "task_resume";
         tool_add: "tool_add";
         tool_remove: "tool_remove";
+        trial_stop: "trial_stop";
     }>;
     request: z.ZodObject<{}, z.core.$catchall<z.ZodUnknown>>;
     repo: z.ZodString;

package/dist/contracts/chat-actions.js

@@ -81,6 +81,10 @@ export const chatActionRequestSchemas = {
     kit_setup: z.strictObject({ repo: words, kit: words }),
     decision_record: z.strictObject({ repo: words, claim: words, why: words, supersedes: id.optional(), source: words.optional() }),
     decision_retire: z.strictObject({ repo: words, decision: id, reason: words }),
+    // Results routing: Not now on a suggested cheaper model (accepting stays in Settings → Models, behind a step-up).
+    suggestion_not_now: z.strictObject({ repo: words, suggestion: words }),
+    // Slice 3: stopping a trial (starting one stays in Settings → Models, behind a step-up).
+    trial_stop: z.strictObject({ repo: words, trial: id }),
     /** The line, and (from 1) the line it replaces; 0 or none adds it. */
     lead_about_you: z.strictObject({ line: words, replaces: z.int().min(0).optional() }),
     scope_approve: z.strictObject({ task: words }),

package/dist/contracts/console-api.d.ts

@@ -112,6 +112,7 @@ export declare const CONSOLE_FORMS: {
     readonly appearance: FormContract<"accent" | "quiet" | "return" | "theme">;
     readonly models: FormContract<"enabled" | "tool">;
     readonly modelsChange: FormContract<"build" | "build-light" | "build-strong" | "change" | "digest" | "password" | "plan" | "plan-strong" | "preset" | "repair" | "review" | "review-strong" | "scope" | "switch" | "to">;
+    readonly modelsRules: FormContract<"id" | "password" | "rule" | "scope">;
     readonly knowledgeRefresh: FormContract<"repo">;
     readonly knowledgeProposal: FormContract<"decision" | "proposal" | "repo">;
     readonly knowledgeDecision: FormContract<"action" | "claim" | "decision" | "reason" | "repo" | "why">;

package/dist/contracts/console-api.js

@@ -124,6 +124,9 @@ export const CONSOLE_FORMS = {
     // preset or switch; the digest is what the page showed, and the change digest what the preview showed.
     modelsChange: formContract("POST /settings/models/agent, /settings/models/apply", ["password", "scope", "digest", "change", "preset", "switch", "to",
         "plan", "plan-strong", "build-light", "build", "build-strong", "repair", "review", "review-strong"]),
+    // Settings → Models → Suggested (results routing): the project, a suggestion's id or a rule's number, and the step-up
+    // password for accepting, keeping and switching suggestions on.
+    modelsRules: formContract("POST /settings/models/accept, /settings/models/keep, /settings/models/suggest-on, /settings/models/turn-off, /settings/models/not-now, /settings/models/suggest-off, /settings/models/try, /settings/models/stop", ["password", "scope", "id", "rule"]),
     knowledgeRefresh: formContract("POST /settings/knowledge/refresh", ["repo"]),
     knowledgeProposal: formContract("POST /settings/knowledge/proposal", ["repo", "decision", "proposal"]),
     knowledgeDecision: formContract("POST /settings/knowledge/decision", ["repo", "action", "claim", "why", "decision", "reason"]),

package/dist/contracts/route-results.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Result records (docs/plans/results-routing.md, slice 1): the words and shapes a task family's result record is kept
+ * and shown in. A policy path (release-auto.ts EVAL_POLICY): the states, reasons and the execution-class table decide
+ * what a cheaper model's evidence is, so a change to them needs a person.
+ */
+import { z } from "zod";
+/** A record's lifecycle. Only mature and rejected records are decided; pending and provisional never count anywhere. */
+export declare const RECORD_STATES: readonly ["pending", "provisional", "mature", "rejected", "not-counted"];
+export type RecordState = (typeof RECORD_STATES)[number];
+/** Why a record was rejected, in the order they are checked. */
+export declare const REJECT_REASONS: readonly ["model-failures", "task-failed", "cancelled-after-result", "high-finding", "person-revision", "proof-refuted", "check-failed"];
+/** Why a record is not counted. Never counted as good, never as 0. */
+export declare const NOT_COUNTED_REASONS: readonly ["before-records", "not-eligible", "mixed-cohort", "mixed-models", "model-not-reported", "infrastructure-only", "cancelled-before-result", "no-check", "check-unavailable", "touched-protected", "changed-files-unknown", "unanswered"];
+export type RejectReason = (typeof REJECT_REASONS)[number];
+export type NotCountedReason = (typeof NOT_COUNTED_REASONS)[number];
+export type RecordReason = RejectReason | NotCountedReason;
+/** The plain words for each reason. */
+export declare const REASON_WORDS: Readonly<Record<RecordReason, string>>;
+/** Why a run was refused a cohort before dispatch: any of these makes its record not counted ("not eligible"). */
+export declare const INELIGIBLE_REASONS: readonly ["no-sealed-route", "not-built-in", "large", "risky", "unsized", "strict", "evidence-demands", "automerge", "release", "protected"];
+export type IneligibleReason = (typeof INELIGIBLE_REASONS)[number];
+/** Who a revision came from (task_ref.revision_origin). Only `person` rejects a record. */
+export declare const REVISION_ORIGINS: readonly ["person", "automatic-review", "flow", "lead", "machine"];
+export type RevisionOrigin = (typeof REVISION_ORIGINS)[number];
+/** A failed run's execution class, kept before the tick normalizes its reason (run.exec_class). */
+export declare const EXEC_CLASSES: readonly ["model", "infrastructure"];
+export type ExecClass = (typeof EXEC_CLASSES)[number];
+/** The build leg's sealed selection, as a run's cohort keeps it (route v3 `selection`; earlier routes by `chosen`). */
+export declare const selectionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"rule">;
+    rule: z.ZodNumber;
+    ruleGeneration: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"trial">;
+    rule: z.ZodNumber;
+    reservation: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodEnum<{
+        configured: "configured";
+        override: "override";
+        pin: "pin";
+    }>;
+}, z.core.$strict>], "kind">;
+export type Selection = z.infer<typeof selectionSchema>;
+/** One record as `toolroll models results --json` returns it. */
+export declare const resultRecordSchema: z.ZodObject<{
+    task: z.ZodString;
+    repo: z.ZodNullable<z.ZodString>;
+    size: z.ZodNullable<z.ZodEnum<{
+        medium: "medium";
+        small: "small";
+    }>>;
+    provider: z.ZodNullable<z.ZodString>;
+    model: z.ZodNullable<z.ZodString>;
+    state: z.ZodEnum<{
+        mature: "mature";
+        "not-counted": "not-counted";
+        pending: "pending";
+        provisional: "provisional";
+        rejected: "rejected";
+    }>;
+    reason: z.ZodNullable<z.ZodEnum<{
+        "before-records": "before-records";
+        "cancelled-after-result": "cancelled-after-result";
+        "cancelled-before-result": "cancelled-before-result";
+        "changed-files-unknown": "changed-files-unknown";
+        "check-failed": "check-failed";
+        "check-unavailable": "check-unavailable";
+        "high-finding": "high-finding";
+        "infrastructure-only": "infrastructure-only";
+        "mixed-cohort": "mixed-cohort";
+        "mixed-models": "mixed-models";
+        "model-failures": "model-failures";
+        "model-not-reported": "model-not-reported";
+        "no-check": "no-check";
+        "not-eligible": "not-eligible";
+        "person-revision": "person-revision";
+        "proof-refuted": "proof-refuted";
+        "task-failed": "task-failed";
+        "touched-protected": "touched-protected";
+        unanswered: "unanswered";
+    }>>;
+    words: z.ZodString;
+    resultRun: z.ZodNullable<z.ZodNumber>;
+    acceptedAt: z.ZodNullable<z.ZodString>;
+    decidedAt: z.ZodNullable<z.ZodString>;
+    failures: z.ZodObject<{
+        model: z.ZodNumber;
+        infrastructure: z.ZodNumber;
+    }, z.core.$strict>;
+    spend: z.ZodObject<{
+        apiMicrousd: z.ZodNumber;
+        subscriptionRuns: z.ZodNumber;
+        subscriptionTokens: z.ZodNumber;
+        unknownRuns: z.ZodNumber;
+        remediationRuns: z.ZodNumber;
+    }, z.core.$strict>;
+    personRevisions: z.ZodNumber;
+    firstCheckPassed: z.ZodNullable<z.ZodBoolean>;
+    turns: z.ZodObject<{
+        known: z.ZodNumber;
+        unknownRuns: z.ZodNumber;
+    }, z.core.$strict>;
+    closed: z.ZodBoolean;
+    selections: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"rule">;
+        rule: z.ZodNumber;
+        ruleGeneration: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"trial">;
+        rule: z.ZodNumber;
+        reservation: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodEnum<{
+            configured: "configured";
+            override: "override";
+            pin: "pin";
+        }>;
+    }, z.core.$strict>], "kind">>;
+}, z.core.$strict>;
+export type ResultRecordView = z.infer<typeof resultRecordSchema>;

package/dist/contracts/route-results.js

@@ -0,0 +1,71 @@
+/**
+ * Result records (docs/plans/results-routing.md, slice 1): the words and shapes a task family's result record is kept
+ * and shown in. A policy path (release-auto.ts EVAL_POLICY): the states, reasons and the execution-class table decide
+ * what a cheaper model's evidence is, so a change to them needs a person.
+ */
+import { z } from "zod";
+/** A record's lifecycle. Only mature and rejected records are decided; pending and provisional never count anywhere. */
+export const RECORD_STATES = ["pending", "provisional", "mature", "rejected", "not-counted"];
+/** Why a record was rejected, in the order they are checked. */
+export const REJECT_REASONS = ["model-failures", "task-failed", "cancelled-after-result", "high-finding", "person-revision", "proof-refuted", "check-failed"];
+/** Why a record is not counted. Never counted as good, never as 0. */
+export const NOT_COUNTED_REASONS = [
+    "before-records", "not-eligible", "mixed-cohort", "mixed-models", "model-not-reported", "infrastructure-only", "cancelled-before-result",
+    "no-check", "check-unavailable", "touched-protected", "changed-files-unknown", "unanswered",
+];
+/** The plain words for each reason. */
+export const REASON_WORDS = Object.freeze({
+    "model-failures": "two or more attempts failed on the model's own account",
+    "task-failed": "the task failed",
+    "cancelled-after-result": "it was cancelled after a result",
+    "high-finding": "the automatic review found a serious problem",
+    "person-revision": "a person asked for changes",
+    "proof-refuted": "its evidence didn't match the changes",
+    "check-failed": "its checks failed",
+    "before-records": "started before results were recorded",
+    "not-eligible": "not a small or routine task with default checks",
+    "mixed-cohort": "its attempts ran under different task sizes or settings",
+    "mixed-models": "its attempts ran on different models",
+    "model-not-reported": "the provider didn't report the model",
+    "infrastructure-only": "it failed only for reasons outside the model",
+    "cancelled-before-result": "it was cancelled before a result",
+    "no-check": "no checks configured",
+    "check-unavailable": "its check result can't be read",
+    "touched-protected": "touched protected files",
+    "changed-files-unknown": "changed files unknown",
+    "unanswered": "no answer in 30 days",
+});
+/** Why a run was refused a cohort before dispatch: any of these makes its record not counted ("not eligible"). */
+export const INELIGIBLE_REASONS = ["no-sealed-route", "not-built-in", "large", "risky", "unsized", "strict", "evidence-demands", "automerge", "release", "protected"];
+/** Who a revision came from (task_ref.revision_origin). Only `person` rejects a record. */
+export const REVISION_ORIGINS = ["person", "automatic-review", "flow", "lead", "machine"];
+/** A failed run's execution class, kept before the tick normalizes its reason (run.exec_class). */
+export const EXEC_CLASSES = ["model", "infrastructure"];
+/** The build leg's sealed selection, as a run's cohort keeps it (route v3 `selection`; earlier routes by `chosen`). */
+export const selectionSchema = z.discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("rule"), rule: z.number().int().positive(), ruleGeneration: z.number().int().positive() }),
+    z.strictObject({ kind: z.literal("trial"), rule: z.number().int().positive(), reservation: z.number().int().positive() }),
+    z.strictObject({ kind: z.enum(["configured", "override", "pin"]) }),
+]);
+/** One record as `toolroll models results --json` returns it. */
+export const resultRecordSchema = z.strictObject({
+    task: z.string(),
+    repo: z.string().nullable(),
+    size: z.enum(["small", "medium"]).nullable(),
+    provider: z.string().nullable(),
+    model: z.string().nullable(),
+    state: z.enum(RECORD_STATES),
+    reason: z.enum([...REJECT_REASONS, ...NOT_COUNTED_REASONS]).nullable(),
+    words: z.string(),
+    resultRun: z.number().int().nullable(),
+    acceptedAt: z.string().nullable(),
+    decidedAt: z.string().nullable(),
+    failures: z.strictObject({ model: z.number().int(), infrastructure: z.number().int() }),
+    spend: z.strictObject({ apiMicrousd: z.number().int(), subscriptionRuns: z.number().int(), subscriptionTokens: z.number().int(), unknownRuns: z.number().int(), remediationRuns: z.number().int() }),
+    /** Counts that keep accumulating after the verdict is final, until the record closes. */
+    personRevisions: z.number().int(),
+    firstCheckPassed: z.boolean().nullable(),
+    turns: z.strictObject({ known: z.number().int(), unknownRuns: z.number().int() }),
+    closed: z.boolean(),
+    selections: z.array(selectionSchema),
+});