toolroll 0.9.103 → 0.9.105

package/dist/fast-start.js

@@ -1,25 +1,3 @@
-/**
- * The fast path: file and approve in one step (docs/plans/plain-toolroll.md P2.4).
- *
- * For an eligible small task a person starts themselves, the New task form shows the exact terms a plan approval would
- * seal, and pressing Build is that person's approval of exactly those terms: approve()'s own checks on the digest they
- * saw, with the same proofs, inside the filing's transaction. Nothing is narrowed or widened. The seal is the ordinary
- * person basis; the marker (the proof row's `fastStart`, `task_ref.fast_start_at`) only adds restrictions:
- *
- * - **the start window**: the first build starts within 30 minutes, or the seal is cleared in a logged transaction and
- *   the task shows the ordinary Approve plan (approval-authority.ts fastStartStandsSql, expireFastStarts);
- * - **the Accept backstop**: a machine can't complete it, the project's grant doesn't push it until a person accepted it,
- *   and completion, publication and merge all read one verified measure of the whole change (verifiedChange).
- *
- * Only a person's own surfaces reach here (the browser, the terminal UI as the local owner, interactive `task new`, and
- * a person's own tap or typed yes on a chat's Start card: docs/plans/one-step-chat.md). Every machine is refused in the
- * writer from trusted context. `task add` never comes this way.
- *
- * A chat start (`via: "chat"`) runs the same rules (fastStartRules). Its words are the lead's, so it is filed as the
- * lead's text (`proposedVia: "mate"`, quarantined), and only its person-proof step differs: chat has no password, so
- * instead of the password field it passes only within the person's own chat approval limits (chatLimitProblem), and
- * quarantined text is approvable in chat only on a card that showed every term whole (store.ts sealScopeApproval).
- */
 import { randomBytes } from "node:crypto";
 import { approvalPasswordField } from "./approval-password.js";
 import { chatLimitProblem } from "./chat-terms.js";
@@ -36,12 +14,10 @@ import { classifyTask, filingSizer, heuristicSizing } from "./task-sizing.js";
 import { issueImported } from "./task-source.js";
 import { titleWithin } from "./task-text.js";
 import { viewedGitSync } from "./teardown-git.js";
-/** The constants, in one place, versioned together in every marker. */
 export const FAST_START_RULE = "small-v1";
 export const FAST_WINDOW_MS = 30 * 60_000;
 export const FAST_MAX_FILES = 3;
 export const FAST_MAX_LINES = 150;
-/** How long a rendered form may still be pressed. */
 export const FAST_PREVIEW_MS = 15 * 60_000;
 const FAST_WORDS = {
     setting: "Small tasks don't start right away in this project.",
@@ -63,9 +39,6 @@ const FAST_WORDS = {
     limit: "This is more than your chat approval setting allows.",
 };
 export const fastRefusalWords = (reason) => FAST_WORDS[reason];
-// ---- the project setting ---------------------------------------------------------------------------------------------
-/** Small tasks start right away: a project's own choice, else on for single-approver installs and off once there's more
- * than one approver. */
 export function fastStartOn(store, repo) {
     const saved = store.handle.prepare("SELECT fast_start FROM project WHERE path = ?").get(repo)?.["fast_start"];
     if (saved === 0 || saved === 1)
@@ -73,7 +46,6 @@ export function fastStartOn(store, repo) {
     const approvers = Number(store.handle.prepare("SELECT COUNT(*) AS n FROM approver WHERE revoked_at IS NULL AND role = 'approver'").get()?.["n"] ?? 0);
     return approvers === 1;
 }
-/** A person's logged settings act. */
 export function setFastStart(store, repo, on, by, now) {
     return store.transact(() => {
         const written = store.handle.prepare("UPDATE project SET fast_start = ? WHERE path = ?").run(on ? 1 : 0, repo);
@@ -83,17 +55,12 @@ export function setFastStart(store, repo, on, by, now) {
         return true;
     });
 }
-// ---- eligibility: one function, read by the form and again inside the transaction ------------------------------------
-/** Filed this way, the plan's words are the person's words, and they inspect the result. */
 export const fastAcceptance = (title) => [{ id: "c1", statement: title, how: null, evidence: ["manual-review"] }];
-/** Every person surface's eligibility: the rules, then a machine is refused. */
 export function fastStartEligible(store, input, now) {
     if (machineActing())
         return { ok: false, reason: "machine" };
     return fastStartRules(store, { ...input, proof: "proof" in input ? input.proof : { password: input.password } }, now);
 }
-/** The rules alone, the same for every surface: only the person-proof step has two forms (FastProof). A preview reads
- * these as any caller; Build reads them again behind the machine check (fastStartEligible). */
 export function fastStartRules(store, input, now) {
     const no = (reason) => ({ ok: false, reason });
     if (!fastStartOn(store, input.repo))
@@ -101,7 +68,6 @@ export function fastStartRules(store, input, now) {
     const account = store.accountOf(input.actor);
     if (account === null || account.revokedAt !== null || account.role !== "approver" || !store.accountCanAccess(input.actor, input.repo))
         return no("rules");
-    // The description decides "small"; the classifier can only confirm it, and silence is no.
     if (heuristicSizing({ title: input.title, goal: input.title }).size !== "small")
         return no("size");
     if (input.sizing.source !== "classifier")
@@ -136,7 +102,6 @@ export function fastStartRules(store, input, now) {
         return no("release");
     if (legOf(route, "build").selection?.kind === "trial")
         return no("trial");
-    // Anything approving would take a typed password for: escalated terms, wider check access, sandbox widenings.
     const profile = scope.profile;
     if (levelOfProfile(scope.profile) === "escalated" || profile["checkAccess"] !== undefined || profile["machLookup"] !== undefined)
         return no("password");
@@ -154,8 +119,6 @@ export function fastStartRules(store, input, now) {
         return no("policy");
     return { ok: true, scope };
 }
-/** File the task, inside the caller's transaction, exactly as Build will. A chat start's words are the lead's: its text
- * stays quarantined (`proposedVia: "mate"`), as every lead-written scope is. */
 function fileIt(store, id, input, now) {
     const filed = fileTaskProposal(store, {
         id, title: titleWithin(input.title), repo: input.repo, goal: input.title, acceptance: fastAcceptance(input.title), planning: "skip", sizing: input.sizing,
@@ -172,8 +135,6 @@ class RolledBack extends Error {
         this.answer = answer;
     }
 }
-/** Run `body` in a savepoint that never commits: a preview writes nothing, at any nesting depth (a nested transact runs
- * in place, so only the savepoint undoes the writes when a caller already holds a transaction). */
 function dryRun(store, body) {
     try {
         store.transact(() => store.savepoint(() => { throw new RolledBack(body()); }));
@@ -185,22 +146,15 @@ function dryRun(store, body) {
     }
     throw new Error("unreachable");
 }
-/**
- * What the form renders: the classifier asked (at most its budget), then the same proposal the plan step would seal, in a
- * transaction that's rolled back. The filing's words and the classifier's answer are kept (fast_preview), so Build
- * files exactly this, whatever is posted.
- */
 export async function prepareFastStart(store, input, now) {
     if (machineActing())
         return { eligible: false, reason: "machine" };
-    // A chat start is prepared in the lead's turn (prepareChatStart), bound to it.
     if (input.via === "chat")
         return { eligible: false, reason: "rules" };
     if (!fastStartOn(store, input.repo))
         return { eligible: false, reason: "setting" };
     if (heuristicSizing({ title: input.title, goal: input.title }).size !== "small")
         return { eligible: false, reason: "size" };
-    // A mode that auto-approves filings comes first: its own road, its own seal.
     const mode = store.activeMode(input.repo, now);
     if (mode !== null && /"autoApproveFiling":true/.test(mode.termsJson))
         return { eligible: false, reason: "mode" };
@@ -220,15 +174,10 @@ export async function prepareFastStart(store, input, now) {
         .run(preview, input.actor, input.via, taskId, input.repo, input.title, input.permissionMode ?? null, JSON.stringify(sizing), read.scope.digest, now.toISOString(), new Date(now.getTime() + FAST_PREVIEW_MS).toISOString());
     return { eligible: true, preview, digest: read.scope.digest, scope: read.scope, taskId };
 }
-/**
- * Build: file and approve in one transaction. Every check is made here, on the rows written here; anything refused
- * rolls the filing back, so a refusal leaves nothing behind.
- */
 export function fastStartBuild(store, input, now) {
     if (machineActing())
         return { ok: false, reason: "machine", message: FAST_WORDS.machine };
     const proof = "proof" in input ? input.proof : { password: input.password };
-    // The chat form of the proof is a chat start's alone; the form's surfaces keep the password rule.
     if ("chat" in proof && input.via !== "chat")
         return { ok: false, reason: "rules", message: FAST_WORDS.rules };
     class Refused extends Error {
@@ -240,13 +189,10 @@ export function fastStartBuild(store, input, now) {
     }
     const refuse = (answer) => { throw new Refused(answer); };
     try {
-        // A savepoint inside the transaction: a refusal undoes the filing even when the caller already holds a transaction
-        // (a nested transact runs in place, and this function catches its own refusal).
         return store.transact(() => store.savepoint(() => {
             const row = store.handle.prepare("SELECT * FROM fast_preview WHERE id = ? AND consumed_at IS NULL AND expires_at > ?").get(input.preview, now.toISOString());
             if (row === undefined || row["actor"] !== input.actor || row["via"] !== input.via)
                 return refuse({ ok: false, reason: "gone", message: "This form has expired. Start again." });
-            // A chat preview without a turn, or from another turn than its card's, is nobody's card.
             if (input.via === "chat" && (row["turn"] === null || row["turn"] === undefined || input.turn === undefined || Number(row["turn"]) !== input.turn))
                 return refuse({ ok: false, reason: "gone", message: "This card has expired. Ask again." });
             const sizing = JSON.parse(String(row["sizing_json"]));
@@ -259,11 +205,9 @@ export function fastStartBuild(store, input, now) {
             if (!eligible.ok)
                 return refuse({ ok: false, reason: eligible.reason, message: FAST_WORDS[eligible.reason] });
             const at = now.toISOString();
-            // approve() compares the digest the person saw with the plan just filed: changed terms refuse "changed".
             const approved = input.approveNow(taskId, input.digest, { rule: FAST_START_RULE, at });
             if (!approved.ok && approved.reason === "changed")
                 return refuse({ ok: false, reason: "changed", message: "This changed since you read it. Read it again." });
-            // Chat has no password: a refusal there says the rule, not "takes your password".
             if (!approved.ok)
                 return refuse(input.via === "chat" ? { ok: false, reason: "rules", message: approved.reason === "policy" ? approved.message : FAST_WORDS.rules } : { ok: false, reason: "password", message: FAST_WORDS.password });
             store.handle.prepare("UPDATE fast_preview SET consumed_at = ? WHERE id = ?").run(at, input.preview);
@@ -278,14 +222,8 @@ export function fastStartBuild(store, input, now) {
         throw error;
     }
 }
-// ---- the start window ------------------------------------------------------------------------------------------------
-/**
- * A fast start that didn't start in time: its seal is cleared, in a logged transaction, and the task shows the ordinary
- * Approve plan. A task with a build running or a result to read is left to that.
- */
 export function expireFastStarts(store, now) {
     const stamp = now.toISOString();
-    // Forms nobody pressed hold a person's words: they go once they can't be pressed.
     store.handle.prepare("DELETE FROM fast_preview WHERE expires_at <= ?").run(stamp);
     const late = store.handle.prepare(`SELECT r.id AS ref, r.external_id AS task, r.repo AS repo FROM task_ref r JOIN task t ON t.id = r.external_id
     WHERE r.backend = ? AND r.fast_start_until IS NOT NULL AND r.fast_start_until <= ? AND t.state = 'queued'`).all(BUILT_IN, stamp);
@@ -305,11 +243,8 @@ export function expireFastStarts(store, now) {
         store.bumpWake();
     return cleared;
 }
-// ---- the Accept backstop ---------------------------------------------------------------------------------------------
-/** Files a small change has no business touching, by name, wherever they sit. */
 const HEAVY_FILE = /(?:^|\/)(?:package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.ya?ml|bun\.lockb?|Cargo\.lock|Gemfile\.lock|poetry\.lock|Pipfile\.lock|composer\.lock|go\.sum|uv\.lock|package\.json|Cargo\.toml|Gemfile|go\.mod|pyproject\.toml|requirements[^/]*\.txt|composer\.json|schema\.(?:sql|prisma|rb|graphql)|structure\.sql)$|(?:^|\/)(?:migrations?|migrate|db\/migrate)\//i;
 const SHA = /^[0-9a-f]{40}$/;
-/** `ls-tree -r -z`: path to mode and object, read from the commit, so a gitlink can't hide from a diff setting. */
 function treeOf(repo, commit) {
     const out = new Map();
     const listed = viewedGitSync(repo, ["ls-tree", "-r", "-z", "--full-tree", commit], { timeoutMs: 30_000, maxBuffer: 64 * 1024 * 1024 });
@@ -326,11 +261,6 @@ function treeOf(repo, commit) {
     }
     return out;
 }
-/**
- * The whole change a result carries, verified: every version of the task (any ancestry problem refuses), from the base in
- * Toolroll's own records to the head on the run record, every contributing build's saved diff present, and every file
- * countable through the hardened git. Null-like answers refuse: nothing here is ever a guess.
- */
 export function verifiedChange(store, taskId, runId) {
     const no = (problem) => ({ ok: false, problem });
     const ancestry = store.revisionAncestryStatus(taskId);
@@ -389,7 +319,6 @@ export function verifiedChange(store, taskId, runId) {
         return no("The change couldn't be read.");
     }
 }
-/** Whether any version of this task started fast. An unreadable history counts: it fails closed below. */
 export function fastStarted(store, taskId) {
     const ancestry = store.revisionAncestryStatus(taskId);
     if (ancestry.problem !== null) {
@@ -399,14 +328,12 @@ export function fastStarted(store, taskId) {
     const chain = ancestry.chain.length === 0 ? [taskId] : ancestry.chain;
     return store.handle.prepare(`SELECT 1 AS hit FROM task_ref WHERE backend = ? AND fast_start_at IS NOT NULL AND external_id IN (SELECT value FROM json_each(?))`).get(BUILT_IN, JSON.stringify(chain)) !== undefined;
 }
-/** The one sentence over every over-the-caps refusal; the road on is the approval of the expanded commit (keepGrownChange). */
 export const GREW_WORDS = "This grew beyond a small change. Approve it to keep it.";
 function grownApproved(store, taskId, runId) {
     const scope = store.getScope(taskId), run = store.getRun(runId);
     return scope !== null && run !== null && scope.candidate != null && scope.candidate === run.headRevision && scope.approvedDigest === scope.digest && run.scopeDigest === scope.digest
         && (scope.approvalBasis === "password" || scope.approvalBasis === "chat");
 }
-/** Why this exact result can't go further as a small change, or null. */
 export function fastChangeProblem(store, taskId, runId) {
     if (!fastStarted(store, taskId))
         return null;
@@ -425,7 +352,6 @@ export function fastChangeProblem(store, taskId, runId) {
         return GREW_WORDS;
     return null;
 }
-/** Completion: a person only, and only a change the measure accepts. */
 export function fastCompletionProblem(store, taskId, runId, person) {
     if (!fastStarted(store, taskId))
         return null;
@@ -433,7 +359,6 @@ export function fastCompletionProblem(store, taskId, runId, person) {
         return "A person accepts this one.";
     return fastChangeProblem(store, taskId, runId);
 }
-/** Publication and merge: nothing leaves until a person accepted this exact build, and the measure still accepts it. */
 export function fastPublishProblem(store, taskId, runId) {
     if (!fastStarted(store, taskId))
         return null;
@@ -442,11 +367,6 @@ export function fastPublishProblem(store, taskId, runId) {
         return "It waits for a person to accept it.";
     return fastChangeProblem(store, taskId, runId);
 }
-/**
- * "Approve it to keep it": a plan for the actual expanded commit, proposed the way a rerun proposes one (dispose.ts
- * regateTask): the same terms with `candidate` set to the exact head. It seals nothing; the person approves it on the
- * ordinary ceremony, Toolroll checks that commit out with no agent, and only that attempt's result goes further.
- */
 export function keepGrownChange(store, taskId, now) {
     if (machineActing())
         return { ok: false, message: FAST_WORDS.machine };
@@ -465,15 +385,6 @@ export function keepGrownChange(store, taskId, now) {
         return { ok: true, digest: proposed.digest };
     });
 }
-/**
- * A chat start's preview, prepared by the lead's turn loop before the Start card is drafted: the classifier asked (at
- * most its budget), the filing dry-run, and the rules read. It refuses no machine caller, because a preview grants
- * nothing (the lead's turn runs as the lead): Build refuses a machine (fastStartBuild), and only a person's own tap or
- * typed yes reaches Build. The row is bound to the person, `via = 'chat'` and the turn; a preview without a turn is
- * unusable. The person's own chat limits are read again at the tap, for the chat it comes from; here only the loosest
- * limit that still means something applies (no full access, no cap), so a card is never drafted for terms no chat
- * approval could allow.
- */
 export async function prepareChatStart(store, input, now) {
     if (!Number.isSafeInteger(input.turn) || input.turn < 1)
         return { eligible: false, reason: "rules" };
@@ -501,23 +412,15 @@ export async function prepareChatStart(store, input, now) {
         .run(preview, input.actor, taskId, input.repo, input.title, JSON.stringify(sizing), read.scope.digest, now.toISOString(), new Date(now.getTime() + FAST_PREVIEW_MS).toISOString(), input.turn);
     return { eligible: true, preview, digest: read.scope.digest, scope: read.scope, taskId };
 }
-/** A chat start's preview, as the Start card reads it again: this person's, `via = 'chat'`, prepared in this turn,
- * unexpired and unused. Null otherwise. */
 export function chatStartPreview(store, preview, actor, turn, now) {
     const row = store.handle.prepare("SELECT * FROM fast_preview WHERE id = ? AND consumed_at IS NULL AND expires_at > ?").get(preview, now.toISOString());
     if (row === undefined || row["actor"] !== actor || row["via"] !== "chat" || row["turn"] === null || Number(row["turn"]) !== turn)
         return null;
     return { taskId: String(row["task_id"]), repo: String(row["repo"]), title: String(row["title"]), sizing: JSON.parse(String(row["sizing_json"])), digest: String(row["digest"]) };
 }
-/** A dismissed Start card's preview can't be used: consumed, in the dismissal's transaction. */
 export function consumeChatStartPreview(store, preview, now) {
     store.handle.prepare("UPDATE fast_preview SET consumed_at = ? WHERE id = ? AND via = 'chat' AND consumed_at IS NULL").run(now.toISOString(), preview);
 }
-/**
- * A chat start's filing dry-run, for its card: the scope filing would make, read in a savepoint that is always rolled
- * back, with the rules read on it (any proof form; the card shows the terms, the tap proves the person). The card is made
- * from these words; the tap files again and compares.
- */
 export function chatStartDryRun(store, input, now) {
     return dryRun(store, () => {
         const filed = fileIt(store, input.taskId, { actor: input.actor, repo: input.repo, title: input.title, via: "chat", sizing: input.sizing }, now);

package/dist/fast-terms.js

@@ -1,6 +1,3 @@
-/** A fast start's terms, the words a yes agrees to (scope.ts describeScope, the lines every plan approval reads), plus the
- * project tools its seal will carry. The same lines on the New task form, in the terminal UI and in `task new`. The
- * plan version and approval state rows say nothing yet: nothing is approved. */
 import { describeScope } from "./scope.js";
 const LABELS = { goal: "Goal", "not this": "Not this", files: "Files", budget: "Budget", network: "Network", writes: "Writes", reads: "Reads", checks: "Checks", services: "Services" };
 export function fastTermsLines(store, scope, repo) {

package/dist/fenced-check-coverage.js

@@ -1,12 +1,5 @@
-/** Cases that may stay skipped with no CI case behind them, each with why. Product code, reviewed like it: never a file a
- * release's commits could carry. Empty until a measured run gives a reason. */
 export const FENCED_SKIP_EXEMPTIONS = Object.freeze([]);
 export const unitCaseIdentity = (file, name) => `unit:${file}::${name}`;
-/**
- * Every case in the macOS CI's reports, by the identity the release check's own reporter gives it (test/release-reporter.ts:
- * `suite > test`; Vitest's JSON `fullName` joins with spaces, so it can't be matched as it stands). A name twice in a file
- * passes only if every one of them did. `root` is the checkout the reports name files under.
- */
 export function macosCases(reports, root) {
     const cases = new Map();
     for (const report of reports) {
@@ -25,13 +18,11 @@ export function macosCases(reports, root) {
     }
     return cases;
 }
-/** Every case a check's report says it skipped: unit cases and journeys alike. */
 export function skippedCases(report) {
     const units = (report.units?.identities ?? []).filter(one => one.state === "skipped").map(one => unitCaseIdentity(one.file, one.name));
     const journeys = report.journeys.flatMap(run => run.groups.flatMap(group => group.journeys.filter(one => one.state === "skipped").map(one => `journey:${run.script}:${run.kind}:${group.group}::${one.name}`)));
     return [...new Set([...units, ...journeys])].sort();
 }
-/** Each skipped case: passed in that commit's macOS CI, reviewed as exempt, or not covered. */
 export function skipCoverage(skipped, macos, exemptions = FENCED_SKIP_EXEMPTIONS) {
     const reviewed = new Set(exemptions.map(one => one.identity));
     const result = { covered: [], exempt: [], uncovered: [] };
@@ -39,14 +30,12 @@ export function skipCoverage(skipped, macos, exemptions = FENCED_SKIP_EXEMPTIONS
         (macos.get(identity) === true ? result.covered : reviewed.has(identity) ? result.exempt : result.uncovered).push(identity);
     return result;
 }
-/** The narrowest level a measured check fully covers. No level covered: `unsandboxed`, as today, with a person's yes. */
 export function measuredLevel(measurements) {
     for (const level of ["sandboxed", "sign-ins"])
         if (measurements.some(one => one.level === level && one.passed && one.uncovered === 0))
             return level;
     return "unsandboxed";
 }
-/** Why a sandboxed check can't stand for this release, in words a person can act on. */
 export function uncoveredWords(uncovered) {
     const named = uncovered.slice(0, 5).map(one => one.replace(/^unit:/, "")).join("; ");
     return `${uncovered.length} ${uncovered.length === 1 ? "case" : "cases"} skipped inside the sandbox ${uncovered.length === 1 ? "isn't" : "aren't"} covered by this commit's macOS CI (${named}${uncovered.length > 5 ? "; and more" : ""}). `

package/dist/findings.js

@@ -1,14 +1,3 @@
-/**
- * Findings sent to the task that owns the code (docs/plans/fleet-follow-through.md, part 1).
- *
- * A finding asks the owner for an answer: accepted, with what changed, or rejected, with a reason against the code.
- * Reading one closes nothing. It stays open, and visible, until an answer counts or a person closes it, and a reviewer
- * and an implementer get FINDING_ROUND_LIMIT rounds before it goes to a person.
- *
- * Trust: summary, action, excerpt and every answer can hold model output or repository text. They are data wherever
- * they are read: quoted with `fence` for an agent, and they decide nothing. An answer ends this finding and touches no
- * proof, check or approval, and only a signed-in person (the caller proves it) closes one.
- */
 import { z } from "zod";
 import { fence } from "./brief-fence.js";
 import { redactSecretLines, scanForSecrets } from "./evidence.js";
@@ -16,27 +5,22 @@ import { readingFleet } from "./fleet-schema.js";
 import { buildReviewOf } from "./review-switch.js";
 import { failedVerificationEvidence } from "./verification-evidence.js";
 import { viewedGitSync } from "./teardown-git.js";
-/** A first send and one more: then a person decides. */
 export const FINDING_ROUND_LIMIT = 2;
 export const FINDING_TEXT_LIMIT = 1_000;
 export const FINDING_ACTION_LIMIT = 300;
 export const FINDING_EXCERPT_LIMIT = 2_000;
 export const ANSWER_TEXT_LIMIT = 1_000;
 export const ANSWER_FILE_BYTES = 8 * 1024;
-/** A review pointing this close to an answered finding, in the same file, is raising it again. */
 const SAME_PLACE_LINES = 10;
 export const REVIEW_ACTION = "Check this against the code. Fix it and say what changed, or reject it with a reason that names the file.";
 export const CHECK_ACTION = "Find the cause of this failed check. Fix it and say what changed, or reject it with a reason that names the file.";
 const SOURCE_WORDS = { "build-review": "automatic review", person: "a person", lead: "the lead, confirmed by a person", "check-failure": "the project check" };
 export const findingSourceWords = (source) => SOURCE_WORDS[source];
-/** Who a finding's words are from, naming the person who confirmed the lead's draft: never the person as its author. */
 export const findingFromWords = (finding) => finding.source === "lead" ? `the lead, confirmed by ${finding.sentBy}` : SOURCE_WORDS[finding.source];
-/** The family a task belongs to: a broken history keeps the finding on the task it named. */
 export function familyRootOf(store, taskId) {
     const family = store.taskFamilyOf(taskId, null, true);
     return family === null || family.problem !== null ? taskId : family.root.id;
 }
-/** One line of quotable text: controls gone, secrets gone, inside its limit. */
 export function cleanFindingText(text, limit) {
     const redacted = redactSecretLines(text, scanForSecrets(text));
     return redacted.replace(/[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]+/g, " ").replace(/\s+/g, " ").trim().slice(0, limit);
@@ -65,23 +49,18 @@ export function getFinding(store, id) {
         return row === undefined ? null : findingOf(store, row);
     }, null);
 }
-/** Every finding of a task's family, newest first. */
 export function findingsOfTask(store, taskId) {
     return readingFleet(() => {
         const root = familyRootOf(store, taskId);
         return store.handle.prepare("SELECT * FROM finding WHERE family_root = ? ORDER BY id DESC").all(root).map(row => findingOf(store, row));
     }, []);
 }
-/** How many of this task's family's findings used their rounds and wait on a person; none on a database not yet migrated. */
 export const heldFindingCount = (store, taskId) => findingsOfTask(store, taskId).filter(one => one.state === "with-person").length;
-/** The findings still waiting on someone, across a project or everywhere. */
 export function waitingFindings(store, repos) {
     return readingFleet(() => store.handle.prepare("SELECT * FROM finding WHERE state IN ('open', 'with-person') ORDER BY id DESC LIMIT 500").all()
         .map(row => findingOf(store, row)).filter(one => repos === null || (one.repo !== null && repos.includes(one.repo))), []);
 }
 const inReach = (store, who, repo) => who.repos.includes(repo) && store.accountCanAccess(who.name, repo);
-/** Every project a task's family reaches, or null unless this person reaches all of them: one gate for every chat road to
- * a family's findings and handover. A task with no project is out of reach. */
 export function familyInReach(store, who, task) {
     const family = store.taskFamilyOf(task, null, true);
     const repos = (family?.versions.map(one => one.id) ?? [task]).map(id => store.lookupRef(id)?.repo ?? null);
@@ -89,8 +68,6 @@ export function familyInReach(store, who, task) {
         return null;
     return [...new Set(repos)];
 }
-/** The findings this person may see: a task's, only if its whole family is in reach, else those waiting in `repos`. Null
- * for a task out of reach. A finding with no project, or one out of reach, is left out. */
 export function findingsInReach(store, who, query) {
     if (query.task !== undefined && familyInReach(store, who, query.task) === null)
         return null;
@@ -98,7 +75,6 @@ export function findingsInReach(store, who, query) {
     return list.filter(one => one.repo !== null && inReach(store, who, one.repo));
 }
 const words = (text) => text.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim().split(" ").slice(0, 12).join(" ");
-/** The same finding, in another reviewer's words: the same file, and the same opening words or nearly the same line. */
 export function sameFinding(a, b) {
     if (a.file === null || a.file !== b.file)
         return false;
@@ -106,7 +82,6 @@ export function sameFinding(a, b) {
         return true;
     return a.line !== null && b.line !== null && Math.abs(a.line - b.line) <= SAME_PLACE_LINES;
 }
-/** A run that is live on this task right now is the one a mailbox reaches. */
 function liveRunOf(store, taskId, now) {
     const ref = store.lookupRef(taskId);
     if (ref === null)
@@ -116,7 +91,6 @@ function liveRunOf(store, taskId, now) {
         return null;
     return store.runsFor(ref.id).find(one => one.outcome === null && one.leaseId === lease)?.id ?? null;
 }
-/** Tell a person a finding has used its rounds: once per round, never for a put-away task (enqueueNotification). */
 function handToPerson(store, finding, now) {
     const taskRef = store.lookupRef(finding.taskId)?.id;
     store.handle.prepare("UPDATE finding SET state = 'with-person' WHERE id = ?").run(finding.id);
@@ -128,7 +102,6 @@ function handToPerson(store, finding, now) {
         link: `/t/${encodeURIComponent(finding.taskId)}#findings`,
     }, now);
 }
-/** Send a finding, or count a repeat of one already sent as another round. The caller proves who is sending. */
 export function sendFinding(store, input, now) {
     const task = store.getTask(input.taskId);
     if (task === null)
@@ -149,8 +122,6 @@ export function sendFinding(store, input, now) {
                 return { ok: true, id: Number(earlier["id"]), standing: "already-sent", round: Number(earlier["rounds"]) };
         }
         const family = store.handle.prepare("SELECT * FROM finding WHERE family_root = ? AND state <> 'closed' ORDER BY id DESC").all(root).map(row => findingOf(store, row));
-        // A review's wording drifts between rounds, so nearly the same place counts. A person's note counts only word for word:
-        // two different things to say about one function are two findings.
         const repeat = family.find(one => input.source === "build-review" ? sameFinding(one, { file, line, summary }) : one.file === file && words(one.summary) === words(summary));
         if (repeat !== undefined) {
             if (repeat.state === "open")
@@ -182,7 +153,6 @@ function resendLocked(store, finding, now) {
     store.bumpWake();
     return { ok: true, id: finding.id, standing: liveRunOf(store, finding.taskId, now) === null ? "next-attempt" : "running", round };
 }
-/** Send an answered finding back to its owner: one more round, or to a person once the rounds are used. */
 export function resendFinding(store, id, now) {
     return store.transact(() => {
         const finding = getFinding(store, id);
@@ -193,7 +163,6 @@ export function resendFinding(store, id, now) {
         return resendLocked(store, finding, now);
     });
 }
-/** A person's decision on a finding. The caller has proved the person. */
 export function closeFinding(store, id, by, note, now) {
     const words = cleanFindingText(note, FINDING_TEXT_LIMIT);
     if (words === "")
@@ -203,7 +172,6 @@ export function closeFinding(store, id, by, note, now) {
         return Number(closed.changes) === 1 ? { ok: true } : { ok: false, message: `Finding #${id} is closed already, or doesn't exist.` };
     });
 }
-/** The open findings of a run's family it has not been given yet. */
 export function undeliveredFindings(store, taskRef, runId) {
     return readingFleet(() => {
         const taskId = store.refById(taskRef)?.externalId;
@@ -212,12 +180,10 @@ export function undeliveredFindings(store, taskRef, runId) {
         return store.handle.prepare("SELECT * FROM finding WHERE family_root = ? AND state = 'open' AND delivered_run IS NOT ? ORDER BY id").all(familyRootOf(store, taskId), runId).map(row => findingOf(store, row));
     }, []);
 }
-/** Recorded only after the file reached the run, or the brief named it: a pending delivery is never counted as read. */
 export function markFindingDelivered(store, id, runId, how, now) {
     const marked = store.handle.prepare("UPDATE finding SET delivered_run = ?, delivered_how = ?, delivered_at = ?, read_at = NULL WHERE id = ? AND state = 'open'").run(runId, how, now.toISOString(), id);
     return Number(marked.changes) === 1;
 }
-/** The findings a fresh attempt's brief quotes, recorded as reaching it. Bounded by the caller's brief. */
 export function attachFindings(store, taskRef, runId, now) {
     return readingFleet(() => store.transact(() => {
         const open = undeliveredFindings(store, taskRef, runId);
@@ -226,12 +192,10 @@ export function attachFindings(store, taskRef, runId, now) {
         return open;
     }), []);
 }
-/** The agent moved the file to handled/: it read it. That closes nothing. */
 export function markFindingRead(store, id, runId, now) {
     store.handle.prepare("UPDATE finding SET read_at = ? WHERE id = ? AND delivered_run = ? AND read_at IS NULL").run(now.toISOString(), id, runId);
 }
 const line = z.string().min(1).max(ANSWER_TEXT_LIMIT);
-/** An answer as an agent writes it. Its `key` proves the attempt's own folder wrote it, nothing more. */
 export const findingAnswerSchema = z.strictObject({
     key: z.string().min(1).max(64),
     finding: z.number().int().min(1),
@@ -240,8 +204,6 @@ export const findingAnswerSchema = z.strictObject({
     file: z.string().min(1).max(300).optional(),
     line: z.number().int().min(1).max(10_000_000).optional(),
 });
-/** Save what an attempt answered. It counts only when that attempt settles (settleFindingAnswers). A finding this run
- * was not given, or one no longer open, takes no answer. */
 export function saveFindingAnswer(store, runId, answer, now) {
     return store.transact(() => {
         const finding = store.handle.prepare("SELECT rounds FROM finding WHERE id = ? AND delivered_run = ? AND state = 'open'").get(answer.finding, runId);
@@ -256,9 +218,7 @@ export function saveFindingAnswer(store, runId, answer, now) {
         return Number(saved.changes) === 1;
     });
 }
-/** A path as a repository names one: relative, inside, and never read as an option. */
 const repoPath = (path) => path !== "" && !path.startsWith("/") && !path.startsWith("-") && !path.split("/").includes("..") && !/[\u0000-\u001f\u007f:]/.test(path);
-/** Whether the file an answer names is in the code at that commit. The checkout is the agent's: the hardened git reads it. */
 function fileAt(worktree, head, path) {
     if (!repoPath(path) || !/^[a-f0-9]{40}$/.test(head))
         return false;
@@ -269,11 +229,6 @@ function fileAt(worktree, head, path) {
         return false;
     }
 }
-/**
- * The attempt has settled: each answer it saved counts or is refused, against what the machine saw, not what it said.
- * Accepted needs a commit past the revision the finding was sent about. Rejected needs a file that exists at the run's
- * commit. A refused answer leaves the finding open, and the next attempt gets it again.
- */
 export function settleFindingAnswers(store, runId, worktree, now) {
     return readingFleet(() => {
         const run = store.getRun(runId);
@@ -323,11 +278,6 @@ export function settleFindingAnswers(store, runId, worktree, now) {
         return counted;
     }, 0);
 }
-/**
- * A finished review's HIGH findings. Sent back: each becomes a finding its revision must answer. Not sent back (a family
- * gets one automatic send-back): a HIGH that repeats an answered finding is that finding's next round, and any other
- * stays where it is, for the person to decide. Never at the review's expense.
- */
 export function recordReviewFindings(store, input, now) {
     try {
         store.transact(() => store.savepoint(() => {
@@ -341,19 +291,16 @@ export function recordReviewFindings(store, input, now) {
             });
         }));
     }
-    catch { /* the review stands; its findings stay on the result */ }
+    catch { }
 }
 const BRIEF_FINDINGS = 10;
 const BRIEF_EXCERPT = 500;
 export const NOT_ON_TASK = "That result isn't on this task.";
-/** Whether a run belongs to this task's family. Admission proves the task named, never a run a form or flag names beside
- * it, so every act that takes a run checks it here: no finding's text crosses a task or a project. */
 export function runOnTask(store, runId, taskId) {
     const run = Number.isSafeInteger(runId) ? store.getRun(runId) : null;
     const owner = run === null ? null : store.externalIdFor(run.taskRef);
     return owner !== null && store.lookupRef(taskId) !== null && familyRootOf(store, owner) === familyRootOf(store, taskId);
 }
-/** Send one of a result's review findings: `<run>:<number>`, counted from 1 as the result lists them. */
 export function sendReviewFinding(store, taskId, pointer, by, now) {
     const read = reviewFindingAt(store, taskId, pointer);
     if (!read.ok)
@@ -361,7 +308,6 @@ export function sendReviewFinding(store, taskId, pointer, by, now) {
     const { finding, run } = read;
     return sendFinding(store, { taskId, source: "build-review", by, summary: finding.scenario, file: finding.file, line: finding.line, severity: finding.severity, run, key: `review-send:${pointer}` }, now);
 }
-/** The review finding `<run>:<number>` names, on this task's family: what a send would quote, read once for both. */
 export function reviewFindingAt(store, taskId, pointer) {
     const match = /^([1-9][0-9]{0,14}):([1-9][0-9]{0,3})$/.exec(pointer);
     if (match !== null && !runOnTask(store, Number(match[1]), taskId))
@@ -370,7 +316,6 @@ export function reviewFindingAt(store, taskId, pointer) {
     const finding = view === null ? undefined : [...view.high, ...view.followUps][Number(match[2]) - 1];
     return finding === undefined ? { ok: false, message: `That result has no review finding ${pointer}.` } : { ok: true, run: Number(match[1]), finding };
 }
-/** Send a result's failed check, with the end of its sealed log as the evidence. The summary is Toolroll's own words. */
 export function sendCheckFinding(store, root, taskId, runId, by, now) {
     const read = checkFindingAt(store, root, taskId, runId);
     if (!read.ok)
@@ -378,7 +323,6 @@ export function sendCheckFinding(store, root, taskId, runId, by, now) {
     const { summary, head, excerpt } = read;
     return sendFinding(store, { taskId, source: "check-failure", by, summary, run: runId, revision: head, excerpt, key: `check-send:${runId}` }, now);
 }
-/** A failed check as a send would quote it. */
 export function checkFindingAt(store, root, taskId, runId) {
     if (!runOnTask(store, runId, taskId))
         return { ok: false, message: NOT_ON_TASK };
@@ -388,7 +332,6 @@ export function checkFindingAt(store, root, taskId, runId) {
     const head = store.getRun(runId)?.headRevision ?? null;
     return { ok: true, summary: `The approved check failed on ${head?.slice(0, 7) ?? "this result"}.`, head, excerpt: failure.log.slice(-FINDING_EXCERPT_LIMIT) };
 }
-/** The folder an attempt's answers go in, and what the brief says about writing one. Trusted words: nothing here is quoted. */
 export function findingAnswerRule(folder, key) {
     return [
         `  Answer each finding by writing ${folder}/answers/<finding id>.json, with the key ${key}:`,
@@ -398,7 +341,6 @@ export function findingAnswerRule(folder, key) {
         "  finding is not an answer, and an unanswered one stays open.",
     ];
 }
-/** The findings a fresh attempt starts with, quoted as data. `answer` is the folder and key, when this attempt has one. */
 export function findingsBriefLines(findings, answer) {
     if (findings.length === 0)
         return [];
@@ -419,7 +361,6 @@ export function findingsBriefLines(findings, answer) {
         "",
     ];
 }
-/** How a finding stands, for a person, in one sentence. Text after a colon is the agent's. */
 export function findingStandingWords(finding) {
     const answer = finding.answer;
     switch (finding.state) {
@@ -435,13 +376,10 @@ export function findingStandingWords(finding) {
         case "closed": return `Closed by ${finding.closedBy ?? "a person"}: ${finding.closedNote ?? ""}`;
     }
 }
-/** Plain lines for `task show`, `finding list` and the handover note. */
 export function findingLine(finding) {
     const where = finding.file === null ? "" : ` ${finding.file}${finding.line === null ? "" : `:${finding.line}`}`;
     return `#${finding.id}${finding.severity === null ? "" : ` ${finding.severity}`}${where} — ${finding.summary}`;
 }
-/** The web's door to the same gate as chat (familyInReach): the projects this person reaches are those the page can
- * see and their account may access, and every project in the task's family must be one of them. Null: out of reach. */
 export function familyInWebReach(store, who, task, visible) {
     const family = store.taskFamilyOf(task, null, true);
     const repos = (family?.versions.map(one => one.id) ?? [task]).map(id => store.lookupRef(id)?.repo ?? null).filter((one) => one !== null && visible(one));