toolroll 0.9.92 → 0.9.93

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/desktop-update.d.ts

@@ -74,8 +74,8 @@ export declare function desktopUpdateWaitingOf(databaseFile: string, inTheWay: (
 /** The same settling reconcile the background worker runs: a finished run's leftover record of a process that never
  * started settles once the run's process groups are proven gone. A record nothing can prove either way stays. */
 export declare function settleLeftoverRecords(db: DatabaseSync, now: Date): number;
-/** Store.stopQuiescenceProblem's reasons, said for a person: no internal terms, and `toolroll run settle` only where it
- * can clear the record (it refuses while anything of the run is alive). */
+/** Store.stopQuiescenceProblem's reasons, said for a person: no internal terms. Nobody vouches that a run stopped:
+ * Toolroll proves it itself (stop-proof.ts), and `toolroll run settle` only has it look again now. */
 export declare function plainLingering(fallbackRun: number, problem: string): LingeringRun;
 export declare function previewDesktopUpdate(stateDir: string, installed: string, candidate: string, label: string, hooks?: UpdateHooks): Promise<{
     old: DesktopBundle;

package/dist/desktop-update.js

@@ -193,11 +193,11 @@ export function lingeringWork(db) {
     const lingering = lingeringRun(db);
     return lingering && lingeringWords(lingering);
 }
-export const lingeringWords = (l) => l.action ? `${l.on}. If nothing of it is running, run: ${l.action}` : `${l.on}.`;
+export const lingeringWords = (l) => l.action ? `${l.on}. To have Toolroll check again, run: ${l.action}` : `${l.on}.`;
 /** What an update says when it stops waiting on `l`: what is in the way, the command, and that new work resumed. */
 export const stoppedWaitingWords = (l) => `Stopped waiting after 2 minutes. ${l.on}. ${clearWords(l)} New work resumed; nothing was changed.`;
 /** The next step once an update has stopped on `l`. */
-export const clearWords = (l) => l.action ? `If nothing of it is running, run ${l.action}, then update again.` : "Update again once it has stopped.";
+export const clearWords = (l) => l.action ? `To have Toolroll check again, run ${l.action}, then update again.` : "Update again once it has stopped.";
 export function updateWaitingWords(o) {
     const { app, version, stopped, lingering: l } = o;
     const update = `${app ? "App update" : "Update"} to ${version}`;
@@ -206,7 +206,7 @@ export function updateWaitingWords(o) {
         const words = `${update} is waiting for ${on}. New work is paused.`;
         return { app, version, stopped: false, run: null, on, action: null, words, short: words };
     }
-    const next = l.action ? ` If nothing of it is running, run ${l.action}${stopped ? ", then update again" : ""}.` : stopped ? " Update again once it has stopped." : "";
+    const next = l.action ? ` To have Toolroll check again, run ${l.action}${stopped ? ", then update again" : ""}.` : stopped ? " Update again once it has stopped." : "";
     return { app, version, stopped, run: l.run, on: l.on, action: l.action,
         words: `${update} ${stopped ? "stopped waiting" : "is waiting"}: ${l.on}.${next}`,
         short: `${update} ${stopped ? `stopped: run #${l.run} is in the way` : `is waiting on run #${l.run}`}.${next}` };
@@ -284,18 +284,22 @@ export function desktopUpdateWaitingOf(databaseFile, inTheWay, stateDirs = [dirn
 export function settleLeftoverRecords(db, now) {
     return new Store(db).settleUnspawnedWitnesses(now);
 }
-/** Store.stopQuiescenceProblem's reasons, said for a person: no internal terms, and `toolroll run settle` only where it
- * can clear the record (it refuses while anything of the run is alive). */
+/** Store.stopQuiescenceProblem's reasons, said for a person: no internal terms. Nobody vouches that a run stopped:
+ * Toolroll proves it itself (stop-proof.ts), and `toolroll run settle` only has it look again now. */
 export function plainLingering(fallbackRun, problem) {
     const run = Number(/run #(\d+)/.exec(problem)?.[1] ?? fallbackRun);
-    const settle = `toolroll run settle ${run} --why "it is not running"`;
+    const settle = `toolroll run settle ${run}`;
     const pid = /process (\d+)/.exec(problem)?.[1];
     if (/incomplete spawn witness|before its process witness was recorded/.test(problem))
-        return { run, on: `Run #${run} finished, but Toolroll has no process ID for one of its processes, so it can't confirm that process ended`, action: settle };
-    if (/belongs to another host|another host/.test(problem))
+        return { run, on: `Run #${run} finished, and Toolroll is making sure none of its processes is still running`, action: settle };
+    if (/belongs to another host|another host|another computer/.test(problem))
         return { run, on: `Run #${run} finished on another computer, and Toolroll can only confirm its processes ended there`, action: `${settle} (on that computer)` };
+    if (/can't be proven stopped: .* is using its folder/.test(problem))
+        return { run, on: `Run #${run} finished, but something Toolroll didn't start is using its folder`, action: settle };
+    if (/can't be checked on this computer/.test(problem))
+        return { run, on: `Run #${run} finished, but Toolroll can't check this computer's processes`, action: settle };
     if (/incomplete native containment custody|cannot be proven empty/.test(problem))
-        return { run, on: `Run #${run} finished, but Toolroll can't confirm its sandbox is empty`, action: settle };
+        return { run, on: `Run #${run} finished, but Toolroll can't confirm its sandbox is empty`, action: null };
     if (/still has members/.test(problem))
         return { run, on: `Run #${run} finished, but processes are still running in its sandbox`, action: null };
     if (/workspace is still held/.test(problem))

package/dist/eval-hooks.d.ts

@@ -1,3 +1,4 @@
+import type ts from "typescript-parser";
 /** One required call: in this file, inside this top-level function, a call to this name, the name bound as `from`
  * says (a module specifier its un-renamed named import comes from; `self`: the file's own top-level function; `local`:
  * declared inside `inside`). `args`: the call's arguments, as text, must stay as the base has them. */
@@ -9,12 +10,17 @@ export type EvalHook = {
     args?: true;
     why: string;
 };
+/** `fn` may also be `outer>inner` (docs/plans/learning-loops.md, Protection 3): a `const inner = (…) => …` (or function
+ * expression) or `function inner`, bound once in the file and never reassigned, inside the top-level function `outer`
+ * and in no other function between them. `strict`: a base that holds the file but can't resolve the pin is a problem,
+ * never skipped (a base without the file at all is a project that isn't Toolroll, and holds none). */
 /** One function whose body (its text, as the candidate has it) must stay as the base has it: a top-level function, or
  * `Class#method`, a method of a top-level class. */
 export type EvalPinned = {
     file: string;
     fn: string;
     why: string;
+    strict?: true;
 };
 export declare const EVAL_HOOKS: readonly EvalHook[];
 export declare const EVAL_PINNED: readonly EvalPinned[];
@@ -37,3 +43,52 @@ export declare const EVAL_HOOK_FILES: readonly string[];
  * files the verified diff says exist at the candidate, so no bytes is a failed read, never a deletion.
  */
 export declare function storeRewriteProblem(paths: readonly string[], candidate: ((file: string) => Buffer | null) | null, base: ((file: string) => Buffer | null) | null, pinned?: readonly string[]): string | null;
+/** The calls that record a check's facts: at disposition, and as the check's command starts. */
+export declare const LEARNING_HOOKS: readonly EvalHook[];
+/** The bodies a release can't change by itself, every one strict: what a run is told from project memory, how a memory
+ * proposal and a decision are written, and where a check's conditions are captured. */
+export declare const LEARNING_PINNED: readonly EvalPinned[];
+/** Every file the learning manifest reads. */
+export declare const LEARNING_HOOK_FILES: readonly string[];
+/** Each protected table and its only writer modules (the v149 migration in store.ts aside). The decision tables'
+ * existing writers stay theirs: project-memory.ts records and retires, project-delete.ts deletes a whole project. */
+export declare const LEARNING_WRITERS: Readonly<Record<string, readonly string[]>>;
+/** One SQL-shaped construct in a file: its static text (a placeholder `${}` where an expression sits), the protected
+ * tables it writes, and the top-level declaration it's in ("" for none). `unreadable`: a write whose table name is
+ * split around an expression; `bare`: a string that is only a protected table's name (SQL assembled elsewhere). */
+type LearningConstruct = {
+    text: string;
+    tables: string[];
+    inside: string;
+    unreadable: boolean;
+    bare: boolean;
+};
+/**
+ * Every construct in the file that could write a protected table: each string literal, template (its static parts)
+ * and `+` concatenation (its literal operands), whatever it's passed to — `prepare`, `exec`, a renamed `prepare`, a
+ * helper. A write verb next to a protected table's name, a table name split around an expression next to a write
+ * word, and a string that is only a protected table's name are each found.
+ */
+export declare function learningConstructs(source: ts.SourceFile): LearningConstruct[];
+/**
+ * Why a changed file writes a learning-loops table (or a decision merge or restore) from a place that may not, or null
+ * (docs/plans/learning-loops.md, Protection 4). Every changed JavaScript or TypeScript file but tests is parsed; a
+ * construct its writer module doesn't own is new unless the base's copy of that file already had exactly that text
+ * (counted by its sha256, as storeRewriteProblem does). A file that can't be read or parsed needs a person. It reads
+ * text the candidate wrote, never runs it: it raises the bar for review; a person reviewing these files is the backstop.
+ */
+export declare function learningWriteProblem(paths: readonly string[], candidate: ((file: string) => Buffer | null) | null, base: ((file: string) => Buffer | null) | null): string | null;
+/**
+ * Why a candidate needs a person for learning loops, or null: a required call dropped, a pinned body changed (strict
+ * pins included), or a changed file writing a protected table from outside its writers. With `manifest.base`, only what
+ * the base holds is required, as evalHookProblem does — except a strict pin whose file the base holds.
+ */
+export declare function learningHookProblem(manifest: {
+    candidate: (file: string) => Buffer | null;
+    base?: (file: string) => Buffer | null;
+}, changed: {
+    paths: readonly string[];
+    candidate: ((file: string) => Buffer | null) | null;
+    base: ((file: string) => Buffer | null) | null;
+}): string | null;
+export {};

package/dist/eval-hooks.js

@@ -36,6 +36,7 @@ export const EVAL_HOOKS = Object.freeze([
     { file: "src/release-auto.ts", inside: "changeProblem", calls: "evalHookProblem", from: "./eval-hooks.js", why: "this check itself" },
     { file: "src/release-auto.ts", inside: "changeProblem", calls: "autoPathProblem", from: "self", why: "policy paths need a person" },
     { file: "src/release-auto.ts", inside: "changeProblem", calls: "storeRewriteProblem", from: "./eval-hooks.js", why: "no changed file rewrites a pinned Store method" },
+    { file: "src/release-auto.ts", inside: "changeProblem", calls: "learningHookProblem", from: "./eval-hooks.js", why: "learning loops' hooks, pins and writers (docs/plans/learning-loops.md)" },
     // The invocation gateway (invoke.ts): every agent run an eval world spawns takes a slot.
     { file: "src/invoke.ts", inside: "invokeAgent", calls: "takeEvalDispatch", from: "./eval-gate.js", why: "every agent dispatch in an eval world takes a slot" },
     // PR #263 review: what the run's billing basis and its unknown cost are computed from is held too, not only the call.
@@ -227,7 +228,7 @@ function boundAs(source, name, from, inside) {
     if (from === "self")
         return compiler.isFunctionDeclaration(only) && only.parent === source ? null : `${name} isn't its own top-level function`;
     if (from === "local")
-        return only.pos >= inside.pos && only.end <= inside.end && !compiler.isParameter(only) ? null : `${name} isn't declared inside ${inside.name?.text ?? "it"}`;
+        return only.pos >= inside.pos && only.end <= inside.end && !compiler.isParameter(only) ? null : `${name} isn't declared inside its function`;
     if (!compiler.isImportSpecifier(only) || only.propertyName !== undefined || only.isTypeOnly)
         return `${name} isn't imported by its own name`;
     const clause = only.parent.parent;
@@ -254,6 +255,46 @@ function heldFunction(source, name) {
     const fn = topFunction(source, name);
     return fn === null || boundAs(source, name, "self", fn) !== null ? null : fn;
 }
+/** `outer>inner`: the one function-like `inner` declared inside the held top-level `outer` (no other function between
+ * them), bound once in the file and never reassigned — a `function inner` or a `const inner =` arrow or function
+ * expression. Null otherwise. */
+function nestedFunction(source, spec) {
+    const compiler = typescript();
+    const [outerName, innerName, ...rest] = spec.split(">");
+    if (outerName === undefined || innerName === undefined || rest.length > 0 || outerName === "" || innerName === "")
+        return null;
+    const outer = heldFunction(source, outerName);
+    if (outer === null || outer.body === undefined)
+        return null;
+    const all = bindingsOf(source, innerName);
+    if (all.length !== 1)
+        return null;
+    const only = all[0];
+    let fn = null;
+    if (compiler.isFunctionDeclaration(only) && only.body !== undefined)
+        fn = only;
+    else if (compiler.isVariableDeclaration(only) && only.initializer !== undefined && (compiler.isArrowFunction(only.initializer) || compiler.isFunctionExpression(only.initializer))
+        && compiler.isVariableDeclarationList(only.parent) && (only.parent.flags & compiler.NodeFlags.Const) !== 0)
+        fn = only.initializer;
+    if (fn === null)
+        return null;
+    // Directly inside `outer`: the first function-like ancestor of the declaration is `outer` itself.
+    for (let at = only.parent; at !== undefined; at = at.parent) {
+        if (at === outer)
+            return fn;
+        if (compiler.isFunctionLike(at) || compiler.isClassLike(at))
+            return null;
+    }
+    return null;
+}
+/** A held function by its manifest name: top-level, `Class#method` or `outer>inner`. */
+function heldNode(source, spec) {
+    if (spec.includes(">"))
+        return nestedFunction(source, spec);
+    if (spec.includes("#"))
+        return classMethod(source, spec);
+    return heldFunction(source, spec);
+}
 /** A reader that parses each file once. */
 function parser(read) {
     const seen = new Map();
@@ -265,7 +306,7 @@ function hookIn(tree, hook) {
     const parsed = tree(hook.file);
     if ("problem" in parsed)
         return { missing: `${parsed.problem}, and it holds a required call (${hook.why})` };
-    const fn = heldFunction(parsed.source, hook.inside);
+    const fn = (hook.inside.includes(">") ? nestedFunction(parsed.source, hook.inside) : heldFunction(parsed.source, hook.inside));
     if (fn === null || fn.body === undefined)
         return { missing: `${hook.file} no longer has ${hook.inside} as one function, which must call ${hook.calls} (${hook.why})` };
     const found = callsOf(fn.body, hook.calls);
@@ -281,7 +322,7 @@ function pinnedText(tree, pin) {
     const parsed = tree(pin.file);
     if ("problem" in parsed)
         return null;
-    const fn = pin.fn.includes("#") ? classMethod(parsed.source, pin.fn) : heldFunction(parsed.source, pin.fn);
+    const fn = heldNode(parsed.source, pin.fn);
     if (fn === null)
         return null;
     // The static block's pin holds the class header too: its name, modifiers and heritage, as the base has them.
@@ -308,8 +349,12 @@ export function evalHookProblem(candidate, base, hooks = EVAL_HOOKS, pinned = EV
     }
     for (const pin of pinned) {
         const before = was === null ? null : pinnedText(was, pin);
-        if (was !== null && before === null)
+        if (was !== null && before === null) {
+            // A strict pin the base holds the file of but can't resolve is a problem (learning loops, Protection 2), never a skip.
+            if (pin.strict === true && base(pin.file) !== null)
+                return `${pin.file} at the base has no ${pin.fn} as one function, which is pinned strictly (${pin.why})`;
             continue;
+        }
         const after = pinnedText(now, pin);
         if (after === null)
             return `${pin.file} no longer has ${pin.fn} as one function (${pin.why})`;
@@ -475,3 +520,181 @@ export function storeRewriteProblem(paths, candidate, base, pinned = PINNED_STOR
     }
     return null;
 }
+// ---- learning loops (docs/plans/learning-loops.md, "Safety", Protection 2-4) ----------------------------------------
+/** The calls that record a check's facts: at disposition, and as the check's command starts. */
+export const LEARNING_HOOKS = Object.freeze([
+    { file: "src/builder.ts", inside: "settleProof", calls: "recordCheckFacts", from: "./check-facts.js", why: "every settled check records its facts" },
+    { file: "src/builder.ts", inside: "settleProof>runVerification", calls: "captureCheckConditions", from: "./check-facts.js", why: "a check's conditions are captured as its command starts" },
+]);
+/** The bodies a release can't change by itself, every one strict: what a run is told from project memory, how a memory
+ * proposal and a decision are written, and where a check's conditions are captured. */
+export const LEARNING_PINNED = Object.freeze([
+    { file: "src/project-knowledge.ts", fn: "knowledgeContext", strict: true, why: "the decisions and references a run is given, and their snapshot" },
+    { file: "src/project-learning.ts", fn: "learningContext", strict: true, why: "the lessons a run is given, and their snapshot" },
+    { file: "src/memory-pass.ts", fn: "decideProposal", strict: true, why: "a memory proposal's one writer" },
+    { file: "src/project-memory.ts", fn: "recordDecision", strict: true, why: "how a decision is recorded and what it supersedes" },
+    { file: "src/project-memory.ts", fn: "retireDecision", strict: true, why: "how a decision is retired" },
+    { file: "src/builder.ts", fn: "settleProof>runVerification", strict: true, why: "the check's command and the conditions it starts under" },
+]);
+/** Every file the learning manifest reads. */
+export const LEARNING_HOOK_FILES = Object.freeze([...new Set([...LEARNING_HOOKS.map(hook => hook.file), ...LEARNING_PINNED.map(pin => pin.file)])]);
+/** Each protected table and its only writer modules (the v149 migration in store.ts aside). The decision tables'
+ * existing writers stay theirs: project-memory.ts records and retires, project-delete.ts deletes a whole project. */
+export const LEARNING_WRITERS = Object.freeze({
+    check_fact: ["src/check-facts.ts"], check_result: ["src/check-facts.ts"],
+    local_observation: ["src/flaky.ts"], ci_flaky_observation: ["src/flaky-ci.ts"], ci_pairing_rejected: ["src/flaky-ci.ts"],
+    learning_watch: ["src/flaky.ts", "src/lesson-notes.ts"],
+    lesson_note: ["src/lesson-notes.ts"], lesson_note_tally: ["src/lesson-notes.ts"],
+    memory_use: ["src/memory-use.ts"],
+    memory_tidy_proposal: ["src/memory-tidy.ts"], decision_merge: ["src/memory-tidy.ts"],
+    project_decision: ["src/memory-tidy.ts", "src/project-memory.ts", "src/project-delete.ts"],
+    decision_change: ["src/memory-tidy.ts", "src/project-memory.ts", "src/project-delete.ts"],
+});
+/** store.ts's v149 migration: the only place outside the writers that may name these tables in SQL. */
+const LEARNING_MIGRATION = Object.freeze({ "src/store.ts": ["V149_SCHEMA", "V149_TABLES", "V149_REPO_TABLES"] });
+const PROTECTED = Object.keys(LEARNING_WRITERS);
+const tableWrite = (table) => new RegExp(String.raw `(?:\b(?:(?:INSERT(?:\s+OR\s+\w+)?|REPLACE)\s+INTO|UPDATE(?:\s+OR\s+\w+)?|DELETE\s+FROM)\s+(?:main\s*\.\s*)?["\`\[]?${table}["\`\]]?(?!\w)`
+    + String.raw `|\b(?:DROP\s+(?:TABLE|TRIGGER|INDEX|VIEW)(?:\s+IF\s+EXISTS)?|ALTER\s+TABLE)\s+(?:main\s*\.\s*)?["\`\[]?${table})`, "i");
+const TABLE_WRITES = PROTECTED.map(table => ({ table, write: tableWrite(table) }));
+const WRITE_WORD = /\b(?:INSERT|UPDATE|DELETE|REPLACE|DROP|ALTER)\b/i;
+const BARE_NAME = new RegExp(String.raw `^\s*(?:main\s*\.\s*)?["\`\[]?(?:${PROTECTED.join("|")})["\`\]]?\s*$`, "i");
+/**
+ * Every construct in the file that could write a protected table: each string literal, template (its static parts)
+ * and `+` concatenation (its literal operands), whatever it's passed to — `prepare`, `exec`, a renamed `prepare`, a
+ * helper. A write verb next to a protected table's name, a table name split around an expression next to a write
+ * word, and a string that is only a protected table's name are each found.
+ */
+export function learningConstructs(source) {
+    const compiler = typescript();
+    const found = [];
+    const topOf = (node) => {
+        let at = node;
+        while (at.parent !== undefined && !compiler.isSourceFile(at.parent))
+            at = at.parent;
+        if (compiler.isFunctionDeclaration(at) || compiler.isClassDeclaration(at))
+            return at.name?.text ?? "";
+        if (compiler.isVariableStatement(at))
+            return at.declarationList.declarations.map(one => compiler.isIdentifier(one.name) ? one.name.text : "").join(",");
+        return "";
+    };
+    const fragmentRisk = (parts) => {
+        // Around each placeholder: the identifier characters just before and just after it.
+        for (let i = 0; i < parts.length - 1; i++) {
+            const before = /[A-Za-z0-9_]*$/.exec(parts[i])[0].toLowerCase(), after = /^[A-Za-z0-9_]*/.exec(parts[i + 1])[0].toLowerCase();
+            if (before === "" && after === "")
+                continue;
+            if (PROTECTED.some(table => (before !== "" && table.startsWith(before) && table !== before) || (after !== "" && table.endsWith(after) && table !== after)
+                || (before !== "" && after !== "" && table.startsWith(before) && table.endsWith(after))))
+                return true;
+        }
+        return false;
+    };
+    const consider = (node, parts) => {
+        const text = parts.join("${}");
+        const tables = TABLE_WRITES.filter(one => one.write.test(text)).map(one => one.table);
+        const unreadable = parts.length > 1 && WRITE_WORD.test(text) && fragmentRisk(parts);
+        const bare = parts.length === 1 && BARE_NAME.test(text);
+        if (tables.length > 0 || unreadable || bare)
+            found.push({ text: text.replace(/\s+/g, " ").trim(), tables, inside: topOf(node), unreadable, bare });
+    };
+    const isPlus = (node) => compiler.isBinaryExpression(node) && node.operatorToken.kind === compiler.SyntaxKind.PlusToken;
+    const flatten = (node, into) => {
+        let at = node;
+        while (compiler.isParenthesizedExpression(at))
+            at = at.expression;
+        if (isPlus(at)) {
+            flatten(at.left, into);
+            flatten(at.right, into);
+        }
+        else
+            into.push(at);
+    };
+    const visit = (node) => {
+        if (isPlus(node) && !(node.parent !== undefined && (isPlus(node.parent) || (compiler.isParenthesizedExpression(node.parent) && node.parent.parent !== undefined && isPlus(node.parent.parent))))) {
+            const operands = [];
+            flatten(node, operands);
+            if (operands.some(one => compiler.isStringLiteralLike(one) || compiler.isTemplateExpression(one))) {
+                const parts = [""];
+                for (const one of operands) {
+                    if (compiler.isStringLiteralLike(one))
+                        parts[parts.length - 1] += one.text;
+                    else if (compiler.isTemplateExpression(one)) {
+                        parts[parts.length - 1] += one.head.text;
+                        for (const span of one.templateSpans)
+                            parts.push(span.literal.text);
+                    }
+                    else
+                        parts.push("");
+                }
+                if (parts.length > 1 || operands.length > 1)
+                    consider(node, parts);
+            }
+        }
+        if (compiler.isStringLiteralLike(node))
+            consider(node, [node.text]);
+        else if (compiler.isTemplateExpression(node))
+            consider(node, [node.head.text, ...node.templateSpans.map(span => span.literal.text)]);
+        compiler.forEachChild(node, visit);
+    };
+    visit(source);
+    return found;
+}
+/** Whether this construct may stand in this file: its writer module for every table it writes, or the migration's own
+ * declarations in store.ts. An unreadable or bare construct stands only in a writer of some protected table. */
+function learningAllowed(file, one) {
+    if ((LEARNING_MIGRATION[file] ?? []).some(name => one.inside.split(",").includes(name)))
+        return true;
+    if (one.tables.length > 0)
+        return one.tables.every(table => LEARNING_WRITERS[table].includes(file));
+    return Object.values(LEARNING_WRITERS).some(writers => writers.includes(file));
+}
+/**
+ * Why a changed file writes a learning-loops table (or a decision merge or restore) from a place that may not, or null
+ * (docs/plans/learning-loops.md, Protection 4). Every changed JavaScript or TypeScript file but tests is parsed; a
+ * construct its writer module doesn't own is new unless the base's copy of that file already had exactly that text
+ * (counted by its sha256, as storeRewriteProblem does). A file that can't be read or parsed needs a person. It reads
+ * text the candidate wrote, never runs it: it raises the bar for review; a person reviewing these files is the backstop.
+ */
+export function learningWriteProblem(paths, candidate, base) {
+    const scanned = paths.filter(path => /\.(?:[cm]?[jt]sx?)$/.test(path) && !/\.test\.[cm]?[jt]sx?$/.test(path) && !path.startsWith("test/")
+        && !path.startsWith("node_modules/") && !path.includes("/node_modules/"));
+    if (scanned.length === 0)
+        return null;
+    if (candidate === null || base === null)
+        return "the changed files can't be read";
+    const key = (text) => createHash("sha256").update(text).digest("hex");
+    for (const path of scanned) {
+        const bytes = candidate(path);
+        if (bytes === null)
+            return `${path} can't be read`;
+        const now = parse(path, bytes);
+        if ("problem" in now)
+            return now.problem;
+        const before = base(path);
+        const was = before === null ? null : parse(path, before);
+        const kept = new Map();
+        if (was !== null && !("problem" in was))
+            for (const one of learningConstructs(was.source))
+                kept.set(key(one.text), (kept.get(key(one.text)) ?? 0) + 1);
+        for (const one of learningConstructs(now.source)) {
+            if (learningAllowed(path, one))
+                continue;
+            const left = kept.get(key(one.text)) ?? 0;
+            if (left > 0) {
+                kept.set(key(one.text), left - 1);
+                continue;
+            }
+            const what = one.unreadable ? "builds a learning-loops table's name around an expression in SQL" : one.bare ? "names a learning-loops table outside its writers" : "writes learning-loops rows outside their writers";
+            return `${path} ${what} (\`${one.text.slice(0, 80)}\`)`;
+        }
+    }
+    return null;
+}
+/**
+ * Why a candidate needs a person for learning loops, or null: a required call dropped, a pinned body changed (strict
+ * pins included), or a changed file writing a protected table from outside its writers. With `manifest.base`, only what
+ * the base holds is required, as evalHookProblem does — except a strict pin whose file the base holds.
+ */
+export function learningHookProblem(manifest, changed) {
+    return evalHookProblem(manifest.candidate, manifest.base, LEARNING_HOOKS, LEARNING_PINNED) ?? learningWriteProblem(changed.paths, changed.candidate, changed.base);
+}

package/dist/flaky.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Mixed outcomes under recorded conditions (docs/plans/learning-loops.md, "Flaky tests"): advisory only. Nothing here
+ * changes a check's outcome, a verdict, an approval or a rerun; rerunning stays a person's `task regate`.
+ *
+ * Slice 1 holds the tracked identities an observation adds (`learning_watch`, reason `observation`): every Full check
+ * with a handshake asks about them for 90 days (check-facts.ts learnRequestFor). Lesson notes (lesson-notes.ts) add
+ * their own. This module and lesson-notes.ts are the only writers of `learning_watch`; release-auto's learning scan
+ * (eval-hooks.ts learningWriteProblem) needs a person for any other. A policy path (release-auto.ts EVAL_POLICY).
+ */
+import type { Store } from "./store.js";
+/** Track an identity a local observation named (one row per observation; first write wins, never rewritten). */
+export declare function watchObservation(store: Store, input: {
+    repo: string;
+    identity: string;
+    observation: number;
+    now: Date;
+}): boolean;

package/dist/flaky.js

@@ -0,0 +1,9 @@
+/** Track an identity a local observation named (one row per observation; first write wins, never rewritten). */
+export function watchObservation(store, input) {
+    if (input.repo.trim() === "" || input.identity.length < 1 || input.identity.length > 2600 || !Number.isSafeInteger(input.observation) || input.observation < 1) {
+        throw new Error("a tracked identity needs its project, a bounded identity and the observation that named it");
+    }
+    const added = store.handle.prepare(`INSERT INTO learning_watch (repo, identity, reason, source_ref, since, until) VALUES (?, ?, 'observation', ?, ?, NULL)
+    ON CONFLICT (repo, identity, reason, source_ref) DO NOTHING`).run(input.repo, input.identity, `observation:${input.observation}`, input.now.toISOString());
+    return Number(added.changes) === 1;
+}

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. */