toolroll 0.9.91 → 0.9.93

package/dist/check-facts.js

@@ -0,0 +1,272 @@
+/**
+ * Check facts (docs/plans/learning-loops.md, "Foundation: check facts"): what each settled check ran under and what it
+ * reported, recorded at disposition, never trusted for authority. The only writer of `check_fact` and `check_result`
+ * (the v149 migration aside); release-auto's learning scan (eval-hooks.ts learningWriteProblem) needs a person for
+ * SQL that writes them from anywhere else. A policy path (release-auto.ts EVAL_POLICY): any change needs a person.
+ *
+ * - Conditions are captured when the check's command starts (captureCheckConditions, called from the builder's
+ *   runVerification), held in memory and passed here: the commit's tree read through verified objects (never the
+ *   checkout), the approved command's digest, the check's access, the harness digest and lockfile, and the values of
+ *   every environment variable the check inherits (the setup allowlist), hashed with checkContextOf's fields as
+ *   `conditions_digest`. Not re-read later.
+ * - Results are tagged by source: `receipt` (the plane's own whole-check result: trusted for "the check passed or
+ *   failed", nothing finer), `report` (the candidate-written report's lines), `log` (Vitest's FAIL lines in the sealed
+ *   log, failures only, file level) and `learn` (the advisory learning line). Every failure is recorded; the check's
+ *   blocking failure is the check's and is never changed here.
+ * - Explicit execution evidence is a `report` or `learn` line naming an identity. No line is no evidence: never
+ *   skipped, removed or passed.
+ * - Fail closed: an unreadable tree, or conditions never captured (the command never started), records the fact row
+ *   with no conditions and no results at all.
+ *
+ * Nothing here changes a check's outcome, a verdict, an approval or a rerun: every reader of a check's outcome reads
+ * the receipt and run_check, which this module never writes.
+ */
+import { createHash } from "node:crypto";
+import { failingTestsOf } from "./gate-failure.js";
+import { checkContextOf, projectGitDir, treeFactsOf } from "./check-report.js";
+import { readVerifiedArtifact } from "./evidence.js";
+import { CHECK_REPORT_PREFIX, isExactCase, learnLineSchema, learnRequest, LEARN_MAX_BYTES, LEARN_PREFIX } from "./contracts/release-check.js";
+import { nightlyTaskRef, releaseTaskRef } from "./store.js";
+/** The sources a result can come from, and the states it can have. */
+export const CHECK_RESULT_SOURCES = Object.freeze(["receipt", "report", "log", "learn"]);
+/** The receipt's whole-check identity, and the one a failed check with nothing else named records. */
+export const WHOLE_CHECK = "check";
+export const UNEXPLAINED = "unexplained";
+/** How many result rows one check records at most (a report's own bounds are far above any real check). */
+export const MAX_RESULTS_PER_CHECK = 20_000;
+/** How old a tracked observation may be and still be asked about (docs/plans/learning-loops.md, 90-day window). */
+export const OBSERVATION_WATCH_MS = 90 * 24 * 60 * 60 * 1000;
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+/**
+ * The conditions a check's command starts under: its commit's verified tree facts, the approved command's digest, its
+ * access, and the values of `envNames` (the variables the check inherits, builder.ts SETUP_ENV_ALLOWLIST) as this
+ * process holds them now — what the command is given. Hashed with checkContextOf's fields; the class reads
+ * `<platform>-<arch>-node<major>`. Values are hashed, never stored.
+ */
+export function captureCheckConditions(input) {
+    const none = (problem) => ({ head: input.head, tree: null, commandDigest: input.command.digest, access: input.access, harnessDigest: null, lockfile: null, conditionsDigest: null, conditionsClass: null, problem });
+    if (input.repo === null)
+        return none("the check's project isn't recorded");
+    const gitDir = projectGitDir(input.repo);
+    if (gitDir === null)
+        return none("the project's Git directory can't be read");
+    let read;
+    // Advisory: whatever happens reading the tree, the check itself is never stopped by it.
+    try {
+        read = treeFactsOf(gitDir, input.head);
+    }
+    catch (error) {
+        return none(`the checked commit can't be read from verified objects (${error instanceof Error ? error.message : String(error)})`);
+    }
+    if (!read.ok)
+        return none(`the checked commit can't be read from verified objects (${read.problem})`);
+    const context = checkContextOf(read.facts, input.command, input.access);
+    const env = input.env ?? process.env;
+    const environment = Object.fromEntries([...new Set(input.envNames)].sort().map(name => [name, env[name] ?? null]));
+    const digest = sha256(JSON.stringify({ version: 1, context, environment }));
+    const major = /^v?(\d+)/.exec(context.node)?.[1] ?? "unknown";
+    return { head: input.head, tree: read.facts.tree, commandDigest: input.command.digest, access: input.access, harnessDigest: read.facts.harnessDigest, lockfile: read.facts.lockfile,
+        conditionsDigest: digest, conditionsClass: `${context.platform}-${context.arch}-node${major}`, problem: null };
+}
+/** Why the task's check ran: a release's or the nightly's purpose, read from the plane's own records. */
+export function checkPurposeOf(store, taskRef) {
+    if (nightlyTaskRef(store, taskRef))
+        return "nightly";
+    if (releaseTaskRef(store, taskRef))
+        return "release";
+    const terms = store.handle.prepare(`SELECT s.release_terms_json, s.release_check_json FROM task_scope s JOIN task_ref r ON r.external_id = s.task_id AND r.backend = 'built-in' WHERE r.id = ?`).get(taskRef);
+    return terms !== undefined && (terms["release_terms_json"] != null || terms["release_check_json"] != null) ? "release" : "ordinary";
+}
+/** The advisory learning line of a check's output, read strictly: exactly one line carrying this run's nonce, at most
+ * 64 KiB, before the report, matching its contract, naming only requested exact cases, each once. Anything else is
+ * not recorded, with why; that loses learning evidence only. */
+export function learningLinesOf(stdout, nonce, asked) {
+    const lines = stdout.split("\n");
+    let reportAt = -1;
+    for (let at = lines.length - 1; at >= 0; at--)
+        if (lines[at].startsWith(CHECK_REPORT_PREFIX)) {
+            reportAt = at;
+            break;
+        }
+    const ours = [];
+    let oversized = false, others = false, unreadable = false;
+    lines.forEach((line, at) => {
+        if (!line.startsWith(LEARN_PREFIX))
+            return;
+        if (Buffer.byteLength(line) > LEARN_MAX_BYTES) {
+            oversized = true;
+            return;
+        }
+        let value;
+        try {
+            value = JSON.parse(line.slice(LEARN_PREFIX.length));
+        }
+        catch {
+            unreadable = true;
+            return;
+        }
+        if (value === null || typeof value !== "object" || value["nonce"] !== nonce) {
+            others = true;
+            return;
+        }
+        ours.push({ at, value });
+    });
+    if (ours.length === 0)
+        return { ok: false, why: oversized ? "the learning line was over 64 KiB" : unreadable ? "the learning line couldn't be read" : others ? "no learning line carried this run's nonce" : "the check printed no learning line" };
+    if (ours.length > 1)
+        return { ok: false, why: "the check printed more than one learning line" };
+    if (oversized)
+        return { ok: false, why: "a learning line was over 64 KiB" };
+    const only = ours[0];
+    if (reportAt >= 0 && only.at > reportAt)
+        return { ok: false, why: "the learning line came after the report" };
+    const read = learnLineSchema.safeParse(only.value);
+    if (!read.success)
+        return { ok: false, why: "the learning line doesn't match its contract" };
+    const wanted = new Set(asked);
+    const seen = new Set();
+    for (const one of read.data.results) {
+        if (!wanted.has(one.identity) || !isExactCase(one.identity))
+            return { ok: false, why: "the learning line named an identity it wasn't asked about" };
+        if (seen.has(one.identity))
+            return { ok: false, why: "the learning line named an identity twice" };
+        seen.add(one.identity);
+    }
+    return { ok: true, results: read.data.results };
+}
+const RANK = { passed: 0, skipped: 1, "passed-on-retry": 2, failed: 3 };
+/** The report's lines as results: every case it names; a file, group, version or part only when it didn't simply pass. */
+export function reportResults(report) {
+    const rows = [];
+    const add = (identity, state) => rows.push({ identity, state, source: "report" });
+    for (const one of report.units?.identities ?? [])
+        add(`unit:${one.file}::${one.name}`, one.state === "passed" && one.flaky ? "passed-on-retry" : one.state);
+    for (const one of report.units?.files ?? []) {
+        if (one.state !== "passed")
+            add(`file:${one.file}`, one.state);
+        else if (one.flaky)
+            add(`file:${one.file}`, "passed-on-retry");
+    }
+    for (const run of report.journeys)
+        for (const group of run.groups) {
+            if (group.state === "failed")
+                add(`group:${run.script}:${run.kind}:${group.group}`, "failed");
+            else if (group.state === "passed" && group.retried)
+                add(`group:${run.script}:${run.kind}:${group.group}`, "passed-on-retry");
+            if (group.state === "not-run")
+                continue;
+            for (const journey of group.journeys)
+                add(`journey:${run.script}:${run.kind}:${group.group}::${journey.name}`, journey.state === "passed" && group.retried ? "passed-on-retry" : journey.state);
+        }
+    for (const one of report.upgrades?.versions ?? [])
+        if (one.state === "failed")
+            add(`upgrade:${one.version}`, "failed");
+    for (const part of report.parts)
+        if (part.selected && part.ran && (part.code !== 0 || part.timedOut))
+            add(`part:${part.part}`, "failed");
+    return rows;
+}
+/** The sealed log's FAIL lines (Vitest), failures only, file level; nothing when the log's own count disagrees. */
+function logResults(store, root, runId) {
+    const logs = store.artifactsFor(runId).filter(one => one.kind === "check-log");
+    if (logs.length !== 1)
+        return [];
+    const read = readVerifiedArtifact(root, logs[0]);
+    if (!read.ok)
+        return [];
+    const failing = failingTestsOf(read.content.toString("utf8")) ?? [];
+    return failing.filter(one => /^(?!\/)(?!.*(?:^|\/)\.\.?(?:\/|$))[^\u0000-\u001f\\]{1,512}$/.test(one.file)).map(one => ({ identity: `file:${one.file}`, state: "failed", source: "log" }));
+}
+/**
+ * Record what a settled check ran under and reported, once (first write wins), in one transaction: its fact row and
+ * every result row. Called at disposition by the builder right after it records the check's own outcome. Advisory:
+ * nothing reads these for a verdict, a rerun or an approval.
+ */
+export function recordCheckFacts(store, root, input) {
+    const conditions = input.conditions;
+    const comparable = conditions !== null && conditions.tree !== null && conditions.conditionsDigest !== null;
+    const asked = input.attempt === null ? [] : learnRequest(input.attempt.learn);
+    let learnState = asked.length === 0 ? "not-asked" : "not-recorded";
+    let learnWhy = null;
+    const rows = [];
+    if (comparable) {
+        if (input.receipt.status !== "not-run")
+            rows.push({ identity: WHOLE_CHECK, state: input.receipt.status, source: "receipt" });
+        if (input.report !== null)
+            rows.push(...reportResults(input.report));
+        rows.push(...logResults(store, root, input.runId));
+    }
+    if (asked.length > 0) {
+        if (!comparable)
+            learnWhy = conditions === null ? "the check's command never started" : conditions.problem ?? "the check's conditions weren't recorded";
+        else if (input.stdout === null || input.attempt === null)
+            learnWhy = "the check's output wasn't kept";
+        else {
+            const learned = learningLinesOf(input.stdout, input.attempt.nonce, asked);
+            if (!learned.ok)
+                learnWhy = learned.why;
+            else {
+                learnState = "recorded";
+                for (const one of learned.results)
+                    rows.push({ identity: one.identity, state: one.state, source: "learn" });
+            }
+        }
+    }
+    if (comparable && input.receipt.status === "failed" && !rows.some(one => one.source !== "receipt" && one.state === "failed"))
+        rows.push({ identity: UNEXPLAINED, state: "failed", source: "receipt" });
+    // One row per (identity, source), its worst state; bounded.
+    const kept = new Map();
+    for (const row of rows) {
+        if (row.identity.length < 1 || row.identity.length > 2600)
+            continue;
+        const key = `${row.source}\u0000${row.identity}`;
+        const before = kept.get(key);
+        if (before === undefined || RANK[row.state] > RANK[before.state])
+            kept.set(key, row);
+    }
+    const at = input.now.toISOString();
+    store.transact(() => {
+        const inserted = store.handle.prepare(`INSERT INTO check_fact (run, repo, task_ref, head, tree, command_digest, access, harness_digest, lockfile, conditions_digest,
+        conditions_class, purpose, learn_state, learn_why, recorded_at) SELECT id, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ? FROM run WHERE id = ?
+      ON CONFLICT (run) DO NOTHING`).run(input.repo, input.taskRef, conditions?.head ?? null, comparable ? conditions.tree : null, conditions?.commandDigest ?? null, conditions?.access ?? null, comparable ? conditions.harnessDigest : null, comparable ? conditions.lockfile : null, comparable ? conditions.conditionsDigest : null, comparable ? conditions.conditionsClass : null, checkPurposeOf(store, input.taskRef), learnState, learnState === "not-recorded" ? learnWhy ?? "not recorded" : null, at, input.runId);
+        if (Number(inserted.changes) !== 1)
+            return;
+        const insert = store.handle.prepare("INSERT INTO check_result (run, identity, state, source, recorded_at) VALUES (?, ?, ?, ?, ?)");
+        for (const row of [...kept.values()].slice(0, MAX_RESULTS_PER_CHECK))
+            insert.run(input.runId, row.identity, row.state, row.source, at);
+    });
+}
+export function checkFactOf(store, runId) {
+    const row = store.handle.prepare("SELECT * FROM check_fact WHERE run = ?").get(runId);
+    if (row === undefined)
+        return null;
+    const text = (key) => row[key] === null ? null : String(row[key]);
+    return { run: Number(row["run"]), repo: text("repo"), taskRef: Number(row["task_ref"]), head: text("head"), tree: text("tree"), commandDigest: text("command_digest"), access: text("access"),
+        harnessDigest: text("harness_digest"), lockfile: text("lockfile"), conditionsDigest: text("conditions_digest"), conditionsClass: text("conditions_class"),
+        purpose: String(row["purpose"]), learnState: String(row["learn_state"]), learnWhy: text("learn_why"), recordedAt: String(row["recorded_at"]) };
+}
+/** A check's recorded results, by source then identity. */
+export function checkResultsOf(store, runId) {
+    return store.handle.prepare("SELECT identity, state, source FROM check_result WHERE run = ? ORDER BY source, identity").all(runId)
+        .map(row => ({ identity: String(row["identity"]), state: String(row["state"]), source: String(row["source"]) }));
+}
+/**
+ * What a project's Full checks are asked about for learning (`learn`): its tracked identities (learning_watch) — an
+ * accepted note's until it ends, an observation's for 90 days — exact cases only, the most recently tracked first, at
+ * most 200. Those left out are counted (`leftOut`): a coverage gap, said, never hidden.
+ */
+export function learnRequestFor(store, repo, now) {
+    const since = new Date(now.getTime() - OBSERVATION_WATCH_MS).toISOString();
+    let tracked;
+    // Advisory: a read that fails asks about nothing, and the check runs as it would have.
+    try {
+        tracked = store.handle.prepare(`SELECT identity, MAX(since) AS latest FROM learning_watch
+      WHERE repo = ? AND ((reason = 'note' AND until IS NULL) OR (reason = 'observation' AND since >= ?))
+      GROUP BY identity ORDER BY latest DESC, identity`).all(repo, since).map(row => String(row["identity"])).filter(isExactCase);
+    }
+    catch {
+        return { learn: [], leftOut: 0 };
+    }
+    const learn = learnRequest(tracked);
+    return { learn, leftOut: tracked.length - learn.length };
+}

package/dist/check-report.d.ts

@@ -88,6 +88,8 @@ export type PreparedAttempt = {
     snapshot: ObligationSnapshot | null;
     /** The identities the check was asked to report one by one (required ones). */
     watch: string[];
+    /** The exact cases the check was asked about for learning only (docs/plans/learning-loops.md): never gate evidence. */
+    learn: string[];
 };
 /** A Full check's preparation refused (eval-harness review 2, finding 4): the plane recorded a release whose commit it
  * can't verify now, so the check's obligations can't be decided. The check isn't run (builder.ts: `baseline-unverifiable`). */
@@ -112,6 +114,9 @@ export declare function prepareCheckAttempt(store: Store, root: string, input: {
     /** A release's check (signed release terms or a release authority): CI never stands in for its unit suite. Sealed in
      * the inventory (whose digest the attempt row holds); only an explicit false lets CI stand in. */
     release?: boolean;
+    /** Exact cases asked about for learning only (docs/plans/learning-loops.md): a separate handshake field, at most 200,
+     * that never joins `watch`, the inventory or anything the check owes. */
+    learn?: readonly string[];
 }, now: Date): PreparedAttempt | null;
 /** Seal one JSON payload as a structured-output artifact under its capture label. */
 export declare function sealJson(store: Store, root: string, runId: number, name: string, value: unknown, capture: string, now: Date): number;

package/dist/check-report.js

@@ -21,7 +21,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { lstatSync, realpathSync } from "node:fs";
 import { join } from "node:path";
 import { readVerifiedCommit, verifiedBlobs, verifiedTreeEntries } from "./commit-extract.js";
-import { CHECK_PARTS, CHECK_REPORT_MAX_BYTES, CHECK_REPORT_PREFIX, readCheckReport, } from "./contracts/release-check.js";
+import { CHECK_PARTS, CHECK_REPORT_MAX_BYTES, CHECK_REPORT_PREFIX, learnRequest, readCheckReport, } from "./contracts/release-check.js";
 import { readVerifiedArtifact, storeEvidence } from "./evidence.js";
 import { releaseBaselineRecord } from "./release-card.js";
 import { checkAttemptOf, recordCheckAttempt } from "./store.js";
@@ -219,8 +219,9 @@ export function prepareCheckAttempt(store, root, input, now) {
     // The command's own limit rides along, so the check ends itself (logs and report printed) before the plane stops it.
     // `reportBytes`: the largest report this plane reads back once sealed. A plane that doesn't say (0.9.77 and older) reads
     // only 64 KiB, so the check gives it no larger report rather than one that poisons the receipt (scripts/release-check.mjs).
-    const stdin = JSON.stringify({ nonce, mode, plan, watch: [...(input.watch ?? [])], limitMs: input.command.timeoutMs, reportBytes: CHECK_ARTIFACT_CAP, ...(plan === null ? { owed, ciSubstitute } : {}) });
-    return { runId: input.runId, nonce, stdin, mode, inventory, context, plan, snapshot, watch: [...(input.watch ?? [])] };
+    const learn = learnRequest(input.learn ?? []);
+    const stdin = JSON.stringify({ nonce, mode, plan, watch: [...(input.watch ?? [])], limitMs: input.command.timeoutMs, reportBytes: CHECK_ARTIFACT_CAP, ...(plan === null ? { owed, ciSubstitute } : {}), ...(learn.length > 0 ? { learn } : {}) });
+    return { runId: input.runId, nonce, stdin, mode, inventory, context, plan, snapshot, watch: [...(input.watch ?? [])], learn };
 }
 /** Seal one JSON payload as a structured-output artifact under its capture label. */
 export function sealJson(store, root, runId, name, value, capture, now) {

package/dist/cli.js

@@ -113,6 +113,8 @@ export const OPERATE_COMMANDS = new Set([
     "evals",
     // Only `lead token` reaches here; the central service's lead verbs answer first.
     "lead",
+    // Only `release approve` reaches here: every other `release` form is release-cli.ts, routed before this set.
+    "release",
     "onboard",
     "status",
     "ready",
@@ -344,6 +346,9 @@ async function dispatch(argv, write, mainOptions) {
     }
     if (first === "update")
         return (await import("./toolroll-update-cli.js")).runUpdateCommand(rest, write, mainOptions.update);
+    // `toolroll release approve`: a person's approval, with the operate commands' own credential prompt and context.
+    if (first === "release" && rest[0] === "approve")
+        return runOperate("release", rest, write, mainOptions.operate ?? {});
     if (first === "release") {
         const { runReleaseCommand } = await import("./release-cli.js");
         return runReleaseCommand(rest, write, { releaseLease: lease => runOperate("worker", ["release", ...lease], write, mainOptions.operate ?? {}), ...mainOptions.release });

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">;
@@ -149,7 +150,7 @@ export declare const CONSOLE_FORMS: {
     readonly peopleRevoke: FormContract<"name" | "token">;
     readonly runnerRetire: FormContract<"name" | "token">;
     readonly decisionAnswer: FormContract<"choice" | "confirm" | "note" | "return">;
-    readonly confirmStopped: FormContract<"checked" | "return" | "run" | "token">;
+    readonly recheckStopped: FormContract<"return" | "run">;
     readonly merge: FormContract<"anyway" | "run" | "token">;
     readonly onboard: FormContract<"big-ok" | "nonce" | "repo" | "root" | "token">;
     readonly pushSubscribe: FormContract<"auth" | "endpoint" | "p256dh" | "token">;
@@ -198,7 +199,7 @@ export declare const CONSOLE_FORMS: {
     readonly taskCancel: FormContract<"reason">;
     readonly taskRoute: FormContract<"agent" | "clear-phase" | "model" | "phase" | "provider" | "return" | "risky" | "sawDigest" | "size">;
     readonly taskScope: FormContract<"acceptance" | "budget-microusd" | "budget-usd" | "goal" | "goal-brief" | "not" | "permission-mode" | "quality-mode" | "requirement" | "requirement-new" | "sawDigest" | "touches">;
-    readonly taskApprove: FormContract<"digest" | "nonce" | "rebuild" | "return" | "token">;
+    readonly taskApprove: FormContract<"digest" | "nonce" | "rebuild" | "return" | "sheet" | "token">;
     readonly taskAcceptProof: FormContract<"note" | "return" | "run">;
     readonly taskComplete: FormContract<"accept" | "note" | "publish" | "receipt" | "return" | "run">;
     readonly taskStop: FormContract<"return" | "run">;

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"]),
@@ -162,7 +165,7 @@ export const CONSOLE_FORMS = {
     peopleRevoke: formContract("POST /people/revoke", ["token", "name"]),
     runnerRetire: formContract("POST /fleet/runner/retire", ["token", "name"]),
     decisionAnswer: formContract("POST /d/<id>/answer", ["return", "choice", "confirm", "note"]),
-    confirmStopped: formContract("POST /t/<task>/confirm-stopped", ["run", "token", "checked", "return"]),
+    recheckStopped: formContract("POST /t/<task>/recheck-stopped", ["run", "return"]),
     merge: formContract("POST /t/<task>/merge", ["run", "token", "anyway"]),
     onboard: formContract("POST /projects/onboard-preview, /projects/onboard-confirm", ["repo", "root", "token", "nonce", "big-ok"]),
     pushSubscribe: formContract("POST /push/subscribe", ["token", "endpoint", "p256dh", "auth"]),
@@ -214,7 +217,7 @@ export const CONSOLE_FORMS = {
     taskCancel: formContract("POST /t/<task>/cancel", ["reason"]),
     taskRoute: formContract("POST /t/<task>/route", ["size", "risky", "phase", "clear-phase", "agent", "provider", "model", "sawDigest", "return"]),
     taskScope: formContract("POST /t/<task>/scope", ["sawDigest", "permission-mode", "quality-mode", "budget-usd", "budget-microusd", "requirement", "requirement-new", "goal-brief", "goal", "not", "touches", "acceptance"]),
-    taskApprove: formContract("POST /t/<task>/approve", ["return", "digest", "token", "nonce", "rebuild"]),
+    taskApprove: formContract("POST /t/<task>/approve", ["return", "digest", "token", "nonce", "rebuild", "sheet"]),
     taskAcceptProof: formContract("POST /t/<task>/accept-proof", ["run", "note", "return"]),
     taskComplete: formContract("POST /t/<task>/complete", ["receipt", "run", "accept", "note", "publish", "return"]),
     taskStop: formContract("POST /t/<task>/stop", ["run", "return"]),

package/dist/contracts/release-check.d.ts

@@ -233,7 +233,9 @@ export declare const obligationSnapshotSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type ObligationSnapshot = z.infer<typeof obligationSnapshotSchema>;
-/** What the plane writes on the check's stdin before closing it. */
+/** What the plane writes on the check's stdin before closing it. `learn` (docs/plans/learning-loops.md) is advisory and
+ * apart from everything else: exact case identities the check is asked to say it ran, on their own line
+ * (LEARN_PREFIX), never in the report and never part of what the check owes. */
 export type CheckHandshake = {
     nonce: string;
     mode: "full" | "targeted";
@@ -241,7 +243,29 @@ export type CheckHandshake = {
     watch: string[];
     owed?: CheckPart[];
     ciSubstitute?: boolean;
+    learn?: string[];
 };
+/** The advisory learning line a check prints before its report: `TOOLROLL-LEARN <json>`, at most 64 KiB, holding only
+ * the requested identities that ran. Never part of the report: buildReport, reportLine and fullCheckProblem don't read
+ * it, and a missing, malformed or oversized one loses learning evidence only. */
+export declare const LEARN_PREFIX = "TOOLROLL-LEARN ";
+export declare const LEARN_MAX_BYTES: number;
+export declare const LEARN_MAX_IDENTITIES = 200;
+export declare const isExactCase: (identity: unknown) => identity is string;
+/** What the plane asks a check to report for learning: exact cases only, first seen first, at most 200. */
+export declare function learnRequest(identities: readonly unknown[]): string[];
+export declare const learnLineSchema: z.ZodObject<{
+    nonce: z.ZodString;
+    results: z.ZodArray<z.ZodObject<{
+        identity: z.ZodString;
+        state: z.ZodEnum<{
+            failed: "failed";
+            passed: "passed";
+            skipped: "skipped";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type LearnLine = z.infer<typeof learnLineSchema>;
 /** A unit test: its file and full name. */
 export declare const unitIdentity: (file: string, testName: string) => string;
 /** A unit file. */

package/dist/contracts/release-check.js

@@ -146,6 +146,25 @@ export const obligationSnapshotSchema = versioned(1, {
     base: z.int().min(1),
     earlier: z.array(z.strictObject({ run: z.int().min(1), reportDigest: z.string().max(64).nullable(), failed: z.array(z.string().min(1).max(2600)).max(5000) })).max(200),
 });
+// ------------------------------------------------------------------ advisory learning lines (docs/plans/learning-loops.md)
+/** The advisory learning line a check prints before its report: `TOOLROLL-LEARN <json>`, at most 64 KiB, holding only
+ * the requested identities that ran. Never part of the report: buildReport, reportLine and fullCheckProblem don't read
+ * it, and a missing, malformed or oversized one loses learning evidence only. */
+export const LEARN_PREFIX = "TOOLROLL-LEARN ";
+export const LEARN_MAX_BYTES = 64 * 1024;
+export const LEARN_MAX_IDENTITIES = 200;
+/** An exact case: a unit test (`unit:<file>::<name>`) or a journey (`journey:<script>:<kind>:<group>::<name>`), never a
+ * file, group, part or version; one line, no control characters, at most 2600 characters. */
+const EXACT_CASE = /^(?:unit:[^\u0000-\u001f\\:][^\u0000-\u001f\\]*?::[^\u0000-\u001f]+|journey:(?:app|flows):(?:scripted|real):[A-Za-z0-9._/-]{1,200}::[^\u0000-\u001f]+)$/;
+export const isExactCase = (identity) => typeof identity === "string" && identity.length <= 2600 && EXACT_CASE.test(identity);
+/** What the plane asks a check to report for learning: exact cases only, first seen first, at most 200. */
+export function learnRequest(identities) {
+    return [...new Set(identities.filter(isExactCase))].slice(0, LEARN_MAX_IDENTITIES);
+}
+export const learnLineSchema = z.strictObject({
+    nonce: hex64,
+    results: z.array(z.strictObject({ identity: z.string().min(1).max(2600), state: z.enum(["passed", "failed", "skipped"]) })).max(LEARN_MAX_IDENTITIES),
+});
 // ------------------------------------------------------------------ identities
 /** A unit test: its file and full name. */
 export const unitIdentity = (file, testName) => `unit:${file}::${testName}`;

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>;