toolroll 0.9.103 → 0.9.105

package/dist/templates.js

@@ -1,27 +1,3 @@
-/**
- * The template library (adoption track, step 2) — common work shipped as
- * STATIC DATA that renders into editable, UNAPPROVED drafts.
- *
- * What a template is: a pre-filled form. What it is not: automation with
- * authority. Applying one produces exactly the rows a manual filing
- * produces — through the same one door (proposal.ts), with the same
- * validators, landing unapproved — and the apply output says so in
- * capitals, because `--file` must never read as a yes.
- *
- * The Codex adoption review (finding 10) drew the v1 line: templates may
- * express ONLY what a task proposal or a scheduled flow can carry today. A
- * repeating template (v115: what a routine template was) makes a scheduled
- * flow whose schedule starts paused, and whose every firing waits for
- * approval under the project's rules. The two
- * use cases that imply separate authenticated authority — GitHub issue
- * intake (a grant) and CI babysitting (publish + the repair button) —
- * ship as RECIPES: they display the existing ceremonies, and cannot be
- * applied, because a template must never create a grant, enable
- * autonomous repair, or touch provider configuration.
- *
- * Deliberately no versioning story: an applied draft is a COPY. Editing
- * this library later changes nothing anybody filed.
- */
 export const TEMPLATES = [
     {
         kind: "scheduled",

package/dist/terminal-catalog.js

@@ -1,15 +1,3 @@
-/**
- * Live terminals, written down for the updater (docs/plans/live-terminal.md, review round 2 finding 7). Terminals live
- * in the console's memory, but an update is decided by another process, so each one is a row in a small catalog
- * beside the database (`<db>.terminals.sqlite`), as the coding workspace keeps its own:
- *
- * - a start inserts its row before any work, and an update's gate (a trigger) refuses that insert while the update
- *   owns admission: no terminal starts during a drain;
- * - a row is `starting` or `running` until the terminal's sweep ends, then deleted — or kept as `uncertain` when the
- *   sweep couldn't prove its processes gone, until the terminal is removed; the updater counts rows whose console is
- *   still alive as active work, so "update when idle" waits for running and unproved terminals;
- * - rows of a console that is gone are stale (its programs went with it, or are swept at its next start).
- */
 import { chmodSync, lstatSync } from "node:fs";
 import { processMayBeAlive } from "./process-liveness.js";
 import { sqliteRuntime } from "./sqlite-runtime.js";
@@ -35,7 +23,6 @@ function open(file, readOnly) {
     db.exec("PRAGMA busy_timeout=1000");
     return db;
 }
-/** The updater's read: never creates the catalog. */
 function withCatalog(orders, absent, readOnly, action) {
     const file = terminalCatalogPath(orders);
     if (file === null || !exists(file))
@@ -48,7 +35,6 @@ function withCatalog(orders, absent, readOnly, action) {
         db.close();
     }
 }
-/** The console's ledger: creates the catalog, drops rows of consoles that are gone, and writes its own. */
 export function openTerminalLedger(orders, alive = pid => processMayBeAlive(pid, false)) {
     const file = terminalCatalogPath(orders);
     if (file === null)
@@ -63,8 +49,6 @@ export function openTerminalLedger(orders, alive = pid => processMayBeAlive(pid,
     }
     return {
         reserve(id) {
-            // Fail closed even where this catalog had no gate to install (it didn't exist yet when the update began): the main
-            // database's own admission pause refuses too.
             if (orders.prepare("SELECT 1 FROM sqlite_master WHERE type='trigger' AND name GLOB 'so_desktop_update_*' LIMIT 1").get() !== undefined)
                 throw new Error(PAUSED);
             try {
@@ -75,7 +59,6 @@ export function openTerminalLedger(orders, alive = pid => processMayBeAlive(pid,
             }
         },
         running(id) { db.prepare("UPDATE live_terminal SET state='running', at=? WHERE id=?").run(new Date().toISOString(), id); },
-        // A sweep that couldn't prove its processes gone stays written down: the updater counts it while this console lives.
         release(id, cleanup) {
             try {
                 if (cleanup === "uncertain")
@@ -83,12 +66,12 @@ export function openTerminalLedger(orders, alive = pid => processMayBeAlive(pid,
                 else
                     db.prepare("DELETE FROM live_terminal WHERE id=?").run(id);
             }
-            catch { /* the next start drops it as stale */ }
+            catch { }
         },
         forget(id) { try {
             db.prepare("DELETE FROM live_terminal WHERE id=?").run(id);
         }
-        catch { /* stale later */ } },
+        catch { } },
     };
 }
 function gateStatement(id) {
@@ -118,7 +101,6 @@ function changeGate(db, id, install) {
 }
 export function installTerminalUpdateGate(orders, id) { withCatalog(orders, undefined, false, db => changeGate(db, id, true)); }
 export function removeTerminalUpdateGate(orders, id) { withCatalog(orders, undefined, false, db => changeGate(db, id, false)); }
-/** Terminals starting or running in a console that is still alive: active work an update waits for. */
 export function activeTerminalUpdateWork(orders, alive = pid => processMayBeAlive(pid, false)) {
     return withCatalog(orders, { terminals: 0 }, true, db => {
         if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='live_terminal'").get())

package/dist/terminal-text.js

@@ -1,26 +1,14 @@
-/**
- * Text someone else wrote, made safe to print on a terminal: the one sanitizer the live view, `peek` and the terminal
- * UI share. Escape sequences in every form go (CSI in 7- or 8-bit form, OSC such as hyperlinks and title changes,
- * every other ESC sequence), and with them every C0 and C1 control character (a carriage return that would
- * overwrite a line, a backspace, a bell), every invisible format character and bidi override; a tab becomes a space.
- * Pure: no imports, so the terminal UI's bundle carries it as is.
- */
-/** Bidi embedding, override and isolate controls. */
 const BIDI_CONTROLS = /[‪-‮⁦-⁩]/g;
-/** One line: controls, escapes and bidi overrides out; tabs to spaces. A newline is a control here too. */
 export function cleanTerminalLine(text) {
     return text
-        // Escape sequences in every form: CSI (7- or 8-bit, any parameter bytes including ':'), OSC, and the rest.
         .replace(/(?:\x1b\[|\u009b)[0-?]*[ -/]*[@-~]/g, "")
         .replace(/(?:\x1b\]|\u009d)[^\x07\x1b\u009c]*(?:\x07|\x1b\\|\u009c)?/g, "")
         .replace(/\x1b[ -/]*[0-~]/g, "")
         .replace(/\t/g, " ")
         .replace(/[\x00-\x1f\x7f-\x9f]/g, "")
-        // Every invisible format character (zero-width, direction marks and overrides, joiners, BOM): never shown.
         .replace(/\p{Cf}/gu, "")
         .replace(BIDI_CONTROLS, "");
 }
-/** Any text for the terminal UI: each line cleaned as above, its newlines kept (a lone carriage return is not one). */
 export function terminalText(text) {
     return text.split("\n").map(cleanTerminalLine).join("\n");
 }

package/dist/test-infra.js

@@ -1,15 +1,3 @@
-/**
- * Test infrastructure, found structurally (docs/plans/auto-approve-green.md): every non-test source file that the tests
- * or the test runner's own setup import, directly or through other files, and that the product's entry points never
- * reach. Changing one changes how tests check things — an automatic release approval leaves that to a person.
- *
- * Imports are read with the TypeScript compiler (typescript-parser, a runtime dependency): `preProcessFile` for static,
- * dynamic and `require` specifiers (comments never count), and the syntax tree for dynamic imports or requires whose
- * specifier isn't a plain string. Specifiers resolve as the build resolves them: relative paths (`./x.js` → `./x.ts`),
- * the project's tsconfig `paths`, and package.json `imports`. Fail closed: a specifier reached from the tests that
- * resolves to no file and to no known package is "unresolved", with what it might name, and the caller refuses when the
- * change touches anything it might name.
- */
 import { createRequire } from "node:module";
 import { builtinModules } from "node:module";
 let compiler;
@@ -18,7 +6,6 @@ const SOURCE = /\.(?:[cm]?[jt]sx?)$/;
 const TEST = /\.test\.[cm]?[jt]sx?$/;
 const VITEST_CONFIG = /(^|\/)vitest\.config\.[cm]?[jt]s$/;
 const EXTENSIONS = ["ts", "tsx", "mts", "cts", "js", "mjs", "cjs", "jsx"];
-/** The product's entry points: the CLI binary, the processes it starts by file name, and the browser bundles. */
 export const PRODUCT_ENTRIES = Object.freeze([
     "src/bin.ts", "src/cli.ts", "src/controller-service.ts", "src/up-role-child.ts", "src/desktop-host.ts", "src/sandbox-launch.ts", "src/tool-launcher.ts",
     "src/browser/app.tsx", "src/browser/terminal-app.tsx",
@@ -39,13 +26,11 @@ const join = (dir, spec) => {
     return parts.join("/");
 };
 const dirOf = (path) => path.split("/").slice(0, -1).join("/");
-/** A repository path, tried as the build tries it (with or without its extension, or as a folder's index). */
 function fileAt(target, files) {
     const stem = target.replace(/\.(?:[cm]?js|jsx)$/, "");
     const tries = [target, ...EXTENSIONS.map(ext => `${stem}.${ext}`), ...EXTENSIONS.map(ext => `${target}/index.${ext}`)];
     return tries.find(one => files.has(one)) ?? null;
 }
-/** The project's resolution rules, read from its own tsconfig.json and package.json (as text in the same tree). */
 function resolverFor(files, names, allPaths, aliases) {
     const tsc = typescript();
     let paths = {}, baseUrl = "";
@@ -63,7 +48,6 @@ function resolverFor(files, names, allPaths, aliases) {
         pkg = {};
     }
     const packages = new Set([pkg.dependencies, pkg.devDependencies, pkg.peerDependencies, pkg.optionalDependencies].flatMap(one => Object.keys(one ?? {})));
-    // The package's own name resolves to itself: never "some installed package".
     const own = typeof pkg.name === "string" ? pkg.name : null;
     const builtins = new Set(builtinModules);
     const pattern = (key, spec) => {
@@ -73,7 +57,6 @@ function resolverFor(files, names, allPaths, aliases) {
         return spec.startsWith(head) && spec.endsWith(tail) && spec.length >= head.length + tail.length ? spec.slice(head.length, spec.length - tail.length) : null;
     };
     return (from, spec) => {
-        // vitest's own aliases come first, as vitest applies them.
         for (const alias of aliases) {
             if (spec !== alias.find && !spec.startsWith(`${alias.find}/`))
                 continue;
@@ -86,7 +69,6 @@ function resolverFor(files, names, allPaths, aliases) {
             const file = target === null ? null : fileAt(target, names);
             if (file !== null)
                 return { file };
-            // A file that isn't source (a stylesheet, JSON, an asset) is a leaf: it imports nothing.
             if (target !== null && allPaths.has(target))
                 return { external: true };
             return { unresolved: target };
@@ -123,24 +105,15 @@ function resolverFor(files, names, allPaths, aliases) {
             return { unresolved: null };
         if (spec.startsWith("node:") || builtins.has(name) || packages.has(name))
             return { external: true };
-        // A package the manifest doesn't declare: what it names can't be known here.
         return { unresolved: null };
     };
 }
-/** The module-loading helpers vitest offers: each takes a specifier first. */
 const VI_LOADERS = new Set(["mock", "doMock", "unmock", "doUnmock", "importActual", "importMock"]);
-/**
- * Every specifier a file names: string ones (preProcessFile: static, dynamic, `require`; comments don't count); every
- * call that loads a module from its first argument — `require`, `import()`, `createRequire(…)(…)` and any name bound to
- * `createRequire(…)`, `vi.*`/`vitest.*` mock and import helpers — whose argument isn't a plain string is computed (`null`,
- * or the template's literal head); and `soft`: every other relative string literal, an edge when it names a repo file.
- */
 function specifiersOf(path, text) {
     const tsc = typescript();
     const literal = tsc.preProcessFile(text, true, true).importedFiles.map(one => one.fileName);
     const computed = [], soft = [];
     const source = tsc.createSourceFile(path, text, tsc.ScriptTarget.Latest, false, /x$/.test(path) ? tsc.ScriptKind.TSX : tsc.ScriptKind.TS);
-    // Names bound to createRequire(…) anywhere in the file (a loader by another name).
     const requires = new Set(["require"]);
     const isCreateRequire = (node) => tsc.isCallExpression(node) && ((tsc.isIdentifier(node.expression) && node.expression.text === "createRequire")
         || (tsc.isPropertyAccessExpression(node.expression) && node.expression.name.text === "createRequire"));
@@ -174,10 +147,6 @@ function specifiersOf(path, text) {
     visit(source);
     return { literal, computed, soft };
 }
-/**
- * The vitest configs' `resolve.alias` and `test.alias` (string keys to string paths, as an object or a list of
- * `{ find, replacement }`), and whether any alias couldn't be read statically.
- */
 function vitestAliases(files) {
     const tsc = typescript(), aliases = [], unreadable = [];
     for (const [path, text] of files) {
@@ -227,7 +196,6 @@ function vitestAliases(files) {
     }
     return { aliases, unreadable };
 }
-/** The vitest configs' setupFiles and globalSetup entries (string literals), as repository paths. */
 function setupRoots(files, names) {
     const tsc = typescript(), roots = [], unresolved = [];
     for (const [path, text] of files) {
@@ -242,7 +210,6 @@ function setupRoots(files, names) {
                         unresolved.push({ from: path, specifier: null, prefix: null });
                         continue;
                     }
-                    // vitest resolves them from its root: the config's own folder, or the repository root a config names.
                     const found = [dirOf(path), ""].map(dir => { const target = join(dir, value.text); return target === null ? null : fileAt(target, names); }).find(one => one !== null) ?? null;
                     if (found !== null)
                         roots.push(found);
@@ -256,11 +223,6 @@ function setupRoots(files, names) {
     }
     return { roots, unresolved };
 }
-/**
- * The infrastructure among `files` (path → text: the tree's sources, and its tsconfig.json and package.json): reachable
- * from a test root — every test file, every file under `test/`, every vitest config and its setup files — not itself a
- * test, and not reachable from PRODUCT_ENTRIES; plus every specifier reached from a test root that couldn't be resolved.
- */
 export function testInfrastructure(files, allPaths = new Set(files.keys())) {
     const names = new Set([...files.keys()].filter(path => SOURCE.test(path)));
     const vitest = vitestAliases(files);
@@ -278,7 +240,6 @@ export function testInfrastructure(files, allPaths = new Set(files.keys())) {
         }
         for (const head of computed)
             open.push({ from: path, specifier: head, prefix: head === null ? null : join(dirOf(path), head) });
-        // Any other relative string that names a repository source file is an edge (a path handed to a loader by any name).
         for (const spec of soft) {
             const found = resolve(path, spec);
             if ("file" in found)
@@ -308,10 +269,6 @@ export function testInfrastructure(files, allPaths = new Set(files.keys())) {
     const unresolved = [...setup.unresolved, ...vitest.unreadable.map(from => ({ from, specifier: null, prefix: null })), ...[...tested].flatMap(path => loose.get(path) ?? [])];
     return { infra, unresolved, product };
 }
-/**
- * Whether a changed path is something an unresolved specifier might name. A computed one (no prefix) might name anything
- * the other rules don't already trust: any source file that is neither a test nor product code.
- */
 export function mightName(open, path, found) {
     if (open.prefix === null)
         return SOURCE.test(path) && !TEST.test(path) && !found.product.has(path);
@@ -319,15 +276,8 @@ export function mightName(open, path, found) {
     const stem = path.replace(/\.[^/.]+$/, "");
     return path === prefix || stem === prefix.replace(/\.(?:[cm]?js|jsx)$/, "") || path.startsWith(`${prefix}/`) || (open.specifier !== null && open.specifier.endsWith("/") === false && path.startsWith(prefix));
 }
-/** Whether a path is a test file by any extension a test runner could be pointed at, not only those run today. */
 export const isTestPath = (path) => TEST.test(path);
-/** A specifier that names a test file, whatever it is spelled as: `./a.test.js`, `../b.test`, `@/c.test.ts`. */
 const NAMES_TEST = /\.test(?:\.[cm]?[jt]sx?)?(?:[?#].*)?$/;
-/**
- * Why a new test file can't carry on what it imports, or null (docs/plans/trusted-release-reports.md, H4). A test file is
- * never infrastructure here, so nothing else looks at an edge between two of them, and importing one runs its top level
- * (its `vi.mock`s and hooks included) in the importer. A computed import might name one, so it refuses too.
- */
 export function testImportProblem(path, text) {
     const { literal, computed, soft } = specifiersOf(path, text);
     const named = [...literal, ...soft].find(spec => NAMES_TEST.test(spec));

package/dist/test-temp.js

@@ -1,22 +1,10 @@
-/**
- * Test temp folders (`toolroll storage`, `storage clean`, the plane's daily storage sweep): what the unit tests,
- * journeys and scripts make in the system temp folder. The suites delete their own on pass, failure, timeout and
- * interrupt (scripts/suite-lifecycle.mjs, test/temp-root.ts); a run killed outright, a proof that keeps its output and
- * older versions leave folders behind. `toolroll storage` counts them; the daily sweep (storage-sweep.ts) and
- * `storage clean` remove the ones nothing has touched for a day, never one whose owner is still running.
- *
- * Every prefix the tests and scripts give tmpdir() is covered here (test-temp.test.ts reads the sources to keep it
- * so), and Playwright's own browser profiles.
- */
 import { execFile } from "node:child_process";
 import { lstatSync, readFileSync, readdirSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 const DAY_MS = 86_400_000;
-/** In a suite's temp root: who made it (scripts/suite-lifecycle.mjs). */
 export const OWNER_FILE = ".toolroll-temp-owner";
-/** Name prefixes of what tests, journeys and scripts leave in the temp folder. */
 export const TEST_TEMP_PREFIXES = [
     "so-", "standing-orders-", "toolroll-", "no-wt", "epoch", "cancel-floor",
     "attest-", "budgets-", "chat-v66-", "check-levels-", "coding-context-", "console-url-", "console-v2-", "e2-attest-",
@@ -24,10 +12,8 @@ export const TEST_TEMP_PREFIXES = [
     "proposal-repo-", "race-", "refresh-migration-", "refresh-refusal-", "release-check-", "shared-chat-", "skills-test-",
     "task-status-surfaces-", "template-repo-", "template-test-", "v14-migrate-", "v17-migrate-", "watch-anchor-",
     "needs-you-", "deps-lock-", "deps-state-", "upgrade-fresh-", "upgrade-path-", "deploy-restore-", "result-review-", "one-result-page-", "deploy-before-swap-", "one-vocabulary-", "accept-finishes-", "lead-promises-", "lead-people-", "sizing-repo-", "batch-checks-", "deps-identity-",
-    // Playwright's browser profiles and artifacts.
     "playwright_chromiumdev_profile-", "playwright_firefoxdev_profile-", "playwright-artifacts-",
 ];
-/** Who made a temp root, from its owner file; null when it has none (older suites, scripts, Playwright). */
 export function tempOwner(path) {
     try {
         const parsed = JSON.parse(readFileSync(join(path, OWNER_FILE), "utf8"));
@@ -41,14 +27,12 @@ export function tempOwner(path) {
 export function isTestTemp(name) {
     return TEST_TEMP_PREFIXES.some(prefix => name.startsWith(prefix));
 }
-/** Where they collect: the temp folder (and /tmp, where some scripts write). */
 export function tempRoots() {
     const roots = [tmpdir()];
     if (process.platform !== "win32" && !roots.includes("/tmp"))
         roots.push("/tmp");
     return roots;
 }
-/** When anything last happened in a folder: it, or what is directly in it, last changed. */
 function touchedAt(path) {
     let newest = lstatSync(path).mtimeMs;
     let names = [];
@@ -62,11 +46,10 @@ function touchedAt(path) {
         try {
             newest = Math.max(newest, lstatSync(join(path, name)).mtimeMs);
         }
-        catch { /* gone */ }
+        catch { }
     }
     return newest;
 }
-/** Every test temp folder in `roots`, and which of them nothing has touched for a day. */
 export function testTempFolders(roots, now) {
     const all = [];
     const seen = new Set();
@@ -90,16 +73,11 @@ export function testTempFolders(roots, now) {
                 seen.add(key);
                 all.push({ path, touchedAt: stat.isDirectory() ? touchedAt(path) : stat.mtimeMs });
             }
-            catch { /* gone */ }
+            catch { }
         }
     }
     return { all, stale: all.filter(one => now.getTime() - one.touchedAt > DAY_MS) };
 }
-/**
- * Remove the test temp folders nothing has touched for a day; each is looked at again right before it goes (still a
- * folder of its own, not a link, still directly in its temp folder, still a day untouched, its owner gone, nothing
- * live using it). Removal never holds the event loop: a worker's heartbeats keep beating while thousands go.
- */
 export async function removeStaleTestTemp(roots, now, options = {}) {
     const removed = [];
     const failed = [];
@@ -131,13 +109,12 @@ export async function removeStaleTestTemp(roots, now, options = {}) {
     return { removed, failed, more: false };
 }
 const nextTurn = () => new Promise(resolve => setImmediate(resolve));
-/** rm -r; a tree a test made read-only (a shared dependency copy, a locked fixture) is made writable first. */
 async function removeTree(path) {
     try {
         await rm(path, { recursive: true, force: true, maxRetries: 3 });
         return;
     }
-    catch { /* read-only inside */ }
+    catch { }
     if (process.platform !== "win32")
         await new Promise(resolve => execFile("chmod", ["-R", "u+w", path], { timeout: 120_000 }, () => resolve()));
     await rm(path, { recursive: true, force: true, maxRetries: 3 });

package/dist/text-limits.js

@@ -1,53 +1,31 @@
-/**
- * Text limits, in one place, and the one way a limit is met: a model is told the exact limit before it writes, an
- * answer still over it is asked once to shorten (one repair turn), and an answer still over after that is kept whole
- * in the record and linked, never chopped. Chat platforms' own message limits are met by splitting across messages.
- *
- * Limits apply when text is written. Reading never re-validates length, so a runtime with lower limits (0.9.23 to
- * 0.9.26) still opens a store holding longer text (scripts/upgrade-path.mjs, the rollback leg).
- */
-/** UTF-16 code units, the JavaScript and HTML maxlength measure, unless a name says bytes. */
 export const TEXT_LIMITS = {
-    /** A task's goal and its out-of-scope text. */
     goal: 8_000,
     goalBytes: 32_000,
-    /** Revise feedback, steering and decision notes. */
     note: 4_000,
     noteBytes: 16_000,
-    /** A flow work zone's instructions; nothing is held back for the card's details (they are attached when long). */
     flowInstructions: 8_000,
-    /** A flow's zones and steps (src/contracts/flow.ts): a zone's name, a step's id as written, and a reference to another step. */
     flowTitle: 60,
     flowStepId: 32,
     flowRef: 60,
-    /** A Message zone's message, or the comment an Update zone leaves. */
     flowMessage: 1_000,
-    /** Who decides a "Person decides" zone (a sign-in name), and the subagent who works a zone, as written. */
     flowDecider: 64,
     flowSubagent: 40,
-    /** A Build zone's other project: its path. */
     flowRepo: 1_000,
-    /** A script's or subagent's answer, a choice's button, a Sort zone's answer and what it means, its question, and a score's level. */
     flowAnswer: 40,
     flowChoice: 40,
     flowSortMeans: 200,
     flowSortQuestion: 300,
     flowSortLevel: 120,
-    /** A Web request zone's address, one header's value and the body it sends (an email's body too). */
     flowUrl: 2_000,
     flowHeader: 500,
     flowBody: 8_000,
-    /** An email's recipients and subject. */
     flowEmailTo: 500,
     flowEmailSubject: 200,
-    /** A tool zone's tool (MCP server), its function, and the arguments as JSON. */
     flowToolServer: 64,
     flowToolName: 100,
     flowToolArgs: 4_000,
-    /** A wait or reminder said in words ("3 days"), and a time zone's name. */
     flowDuration: 40,
     flowTimeZone: 60,
-    /** A flow's name, and a flow file's about line, needs, parameter questions and answers, and scripts. */
     flowName: 80,
     flowFileAbout: 600,
     flowFileNeed: 80,
@@ -55,7 +33,6 @@ export const TEXT_LIMITS = {
     flowScriptAbout: 160,
     flowScriptBody: 20_000,
     flowScriptFile: 200,
-    /** A trigger's settings: a button's label and questions, a schedule and the card it makes, GitHub, Linear, webhook and email terms. */
     triggerButton: 40,
     triggerQuestion: 80,
     triggerSchedule: 80,
@@ -68,97 +45,61 @@ export const TEXT_LIMITS = {
     triggerState: 40,
     triggerWebhookTitle: 120,
     triggerWebhookField: 80,
-    /** v126: a Sentry or Vercel project (or Vercel team) a signed webhook is scoped to. */
     triggerWebhookScope: 120,
     triggerFolder: 100,
     triggerSender: 300,
     triggerSubject: 100,
-    /** A schedule's secrets written as one line ("API_KEY, CRM_TOKEN"). */
     triggerSecrets: 500,
-    /** A card the lead adds to a flow: its title and description; a script it saves inline. */
     flowCardTitle: 200,
     flowCardDescription: 4_000,
     flowScriptInline: 1_600,
-    /** A research report's summary, in UTF-8 bytes. */
     reportSummary: 2_500,
-    /** A scout's whole report file (src/contracts/scout-report.ts), in UTF-8 bytes. */
     reportPayloadBytes: 96 * 1024,
-    /** A report's document (markdown), in UTF-8 bytes. */
     reportDocumentBytes: 64 * 1024,
-    /** A report's title, and a follow-up's or an item's title, in UTF-8 bytes. */
     reportTitleBytes: 200,
-    /** Why an item fits, in UTF-8 bytes. */
     reportWhyBytes: 1_000,
-    /** A web address a report cites, in UTF-8 bytes. */
     reportUrlBytes: 2_000,
-    /** A screenshot's caption and its file name, in UTF-8 bytes. */
     reportCaptionBytes: 300,
-    /** What one flow step passes on to the steps after it. */
     stageOutput: 12_000,
-    /** The planner's whole handoff file, in UTF-8 bytes. */
     planPayloadBytes: 64 * 1024,
-    /** The plan document (markdown), in UTF-8 bytes. */
     planDocumentBytes: 16 * 1024,
-    /** The plan document's Approach section. */
     planApproach: 2_000,
-    /** One Milestones, Dependencies, Risks or Proof item in the plan document. */
     planItem: 600,
-    /** One path a plan expects to touch. */
     planTouch: 200,
-    /** How many paths a task's scope may say it touches (a plan says at most 32 of them). A count, not a length. */
     scopeTouches: 50,
-    /** Why a task was sized as it was, as its sealed route keeps it. */
     sizeReason: 300,
-    /** A planner's amendment note: why the filed contract must change. */
     planAmendment: 1_000,
-    /** An acceptance criterion's id, statement and advisory how, in UTF-8 bytes. */
     acceptanceIdBytes: 40,
     acceptanceStatementBytes: 1_000,
     acceptanceHowBytes: 500,
-    /** A builder's whole proof file, in UTF-8 bytes. */
     proofPayloadBytes: 64 * 1024,
-    /** A proof criterion's id, in UTF-8 bytes. */
     proofCriterionIdBytes: 40,
-    /** How a proof criterion was met, in UTF-8 bytes. */
     proofHowBytes: 500,
-    /** One proof line — a criterion statement, evidence ref, check command or summary, changed path, caveat, or
-     * screenshot path or caption — in UTF-8 bytes. */
     proofLineBytes: 300,
-    /** The task sizing classifier's reason (src/contracts/task-sizing.ts). */
     sizingReason: 160,
-    /** A review comment's or build-review finding's path, and its note or failure scenario (src/contracts/review-findings.ts). */
     reviewPath: 300,
     reviewNote: 500,
-    /** A parked decision (src/contracts/decision.ts): its recap and question, an option's id, label and consequence, and who it is for. */
     decisionRecap: 2_000,
     decisionQuestion: 2_000,
     decisionOptionId: 40,
-    /** A decision's recommendation: an option's id, optionally followed by ": " and why. */
     decisionRecommendation: 500,
     decisionLabel: 120,
     decisionConsequence: 500,
     decisionAssignee: 120,
-    /** A subagent's turn (src/contracts/subagent-turn.ts): the answer it picks (and each option it offers), its question, its reason and what it remembers. */
     subagentAnswer: 60,
     subagentQuestion: 600,
     subagentReason: 400,
     subagentRemember: 300,
-    /** The lead's tools and the MCP gateway (src/contracts/lead-tools.ts, gateway-tools.ts): a task's id as a tool names
-     * it, a task's title and one path it touches, and a project's path as the gateway names it (an assignment brief or
-     * project context, and the rest of the gateway). */
     taskRef: 64,
     taskTitle: 200,
     taskTouch: 200,
     projectPath: 4_096,
     gatewayRepo: 800,
-    /** A project-context query, a check-log search, a memory search, a task search and a changed file's path. */
     contextQuery: 1_000,
     logSearch: 120,
     memorySearch: 300,
     taskSearch: 200,
     diffPath: 300,
-    /** A hold's or cancel's reason, an answer's rationale and option, a worker's name, an agent change's reason, a
-     * provider and model name, how a task's checks were asked for, and an ISO time a recap counts from. */
     proposalReason: 200,
     answerRationale: 400,
     answerOption: 64,
@@ -168,7 +109,6 @@ export const TEXT_LIMITS = {
     agentModel: 120,
     checksWords: 80,
     recapSince: 30,
-    /** A shared action's fields as the lead proposes them (propose_action). */
     actionSample: 800,
     actionContent: 12_000,
     actionTitle: 120,
@@ -177,8 +117,6 @@ export const TEXT_LIMITS = {
     actionUrl: 500,
     actionSecret: 64,
     actionAbout: 240,
-    /** A subagent change (propose_subagent): a soul section's title, a routine's schedule, a tool, an action, a limit's
-     * field, a name, a soul file, a note, a choice and text. */
     subagentSection: 60,
     subagentSchedule: 80,
     subagentTool: 40,
@@ -188,8 +126,6 @@ export const TEXT_LIMITS = {
     subagentNote: 300,
     subagentChoice: 60,
     subagentText: 2_000,
-    /** A project knowledge reference id, a promise and why it is released, what the lead remembers (its text, a
-     * decision's reason and source), a person's name, and a question to the owner with its options. */
     knowledgeReference: 20,
     promise: 240,
     rememberText: 240,
@@ -198,18 +134,12 @@ export const TEXT_LIMITS = {
     personName: 80,
     ownerQuestion: 200,
     ownerOption: 40,
-    /** A gateway filing's idempotency key. */
     idempotencyKey: 64,
-    /** The lead's catch-up bundle (src/contracts/lead-context.ts), in UTF-8 bytes, and the lines it clips: an open promise,
-     * a confirmed correction, the end of changed instructions a correction shows, and what an open proposal is about. */
     leadContextBytes: 8_000,
     leadPromise: 160,
     leadCorrection: 300,
     leadCorrectionInstructions: 240,
     leadProposalAbout: 120,
-    /** Project knowledge (src/contracts/project-knowledge.ts), in UTF-8 bytes: the instructions (also the memory pass's
-     * budget for them), a reference's title, path and text, the context a run gets, the decision lines in it, and the
-     * repository excerpts added when at least the minimum is left. */
     knowledgeInstructionsBytes: 4_000,
     knowledgeTitleBytes: 120,
     knowledgePathBytes: 300,
@@ -218,16 +148,11 @@ export const TEXT_LIMITS = {
     knowledgeDecisionsBytes: 1_500,
     knowledgeRepositoryBytes: 6_000,
     knowledgeRepositoryMinBytes: 3_000,
-    /** A project decision (src/contracts/project-memory.ts), in UTF-8 bytes: the choice, why, who decided, where it came
-     * from, and why it was retired. */
     decisionClaimBytes: 240,
     decisionWhyBytes: 2_000,
     decisionByBytes: 80,
     decisionSourceBytes: 200,
     decisionRetireBytes: 500,
-    /** A skill package (src/contracts/project-skills.ts): its name, description, requirements and source in UTF-8 bytes,
-     * a file's path, SKILL.md, one file, the package and the enabled selection in bytes; a test's sample request and
-     * feedback in characters and bytes. */
     skillNameBytes: 64,
     skillDescriptionBytes: 1_024,
     skillRequirementsBytes: 500,
@@ -241,28 +166,20 @@ export const TEXT_LIMITS = {
     skillSampleBytes: 4_000,
     skillFeedback: 500,
     skillFeedbackBytes: 2_000,
-    /** The memory pass (src/contracts/memory-pass.ts): one session's trace, and in its verdict an effect, a mistake and
-     * the instruction it proposes. */
     memoryTrace: 40_000,
     memoryEffect: 300,
     memoryMistake: 300,
     memoryInstruction: 240,
-    /** A Telegram button's callback_data, in UTF-8 bytes: Telegram refuses a button with more. */
     telegramCallbackDataBytes: 64,
 };
-/** One chat message on each platform. Longer text is split across messages, never cut. Teams: the text one Adaptive Card
- * holds, well inside its 28 KB message. */
 export const PLATFORM_LIMITS = { telegram: 4_096, discord: 2_000, slack: 4_000, teams: 6_000 };
 const count = (n) => n.toLocaleString("en-US");
-/** The line a model reads before it writes a field with a limit. */
 export function limitRule(what, limit, unit = "characters", shorten = true) {
     if (!shorten)
         return `${what}: at most ${count(limit)} ${unit}. Longer text is refused.`;
     return `${what}: at most ${count(limit)} ${unit}. Put the most important part first. Longer text is not cut: you will be asked to shorten it.`;
 }
-/** How long a text is in a limit's unit. */
 export const lengthIn = (text, unit = "characters") => unit === "bytes" ? Buffer.byteLength(text, "utf8") : text.length;
-/** The fields of `values` over their limits. */
 export function overruns(values, limits, unit = "characters") {
     return Object.entries(limits).flatMap(([field, limit]) => {
         const value = values[field];
@@ -272,7 +189,6 @@ export function overruns(values, limits, unit = "characters") {
         return length > limit ? [{ field, limit, length, ...(unit === "bytes" ? { unit } : {}) }] : [];
     });
 }
-/** The repair turn's ask: each field over its limit, by how much, and the same answer again within it. */
 export function shortenAsk(over) {
     return [
         "Your answer is over a limit:",
@@ -280,10 +196,6 @@ export function shortenAsk(over) {
         "Answer again with the same decision and meaning, each field within its limit. Shorten by dropping repetition and detail, not facts that matter.",
     ].join("\n");
 }
-/**
- * Ask, check, and ask once more to shorten. `write` gets null the first time and the shorten ask the second.
- * The second answer is returned whatever its length: the caller keeps it whole (and links it when it must).
- */
 export async function writeWithin(write, check) {
     const first = await write(null);
     const over = check(first);
@@ -292,10 +204,6 @@ export async function writeWithin(write, check) {
     const second = await write(shortenAsk(over));
     return { answer: second, over: check(second), repaired: true };
 }
-/**
- * Text passed on under a limit: whole when it fits; otherwise kept whole in the record named by `where` and passed on
- * as a pointer to it. Never a cut.
- */
 export function passOn(text, limit, where, holds = "a step passes on") {
     if (text.length <= limit)
         return { text, kept: false };