toolroll 0.9.104 → 0.9.105

package/dist/result-follow-ups.js

@@ -19,7 +19,6 @@ export const CHECKS_FINISHED = "checks finished";
 export const FOLLOW_UP_LOG = "follow-up check log v1";
 export const FOLLOW_UP_RECEIPT = "follow-up check receipt v1";
 export const ADD_TESTS_ACTION = "tests task filed";
-/** A started check with no result after its time limit and this grace didn't finish. */
 const ABANDONED_GRACE_MS = 10 * 60_000;
 const refuse = (reason, message) => ({ ok: false, reason, message });
 function ledgerFor(store, runId) {
@@ -29,7 +28,6 @@ function ledgerFor(store, runId) {
         .map(row => ({ id: Number(row["id"]), actor: String(row["actor"]), at: String(row["at"]), outcome: String(row["outcome"]),
         detail: row["detail"] === null ? null : String(row["detail"]), action: String(row["action"]) }));
 }
-/** Every follow-up check a result has had, oldest first, as the ledger and its sealed receipts say. */
 export function followUpChecksOf(store, runId, now = new Date(), root) {
     const rows = ledgerFor(store, runId);
     const receipts = new Map();
@@ -47,11 +45,9 @@ export function followUpChecksOf(store, runId, now = new Date(), root) {
                     log: typeof body.log?.artifactId === "number" ? body.log.artifactId : null, head,
                     tested: typeof body.tested === "string" ? body.tested : head, batch: batchFactsOf(body.batch, runId, head) });
             }
-            catch { /* an unreadable receipt upgrades nothing */ }
+            catch { }
         }
     }
-    // A pass stands only while its saved log still verifies and the command it ran is still the approved one, the same
-    // bar the build's own check receipt meets (verification-evidence.ts): otherwise it can't be read as a pass now.
     const repo = root === undefined ? null : repoOfRun(store, runId);
     const logVerifies = (artifactId) => {
         if (root === undefined || artifactId === null)
@@ -79,8 +75,6 @@ export function followUpChecksOf(store, runId, now = new Date(), root) {
         if (finished !== null) {
             const status = finished.outcome.slice(String(request.id).length + 1);
             const sealed = receipts.get(request.id) ?? null;
-            // With the evidence at hand, only a sealed receipt can say passed: for this result's own commit, and,
-            // for a batch, a batch that names this result.
             if (status === "passed" && root !== undefined && (sealed === null || !sealed.ran || sealed.exitCode !== 0 || (sealed.head !== null && sealed.head !== head)
                 || (base.why === "batch" && sealed.batch === null) || !logVerifies(sealed.log) || !stillApproved(base.level, digest))) {
                 return { ...base, state: "not-run", note: "The saved check result could not be verified." };
@@ -99,7 +93,6 @@ export function followUpChecksOf(store, runId, now = new Date(), root) {
         return { ...base, state: "waiting" };
     });
 }
-/** A receipt's batch facts, only when they are whole and name this result at its own commit. */
 function batchFactsOf(value, runId, head) {
     if (value === null || typeof value !== "object")
         return null;
@@ -114,12 +107,10 @@ function batchFactsOf(value, runId, head) {
     });
     if (members.length !== raw.members.length || !members.some(one => one.run === runId && one.head === head))
         return null;
-    // Checked on its own: the commit tested is the result's own.
     if (mode !== "together" && (members.length !== 1 || raw.tested !== head))
         return null;
     return { mode, tested: raw.tested, base: typeof raw.base === "string" ? raw.base : null, members };
 }
-/** Whether a result can have checks run on it, and with which command. */
 function checkTarget(store, runId, level) {
     const run = store.getRun(runId);
     const ref = run === null ? null : store.refById(run.taskRef);
@@ -129,7 +120,6 @@ function checkTarget(store, runId, level) {
         return refuse("no-commit", "This result has no finished commit to check.");
     if (ref.repo === null)
         return refuse("unplaced", "This result isn't in a project, so there is no check to run.");
-    // A put-away task (v145) runs no checks: asked for or already waiting, it is refused until restored.
     if (refArchived(store, ref.id))
         return refuse("archived", "This task is put away. Restore it first.");
     const chosen = checkCommandFor(store, ref.repo, level);
@@ -137,8 +127,6 @@ function checkTarget(store, runId, level) {
         return refuse("no-check", `${ref.repo} has no approved ${level === "quick" ? "quick or full" : "full"} check. Set one in Settings → Projects → Checks.`);
     return { ok: true, repo: ref.repo, taskId: ref.externalId, head: run.headRevision, level: chosen.level, command: chosen.command };
 }
-/** Ask for checks on a result's exact commit. Asking twice while one is waiting
- * or running returns the same request; a worker runs it once. */
 export function requestFollowUpChecks(store, input, now) {
     return store.transact(() => {
         const target = checkTarget(store, input.runId, input.level);
@@ -153,7 +141,6 @@ export function requestFollowUpChecks(store, input, now) {
         return { ok: true, request, level: target.level, existing: false };
     });
 }
-/** Requests nobody has started yet, oldest first. Batch requests wait for the batch pass (batch-checks.ts). */
 export function waitingCheckRequests(store, now) {
     return waitingRequestsOfAnyKind(store, now).filter(one => one.why !== "batch");
 }
@@ -163,12 +150,9 @@ export function waitingRequestsOfAnyKind(store, now) {
         .all(CHECKS_REQUESTED, CHECKS_STARTED).map(row => Number(row["run"]));
     return runs.flatMap(runId => followUpChecksOf(store, runId, now).filter(one => one.state === "waiting"));
 }
-/** Run one waiting request: claim it, check out its commit, run the approved
- * setup (when the project has one) and the check, seal the log and receipt. */
 export async function runFollowUpCheck(store, root, request, deps = {}) {
     const now = deps.now ?? (() => new Date());
     const runner = deps.runner ?? execRun;
-    // The project's repository and a checkout of a build's commit, both agent-writable: the hardened git (teardown-git.ts).
     const git = deps.git ?? hardenedGit(execRun);
     const asked = store.handle.prepare("SELECT run_id FROM action_ledger WHERE id = ? AND action = ?").get(request, CHECKS_REQUESTED);
     if (asked === undefined)
@@ -183,7 +167,6 @@ export async function runFollowUpCheck(store, root, request, deps = {}) {
             action: CHECKS_FINISHED, outcome: `${request}:${status}`, source: "work", detail });
         store.bumpWake();
     };
-    // The claim: one started entry per request, written only while none exists.
     const claimed = store.transact(() => {
         if (store.handle.prepare("SELECT 1 FROM action_ledger WHERE run_id = ? AND action = ? AND outcome = ?").get(runId, CHECKS_STARTED, String(request)) !== undefined)
             return false;
@@ -197,18 +180,15 @@ export async function runFollowUpCheck(store, root, request, deps = {}) {
         finish("not-run", target.message);
         return followUpChecksOf(store, runId, now(), root).find(one => one.request === request) ?? null;
     }
-    // The commit asked about is the one checked, even if the result changed since.
     if (target.head !== wanted.head) {
         finish("not-run", "The result's commit changed after checks were asked for.");
         return followUpChecksOf(store, runId, now(), root).find(one => one.request === request) ?? null;
     }
-    // An automatic recheck runs only on its check-only authorization, read again now (check-only.ts): no record, no run.
     const authorized = wanted.why === "recheck" ? recheckStanding(store, { request, runId, head: target.head, digest: wanted.digest }) : null;
     if (wanted.why === "recheck" && !authorized?.ok) {
         finish("not-run", authorized?.problem ?? "Its authorization couldn't be read.");
         return followUpChecksOf(store, runId, now(), root).find(one => one.request === request) ?? null;
     }
-    /** Every command of an automatic recheck, refused at the moment it would run wider than the build's own access. */
     const launched = (inner) => !authorized?.ok ? inner : (file, args, options) => {
         if (widerThan(actualCheckAccess(store, checkoutLaunchOf(store, target.repo, [runId]).access), authorized.access))
             return Promise.resolve({ code: 126, stdout: "", stderr: "", notFound: true, timedOut: false });
@@ -217,7 +197,6 @@ export async function runFollowUpCheck(store, root, request, deps = {}) {
     const folder = mkdtempSync(join(deps.scratch ?? tmpdir(), "toolroll-checks-"));
     const checkout = join(folder, "checkout");
     const log = [];
-    // How each command actually ran (check-access.ts): the widest is on the receipt and in the log.
     const ranAt = [];
     const bound = (text) => { const hits = scanForSecrets(text); return boundStreamHeadTail(hits.length > 0 ? redactSecretLines(text, hits) : text, 24 * 1024); };
     const note = (label, command, result) => log.push(`=== ${label} ===\n$ ${command}\n(exit ${result.code}${result.notFound ? ", could not start" : ""}${result.timedOut ? ", timed out" : ""})\n\n--- stdout ---\n${bound(result.stdout)}\n\n--- stderr ---\n${bound(result.stderr)}`);
@@ -230,7 +209,6 @@ export async function runFollowUpCheck(store, root, request, deps = {}) {
         }
         else {
             const setup = store.liveWorktreeSetup(target.repo);
-            // Worked out again right before each command (check-access.ts): a narrowing meanwhile applies to the next one.
             let ready = true;
             if (setup !== null) {
                 const shell = approvedCommandShell(setup.command);
@@ -242,7 +220,6 @@ export async function runFollowUpCheck(store, root, request, deps = {}) {
                 }
             }
             if (ready) {
-                // The approval is re-read right before the check starts: a revoked or changed command never runs.
                 const live = store.liveVerifyCommand(target.command.repo);
                 if (live === null || live.digest !== target.command.digest || live.digest !== wanted.digest) {
                     result = { ran: false, failure: "The approved check changed before it started." };
@@ -279,7 +256,6 @@ export async function runFollowUpCheck(store, root, request, deps = {}) {
         finish("not-run", result.failure);
     return followUpChecksOf(store, runId, now(), root).find(one => one.request === request) ?? null;
 }
-/** The worker's pass: run every waiting request, one at a time. */
 export async function runWaitingChecks(store, root, deps = {}) {
     let ran = 0;
     for (const one of waitingCheckRequests(store, (deps.now ?? (() => new Date()))())) {
@@ -290,9 +266,6 @@ export async function runWaitingChecks(store, root, deps = {}) {
     }
     return ran;
 }
-/** The build's own check, then each finished follow-up in order on the same
- * commit: a pass upgrades (a quick pass never replaces a full one), a failure
- * is shown as it is. A follow-up that couldn't run changes nothing. */
 export function withFollowUps(original, followUps) {
     let reading = original;
     for (const one of followUps) {
@@ -308,8 +281,6 @@ export function withFollowUps(original, followUps) {
     const running = followUps.filter(one => one.state === "waiting" || one.state === "running").at(-1)?.level ?? null;
     return { ...reading, running };
 }
-/** The level a result's checks stand at now: the build's own level, raised by
- * a follow-up that passed on the same commit. null for results from before levels. */
 export function resultCheckLevel(store, runId, now) {
     const level = runCheckLevel(store, runId);
     const run = store.getRun(runId);
@@ -326,10 +297,7 @@ export function fullCheckGate(store, runId, now) {
     if (level === null || repo === null || run === null)
         return { state: "clear" };
     const fulls = followUpChecksOf(store, runId, now).filter(one => one.level === "full" && one.head === run.headRevision);
-    // A Full build that waited for a batch check has had no check of its own: Merge waits for the batch, like Quick does.
     const batched = level === "full" && fulls.some(one => one.why === "batch");
-    // A recorded Full level is not a pass (review round 1): the build's own check must have passed, and a release
-    // check that re-ran only what failed is proved by its release alone, never cleared here.
     if (level === "full" && !batched) {
         const targeted = store.handle.prepare("SELECT 1 AS hit FROM release_check_attempt WHERE run = ? AND mode = 'targeted'").get(runId) !== undefined;
         if (targeted)
@@ -337,8 +305,6 @@ export function fullCheckGate(store, runId, now) {
         const own = store.handle.prepare("SELECT status FROM run_check WHERE run = ?").get(runId);
         if (own !== undefined && own["status"] === "passed")
             return { state: "clear" };
-        // An ordinary task's own check didn't pass (or has no row): a Full check run again on this same commit decides
-        // (review round 2). A release's task never: it merges only through its release.
         const taskId = store.refById(run.taskRef)?.externalId ?? null;
         const last = fulls.at(-1);
         if (last !== undefined && (taskId === null || !belongsToRelease(store, taskId))) {
@@ -350,7 +316,6 @@ export function fullCheckGate(store, runId, now) {
                 return { state: "not-run", message: `The full check didn't finish on this commit${last.note === null ? "" : `: ${last.note}`} Run it again, or merge anyway.` };
             return { state: "waiting", message: "The full check is still running on this commit. Merge once it passes, or merge anyway." };
         }
-        // No row is a check pending or never requested, never a pass (security review).
         if (own === undefined)
             return { state: "not-requested", message: "The full check hasn't run on this commit yet. Merge once it passes, or merge anyway." };
         return { state: "failed", message: "The full check didn't pass on this commit. Fix it, or merge anyway." };
@@ -368,9 +333,6 @@ export function fullCheckGate(store, runId, now) {
         return { state: "not-run", message: `The full check didn't finish on this commit${last.note === null ? "" : `: ${last.note}`} Run it again, or merge anyway.` };
     return { state: "waiting", message: "The full check is still running on this commit. Merge once it passes, or merge anyway." };
 }
-// ---- Add tests --------------------------------------------------------------
-/** File a small task to write tests for a result's change. It is filed like any
- * other task: nothing runs until a person approves it. */
 export function fileAddTestsTask(store, root, input, now) {
     const run = store.getRun(input.runId);
     const ref = run === null ? null : store.refById(run.taskRef);

package/dist/result-review.js

@@ -1,23 +1,3 @@
-/** Result-first review (workspace package 3, 2026-09-13): the pure parts
- * of ONE result presentation shared by the task chat receipt, the run
- * page, the review cockpit, and the chat's result detail.
- *
- * Nothing here reads a database or renders a full page. The server
- * assembles the same verified records it already reads (handoff, proof,
- * diff, matrix, publication, report) into `SharedResultFacts`; every
- * surface prints those facts through `resultFactsAttributeMap` (as html attributes), so a test —
- * or a person — can check that chat, run detail, and review agree on the
- * run, its head, its checks, its caveats, and its publication.
- *
- * The presentation leads with the deliverable itself: validated
- * screenshots for UI work, the escaped report for an investigation, a
- * concise change summary for code. Missing, corrupt, or truncated
- * evidence is named in `evidenceProblemsOf` and is never described as
- * validated. Three local views — Summary, Changes, Checks — are anchor
- * links (`?tab=`) the server honours, enhanced in the browser by
- * `RESULT_REVIEW_SCRIPT`, which also keeps a bounded review draft, the
- * selected tab, and the reading position in this tab's sessionStorage,
- * keyed by the server-named account, the task, and the run. */
 import { resultStatusOf } from "./workspace-ui.js";
 export function parseFeedbackImage(value) {
     if (value === undefined || value === null || value === "")
@@ -39,8 +19,6 @@ export function parseFeedbackImage(value) {
 export function sameFeedbackImage(a, b) {
     return (a == null && b == null) || (a != null && b != null && a.run === b.run && a.artifact === b.artifact && a.sha256 === b.sha256);
 }
-/** Add re-read evidence health to the existing result/review projection.
- * This is presentation only: the recorded verdict and acceptance stay intact. */
 export function evidenceResultStatusOf(result, publication, evidence) {
     const recorded = resultStatusOf({ ...result, review: null }, publication);
     let stored = recorded;
@@ -48,7 +26,6 @@ export function evidenceResultStatusOf(result, publication, evidence) {
         stored = {
             token: "evidence-damaged",
             label: "Result saved, but some saved material is unavailable",
-            // Never "passed" when the check itself can't be read now (task-status.ts approvedCheckOf).
             detail: recorded.token === "check-unreadable" ? `Some saved material is missing, damaged, or could not be read. ${recorded.detail}`
                 : `Some saved material is missing, damaged, or could not be read. ${result.verdict === "verified" && result.checks !== undefined && ["ready-to-review", "pr-opened", "merge-observed", "pr-closed"].includes(recorded.token)
                     ? "The machine's verdict at completion is unchanged: the approved check passed against it then."
@@ -71,7 +48,6 @@ export const RESULT_TABS = [
     { key: "changes", label: "Changes" },
     { key: "checks", label: "Checks" },
 ];
-/** The requested local view; anything unknown reads as Summary. */
 export function parseResultTab(raw) {
     return raw === "changes" || raw === "checks" ? raw : "summary";
 }
@@ -84,8 +60,6 @@ export function resultLeadOf(input) {
         return "changes";
     return "summary";
 }
-/** Every evidence problem, classified, in a stable order. Empty means
- * every record this result cites is present, whole, and verifies. */
 export function evidenceProblemDetailsOf(input) {
     const problems = [];
     const damaged = (words) => problems.push({ kind: "damaged", words });
@@ -123,7 +97,6 @@ export function evidenceProblemDetailsOf(input) {
         missing("The no-change conclusion has no handoff record.");
     return problems;
 }
-/** Every evidence problem in plain words, in a stable order. */
 export function evidenceProblemsOf(input) {
     return evidenceProblemDetailsOf(input).map(one => one.words);
 }
@@ -133,11 +106,6 @@ export function evidenceHealthOf(problems) {
         health[one.kind] += 1;
     return health;
 }
-/** The `data-result-*` attributes every surface stamps on its result
- * element. Values are short, escaped, and deterministic for one run, so
- * two surfaces rendering the same result carry byte-identical attributes. */
-/** The shared facts as the panel's data attributes, unescaped (the rebuilt
- * result page sets them through React). */
 export function resultFactsAttributeMap(facts) {
     return {
         "data-result-run": String(facts.runId),
@@ -150,11 +118,7 @@ export function resultFactsAttributeMap(facts) {
         "data-result-publication": facts.publicationState,
     };
 }
-/** The shared fact names, in the order `resultFactsAttributeMap` lists them. */
 export const RESULT_FACT_KEYS = ["run", "head", "base", "head-source", "checks", "caveats", "evidence", "publication"];
-/** Parse the shared facts back — the test-side and proof-side reader.
- * Only the shared keys are read; a panel's own presentation attributes
- * (place, lead, task, user) are not facts and are left out. */
 export function resultFactsFromHtml(html) {
     const found = [];
     const tag = /<[a-z]+\b[^>]*\bdata-result-run="[^"]*"[^>]*>/g;
@@ -169,10 +133,6 @@ export function resultFactsFromHtml(html) {
     }
     return found;
 }
-/** Where a result form may send its reader back: the review cockpit's
- * own deep link, the chat's result detail, the page of a task named in
- * `tasks` (the run's own) or its Result tab at this run, or the run page. Anything else lands on the run
- * page. Matched exactly — never a bare open redirect. */
 export function resultReturnTarget(raw, runId, tasks = []) {
     if (raw !== null && raw !== undefined) {
         if (raw === `/r/${runId}?record=1`)
@@ -183,43 +143,25 @@ export function resultReturnTarget(raw, runId, tasks = []) {
         const chat = /^\/chat\?task=([A-Za-z0-9._~%-]{1,200})&result=([0-9]{1,15})(?:&conversation=[A-Za-z0-9-]{1,128})?$/.exec(raw);
         if (chat !== null && Number(chat[2]) === runId)
             return raw;
-        // The run's own task page, which offered Run checks in place; never another task's.
         if (tasks.some(task => raw === `/t/${encodeURIComponent(task)}`))
             return raw;
-        // That task page's Result tab at this run (docs/plans/one-page-task-and-agent.md), its version and view kept.
         const tab = /^\/t\/([A-Za-z0-9._~%-]{1,200})\?(?:version=[A-Za-z0-9._~%-]{1,200}&)?tab=result&run=([0-9]{1,15})(?:&section=(?:summary|changes|checks))?$/.exec(raw);
         if (tab !== null && Number(tab[2]) === runId && tasks.some(task => tab[1] === encodeURIComponent(task)))
             return raw;
     }
     return `/r/${runId}`;
 }
-/** A form's own request token, minted per render — the same shape the
- * chat composer uses. A replayed submission carries the same token, so
- * the server can recognise it and mint nothing twice. */
 export const REQUEST_TOKEN = /^[a-f0-9]{32}$/;
-/** The dedupe key a review note is stored under when the form carried a
- * request token: bound to the account and the token, never to the words,
- * so the same person saying the same thing twice on purpose still lands. */
 export function commentSourceKey(user, request) {
     return request !== null && request !== undefined && REQUEST_TOKEN.test(request) ? `review:${user}:${request}` : undefined;
 }
-/** The revision form's exact batch (repair 2026-09-14): the ids of the
- * live notes the page DISPLAYED, oldest first, joined by commas, plus the
- * source scope digest the page rendered against ("none" when the task has
- * no scope). A seal binds to exactly these — never to "whatever is live
- * when the POST arrives" — so a replayed or second-tab submission can
- * only ever consume the notes its own reader saw. */
 export function revisionBatchOf(comments) {
     return comments.map(one => String(one.id)).join(",");
 }
-/** User feedback requests work; a reviewer's observations only do so when
- * they are problems. The original findings always remain on record. */
 export function isRevisionFeedback(comment) {
     return comment.reviewerRun === null || comment.severity === "problem";
 }
 export const REVISION_BATCH_CAP = 500;
-/** Parse a posted batch back into distinct positive ids, or null when the
- * field is absent or malformed (an out-of-date form, a hand-built POST). */
 export function parseRevisionBatch(raw) {
     if (raw === null || raw === undefined)
         return null;
@@ -231,37 +173,9 @@ export function parseRevisionBatch(raw) {
         return null;
     return new Set(ids).size === ids.length ? ids : null;
 }
-/** The source binding the revision form carries: the scope digest the
- * page was rendered against, or "none". */
 export function revisionSourceOf(scopeDigest) {
     return scopeDigest === null ? "none" : scopeDigest;
 }
-/** The in-page half of the result presentation. Everything it does is
- * presentational or a bounded draft: no fetch, no endpoint, no submit.
- *
- * - Tabs: the anchor links switch the visible view in place and record
- *   `?tab=` with replaceState, so refresh and Back land on the same view
- *   the server would render for that URL.
- * - Diff modes: View hides the line pins; Annotate shows them. A pin or a
- *   file button copies its target into the Request changes form, opens
- *   the pin disclosure, and focuses the note.
- * - Review draft: the note, file, and line are kept in sessionStorage
- *   under the account, task, and run the form names, for at most a day,
- *   and restored on load. The draft clears only when the page carries the
- *   receipt for THIS draft's request token (`?noted=<token>`); a refused
- *   submission leaves it in place. Other accounts' drafts on this tab are
- *   dropped, never restored.
- * - Request identity (repair 2026-09-14): the form's request token is
- *   bound to the exact note, file, and line last displayed, even when
- *   FormData is sent directly. An unchanged retry keeps the token, so the server
- *   records it once; editing any of the three after a submission mints a
- *   fresh token, so the edited words are a new note and can never be
- *   swallowed by the earlier one's receipt. A refusal that comes back with
- *   `?conflict=<token>` rotates that token too, keeping the words.
- * - Reading position: the page's scroll offset is kept under the same
- *   account/task and the URL's own result and tab, and restored on load
- *   when the URL carries no hash, so Back to chat and refresh return the
- *   reader to where they were. */
 export const RESULT_REVIEW_SCRIPT = String.raw `
 (function(){
   var panel=document.querySelector('[data-result-panel]');

package/dist/result-shots.js

@@ -1,18 +1,3 @@
-/**
- * Screenshots with results: a person can choose to get a result's saved
- * screenshots in their chat app right after its "ready" (or failed) message —
- * Off (the default), the first one, or up to four.
- *
- * The store records one row per result and person (`RESULT_SHOTS_KIND`) when
- * the result message is made; every transport asks here, at send time, what
- * that row may carry. The checks are the acceptance-evidence sender's: the
- * task is in the projects this chat may reach now, the result is still the
- * task's current one, and each file verifies against its recorded sha256
- * under the evidence root. A failure is one plain line and nothing else; a
- * result whose files retention already removed sends nothing and says
- * nothing. The choice is read again here, so turning it off stops what has
- * not gone yet, and never more than it allows is sent.
- */
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { imageDimensions, readVerifiedProofForRun, readVerifiedReport, RETENTION_NOTE } from "./evidence.js";
@@ -22,19 +7,15 @@ import { chatTitle } from "./chat-voice.js";
 import { itemCaption, readFlowItems } from "./flow-items.js";
 import { FLOW_SHOTS_KIND, RESULT_SHOTS_KIND } from "./store.js";
 import { savedChatPart } from "./chat-delivery-state.js";
-/** "Up to 4": the most screenshots one result ever sends. */
 export const RESULT_SHOTS_MAX = 4;
-/** The choices in the order Settings and the CLI show them. */
 export const RESULT_SHOT_CHOICES = [["off", "Off"], ["first", "First one"], ["all", "Up to 4"]];
 export function resultShotLimit(choice) {
     return choice === "first" ? 1 : choice === "all" ? RESULT_SHOTS_MAX : 0;
 }
-/** Telegram's own photo limits (Bot API sendPhoto, checked 2026-10-03): over them, a screenshot goes as a document. */
 const PHOTO_MAX_BYTES = 10 * 1024 * 1024;
 const PHOTO_MAX_SIDES = 10_000;
 const PHOTO_MAX_RATIO = 20;
 const SCREENSHOT_CAPTURE = /^agent-claimed screenshot at (.+) \(validated (?:png|jpeg)\)/;
-/** A screenshot's own caption from the result's proof, in plain words; null when it has none fit to show. */
 function ownCaptions(store, root, run) {
     const proof = readVerifiedProofForRun(store, root, run);
     const captions = new Map();
@@ -47,7 +28,6 @@ function ownCaptions(store, root, run) {
     }
     return captions;
 }
-/** A scout's screenshots keep the captions its report gave them, by evidence id. */
 function reportCaptions(store, root, taskRef, run) {
     const captions = new Map();
     const view = readVerifiedReport(store, root, taskRef);
@@ -60,7 +40,6 @@ function reportCaptions(store, root, taskRef, run) {
     }
     return captions;
 }
-/** A flow visit's item screenshots from this run, in item order, each with its numbered caption (flow-items.ts). */
 function itemCaptions(store, dedupeKey, run) {
     const captions = new Map();
     const visit = /^flow-shots:([1-9][0-9]{0,14}):([1-9][0-9]{0,9})$/.exec(dedupeKey ?? "");
@@ -89,16 +68,9 @@ function isPhoto(bytes, format) {
     return bytes.length <= PHOTO_MAX_BYTES && size.width + size.height <= PHOTO_MAX_SIDES
         && Math.max(size.width, size.height) / Math.min(size.width, size.height) <= PHOTO_MAX_RATIO;
 }
-/**
- * What one person's screenshots row may send now, to a chat that reaches
- * `repos`. `sent`: screenshots this destination already has, never sent again.
- * Every byte returned was verified this instant; a channel uploads them with
- * no wait in between, or asks again.
- */
 export function resultShotsFor(store, evidenceRoot, repos, row, sent = new Set()) {
     if (!isShotsKind(row.kind) || row.recipient === null || row.taskId === null || row.taskRef === null || row.run === null)
         return { kind: "none", why: "none" };
-    // A flow's "Send to me" or "Person chooses" asked for them: up to four, whatever the person chose for results.
     const limit = row.kind === FLOW_SHOTS_KIND ? RESULT_SHOTS_MAX : resultShotLimit(store.notificationPreference(row.recipient).screenshots);
     if (limit === 0)
         return { kind: "none", why: "off" };
@@ -106,7 +78,6 @@ export function resultShotsFor(store, evidenceRoot, repos, row, sent = new Set()
     const line = (why) => ({ kind: "line", text: `Screenshots for ${title} weren't sent: ${why}.` });
     if (evidenceRoot === undefined)
         return line("saved files can't be read from here");
-    // Retention removed this result's files: nothing to show, and nothing worth saying.
     if (existsSync(join(evidenceRoot, String(row.run), RETENTION_NOTE)))
         return { kind: "none", why: "pruned" };
     const ref = store.lookupRef(row.taskId);
@@ -116,8 +87,6 @@ export function resultShotsFor(store, evidenceRoot, repos, row, sent = new Set()
     const latest = store.runsFor(row.taskRef).find(one => one.finishedAt !== null && ["builder", "repair", "scout"].includes(one.role));
     if (family?.current.id !== row.taskId || latest?.id !== row.run)
         return line("a newer result replaced this one");
-    // After research, a flow's message numbers the report's items (flow-items.ts): their screenshots go first, in that
-    // order, each captioned with its item's number, so "2." here is item 2 in the text.
     const items = row.kind === FLOW_SHOTS_KIND ? itemCaptions(store, row.dedupeKey, row.run) : new Map();
     const order = [...items.keys()];
     const rank = (id) => { const at = order.indexOf(id); return at < 0 ? order.length : at; };
@@ -131,7 +100,6 @@ export function resultShotsFor(store, evidenceRoot, repos, row, sent = new Set()
     for (const [index, artifact] of chosen.entries()) {
         const verified = verifyResultImage(store, evidenceRoot, repos, { taskId: row.taskId, run: row.run, artifact: artifact.id, sha256: artifact.sha256 });
         if (!verified.ok) {
-            // Removed by retention between the check above and now: still nothing to say.
             if (existsSync(join(evidenceRoot, String(row.run), RETENTION_NOTE)))
                 return { kind: "none", why: "pruned" };
             return line(verified.problem);
@@ -148,23 +116,16 @@ export function resultShotsFor(store, evidenceRoot, repos, row, sent = new Set()
     const remaining = shots.filter(one => !sent.has(one.artifact));
     return remaining.length === 0 ? { kind: "none", why: "sent" } : { kind: "send", taskId: row.taskId, run: row.run, shots: remaining };
 }
-/** A row that carries a result's screenshots: one a person asked for with results, or one a flow sends them. */
 export function isShotsKind(kind) {
     return kind === RESULT_SHOTS_KIND || kind === FLOW_SHOTS_KIND;
 }
-/** A screenshot whose result message is not posted yet waits for that message's own next try (at least a second). */
 export function shotWaitsUntil(resultNextAt, now) {
     const soonest = new Date(now.getTime() + 1_000).toISOString();
     return typeof resultNextAt === "string" && resultNextAt > soonest ? resultNextAt : soonest;
 }
-/** Retention removed this result's files: its screenshots go quietly, never as a complaint. */
 export function resultShotsPruned(evidenceRoot, run) {
     return existsSync(join(evidenceRoot, String(run), RETENTION_NOTE));
 }
-/**
- * The chat app refused the upload (no file permission there): this part becomes one plain line and the result's
- * other screenshots in the same message are dropped, so the person reads one line, not one per screenshot.
- */
 export function refuseResultShots(state, store, part, content, app, now) {
     const title = chatTitle(store, content.image?.taskId ?? content.task ?? "");
     const line = { text: `Screenshots for ${title} weren't sent: the ${app} app isn't allowed to upload files here.`,

package/dist/retention-ui.js

@@ -1,17 +1,10 @@
-/**
- * Settings → Retention (v105): how long each kind of data is kept, and what
- * the next daily sweep would remove. An instance operator's page; changes
- * take a step-up. Built from the revamp kit; the Settings frame adds the title.
- */
 import { html, joinHtml } from "./html.js";
 import { bytesWords } from "./storage.js";
 import { RETENTION_KINDS, countWords, periodChoices, periodLabel } from "./retention.js";
 import { formRow, infoLine, note, notice, select, settingsSection } from "./server/kit.js";
 import { kitSectionForm } from "./settings-kit.js";
-/** The page is kit pieces now; nothing of the old look is left. Kept as an export for the shared stylesheet. */
 export const RETENTION_CSS = "";
 const listWords = (parts) => parts.length < 2 ? parts.join("") : `${parts.slice(0, -1).join(", ")} and ${parts.at(-1)}`;
-/** The next sweep in a line: what goes and about how much space, or that nothing is due. */
 function nextWords(view) {
     if (RETENTION_KINDS.every(({ kind }) => view.periods[kind] === null))
         return "Everything is kept forever.";