toolroll 0.9.103 → 0.9.105

package/dist/envelope.js

@@ -1,96 +1,63 @@
-/**
- * The machine envelope — the one shape every `--json` answer takes.
- *
- * Agents branch on this output ten thousand times a night, so the contract
- * is versioned and deliberately dull: `envelopeVersion` first, then `ok`,
- * then `command`, then whatever the command has to say. Failures add a
- * stable `reason` token and a human `message`. Nothing else about the
- * shape is promised, and consumers are told to ignore keys they do not
- * recognize — that is what lets the envelope grow without breaking anyone.
- *
- * Every emission in the CLI routes through `envelopeJson` (a source-level
- * test enforces it), which is also what makes `-o <file>` possible: the
- * entry point asks this module for the last envelope written and copies it
- * to the file, so an agent never has to scrape a terminal.
- */
 export const ENVELOPE_VERSION = 1;
-/**
- * Feature detection for agent consumers, Claude-`system/init` style:
- * a bounded list of protocol behaviors this build honors. Consumers must
- * ignore values they do not recognize. Behaviors, not versions — an agent
- * should ask "can I rely on stable reasons", never "is this 0.1.2".
- */
 export const CAPABILITIES = [
-    "envelope/1", //          every --json answer is one versioned envelope on stdout
-    "stable-reasons", //      failure `reason` is a token that survives rewording
-    "idempotency-keys", //    every mutation takes --key; retries return the first answer
-    "exit-codes/0-1-2-3", //  0 ok · 1 broke · 2 usage · 3 ran fine, answer is no
-    "output-file", //         -o <file> writes the same envelope to a file
-    "command-schema/1", //    contract --commands dumps the declared command guide
-    "skill-guides/1", //      skills list / skills get serve version-matched guides
+    "envelope/1",
+    "stable-reasons",
+    "idempotency-keys",
+    "exit-codes/0-1-2-3",
+    "output-file",
+    "command-schema/1",
+    "skill-guides/1",
 ];
-/**
- * DOCUMENTED reasons — the curated vocabulary the command guide's
- * `notableReasons` may cite. Deliberately named for what it is: a list of
- * tokens that are DOCUMENTED, not a proof of runtime exhaustiveness (the
- * runtime `reason` field remains the truth; consumers branch on tokens
- * and ignore ones they do not recognize). A test ties every entry to a
- * literal in the source so a typo cannot ship.
- */
 export const DOCUMENTED_REASONS = [
-    "usage", //             the invocation itself was malformed
-    "database-busy", //     another writer held the selected database for the full wait
-    "unknown-task", //      the named task does not exist
-    "timeout", //           task wait reached its caller-supplied deadline
-    "failed", //            the watched attempt or task failed
-    "needs-person", //      the task reached a decision or approval only a person can provide
-    "unknown-skill", //     the named guide does not exist (skills get)
-    "unconfirmed", //       a preview answered; add --yes to apply
-    "foreign-file", //      an installer target exists but is not managed by it
-    "not-an-approver", //   the credential offered does not authenticate
-    "held", //              somebody else holds it
-    "fenced", //            a newer lease superseded yours — stop
-    "claimed", //           already being worked
-    "unapproved", //        no person has agreed to the scope yet
-    "reserved", //          the task belongs to another worker's queue
-    "external", //          a tracker mirror is not dispatchable (see detail)
-    "provider-unattested", // the provider binary is outside its attested range
-    "daily-runs", //        the active mode's daily run cap is spent
-    "daily-dollars", //     the active mode's daily measured-spend rail is reached
-    "not-ready", //         blocked, held, or otherwise not dispatchable
-    "not-leased", //        the lease does not exist or already ended
-    "not-yours", //         held or reserved by someone else
-    "no-op", //             nothing to do — an answer, not an error
-    "duplicate", //         the identity already exists
-    "empty", //             nothing matched
-    "quota", //             a budget or cap refused the act
-    "not-a-repo", //        the path has no .git
-    "stale-approval", //    what would run no longer matches what was approved
-    "profile-unresolved", // the scope cannot say exactly what would run — restate it
-    "repair-attempts-spent", // the chain's signed attempt cap is spent
-    "repair-no-progress", // two consecutive repair attempts failed to shrink the unresolved set
-    "repair-refused-integrity", // a refutation named an altered term, not a gap — no automatic repair
-    "ambiguous", //         a value could mean two things (a lease id or a branch) — refused, never guessed
-    "drift", //             the branch, pull request or result moved from the gated commit
-    "check-failed", //      the release check failed; it stays visible and nothing reruns it
-    "ci-failed", //         a required pull-request check failed or is missing — nothing merged
-    "git-too-old", //       the installed git is older than Toolroll's floor (git-floor.ts) — serve, watch and up don't start
-    "base-moved", //        the release branch lacks main's head — nothing filed (gate) or merged
-    "tree-mismatch", //     main's merge commit has a different tree than the gated commit — nothing tagged
-    "conflict", //          a task or tag exists for a different commit
-    "mixed-runtime", //     the console, worker and CLI names don't run one build
-    "gate-held", //         a deployment stopped before its swap and left new work paused — `release --release-gate <id>`
-    "after-swap", //        the deployment got past stopping the service, so its pause is its own recovery's to lift
+    "usage",
+    "database-busy",
+    "unknown-task",
+    "timeout",
+    "failed",
+    "needs-person",
+    "unknown-skill",
+    "unconfirmed",
+    "foreign-file",
+    "not-an-approver",
+    "held",
+    "fenced",
+    "claimed",
+    "unapproved",
+    "reserved",
+    "external",
+    "provider-unattested",
+    "daily-runs",
+    "daily-dollars",
+    "not-ready",
+    "not-leased",
+    "not-yours",
+    "no-op",
+    "duplicate",
+    "empty",
+    "quota",
+    "not-a-repo",
+    "stale-approval",
+    "profile-unresolved",
+    "repair-attempts-spent",
+    "repair-no-progress",
+    "repair-refused-integrity",
+    "ambiguous",
+    "drift",
+    "check-failed",
+    "ci-failed",
+    "git-too-old",
+    "base-moved",
+    "tree-mismatch",
+    "conflict",
+    "mixed-runtime",
+    "gate-held",
+    "after-swap",
 ];
 let captured = null;
 let captureHook = null;
-/** The entry point's early-flush hook (arc 2): for long-running commands,
- * `-o` lands the startup envelope the moment it exists. The hook must not
- * throw — the entry point's own hook catches internally. */
 export function onEnvelopeCaptured(hook) {
     captureHook = hook;
 }
-/** Serialize one envelope, remembering it for `-o` teeing at the entry point. */
 export function envelopeJson(payload) {
     const body = JSON.stringify({ envelopeVersion: ENVELOPE_VERSION, ...payload }, null, 2);
     captured = body;
@@ -98,15 +65,12 @@ export function envelopeJson(payload) {
         captureHook?.(body);
     }
     catch {
-        // A hook that throws must never reach the command's envelope path.
     }
     return body;
 }
-/** The last envelope this process serialized, or null if none has been. */
 export function capturedEnvelope() {
     return captured;
 }
-/** Forget the captured envelope — the entry point calls this before dispatch. */
 export function resetCapturedEnvelope() {
     captured = null;
 }

package/dist/eval-gate.js

@@ -1,25 +1,3 @@
-/**
- * The eval world's dispatch gate (docs/plans/evals-nightly.md, part C), and the provider-gate logic the runner needs
- * at run time, ported from scripts/provider-gate.mjs so it ships in dist.
- *
- * An eval attempt runs in a world of its own (evals.ts). Before the world starts, the attempt's runner makes a gate
- * folder in the world's state folder (which every agent fence in the world denies) holding `gate.json`: the case's
- * dispatch limit. The world's processes find it through TOOLROLL_EVAL_GATE. Every provider dispatch the world makes
- * takes one numbered slot first (an exclusive create, so two dispatches never take the same one):
- *
- *   - every agent run the invocation gateway (invoke.ts) spawns: builder, planner, repair, reviewer, scout;
- *   - every lead request, which doesn't go through the gateway (direct API and subscription), and fleet chat's;
- *   - the helpers that would call a provider and keep no record (task sizing, flow drafts, subagent turns, the
- *     memory pass) refuse in an eval world instead.
- *
- * Past the limit the dispatch refuses and nothing is sent, and the gate remembers it was asked (the attempt then
- * fails). There is no dollar cap (the owner, 2026-10-30): what each dispatch cost is recorded, not limited. Outside an
- * eval world (no TOOLROLL_EVAL_GATE) nothing here changes anything; the variable only ever narrows, and a gate that
- * can't be read refuses every dispatch (fail closed).
- *
- * The runner reads the slots back after the attempt (`evalGateSlots`) and matches them to the world's records; a slot
- * no record accounts for, or a record no slot does, makes the attempt an error with unknown spending.
- */
 import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, writeSync } from "node:fs";
 import { join } from "node:path";
 export const EVAL_GATE_ENV = "TOOLROLL_EVAL_GATE";
@@ -27,8 +5,6 @@ const CONFIG = "gate.json";
 const SLOTS = "slots";
 const OVER = "over-limit";
 const MAX_GATE_BYTES = 4096;
-/** At most `limit` bodies at once; the others start in the order they asked, as each running one ends (provider-gate
- * limiter). */
 export function limiter(limit) {
     if (!Number.isInteger(limit) || limit < 1)
         throw new Error("a limiter takes a whole number, 1 or more");
@@ -48,7 +24,6 @@ export function limiter(limit) {
         }
     });
 }
-/** Read a small regular file without following a link; null when it isn't one, is too big or can't be read. */
 export function readNoFollow(path, maxBytes) {
     let fd;
     try {
@@ -84,8 +59,6 @@ const validConfig = (value) => {
     const one = value;
     return one["v"] === 2 && Number.isInteger(one["max"]) && one["max"] >= 0 && one["max"] <= 50;
 };
-/** Make a world's gate in `dir` (a fresh folder the runner owns): its terms, and an empty slots folder. Refuses a folder
- * that already holds a gate. */
 export function openEvalGate(dir, config) {
     if (!validConfig(config))
         throw new Error("an eval gate needs a whole dispatch limit");
@@ -98,8 +71,6 @@ export function openEvalGate(dir, config) {
         closeSync(fd);
     }
 }
-/** The world's gate, as this process's environment names it: null outside an eval world, its terms, or why it can't
- * be read (which refuses every dispatch). */
 export function evalWorldGate(env = process.env) {
     const dir = env[EVAL_GATE_ENV];
     if (dir === undefined || dir === "")
@@ -116,7 +87,6 @@ export function evalWorldGate(env = process.env) {
     }
     return validConfig(parsed) ? { dir, config: parsed } : { dir, problem: "this eval world's dispatch gate is malformed, so nothing is dispatched" };
 }
-/** Take one dispatch slot of this eval world, before a provider is called. Outside an eval world: `{ active: false }`. */
 export function takeEvalDispatch(kind, env = process.env, now = new Date()) {
     const gate = evalWorldGate(env);
     if (gate === null)
@@ -142,20 +112,16 @@ export function takeEvalDispatch(kind, env = process.env, now = new Date()) {
         }
         return { active: true, ok: true, n };
     }
-    // Remembered for the runner: an attempt that asked past its limit is a fail, whatever it built.
     try {
         const fd = openSync(join(gate.dir, OVER), constants.O_WRONLY | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
         closeSync(fd);
     }
-    catch { /* the slots alone still hold the limit */ }
+    catch { }
     return { active: true, ok: false, why: `this eval case's limit of ${gate.config.max} provider dispatches is reached (eval-dispatch-limit)` };
 }
-/** Whether this process is in an eval world (any gate named, readable or not): the helpers that keep no record refuse
- * there. */
 export function inEvalWorld(env = process.env) {
     return evalWorldGate(env) !== null;
 }
-/** Whether a dispatch in this world asked past its limit (and was refused). */
 export function evalGateOverLimit(dir) {
     try {
         return lstatSync(join(dir, OVER)).isFile();
@@ -164,8 +130,6 @@ export function evalGateOverLimit(dir) {
         return false;
     }
 }
-/** The slots a world's dispatches took, read back by the runner (never following a link). Null when the folder can't
- * be read whole: the runner then counts the world's spending as unknown. */
 export function evalGateSlots(dir) {
     let names;
     try {

package/dist/eval-hooks.js

@@ -1,26 +1,3 @@
-/**
- * The eval and nightly enforcement hooks a release can't drop without a person (docs/plans/evals-nightly.md, part C,
- * "Policy code needs a person", Codex round 2 #10 and C1 round 1 #5, #6).
- *
- * The policy modules themselves are person-only by path (release-auto.ts autoPathProblem: `evals/`, `src/evals*.ts`,
- * `src/eval-*.ts`, `src/reviewer-evals.ts`, `src/nightly-github.ts`, `src/contracts/evals*.ts`, and the accounting
- * readings `src/reported-usage.ts` and `src/run-efficiency.ts`). The calls into them, and the store's accounting reads,
- * live in large product files that ship without a person, so rather than protect those files whole this manifest
- * lists each required call and the function it must be in (EVAL_HOOKS), and each function whose body a release may not
- * change by itself (EVAL_PINNED). The INSTALLED plane checks a candidate's tree against it (`evalHookProblem`, called
- * from release-auto.ts changeProblem): a listed call missing or moved out of its function, its function gone, a pinned
- * body changed, or a listed file that doesn't parse, needs a person. This file is itself a policy path.
- *
- * The check reads the syntax tree (TypeScript's own parser, the runtime dependency `typescript-parser`): only a real
- * call expression of that name inside that top-level function counts, never a comment, a string or a regular
- * expression. The name must also be bound to what the manifest says (`from`): an un-renamed named import from that
- * module, the file's own top-level function, or a local of the function itself, declared exactly once in the file and
- * never assigned (PR #263 review: a renamed import beside a local stand-in of the same name passed). Each enclosing
- * function and pinned body is held the same way, and a pinned `Class#method` is that class's one method of that name,
- * never assigned or redefined by name. With `args`, the call's arguments must read as the base has them. It proves
- * the call is in its function, not that it is reached (a call behind `if (false)` still reads as present); a person
- * reviewing a change to these files remains the backstop.
- */
 import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
 let compiler;
@@ -37,9 +14,7 @@ export const EVAL_HOOKS = Object.freeze([
     { 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.
     { file: "src/invoke.ts", inside: "invokeAgent", calls: "recordRunBillingBasis", from: "./store.js", args: true, why: "a run's billing says whether it was known or guessed" },
     { file: "src/invoke.ts", inside: "invokeAgent", calls: "recordRunCostUnknown", from: "./store.js", args: true, why: "a run whose cost its provider never reported stays unknown money" },
     { file: "src/subscription-chat.ts", inside: "performSubscriptionLeadRequest", calls: "takeEvalDispatch", from: "./eval-gate.js", why: "every subscription lead request in an eval world takes a slot" },
@@ -57,22 +32,17 @@ export const EVAL_PINNED = Object.freeze([
     { file: "src/store.ts", fn: "recordRunModelReported", why: "the exact model a run is held to its pin by" },
     { file: "src/store.ts", fn: "recordRunBillingBasis", why: "whether a run's billing was known" },
     { file: "src/store.ts", fn: "recordRunCostUnknown", why: "a run's unknown cost, once set, is never cleared" },
-    // PR #263 review: the store's own writes of what a run or chat request spent.
     { file: "src/store.ts", fn: "Store#recordUsage", why: "what a run's provider said it cost" },
     { file: "src/store.ts", fn: "Store#settleRunSpend", why: "how a run's spending is priced" },
     { file: "src/store.ts", fn: "Store#fixRunBilling", why: "how a run was billed" },
     { file: "src/store.ts", fn: "Store#finalizeChatTurn", why: "what a chat request spent and how it was billed" },
-    // PR #263 security scan: sealed on the prototype from the class's first static block (before any other code reaches
-    // it), and locked on every instance by the constructor.
     { file: "src/store.ts", fn: "Store#static", why: "the pinned Store methods are sealed as the class is defined" },
     { file: "src/store.ts", fn: "Store#constructor", why: "each Store instance locks the pinned methods" },
     { file: "src/store.ts", fn: "sealStoreMoneyMethods", why: "the pinned Store methods can't be replaced at run time" },
     { file: "src/store.ts", fn: "lockStoreMoneyMethods", why: "the pinned Store methods can't be shadowed on an instance" },
 ]);
-/** The Store methods pinned by body, which no file may write over (storeRewriteProblem, store.ts sealStoreMoneyMethods). */
 export const PINNED_STORE_METHODS = Object.freeze(EVAL_PINNED.filter(pin => pin.fn.startsWith("Store#") && pin.fn !== "Store#static" && pin.fn !== "Store#constructor")
     .map(pin => pin.fn.slice("Store#".length)));
-/** A file's syntax tree, or why it can't be read (missing, or not valid TypeScript: a person decides). */
 function parse(file, bytes) {
     if (bytes === null)
         return { problem: `${file} can't be read` };
@@ -81,17 +51,11 @@ function parse(file, bytes) {
     const diagnostics = source.parseDiagnostics ?? [];
     return diagnostics.length === 0 ? { source } : { problem: `${file} doesn't parse` };
 }
-/** The one top-level function declaration with this name, or null when there is none or more than one. */
 function topFunction(source, name) {
     const compiler = typescript();
     const found = source.statements.filter((one) => compiler.isFunctionDeclaration(one) && one.name?.text === name);
     return found.length === 1 ? found[0] : null;
 }
-/** `Class#method`: the top-level class's one method of that name (no overload, accessor or property of it either),
- * never assigned or redefined by name anywhere in the file; null otherwise. `Class#constructor` is its one
- * constructor; `Class#static` its one static block, which must be the first of its static elements that runs code
- * (no static field initializer or other block runs before it). A class with a decorator anywhere (on it, a member or a
- * parameter: code that runs before the seal) holds none. */
 function classMethod(source, spec) {
     const compiler = typescript();
     const [className, method] = spec.split("#");
@@ -113,7 +77,6 @@ function classMethod(source, spec) {
         return null;
     return memberRewritten(source, method) ? null : named[0];
 }
-/** Whether a decorator appears anywhere in this node. */
 function hasDecorator(node) {
     const compiler = typescript();
     if (compiler.isDecorator(node))
@@ -123,8 +86,6 @@ function hasDecorator(node) {
         hit = true; });
     return hit;
 }
-/** The class header (modifiers, name, type parameters and heritage, up to its opening brace), whitespace normalized:
- * pinned with `Class#static`, so a changed `extends` or modifier needs a person. */
 function classHeader(source, node) {
     const compiler = typescript();
     const owner = node.parent;
@@ -132,8 +93,6 @@ function classHeader(source, node) {
         return "";
     return source.text.slice(owner.getStart(source), owner.members.pos).replace(/\s+/g, " ").trim();
 }
-/** Whether the file writes a property of this name anywhere (`x.name = …`, `x["name"] = …`) or names it as a string to
- * a property-defining call (`Object.defineProperty(…, "name", …)`): a method so replaced isn't the body pinned. */
 function memberRewritten(source, name) {
     const compiler = typescript();
     let hit = false;
@@ -175,8 +134,6 @@ function isAssignment(kind) {
     const compiler = typescript();
     return kind >= compiler.SyntaxKind.FirstAssignment && kind <= compiler.SyntaxKind.LastAssignment;
 }
-/** Every place in the file that binds or rebinds `name`: declarations of any kind (import specifiers, functions,
- * classes, variables, parameters, destructuring, catch variables, enums, namespaces, types) and assignments to it. */
 function bindingsOf(source, name) {
     const compiler = typescript();
     const found = [];
@@ -216,9 +173,6 @@ function bindingsOf(source, name) {
     visit(source);
     return found;
 }
-/** Whether `name` is bound in this file only as `from` says: exactly one binding, and it is an un-renamed, value
- * (not type-only) named import from that module; the top-level function (`self`); or a declaration inside `inside`
- * (`local`). Null when it is; otherwise why not. */
 function boundAs(source, name, from, inside) {
     const compiler = typescript();
     const all = bindingsOf(source, name);
@@ -237,7 +191,6 @@ function boundAs(source, name, from, inside) {
         return `${name} isn't imported from ${from}`;
     return null;
 }
-/** The call expressions in `node` whose callee is the plain identifier `name`. */
 function callsOf(node, name) {
     const compiler = typescript();
     const found = [];
@@ -249,15 +202,10 @@ function callsOf(node, name) {
     visit(node);
     return found;
 }
-/** A function the manifest names, held like a hook's callee: one top-level function, never rebound (a later
- * `name = …` would replace the body that was checked). */
 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(">");
@@ -278,7 +226,6 @@ function nestedFunction(source, spec) {
         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;
@@ -287,7 +234,6 @@ function nestedFunction(source, spec) {
     }
     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);
@@ -295,13 +241,11 @@ function heldNode(source, spec) {
         return classMethod(source, spec);
     return heldFunction(source, spec);
 }
-/** A reader that parses each file once. */
 function parser(read) {
     const seen = new Map();
     return file => { if (!seen.has(file))
         seen.set(file, parse(file, read(file))); return seen.get(file); };
 }
-/** This hook as `tree` holds it: its calls' arguments as text (for `args`), or why it doesn't hold it. */
 function hookIn(tree, hook) {
     const parsed = tree(hook.file);
     if ("problem" in parsed)
@@ -317,7 +261,6 @@ function hookIn(tree, hook) {
         return { missing: `${hook.file}'s ${hook.inside} no longer calls the real ${hook.calls}: ${bound} (${hook.why})` };
     return { args: found.map(call => call.arguments.map(argument => argument.getText(parsed.source).replace(/\s+/g, " ")).join(", ")).sort() };
 }
-/** A pinned function's text in `tree`, or null when it can't be found once. */
 function pinnedText(tree, pin) {
     const parsed = tree(pin.file);
     if ("problem" in parsed)
@@ -325,15 +268,8 @@ function pinnedText(tree, pin) {
     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.
     return pin.fn.endsWith("#static") ? `${classHeader(parsed.source, fn)}\n${fn.getText(parsed.source)}` : fn.getText(parsed.source);
 }
-/**
- * Why a candidate drops a required hook or changes a pinned body, or null. `candidate` gives a listed file's bytes at
- * the candidate (null: missing or unreadable, which needs a person too). With `base` (the plane's own record of where
- * the release started, which the candidate can't rewrite), only what the base holds is required: a project that isn't
- * Toolroll holds none, and a hook not yet landed can't be dropped.
- */
 export function evalHookProblem(candidate, base, hooks = EVAL_HOOKS, pinned = EVAL_PINNED) {
     const now = parser(candidate);
     const was = base === undefined ? null : parser(base);
@@ -350,7 +286,6 @@ 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) {
-            // 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;
@@ -363,26 +298,12 @@ export function evalHookProblem(candidate, base, hooks = EVAL_HOOKS, pinned = EV
     }
     return null;
 }
-/** Every file the manifest reads, for one verified read of each tree. */
 export const EVAL_HOOK_FILES = Object.freeze([...new Set([...EVAL_HOOKS.map(hook => hook.file), ...EVAL_PINNED.map(pin => pin.file)])]);
-/** Names whose every new mention in a changed file needs a person: the ways to define, reflect on, wrap or climb to
- * an object's class. */
 const REFLECTIVE = new Set(["defineProperty", "defineProperties", "getOwnPropertyDescriptor", "getOwnPropertyDescriptors", "assign", "setPrototypeOf", "getPrototypeOf",
     "__proto__", "__defineGetter__", "__defineSetter__", "Reflect", "Proxy", "constructor"]);
-/** Built-ins whose members (`Object.x`, `Function.prototype.x`, ...) a changed file may never write: the store's seal
- * captures Object's at load, and nothing should replace them. */
 const BUILTIN_HOLDERS = new Set(["Object", "Function"]);
 const STORE_NAME = /store/i;
 const GLOBAL_HOLDERS = new Set(["Object", "Reflect", "globalThis", "Store"]);
-/**
- * The constructs that could reach a pinned Store method from another file, each as its whole normalized text (the
- * owner, 2026-10-31: one blunt rule, not a chase of syntax variants; store.ts's runtime seal is the other half):
- * a computed member name; a write through a computed element access; a computed element access on Object, Reflect,
- * globalThis or anything named store; any mention of a reflective name (REFLECTIVE, `.constructor` included); a class
- * whose `extends` isn't a plain identifier or names a store; any member, property or string named like a pinned
- * method that isn't a call of it; any decorator (it runs code as a class is defined); and any write to a member of
- * Object or Function (`Object.defineProperty = …`, `Function.prototype.call = …`).
- */
 function storeRewrites(source, pinned, ownClass) {
     const compiler = typescript();
     const names = new Set(pinned);
@@ -401,8 +322,6 @@ function storeRewrites(source, pinned, ownClass) {
         }
         return hit;
     };
-    // A member of Object or Function anywhere along the access chain (`Object.x`, `globalThis.Object.x`,
-    // `Function.prototype.x`, `Object["x"]`), or such a target inside a destructuring pattern.
     const writesBuiltin = (target) => {
         if (compiler.isPropertyAccessExpression(target) || compiler.isElementAccessExpression(target)) {
             for (let holder = target.expression;; holder = holder.expression) {
@@ -459,10 +378,8 @@ function storeRewrites(source, pinned, ownClass) {
                         say(clause);
             }
         }
-        // Named like a pinned method: anything but calling it (`store.recordUsage(…)`) or referring to it.
         if ((compiler.isIdentifier(one) || compiler.isPrivateIdentifier(one) || compiler.isStringLiteralLike(one)) && names.has(one.text)) {
             const parent = one.parent;
-            // store.ts's own declaration of the method (its body is pinned) is the one exempt construct.
             const own = ownClass !== null && compiler.isMethodDeclaration(parent) && parent.name === one && compiler.isClassDeclaration(parent.parent) && parent.parent.name?.text === ownClass
                 && compiler.isSourceFile(parent.parent.parent);
             if (own) {
@@ -480,13 +397,6 @@ function storeRewrites(source, pinned, ownClass) {
     visit(source);
     return found;
 }
-/**
- * Why a changed file could write over a pinned Store method, or null (PR #263 security scan). Each changed JavaScript
- * or TypeScript file, store.ts included (its class's own method declarations exempt; their bodies are pinned), is held to
- * storeRewrites: a construct the base's copy of that file didn't already have (counted, by the sha256 of its whole
- * text) needs a person. A tree or file that can't be read, or a file that doesn't parse, needs one too; `paths` are the
- * files the verified diff says exist at the candidate, so no bytes is a failed read, never a deletion.
- */
 export function storeRewriteProblem(paths, candidate, base, pinned = PINNED_STORE_METHODS) {
     const scanned = paths.filter(path => /\.(?:[cm]?[jt]sx?)$/.test(path) && !path.startsWith("node_modules/") && !path.includes("/node_modules/"));
     if (scanned.length === 0)
@@ -504,7 +414,6 @@ export function storeRewriteProblem(paths, candidate, base, pinned = PINNED_STOR
         const before = base(path);
         const was = before === null ? null : parse(path, before);
         const kept = new Map();
-        // store.ts is scanned too (its own method declarations exempt): nothing added there may reach a pinned method.
         const ownClass = path === "src/store.ts" ? "Store" : null;
         if (was !== null && !("problem" in was))
             for (const one of storeRewrites(was.source, pinned, ownClass))
@@ -520,14 +429,10 @@ 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" },
@@ -536,10 +441,7 @@ export const LEARNING_PINNED = Object.freeze([
     { 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"],
@@ -550,7 +452,6 @@ export const LEARNING_WRITERS = Object.freeze({
     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)`
@@ -558,12 +459,6 @@ const tableWrite = (table) => new RegExp(String.raw `(?:\b(?:(?:INSERT(?:\s+OR\s
 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 = [];
@@ -578,7 +473,6 @@ export function learningConstructs(source) {
         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 === "")
@@ -639,8 +533,6 @@ export function learningConstructs(source) {
     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;
@@ -648,13 +540,6 @@ function learningAllowed(file, one) {
         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/"));
@@ -690,11 +575,6 @@ export function learningWriteProblem(paths, candidate, base) {
     }
     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/eval-oracle-main.js

@@ -1,9 +1,3 @@
-/**
- * The eval oracle's process (eval-oracle.ts): started by the plane's runner from the installed release, outside the
- * fence, once an attempt's whole process tree is gone. It reads one request on stdin (the installed case's folder, the
- * graded files' folder, the time limit), grades, and writes one verdict line on stdout. It never reads anything the
- * build wrote except the named graded files, and never runs the build's code in its own process.
- */
 import { gradeCase } from "./eval-oracle.js";
 const chunks = [];
 let size = 0;
@@ -16,7 +10,6 @@ for await (const chunk of process.stdin) {
 let verdict;
 try {
     const request = JSON.parse(Buffer.concat(chunks).toString("utf8"));
-    // What the graded program may not read beside the installed eval set (the plane's state folder): absolute paths only.
     const deny = Array.isArray(request.deny) ? request.deny.filter((one) => typeof one === "string" && one.startsWith("/")).slice(0, 8) : [];
     if (typeof request.caseDir !== "string" || typeof request.inputDir !== "string" || !Number.isInteger(request.timeoutMs) || request.timeoutMs < 1 || request.timeoutMs > 600_000) {
         verdict = { outcome: "error", why: "the oracle was asked something it can't read" };