toolroll 0.9.103 → 0.9.105

package/dist/plan-login.js

@@ -1,33 +1,18 @@
-/**
- * How a CLI says it is signed in, read live, right before a run: the gateway's billing evidence, and the proof a
- * plan-pinned fallback agent needs before it runs (fallback.ts). Only providers listed in PLAN_LOGIN_PROVABLE can be a
- * plan fallback: for any other there is no live proof, so filing and the chain setting refuse it.
- */
 import { run as runCommand } from "./exec.js";
-/** How Codex says it's signed in (`codex login status`): a ChatGPT sign-in is its plan; a key or Bedrock is a key;
- * null when it says neither (not signed in, or it didn't answer). */
 export async function codexLoginBilling(binary, omitEnv, env) {
     try {
         const status = await runCommand(binary, ["login", "status"], { timeoutMs: 15_000, omitEnv, processGroup: true,
             ...(env === undefined ? {} : { env: Object.fromEntries(Object.entries(env).filter((one) => one[1] !== undefined)) }) });
         const said = `${status.stdout}\n${status.stderr}`;
-        // Strict: the status line itself, at the start of a line. A line naming both is never read as a plan.
         if (/^Logged in using ChatGPT\s*$/m.test(said) && !/api key|bedrock/i.test(said))
             return "subscription";
-        // Anything naming a key or Bedrock is read as a key (never a plan): that only ever narrows.
         return /api key|bedrock/i.test(said) ? "api-key" : null;
     }
     catch {
         return null;
     }
 }
-/** Providers whose CLI can say, live and machine-readably, that the credential a run will use is a plan. */
 export const PLAN_LOGIN_PROVABLE = new Set(["claude", "codex"]);
-/**
- * How Claude says it is signed in (`claude auth status --json`), read with the run's own environment so it reads the
- * credential the child will use. Strict: a plan only for a first-party claude.ai login with a named subscription; any
- * other shape, a key, a cloud provider or no answer is not a plan.
- */
 export async function claudeLoginBilling(binary, omitEnv, env) {
     try {
         const status = await runCommand(binary, ["auth", "status", "--json"], { timeoutMs: 15_000, omitEnv, processGroup: true,
@@ -48,7 +33,6 @@ export async function claudeLoginBilling(binary, omitEnv, env) {
         return null;
     }
 }
-/** The live plan proof for a provider, or null where none exists (the caller refuses). */
 export async function livePlanLogin(provider, binary, omitEnv, env) {
     if (provider === "codex")
         return codexLoginBilling(binary, omitEnv, env);

package/dist/plan.js

@@ -1,10 +1,3 @@
-/**
- * The planner's terminal handoff, parsed with the 422 rule: fail closed,
- * every problem reported at once, stable reasons, caps and control-character
- * rejection on every string — because a plan payload reaches terminals, the
- * approve card, and the builder's brief (Codex planning review, question 2:
- * the scope proposal is authority-bearing, so it gets the park discipline).
- */
 import { createHash } from "node:crypto";
 import { hasForbiddenControls } from "./decision.js";
 import { parseAcceptanceCriteria } from "./scope.js";
@@ -14,9 +7,6 @@ import { planPayloadBody, readPlanPayload } from "./contracts/plan.js";
 const EXECUTION_PLAN_SECTIONS = ["approach", "milestones", "dependencies", "risks", "proof"];
 const EXECUTION_PLAN_LIST_CAP = 12;
 const EXECUTION_PLAN_ITEM_CAP = TEXT_LIMITS.planItem;
-/** Parse the planner's human-readable artifact without executing Markdown.
- * Older free-form plan artifacts remain renderable through the caller's
- * fallback, while every newly accepted planner handoff uses this shape. */
 export function parseExecutionPlanDocument(raw) {
     const problems = [];
     if (Buffer.byteLength(raw, "utf8") > TEXT_LIMITS.planDocumentBytes) {
@@ -98,18 +88,6 @@ export function parseExecutionPlanDocument(raw) {
     };
     return problems.length === 0 ? { ok: true, document } : { ok: false, problems };
 }
-/**
- * The inverse of `parseExecutionPlanDocument`: the canonical fenced-section
- * markdown for a document the parser already admitted.
- *
- * A builder's revision proposal arrives as free-form text that the parser
- * validates and reduces to this shape; what gets STORED — and later
- * hash-verified, re-read, and quoted into the next brief — is rendered back
- * from that validated shape, never the agent's raw bytes (the scout
- * report's rule, and settleProof's). `parseExecutionPlanDocument` composed
- * with this function is the identity on every document the parser admits:
- * sections in their fixed order, one bullet per item, nothing else.
- */
 export function renderExecutionPlanDocument(document) {
     const bullets = (items) => items.map(item => `- ${item}`);
     return [
@@ -142,7 +120,6 @@ function describe(value) {
         return `a ${value.length}-char string`;
     return `a ${Array.isArray(value) ? "array" : typeof value}`;
 }
-/** A progress note or revision field, checked by hand (those payloads are not on the plan contract yet). */
 function prose(value, field, cap, required, problems) {
     if (value === undefined || value === null || value === "") {
         if (required)
@@ -163,13 +140,7 @@ function prose(value, field, cap, required, problems) {
     }
     return value;
 }
-/**
- * A contract issue as a plan problem (`contractProblemOf`): the reason keeps the codes the rest of the code relies on
- * — `missing-goal`, `bad-touches`, `plan-too-long`, `amendment-too-long`, `acceptance-too-many` — so repair eligibility
- * (document-only problems) and durable outcomes read the same as before the contract.
- */
 export const planProblemOf = contractProblemOf;
-/** scope.ts's rubric problem as a path-named line: `acceptance[0].id: is over 40 bytes`. */
 function acceptanceLine(problem) {
     const named = /^(acceptance(?:\[\d+\])?(?:\.[A-Za-z]+)?) (.*)$/.exec(problem.message);
     if (named !== null)
@@ -177,14 +148,7 @@ function acceptanceLine(problem) {
     const at = /^(acceptance\[\d+\])-/.exec(problem.reason)?.[1] ?? "acceptance";
     return `${at}: ${problem.message}`;
 }
-/** True when `problems` name `field` or anything under it. */
 const touched = (problems, field) => problems.some(problem => problem.message.startsWith(`${field}:`) || problem.message.startsWith(`${field}[`) || problem.message.startsWith(`${field}.`));
-/**
- * The rules JSON Schema cannot state, in plain code with named errors: control characters, one-line touches, the
- * document's byte cap and sections, the acceptance rubric's byte limits and duplicate ids (scope.ts's own parser),
- * and the Proof naming every criterion. Fields the contract already refused are skipped, so every problem is
- * reported once and all at once.
- */
 function planRuleProblems(body, contract) {
     const problems = [];
     const text = (field) => {
@@ -240,11 +204,6 @@ function planRuleProblems(body, contract) {
     }
     return { problems, criteria };
 }
-/**
- * The planner's handoff, read against the plan contract (src/contracts/plan.ts): fail closed, every problem at once,
- * each one naming its path (`acceptance[0].evidence[0]: must be one of ...`). A plan saved before plans carried
- * `version` reads as it always did.
- */
 export function parsePlan(raw) {
     if (Buffer.byteLength(raw, "utf8") > TEXT_LIMITS.planPayloadBytes) {
         return refuse("too-large", `payload: over ${TEXT_LIMITS.planPayloadBytes.toLocaleString("en-US")} bytes`);
@@ -281,13 +240,6 @@ export function parsePlan(raw) {
     };
 }
 const MILESTONE_STATES = ["pending", "current", "completed", "blocked"];
-/**
- * A milestone's identity is its position plus a short hash of its
- * normalized text — stable across re-reads of the same revision, but a
- * milestone whose wording changes materially becomes a NEW identity rather
- * than silently inheriting stale completion state from a differently-worded
- * predecessor.
- */
 export function milestoneId(index, description) {
     const hash = createHash("sha256").update(description.trim().toLowerCase(), "utf8").digest("hex").slice(0, 8);
     return `m${index + 1}-${hash}`;
@@ -300,11 +252,6 @@ export const PROGRESS_LIMITS = {
     note: 300,
     milestones: EXECUTION_PLAN_LIST_CAP,
 };
-/** Parse a progress checkpoint written by a running build. `expectedRevisionHash`
- * and `knownIds` come from the plan revision the build's brief actually
- * named — a snapshot naming a different revision, an unknown milestone id,
- * a missing milestone, or more than one "current" milestone fails closed
- * with every problem at once, the same 422 rule as the plan itself. */
 export function parseProgressSnapshot(raw, expectedRevisionHash, knownIds) {
     if (Buffer.byteLength(raw, "utf8") > PROGRESS_LIMITS.payload) {
         return { ok: false, problems: [{ reason: "progress-too-large", message: `progress is over ${PROGRESS_LIMITS.payload} bytes` }] };
@@ -374,10 +321,6 @@ export function parseProgressSnapshot(raw, expectedRevisionHash, knownIds) {
         return { ok: false, problems };
     return { ok: true, snapshot: { revisionHash: revisionHash, milestones } };
 }
-/** Whether a checkpoint transition is a legitimate update or a regression:
- * once a milestone is completed it never reverts — an agent restating an
- * old snapshot (a stale pulse, a retried read) must never erase progress
- * that a later, newer checkpoint already recorded. */
 export function isMilestoneRegression(previous, next) {
     return previous === "completed" && next !== "completed";
 }
@@ -386,10 +329,6 @@ export const REVISION_LIMITS = {
     reason: 2_000,
     evidenceLink: 500,
 };
-/** Parse the builder's terminal revision-proposal file: a complete
- * replacement plan document plus the evidence that invalidated the one it
- * was given. One proposal per build — the caller enforces that by never
- * offering the agent more than one nonce-named path to write. */
 export function parsePlanRevisionProposal(raw) {
     if (Buffer.byteLength(raw, "utf8") > REVISION_LIMITS.payload) {
         return { ok: false, problems: [{ reason: "revision-too-large", message: `revision proposal is over ${REVISION_LIMITS.payload} bytes` }] };
@@ -424,13 +363,6 @@ export function parsePlanRevisionProposal(raw) {
 export function authoritySnapshotDigest(snapshot) {
     return createHash("sha256").update(`${snapshot.scopeDigest}\u0000${snapshot.deliverable}`, "utf8").digest("hex").slice(0, 32);
 }
-/** Classify a revision against the complete authority snapshot the build
- * actually started under. Everything the builder's own proposal can name is
- * plan-only by construction (it carries no scope fields at all) — this
- * check exists as the defense against the world moving underneath a live
- * build: if the signed scope or publication authority changed by any other
- * road while the build ran, the revision is never auto-applied, whatever it
- * proposes. */
 export function classifyRevisionAuthority(previous, current) {
     const changed = [];
     if (previous.scopeDigest !== current.scopeDigest)

package/dist/plane-review.js

@@ -1,32 +1,3 @@
-/**
- * The morning plane review: what went wrong on this plane in the last 24
- * hours, read straight from the store — never a model, never a fenced
- * script — as one problem per distinct thing worth fixing:
- *
- * - failed or no-change runs, grouped by cause (provider error, sign-in
- *   expiry, check failure, timeout, quit without handoff, stuck lease,
- *   orphaned process, no change, other);
- * - tasks stuck for over a day on something the system must fix (unfinished
- *   work no worker holds, repeated failures, an incident hold), grouped by
- *   what they wait for;
- * - sign-in and plan-limit pauses, per provider;
- * - chat replies that couldn't be delivered, per app;
- * - integrations that are Broken (integration_check);
- * - release checks that failed;
- * - worker passes that logged work as broke.
- *
- * Each problem has a stable key, so the same problem tomorrow is the same
- * problem (flow-triggers.ts joins it to its card), and carries counts, run
- * ids and short evidence excerpts with anything shaped like a secret hidden.
- * A clean day is no problems at all. Only projects the reader may see count.
- *
- * Waits only a person can end — a result to open, a question to answer, a
- * plan or task to approve, a hold to lift, a scope to write — are never
- * problems: each card starts a find-the-cause → fix → pull request flow, and
- * no code change opens a result for someone. Needs you and chat already ask
- * the person. `longPersonWaits` counts the ones over `LONG_WAIT_DAYS` so the
- * review's own summary line can mention them once, filing nothing.
- */
 import { scanForSecrets } from "./evidence.js";
 import { scrubIntegrationText } from "./integrations.js";
 import { taskWaitSnapshot } from "./lead-status.js";
@@ -34,9 +5,7 @@ import { wasInterrupted } from "./run-ending.js";
 export const REVIEW_HOURS = 24;
 const EVIDENCE_LINES = 5;
 const WAITING_DAYS = 1;
-/** A person's wait this long is mentioned in the review's summary line. */
 export const LONG_WAIT_DAYS = 3;
-/** What a person, not the code, must do next (lead-status.ts `taskWaitSnapshot`). The rest have a system cause. */
 const PERSON_NEXT = new Set(["Open result", "Answer the task's question", "Answer question", "Remove hold", "Review plan", "Resume or close attempt", "Choose a result", "Approve plan", "Add scope", "Approve task"]);
 export const RUN_CAUSES = ["provider", "sign-in", "check", "timeout", "no-handoff", "stuck-lease", "orphaned", "no-change", "other"];
 const CAUSE_TITLES = {
@@ -50,7 +19,6 @@ const CAUSE_TITLES = {
     "no-change": "Runs ended with no change",
     other: "Runs failed for another reason",
 };
-/** Anything shaped like a key is hidden; one short line. */
 export function excerpt(text, cap = 160) {
     if (text === null || text === undefined)
         return "";
@@ -61,7 +29,6 @@ export function excerpt(text, cap = 160) {
 }
 const PROVIDER_REASONS = new Set(["retryable-infra", "provider-init", "provider-protocol", "provider-unattested", "setup"]);
 const TIMEOUT_WORDS = /made no observable progress|ran past \d+ minutes|timed out/i;
-/** Why one finished run is a problem, or null when it isn't. */
 export function runCause(run) {
     const reason = run.reason ?? "";
     if (reason === "auth-expired" || run.terminalClass === "auth-expired")
@@ -89,11 +56,6 @@ const keyPart = (value) => value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").re
 const str = (value) => value === null || value === undefined ? null : String(value);
 const tableExists = (store, table) => store.handle.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table) !== undefined;
 const columnExists = (store, table, column) => store.handle.prepare(`SELECT 1 FROM pragma_table_info('${table}') WHERE name = ?`).get(column) !== undefined;
-/**
- * Every problem worth fixing in the `REVIEW_HOURS` before `now`, worst first.
- * `canSee(repo)` says which projects' work counts (a run or task with no
- * project counts only when every project may be seen).
- */
 export function reviewPlane(store, now, canSee = () => true) {
     const since = new Date(now.getTime() - REVIEW_HOURS * 3_600_000).toISOString();
     const buckets = new Map();
@@ -106,7 +68,6 @@ export function reviewPlane(store, now, canSee = () => true) {
             bucket.evidence.push(item.evidence);
         buckets.set(key, bucket);
     };
-    // Runs that finished badly, by cause.
     const runs = store.handle.prepare(`SELECT run.id, run.outcome, run.reason, run.terminal_class, run.handoff, run.provider, ref.repo, ref.external_id AS task,
       (SELECT status FROM run_check WHERE run_check.run = run.id AND run_check.release = 0) AS check_status,
       (SELECT line FROM run_check WHERE run_check.run = run.id AND run_check.release = 0) AS check_line,
@@ -129,7 +90,6 @@ export function reviewPlane(store, now, canSee = () => true) {
         else
             add(`run/${cause}`, CAUSE_TITLES[cause], ["run", "runs"], { run: id, evidence });
     }
-    // Leases that expired without being given back: the worker holding them went quiet.
     const leases = store.handle.prepare(`SELECT claim.lease_id, claim.runner, claim.expires_at, claim.released_by, ref.repo, ref.external_id AS task,
       (SELECT MAX(run.id) FROM run WHERE run.lease_id = claim.lease_id) AS run
     FROM claim JOIN task_ref ref ON ref.id = claim.task_ref
@@ -142,7 +102,6 @@ export function reviewPlane(store, now, canSee = () => true) {
         add("run/stuck-lease", CAUSE_TITLES["stuck-lease"], ["lease", "leases"], { run,
             evidence: `Task ${str(row["task"]) ?? "?"}${run === null ? "" : `, run ${run}`}: the lease held by ${excerpt(str(row["runner"]), 40)} ${row["released_by"] === "reaped" ? "expired and was taken back" : "expired and is still held"}` });
     }
-    // Processes still alive for a run that has finished.
     const orphans = store.handle.prepare(`SELECT rp.run, rp.pid, rp.host, ref.repo, ref.external_id AS task FROM run_process rp
     JOIN run ON run.id = rp.run JOIN task_ref ref ON ref.id = run.task_ref
     WHERE rp.exited_at IS NULL AND run.outcome IS NOT NULL AND (run.finished_at >= ? OR rp.observed_at >= ?) ORDER BY rp.run`).all(since, since);
@@ -152,14 +111,12 @@ export function reviewPlane(store, now, canSee = () => true) {
         const run = Number(row["run"]);
         add("run/orphaned", CAUSE_TITLES.orphaned, ["run", "runs"], { run, evidence: `Run ${run} (task ${str(row["task"]) ?? "?"}): process ${str(row["pid"]) ?? "?"} on ${excerpt(str(row["host"]), 40)} was still running after it finished` });
     }
-    // Tasks stuck for over a day on a system cause, by what they wait for. Waits on a person are never cards.
     for (const wait of openWaits(store, new Date(now.getTime() - WAITING_DAYS * 86_400_000), now, canSee)) {
         if (wait.person)
             continue;
         add(`waiting/${keyPart(wait.next)}`, `Tasks waited over a day: ${wait.next}`, ["task", "tasks"], { run: wait.run,
             evidence: `Task ${wait.id} “${excerpt(wait.title, 80)}”: ${plural(wait.days, "day")} waiting` });
     }
-    // Sign-in and plan-limit pauses.
     if (tableExists(store, "provider_auth_pause")) {
         for (const row of store.handle.prepare("SELECT provider, opened_at, lifted_at, runs, first_run FROM provider_auth_pause WHERE opened_at >= ? OR lifted_at IS NULL OR lifted_at >= ? ORDER BY id").all(since, since)) {
             const provider = String(row["provider"]);
@@ -175,7 +132,6 @@ export function reviewPlane(store, now, canSee = () => true) {
             });
         }
     }
-    // Chat replies that couldn't be delivered.
     if (tableExists(store, "chat_part")) {
         const names = { telegram: "Telegram", slack: "Slack", discord: "Discord", teams: "Teams" };
         for (const row of store.handle.prepare("SELECT provider, problem, attempts FROM chat_part WHERE state = 'dropped' AND created >= ? ORDER BY provider = 'telegram' DESC, provider, id").all(since)) {
@@ -188,14 +144,12 @@ export function reviewPlane(store, now, canSee = () => true) {
             add("chat/telegram", "Telegram replies weren't delivered", ["reply", "replies"], { evidence: `After ${plural(Number(row["attempts"] ?? 0), "try", "tries")}: ${excerpt(str(row["last_error"]))}` });
         }
     }
-    // Integrations that are Broken now and were checked in the window.
     if (tableExists(store, "integration_check")) {
         for (const row of store.handle.prepare("SELECT key, problem, checked_at FROM integration_check WHERE outcome = 'failed' AND checked_at >= ? ORDER BY key").all(since)) {
             const key = String(row["key"]);
             add(`integration/${keyPart(key)}`, `Integration broken: ${excerpt(key, 40)}`, ["check", "checks"], { evidence: excerpt(str(row["problem"])) || "The last check failed." });
         }
     }
-    // Release checks that failed.
     const releases = store.handle.prepare(`SELECT rc.run, rc.line, ref.repo, ref.external_id AS task FROM run_check rc JOIN run ON run.id = rc.run JOIN task_ref ref ON ref.id = run.task_ref
     WHERE rc.release = 1 AND rc.status = 'failed' AND rc.recorded_at >= ? ORDER BY rc.run`).all(since);
     for (const row of releases) {
@@ -205,7 +159,6 @@ export function reviewPlane(store, now, canSee = () => true) {
         const said = excerpt(str(row["line"]));
         add("release-check", "Release checks failed", ["check", "checks"], { run, evidence: `Run ${run} (task ${str(row["task"]) ?? "?"})${said === "" ? "" : `: ${said}`}` });
     }
-    // What the worker counted as broke in its passes.
     if (tableExists(store, "watch_episode") && columnExists(store, "watch_episode", "broke")) {
         for (const row of store.handle.prepare("SELECT id, repo, runner, broke, started_at, ended_at FROM watch_episode WHERE broke > 0 AND COALESCE(ended_at, started_at) >= ? ORDER BY id").all(since)) {
             if (!canSee(str(row["repo"])))
@@ -221,7 +174,6 @@ export function reviewPlane(store, now, canSee = () => true) {
             summary: `${plural(bucket.count, bucket.noun[0], bucket.noun[1])} in the last ${REVIEW_HOURS} hours${runsList.length === 0 ? "" : ` (${runsList.length === 1 ? "run" : "runs"} ${runsList.slice(0, 12).join(", ")}${runsList.length > 12 ? ", …" : ""})`}.` };
     }).sort((a, b) => b.count - a.count || a.key.localeCompare(b.key));
 }
-/** Queued or running tasks last touched by `before` that wait, and on what; replaced versions never wait on their own. */
 function openWaits(store, before, now, canSee) {
     const rows = store.handle.prepare(`SELECT task.id, task.title, task.updated_at, ref.repo FROM task JOIN task_ref ref ON ref.backend = 'built-in' AND ref.external_id = task.id
     WHERE task.updated_at <= ? AND task.state IN ('queued', 'running') ORDER BY task.updated_at LIMIT 500`).all(before.toISOString());
@@ -244,31 +196,23 @@ function waitsOf(store, rows, now, canSee) {
     }
     return waits;
 }
-/**
- * Results nobody has opened, and tasks waiting on a person's answer, approval or hold, for over `LONG_WAIT_DAYS`
- * before `now`. Counted for the review's summary line only; they are never problems.
- */
 export function longPersonWaits(store, now, canSee = () => true) {
     const before = new Date(now.getTime() - LONG_WAIT_DAYS * 86_400_000);
-    // Newest first, so years of Complete work never crowds out this week's unopened results.
     const finished = store.handle.prepare(`SELECT task.id, task.title, task.updated_at, ref.repo FROM task JOIN task_ref ref ON ref.backend = 'built-in' AND ref.external_id = task.id
     WHERE task.updated_at <= ? AND task.state = 'done' ORDER BY task.updated_at DESC LIMIT 500`).all(before.toISOString());
     const results = waitsOf(store, finished, now, canSee).filter(wait => wait.person).length;
     const tasks = openWaits(store, before, now, canSee).filter(wait => wait.person).length;
     return { results, tasks };
 }
-/** "3 results have waited over 3 days for you." — or null when nothing has. */
 export function longWaitWords(waits) {
     const parts = [waits.results > 0 ? plural(waits.results, "result") : null, waits.tasks > 0 ? plural(waits.tasks, "task") : null].filter(one => one !== null);
     if (parts.length === 0)
         return null;
     return `${parts.join(" and ")} ${waits.results + waits.tasks === 1 ? "has" : "have"} waited over ${LONG_WAIT_DAYS} days for you.`;
 }
-/** A problem as a card's details (or a day's note on a card it joins). */
 export function problemText(problem, day) {
     return [`${day}: ${problem.summary}`, ...problem.evidence.map(line => `- ${line}`)].join("\n");
 }
-/** The card's opening details: the day's evidence, and what it is. */
 export function problemCard(problem, day) {
     return { title: problem.title, description: `${problemText(problem, day)}\n\nFound by the morning plane review (problem ${problem.key}). If it comes back, the new day joins this card.` };
 }

package/dist/planner-source.js

@@ -1,40 +1,3 @@
-/**
- * The planner's SOURCE: exactly what was filed for a task at the moment a
- * planning attempt starts — the scope's goal, exclusions, touches, and the
- * whole rubric (ids, statements, evidence kinds, advisory how), its
- * execution terms, the revision brief when the task revises reviewed work,
- * and the operator's earlier answers — captured losslessly as quoted data.
- *
- * Filed intent is DATA, never authorization: nothing here approves, and a
- * planner reading it gains no authority it did not already have. What it
- * gains is the operator's actual words, so a short title can no longer
- * become a title-derived guess that silently drops the UI evidence, the
- * exclusions, or a criterion somebody wrote down (contract handoff plan,
- * task 1).
- *
- * Three facts ride the same record:
- *
- *   identity   `sourceDigest` — a digest over the CONTRACT part (scope
- *              digest and terms, task-level terms, the revision brief's
- *              artifact and hash). The planner run is stamped with it, a
- *              same-session correction inherits it through its parent, a
- *              resumed decision re-derives it, and the plan ingestion
- *              re-derives it INSIDE its transaction: a source that moved
- *              while the planner ran refuses the draft rather than
- *              overwriting the newer terms.
- *   bounds     one explicit byte cap on the whole quoted record. Over it,
- *              the attempt refuses in words BEFORE any provider spend —
- *              a brief that silently trimmed a criterion would be the very
- *              loss this module exists to prevent.
- *   changes    `contractChangesOf` — the mechanical additions, changes,
- *              and removals between the filed terms and what a planner
- *              drafted. A plan that changes filed terms must SAY so with an
- *              explicit amendment; the approval shows every change either
- *              way and binds exactly the terms the operator accepts.
- *
- * Pure primitives plus one store-reading assembler. No spawning, no
- * transactions of its own: the fenced finalizers in claim.ts seal.
- */
 import { readSnapshot, REFERENCE_LIMIT, referenceWords } from "./task-source.js";
 import { createHash } from "node:crypto";
 import { EVIDENCE_CAPS, readVerifiedArtifact } from "./evidence.js";
@@ -44,19 +7,11 @@ import { contractChangesOf } from "./contract-changes.js";
 import { canonicalJsonUndefinedAsNull } from "./canonical-json.js";
 export const PLANNER_SOURCE_VERSION = 1;
 export const PLANNER_SOURCE_LIMITS = {
-    /** The whole recorded source before lossless prompt fencing. Equal to
-     * the evidence cap for its artifact kind, so a recorded source is never
-     * truncated: what the record holds is exactly what the planner read. */
     bytes: EVIDENCE_CAPS["plan-contract"],
-    /** A planner's amendment note: why the filed contract must change. */
     amendment: TEXT_LIMITS.planAmendment,
-    /** Earlier answers quoted into the brief. */
     answers: 5,
-    /** Terms that exceed the entire handoff cap cannot fit regardless of the plan's size. Do not reserve a maximum-
-     * sized plan here: a shorter document can carry larger valid terms. The final payload still enforces its byte cap. */
     handoffTerms: TEXT_LIMITS.planPayloadBytes,
 };
-/** Stable JSON for hashing and equality only — no filling, no trimming. */
 export const canonicalContractJson = canonicalJsonUndefinedAsNull;
 export function plannerSourceDigest(contract) {
     return createHash("sha256").update(`planner-source:v${PLANNER_SOURCE_VERSION}\n${canonicalContractJson(contract)}`, "utf8").digest("hex");
@@ -88,12 +43,6 @@ function contractScopeOf(scope) {
         proposedVia: scope.proposedVia ?? null,
     };
 }
-/**
- * The contract part, read from the store alone — no file I/O — so the plan
- * ingestion can re-derive it inside its own transaction and compare
- * digests. The revision brief enters by artifact id and sha256: the row
- * is immutable, and the hash is what a verified read proves against.
- */
 export function plannerContractOf(store, taskId) {
     const ref = store.lookupRef(taskId);
     if (ref === null)
@@ -124,7 +73,6 @@ export function plannerContractOf(store, taskId) {
                 agentPin: { provider: ref.agentProvider, model: ref.agentModel },
                 planPin: { provider: ref.planProvider, model: ref.planModel },
                 deliverable: ref.deliverable,
-                // The declared risk level was removed in v115; the field stays in the recorded shape.
                 riskLevel: null,
                 qualityMode: ref.qualityMode ?? null,
                 permissionMode: ref.permissionMode ?? null,
@@ -133,13 +81,6 @@ export function plannerContractOf(store, taskId) {
         },
     };
 }
-/**
- * Everything a planning attempt is given, assembled once per attempt from
- * the store and the verified evidence root, and measured against the byte
- * cap BEFORE anything is leased or spent. A brief that cannot be read is a
- * refusal in words (the builder's rule for the same artifact), never a
- * plan drafted without half its contract.
- */
 export function plannerSourceOf(store, root, taskId, answers) {
     const contract = plannerContractOf(store, taskId);
     if (!contract.ok)
@@ -198,15 +139,6 @@ export function plannerSourceOf(store, root, taskId, answers) {
         return { ok: false, reason: "too-long", message: handoff };
     return { ok: true, source, bytes };
 }
-/**
- * The dispatch diagnosis's read of the same gate, from the store alone:
- * why the next pass would refuse to plan this task before spending — the
- * revision brief unreadable, the filed request over the byte cap, or terms
- * the planner's handoff cannot carry. The size is a floor (the brief's
- * stored bytes, before JSON quoting), so a "yes" here is certain and the
- * dispatch refusal itself stays the exact word. Null when nothing here
- * stands in the way.
- */
 export function plannerSourceProblemOf(store, taskId) {
     const filed = (detail) => ({ title: "The filed request cannot be planned as filed", detail });
     if (store.answeredDecisionsFor(taskId, PLANNER_SOURCE_LIMITS.answers + 1).length > PLANNER_SOURCE_LIMITS.answers)
@@ -222,12 +154,6 @@ export function plannerSourceProblemOf(store, taskId) {
     const handoff = contract.contract.scope === null ? null : plannerHandoffProblemOf(contract.contract.scope);
     return handoff === null ? null : { title: "Scope too long to plan", detail: handoff };
 }
-/**
- * Whether the planner can hand the filed terms back (contracts/plan.ts): it must reproduce the goal, exclusions,
- * touches and criteria in its handoff, so terms its handoff cannot carry would end every attempt as a malformed plan.
- * This names the problem before any workspace, run or provider spend instead: the actual size, the limit, and what to
- * shorten. Null when the terms fit.
- */
 export function plannerHandoffProblemOf(terms) {
     const n = (value) => value.toLocaleString("en-US");
     for (const [label, is, text] of [["goal", "is", terms.goal], ["exclusions", "are", terms.outOfScope ?? ""]]) {
@@ -245,7 +171,6 @@ export function plannerHandoffProblemOf(terms) {
     }
     return null;
 }
-/** The exact bytes recorded as evidence; prompt fencing preserves the JSON value. */
 export function encodePlannerSource(source) {
     return Buffer.from(JSON.stringify(source, null, 2), "utf8");
 }
@@ -256,7 +181,6 @@ function isContractTerms(value) {
         Array.isArray(value["touches"]) && value["touches"].every(one => typeof one === "string") &&
         Array.isArray(value["acceptance"]) && value["acceptance"].every(one => object(one) && typeof one["id"] === "string" && typeof one["statement"] === "string" && nullableString(one["how"]) && Array.isArray(one["evidence"]) && one["evidence"].every(kind => ["check", "screenshot", "changed-path", "manual-review"].includes(String(kind))));
 }
-/** Read a recorded source back; null when the bytes are not one. */
 export function decodePlannerSource(content) {
     try {
         const parsed = JSON.parse(content.toString("utf8"));
@@ -279,8 +203,6 @@ export function decodePlannerSource(content) {
         if (contract["revision"] !== null && (!object(contract["revision"]) || typeof contract["revision"]["of"] !== "string" || !Number.isSafeInteger(contract["revision"]["briefArtifact"]) || typeof contract["revision"]["briefSha256"] !== "string"))
             return null;
         const source = parsed;
-        // The record proves itself: the digest it carries is the digest of the
-        // contract it carries, or the file is not the record it claims to be.
         if (plannerSourceDigest(source.contract) !== source.sourceDigest)
             return null;
         return source;
@@ -289,10 +211,8 @@ export function decodePlannerSource(content) {
         return null;
     }
 }
-// ---- amendments -----------------------------------------------------------
 export { contractChangesOf } from "./contract-changes.js";
 const clip = (text, max) => (text.length > max ? `${text.slice(0, max - 1)}…` : text);
-/** One line per change, for terminals, notifications, and validation messages. */
 export function describeContractChanges(changes) {
     return changes.map(change => {
         switch (change.field) {
@@ -343,27 +263,11 @@ export function decodePlanContractRecord(content) {
         return null;
     }
 }
-// ---- the brief ------------------------------------------------------------
-/**
- * One line, prefixed, with nothing that can end the block or start a new
- * rule — the builder's fence, applied to the planner's quoted source. The
- * source is quoted as pretty-printed JSON, so every control character an
- * operator's text carries arrives as a visible JSON escape: lossless, and
- * still one physical line per JSON line.
- */
 export function fenceSourceLine(text) {
     return `| ${text
-        // Preserve the JSON value while removing delimiter-shaped raw bytes.
-        // eslint-disable-next-line no-control-regex
         .replace(/[\u0000-\u001F\u007F-\u009F\u2028\u2029`]/g, one => `\\u${one.charCodeAt(0).toString(16).padStart(4, "0")}`)
         .replace(/STANDING-ORDERS-/g, "\\u0053TANDING-ORDERS-")}`;
 }
-/**
- * The brief's source block: the recorded JSON value, losslessly fenced between markers,
- * followed by the rules that make the filed terms a contract to preserve
- * or amend explicitly — never authorization, never a guess to overwrite.
- */
-/** A person's send-back (the annotation road): its brief carries their notes. Repair drafts carry failure evidence instead. */
 function sentBackWithNotes(brief) {
     try {
         const parsed = JSON.parse(brief);