toolroll 0.9.6 → 0.9.8

package/dist/result-follow-ups.js

@@ -0,0 +1,333 @@
+/** Follow-ups on any result: "Run checks" and "Add tests".
+ *
+ * Run checks runs the project's quick or full check on the result's exact
+ * commit, in a fresh checkout, after the build has finished. A person (or a
+ * pull request opening) asks; the ask is a ledger entry; a worker runs it
+ * once and seals its log and a receipt beside the result. A pass upgrades
+ * what the result's Checks row says; a failure stays visible. Nothing here
+ * rewrites the build's own check or reruns crew work.
+ *
+ * Add tests files a small task, unapproved like any other filing, to write
+ * tests for that change. */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run as execRun } from "./exec.js";
+import { approvedCommandShell, SETUP_ENV_ALLOWLIST, SETUP_ENV_DENYLIST } from "./builder.js";
+import { runWithIsolatedDatabase } from "./child-database.js";
+import { boundStreamHeadTail, readVerifiedArtifact, redactSecretLines, scanForSecrets, storeEvidence } from "./evidence.js";
+import { CHECK_LEVEL_WORDS, checkCommandFor, quickVerifyKey, repoClause, repoOfRun, runCheckLevel } from "./check-levels.js";
+import { fileTaskProposal } from "./proposal.js";
+export const CHECKS_REQUESTED = "checks requested";
+export const CHECKS_STARTED = "checks started";
+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) {
+    const [where, params] = repoClause(repoOfRun(store, runId));
+    return store.handle.prepare(`SELECT id, actor, at, outcome, detail, action FROM action_ledger WHERE ${where} AND run_id = ? AND action IN (?, ?, ?) ORDER BY id`)
+        .all(...params, runId, CHECKS_REQUESTED, CHECKS_STARTED, CHECKS_FINISHED)
+        .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();
+    if (root !== undefined) {
+        for (const artifact of store.artifactsFor(runId).filter(one => one.kind === "structured-output" && one.capture === FOLLOW_UP_RECEIPT)) {
+            const read = readVerifiedArtifact(root, artifact);
+            if (!read.ok)
+                continue;
+            try {
+                const body = JSON.parse(read.content.toString("utf8"));
+                if (typeof body.request !== "number")
+                    continue;
+                receipts.set(body.request, { ran: body.result?.ran === true, exitCode: typeof body.result?.exitCode === "number" ? body.result.exitCode : null,
+                    log: typeof body.log?.artifactId === "number" ? body.log.artifactId : null });
+            }
+            catch { /* an unreadable receipt upgrades nothing */ }
+        }
+    }
+    return rows.filter(row => row.action === CHECKS_REQUESTED && (row.outcome === "quick" || row.outcome === "full")).map(request => {
+        const [head = "", why = "person", digest = ""] = (request.detail ?? "").split(" · ");
+        const started = rows.find(row => row.action === CHECKS_STARTED && row.outcome === String(request.id)) ?? null;
+        const finished = rows.find(row => row.action === CHECKS_FINISHED && row.outcome.startsWith(`${request.id}:`)) ?? null;
+        const base = { request: request.id, runId, level: request.outcome, head, digest, actor: request.actor, at: request.at,
+            why: why === "pull-request" ? "pull-request" : "person", exitCode: null, logArtifactId: null, note: null };
+        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.
+            if (status === "passed" && root !== undefined && (sealed === null || !sealed.ran || sealed.exitCode !== 0)) {
+                return { ...base, state: "not-run", note: "The saved check result could not be verified." };
+            }
+            const exit = /exit (\d+)/.exec(finished.detail ?? "");
+            return { ...base, state: status === "passed" ? "passed" : status === "failed" ? "failed" : "not-run",
+                exitCode: exit === null ? sealed?.exitCode ?? null : Number(exit[1]), logArtifactId: sealed?.log ?? null, note: status === "not-run" ? finished.detail : null };
+        }
+        if (started !== null) {
+            const limit = Number(/limit (\d+)/.exec(started.detail ?? "")?.[1] ?? 3_600_000);
+            if (now.getTime() - Date.parse(started.at) > limit + ABANDONED_GRACE_MS)
+                return { ...base, state: "not-run", note: "The check didn't finish." };
+            return { ...base, state: "running" };
+        }
+        return { ...base, state: "waiting" };
+    });
+}
+/** 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);
+    if (run === null || ref === null)
+        return refuse("unknown", "No such result.");
+    if (run.finishedAt === null || run.headRevision === null || !/^[a-f0-9]{40}$/.test(run.headRevision))
+        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.");
+    const chosen = checkCommandFor(store, ref.repo, level);
+    if (chosen.command === null)
+        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);
+        if (!target.ok)
+            return target;
+        const open = followUpChecksOf(store, input.runId, now).find(one => one.level === target.level && one.head === target.head && (one.state === "waiting" || one.state === "running"));
+        if (open !== undefined)
+            return { ok: true, request: open.request, level: target.level, existing: true };
+        const request = store.recordAction({ at: now.toISOString(), actor: input.actor, repo: target.repo, taskId: target.taskId, runId: input.runId,
+            action: CHECKS_REQUESTED, outcome: target.level, source: "work", detail: `${target.head} · ${input.why ?? "person"} · ${target.command.digest}` });
+        store.bumpWake();
+        return { ok: true, request, level: target.level, existing: false };
+    });
+}
+/** Requests nobody has started yet, oldest first. */
+export function waitingCheckRequests(store, now) {
+    const runs = store.handle.prepare(`SELECT DISTINCT r.run_id AS run FROM action_ledger r WHERE r.action = ? AND r.run_id IS NOT NULL
+    AND NOT EXISTS (SELECT 1 FROM action_ledger s WHERE s.run_id = r.run_id AND s.action = ? AND s.outcome = CAST(r.id AS TEXT)) ORDER BY r.id`)
+        .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;
+    const git = deps.git ?? execRun;
+    const asked = store.handle.prepare("SELECT run_id FROM action_ledger WHERE id = ? AND action = ?").get(request, CHECKS_REQUESTED);
+    if (asked === undefined)
+        return null;
+    const runId = Number(asked["run_id"]);
+    const wanted = followUpChecksOf(store, runId, now()).find(one => one.request === request);
+    if (wanted === undefined || wanted.state !== "waiting")
+        return wanted ?? null;
+    const target = checkTarget(store, runId, wanted.level);
+    const finish = (status, detail) => {
+        store.recordAction({ at: now().toISOString(), actor: "system", repo: target.ok ? target.repo : null, taskId: target.ok ? target.taskId : null, runId,
+            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;
+        store.recordAction({ at: now().toISOString(), actor: "system", repo: target.ok ? target.repo : null, taskId: target.ok ? target.taskId : null, runId,
+            action: CHECKS_STARTED, outcome: String(request), source: "work", detail: `limit ${target.ok ? target.command.timeoutMs : 0}` });
+        return true;
+    });
+    if (!claimed)
+        return followUpChecksOf(store, runId, now(), root).find(one => one.request === request) ?? null;
+    if (!target.ok) {
+        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;
+    }
+    const folder = mkdtempSync(join(deps.scratch ?? tmpdir(), "toolroll-checks-"));
+    const checkout = join(folder, "checkout");
+    const log = [];
+    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)}`);
+    let result;
+    try {
+        const added = await git("git", ["-C", target.repo, "worktree", "add", "--detach", checkout, target.head], { timeoutMs: 120_000 });
+        if (added.code !== 0) {
+            note("Checkout", `git worktree add --detach <fresh folder> ${target.head}`, added);
+            result = { ran: false, failure: "The commit couldn't be checked out. It may have been removed from this computer." };
+        }
+        else {
+            const setup = store.liveWorktreeSetup(target.repo);
+            let ready = true;
+            if (setup !== null) {
+                const shell = approvedCommandShell(setup.command);
+                const prepared = await runWithIsolatedDatabase(runner, shell.file, shell.args, { cwd: checkout, timeoutMs: setup.timeoutMs, processGroup: true, envAllowlist: SETUP_ENV_ALLOWLIST, omitEnv: SETUP_ENV_DENYLIST });
+                note("Approved project setup", setup.command, prepared);
+                if (prepared.code !== 0 || prepared.timedOut || prepared.notFound) {
+                    ready = false;
+                    result = { ran: false, failure: "The project's setup failed, so the check didn't run." };
+                }
+            }
+            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." };
+                }
+                else {
+                    const shell = approvedCommandShell(live.command);
+                    const ran = await runWithIsolatedDatabase(runner, shell.file, shell.args, { cwd: checkout, timeoutMs: live.timeoutMs, processGroup: true, envAllowlist: SETUP_ENV_ALLOWLIST, omitEnv: SETUP_ENV_DENYLIST });
+                    note(`${CHECK_LEVEL_WORDS[target.level]} check`, live.command, ran);
+                    result = ran.timedOut ? { ran: false, failure: "The check ran out of time." } : ran.notFound ? { ran: false, failure: "The check couldn't start." } : { ran: true, exitCode: ran.code };
+                }
+            }
+            else
+                result ??= { ran: false, failure: "The project's setup failed, so the check didn't run." };
+        }
+    }
+    finally {
+        await git("git", ["-C", target.repo, "worktree", "remove", "--force", checkout], { timeoutMs: 120_000 }).catch(() => null);
+        rmSync(folder, { recursive: true, force: true });
+    }
+    const at = now();
+    const text = log.length === 0 ? "No command started." : log.join("\n\n");
+    const logId = storeEvidence(store, root, runId, "structured-output", `follow-up-check-${request}.log`, Buffer.from(text, "utf8"), FOLLOW_UP_LOG, at, { captureStatus: "ok" });
+    const logArtifact = store.getArtifact(logId);
+    const receipt = JSON.stringify({ version: 1, request, run: runId, head: target.head, level: target.level,
+        command: { repo: target.command.repo, command: target.command.command, digest: target.command.digest, approvedBy: target.command.approvedBy },
+        result, log: { artifactId: logArtifact.id, sha256: logArtifact.sha256, bytesStored: logArtifact.bytesStored, truncated: logArtifact.truncated } }, null, 1);
+    storeEvidence(store, root, runId, "structured-output", `follow-up-check-${request}.json`, Buffer.from(receipt, "utf8"), FOLLOW_UP_RECEIPT, at, { captureStatus: "ok" });
+    if (result.ran)
+        finish(result.exitCode === 0 ? "passed" : "failed", `${CHECK_LEVEL_WORDS[target.level]} checks on ${target.head.slice(0, 7)} · exit ${result.exitCode}`);
+    else
+        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()))())) {
+        if (deps.shouldStop?.() === true)
+            break;
+        if ((await runFollowUpCheck(store, root, one.request, deps))?.state !== "waiting")
+            ran++;
+    }
+    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) {
+        if (original.head !== null && one.head !== "" && one.head !== original.head)
+            continue;
+        if (one.state === "passed") {
+            if (!(reading.status === "passed" && reading.level === "full" && one.level === "quick"))
+                reading = { status: "passed", level: one.level, exitCode: 0, head: one.head };
+        }
+        else if (one.state === "failed")
+            reading = { status: "failed", level: one.level, exitCode: one.exitCode, head: one.head };
+    }
+    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);
+    const follows = followUpChecksOf(store, runId, now);
+    if (follows.length === 0)
+        return level;
+    const read = withFollowUps({ status: level === "off" ? "not-run" : "passed", level, exitCode: null, head: run?.headRevision ?? null }, follows);
+    return read.level;
+}
+/** Whether this result's commit has passed the project's full check, here or in a follow-up. */
+export function fullCheckPassed(reading) {
+    return reading.status === "passed" && (reading.level === "full" || reading.level === null);
+}
+export function fullCheckGate(store, runId, now) {
+    const level = runCheckLevel(store, runId);
+    const repo = repoOfRun(store, runId);
+    const run = store.getRun(runId);
+    if (level === null || level === "full" || repo === null || run === null || store.liveVerifyCommand(repo) === null)
+        return { state: "clear" };
+    const last = followUpChecksOf(store, runId, now).filter(one => one.level === "full" && one.head === run.headRevision).at(-1);
+    if (last === undefined)
+        return { state: "not-requested", message: "The full check hasn't run on this commit yet. Merge once it passes, or merge anyway." };
+    if (last.state === "passed")
+        return { state: "clear" };
+    if (last.state === "failed")
+        return { state: "failed", message: `The full check failed on this commit${last.exitCode === null ? "" : ` (exit ${last.exitCode})`}. Fix it, or merge anyway.` };
+    if (last.state === "not-run")
+        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." };
+}
+export const isQuickCommand = (command, repo) => command !== null && command.repo === quickVerifyKey(repo);
+// ---- 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);
+    if (run === null || ref === null)
+        return refuse("unknown", "No such result.");
+    if (ref.repo === null)
+        return refuse("unplaced", "This result isn't in a project.");
+    if (run.headRevision === null || !/^[a-f0-9]{40}$/.test(run.headRevision))
+        return refuse("no-commit", "This result has no commit to write tests for.");
+    const earlier = store.handle.prepare("SELECT outcome FROM action_ledger WHERE run_id = ? AND action = ? ORDER BY id DESC LIMIT 1").get(input.runId, ADD_TESTS_ACTION);
+    if (earlier !== undefined && store.getTask(String(earlier["outcome"])) !== null)
+        return { ok: true, id: String(earlier["outcome"]), existing: true };
+    const task = store.getTask(ref.externalId);
+    const files = root === null ? [] : changedFilesOf(store, root, input.runId);
+    const shown = files.slice(0, 12);
+    const title = `Add tests for ${task?.title ?? ref.externalId}`.slice(0, 200);
+    const goal = [
+        `Write tests for the change made by ${ref.externalId} (commit ${run.headRevision.slice(0, 7)}).`,
+        shown.length === 0 ? "" : `Changed files: ${shown.join(", ")}${files.length > shown.length ? `, and ${files.length - shown.length} more` : ""}.`,
+        "Cover the changed behaviour, including its edge cases. Change product code only if a test shows a real bug, and say so.",
+    ].filter(one => one !== "").join(" ");
+    const filed = store.transact(() => {
+        const made = fileTaskProposal(store, {
+            title, repo: ref.repo, goal, planning: "skip", filedVia: input.filedVia,
+            acceptance: [{ id: "c1", statement: "New tests cover the changed behaviour and pass", evidence: ["check"], how: null }],
+            ...(input.admittedRepos === undefined ? {} : { admittedRepos: input.admittedRepos }),
+        }, now);
+        if (!made.ok)
+            return made;
+        store.recordAction({ at: now.toISOString(), actor: input.actor, repo: ref.repo, taskId: ref.externalId, runId: input.runId, action: ADD_TESTS_ACTION, outcome: made.id, source: "request",
+            detail: `Filed ${made.id}` });
+        return made;
+    });
+    if (!filed.ok)
+        return refuse(filed.reason, filed.message);
+    return { ok: true, id: filed.id, existing: false };
+}
+function changedFilesOf(store, root, runId) {
+    const stat = store.artifactsFor(runId).find(one => one.kind === "diff-stat");
+    if (stat === undefined)
+        return [];
+    const read = readVerifiedArtifact(root, stat);
+    if (!read.ok)
+        return [];
+    try {
+        const parsed = JSON.parse(read.content.toString("utf8"));
+        return (parsed.files ?? []).map(one => one.path).filter((one) => typeof one === "string" && one.length < 300);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/retention-ui.d.ts

@@ -1,7 +1,9 @@
-import { type RetentionCount, type RetentionPeriods } from "./retention.js";
+import { type RetentionCount, type RetentionKind, type RetentionPeriods } from "./retention.js";
 export declare const RETENTION_CSS: string;
+/** `chosen`: the kinds someone chose a period for; the rest keep their default. */
 export type RetentionView = {
     periods: RetentionPeriods;
+    chosen: readonly RetentionKind[];
     next: RetentionCount[];
     lastSweep: string | null;
     csrf: string;

package/dist/retention-ui.js

@@ -4,7 +4,7 @@
  * take a step-up.
  */
 import { bytesWords } from "./storage.js";
-import { PERIOD_CHOICES, RETENTION_KINDS, countWords, periodWords } from "./retention.js";
+import { RETENTION_KINDS, countWords, periodChoices, periodLabel } from "./retention.js";
 const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 export const RETENTION_CSS = `.retention{max-width:720px;min-width:0}.retention-next{margin:0 0 16px}` +
     `.retention form{display:grid;gap:0}.retention .kind{display:grid;grid-template-columns:minmax(0,1fr) 11rem;gap:4px 16px;align-items:center;padding:12px 0;border-bottom:1px solid var(--border)}` +
@@ -26,8 +26,8 @@ export function retentionHtml(view, notice) {
     const note = notice.problem ? `<p class="problem" role="alert">${e(notice.problem)}</p>` : notice.said ? `<p role="status">${e(notice.said)}</p>` : "";
     const rows = RETENTION_KINDS.map(({ kind, label, detail }) => {
         const current = view.periods[kind];
-        const choices = PERIOD_CHOICES.includes(current) ? PERIOD_CHOICES : [...PERIOD_CHOICES.slice(0, -1), current, null].sort((a, b) => (a ?? Infinity) - (b ?? Infinity));
-        const options = choices.map(days => `<option value="${days === null ? "forever" : days}"${days === current ? " selected" : ""}>${days === null ? "Forever" : `${periodWords(days)[0].toUpperCase()}${periodWords(days).slice(1)}`}</option>`).join("");
+        const chosen = view.chosen.includes(kind);
+        const options = periodChoices(kind, current).map(days => `<option value="${days === null ? "forever" : days}"${days === current ? " selected" : ""}>${e(periodLabel(kind, days, chosen || days !== current))}</option>`).join("");
         return `<div class="kind" data-kind="${kind}"><label class="name" for="keep-${kind}">${e(label)}</label><p class="meta">${e(detail)}</p><select id="keep-${kind}" name="${kind}">${options}</select></div>`;
     }).join("");
     const last = view.lastSweep === null ? "" : ` Last sweep ${e(view.lastSweep.slice(0, 10))}.`;
@@ -35,5 +35,5 @@ export function retentionHtml(view, notice) {
         `<form method="post" action="/settings/retention"><input type="hidden" name="csrf" value="${e(view.csrf)}">${rows}` +
         `<label class="step-up">Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label>` +
         `<button type="submit">Save</button></form>` +
-        `<p class="meta">Never removed: the action ledger, and anything a task still needs (unfinished tasks, results not yet completed, anything on hold).</p></article>`;
+        `<p class="meta">Never removed: the action ledger, and anything a task still needs (unfinished tasks, results Ready for review, anything on hold).</p></article>`;
 }

package/dist/retention.d.ts

@@ -1,5 +1,8 @@
-import type { Store } from "./store.js";
-export declare const RETENTION_SCHEMA = "\nCREATE TABLE IF NOT EXISTS retention_setting (\n  kind       TEXT PRIMARY KEY CHECK (kind IN ('evidence', 'checkouts', 'chat', 'notifications')),\n  -- NULL is forever; a row only exists once someone chose.\n  days       INTEGER CHECK (days IS NULL OR (days >= 7 AND days <= 3650)),\n  updated_by TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n";
+import type { Database, Store } from "./store.js";
+export declare const RETENTION_SCHEMA: string;
+/** A file from before 1-day evidence keeps `days >= 7` in its CHECK: rebuild the table with the wider one, keeping
+ * every row, in one transaction. A file already widened is untouched. */
+export declare function widenRetentionSchema(db: Database): void;
 export type RetentionKind = "evidence" | "checkouts" | "chat" | "notifications";
 export type RetentionPeriods = Record<RetentionKind, number | null>;
 export declare const RETENTION_KINDS: readonly {
@@ -7,19 +10,23 @@ export declare const RETENTION_KINDS: readonly {
     label: string;
     detail: string;
 }[];
-/** The periods the page offers; the command line takes any number of days from 7 to 3650. */
-export declare const PERIOD_CHOICES: readonly (number | null)[];
-export declare const MIN_DAYS = 7;
+export declare const PERIOD_CHOICES: Readonly<Record<RetentionKind, readonly (number | null)[]>>;
+export declare const MIN_DAYS = 1;
 export declare const MAX_DAYS = 3650;
 /** A sweep is due once a day. */
 export declare const SWEEP_EVERY_MS = 86400000;
 /** At most this many runs, messages, notifications or records go per kind per sweep; the next sweep takes the rest. */
 export declare const SWEEP_BATCH = 2000;
-export declare const FOREVER: RetentionPeriods;
+/** What each kind keeps until someone chooses: evidence 28 days, everything else forever. */
+export declare const DEFAULT_PERIODS: RetentionPeriods;
 export declare function isRetentionKind(value: string): value is RetentionKind;
 /** "forever", or a number of days ("90", "90d"), weeks ("12w") or years ("1y"); undefined when it's none of those or out of range. */
 export declare function parsePeriod(text: string): number | null | undefined;
 export declare function periodWords(days: number | null): string;
+/** What the page offers for `kind`, with `current` among them (in order) when it was set some other way. */
+export declare function periodChoices(kind: RetentionKind, current: number | null): readonly (number | null)[];
+/** A period as the page and `retention show` say it: "28 days (default)" when nobody chose, "30 days (custom)" when it's not one the page offers. */
+export declare function periodLabel(kind: RetentionKind, days: number | null, chosen: boolean): string;
 export type RetentionCount = {
     kind: RetentionKind;
     days: number | null;

package/dist/retention.js

@@ -1,9 +1,10 @@
 /**
  * Retention (v105): how long Toolroll keeps run evidence and logs,
- * finished checkouts' records, chat messages and notifications. Each kind
- * keeps everything ("forever") until an instance operator chooses a period;
- * a daily sweep then deletes what is older than it and writes one action
- * ledger entry saying what went and about how much space it freed.
+ * finished checkouts' records, chat messages and notifications. Until an
+ * instance operator chooses a period, evidence is kept 28 days and every
+ * other kind forever; a daily sweep deletes what is older than its period
+ * and writes one action ledger entry saying what went and about how much
+ * space it freed.
  *
  * Never deleted, whatever the settings: the action ledger (it is append-only),
  * and anything a task still needs. A task still needs its things until it is
@@ -21,24 +22,47 @@ import { join } from "node:path";
 import { RETENTION_NOTE } from "./evidence.js";
 import { COMPLETION_ACTION } from "./result-completion.js";
 import { bytesWords, treeBytes } from "./storage.js";
-export const RETENTION_SCHEMA = `
-CREATE TABLE IF NOT EXISTS retention_setting (
+const RETENTION_TABLE = (name) => `
+CREATE TABLE IF NOT EXISTS ${name} (
   kind       TEXT PRIMARY KEY CHECK (kind IN ('evidence', 'checkouts', 'chat', 'notifications')),
   -- NULL is forever; a row only exists once someone chose.
-  days       INTEGER CHECK (days IS NULL OR (days >= 7 AND days <= 3650)),
+  days       INTEGER CHECK (days IS NULL OR (days >= 1 AND days <= 3650)),
   updated_by TEXT NOT NULL,
   updated_at TEXT NOT NULL
 );
 `;
+export const RETENTION_SCHEMA = RETENTION_TABLE("retention_setting");
+/** A file from before 1-day evidence keeps `days >= 7` in its CHECK: rebuild the table with the wider one, keeping
+ * every row, in one transaction. A file already widened is untouched. */
+export function widenRetentionSchema(db) {
+    const row = db.prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'retention_setting'").get();
+    if (row === undefined || !/days\s*>=\s*7\b/.test(String(row["sql"])))
+        return;
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        db.exec(RETENTION_TABLE("retention_setting_next"));
+        db.exec("INSERT INTO retention_setting_next (kind, days, updated_by, updated_at) SELECT kind, days, updated_by, updated_at FROM retention_setting");
+        db.exec("DROP TABLE retention_setting");
+        db.exec("ALTER TABLE retention_setting_next RENAME TO retention_setting");
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}
 export const RETENTION_KINDS = [
     { kind: "evidence", label: "Run evidence and logs", detail: "Diffs, check logs, screenshots and reports saved for each run" },
     { kind: "checkouts", label: "Finished checkout records", detail: "Records of build checkouts that were let go and are no longer on disk" },
     { kind: "chat", label: "Chat messages", detail: "Messages in lead and team chats" },
     { kind: "notifications", label: "Notifications", detail: "Delivered or dismissed notifications" },
 ];
-/** The periods the page offers; the command line takes any number of days from 7 to 3650. */
-export const PERIOD_CHOICES = [30, 90, 180, 365, 730, null];
-export const MIN_DAYS = 7;
+/** The periods the page offers for each kind; the command line takes any number of days from 1 to 3650. */
+const LONG_CHOICES = [30, 90, 180, 365, 730, null];
+export const PERIOD_CHOICES = {
+    evidence: [1, 7, 14, 28, null], checkouts: LONG_CHOICES, chat: LONG_CHOICES, notifications: LONG_CHOICES,
+};
+export const MIN_DAYS = 1;
 export const MAX_DAYS = 3650;
 const DAY_MS = 86_400_000;
 /** A sweep is due once a day. */
@@ -46,7 +70,8 @@ export const SWEEP_EVERY_MS = DAY_MS;
 /** At most this many runs, messages, notifications or records go per kind per sweep; the next sweep takes the rest. */
 export const SWEEP_BATCH = 2000;
 const SWEEP_CURSOR = "retention:last-sweep";
-export const FOREVER = { evidence: null, checkouts: null, chat: null, notifications: null };
+/** What each kind keeps until someone chooses: evidence 28 days, everything else forever. */
+export const DEFAULT_PERIODS = { evidence: 28, checkouts: null, chat: null, notifications: null };
 export function isRetentionKind(value) {
     return RETENTION_KINDS.some(one => one.kind === value);
 }
@@ -67,7 +92,20 @@ export function periodWords(days) {
         return "forever";
     if (days % 365 === 0)
         return days === 365 ? "1 year" : `${days / 365} years`;
-    return `${days} days`;
+    return days === 1 ? "1 day" : `${days} days`;
+}
+/** What the page offers for `kind`, with `current` among them (in order) when it was set some other way. */
+export function periodChoices(kind, current) {
+    const offered = PERIOD_CHOICES[kind];
+    return offered.includes(current) ? offered : [...offered, current].sort((a, b) => (a ?? Infinity) - (b ?? Infinity));
+}
+/** A period as the page and `retention show` say it: "28 days (default)" when nobody chose, "30 days (custom)" when it's not one the page offers. */
+export function periodLabel(kind, days, chosen) {
+    const words = periodWords(days);
+    const label = `${words[0].toUpperCase()}${words.slice(1)}`;
+    if (!chosen)
+        return `${label} (default)`;
+    return PERIOD_CHOICES[kind].includes(days) ? label : `${label} (custom)`;
 }
 /** Tasks that no longer need anything kept: cancelled, or done with their result marked complete; not on hold, not
  * running, not a release candidate, and no revision below it (at any depth) still unfinished — cancelled or completed,

package/dist/review-switch.d.ts

@@ -0,0 +1,41 @@
+/** The per-project automatic review switch and the one review each finished
+ * build gets (build-review.ts runs it): tables, and the read-only views every
+ * surface shows. No schema version bump. Kept free of heavy imports so the
+ * status readers can use it without an import cycle. */
+import type { Store } from "./store.js";
+export type FindingSeverity = "HIGH" | "MEDIUM" | "LOW";
+/** One automatic-review finding: how bad, where, and how it fails. */
+export type BuildFinding = {
+    severity: FindingSeverity;
+    file: string;
+    line: number;
+    scenario: string;
+};
+export declare const REVIEW_SCHEMA = "\n-- A project's explicit review switch. No row: on while the project is under a hands-off mode, off otherwise.\nCREATE TABLE IF NOT EXISTS review_switch (\n  repo        TEXT PRIMARY KEY,\n  enabled     INTEGER NOT NULL CHECK (enabled IN (0, 1)),\n  changed_by  TEXT NOT NULL,\n  changed_at  TEXT NOT NULL\n);\n-- One row per reviewed build run: pending until its one reviewer run settles it.\nCREATE TABLE IF NOT EXISTS build_review (\n  run           INTEGER PRIMARY KEY,\n  task_id       TEXT NOT NULL,\n  repo          TEXT NOT NULL,\n  state         TEXT NOT NULL CHECK (state IN ('pending', 'reviewed', 'not-reviewed')),\n  request       INTEGER,\n  reviewer_run  INTEGER,\n  findings_json TEXT,\n  reason        TEXT,\n  sent_back_as  TEXT,\n  queued_at     TEXT NOT NULL,\n  finished_at   TEXT\n);\nCREATE INDEX IF NOT EXISTS build_review_pending ON build_review (repo) WHERE state = 'pending';\nCREATE INDEX IF NOT EXISTS build_review_sent_back ON build_review (sent_back_as) WHERE sent_back_as IS NOT NULL;\n";
+export type ReviewSwitch = {
+    on: boolean;
+    source: "project" | "hands-off" | "default";
+    changedBy: string | null;
+    changedAt: string | null;
+};
+/** How the policy log words a switch state. */
+export declare function reviewSwitchWords(state: ReviewSwitch): string;
+export type BuildReviewView = {
+    run: number;
+    state: "pending" | "reviewed" | "not-reviewed";
+    reviewerRun: number | null;
+    /** Why it was not reviewed, in words. */
+    reason: string | null;
+    /** HIGH findings; they sent the task back when `sentBackAs` is set. */
+    high: BuildFinding[];
+    /** MEDIUM and LOW findings: suggested follow-ups, never blocking. */
+    followUps: BuildFinding[];
+    sentBackAs: string | null;
+    finishedAt: string | null;
+};
+export declare function buildReviewOf(store: Pick<Store, "handle">, runId: number): BuildReviewView | null;
+export declare const findingWords: (finding: BuildFinding) => string;
+/** The review's standing in one line, or null while nothing was asked. */
+export declare function buildReviewHeadline(view: BuildReviewView | null): string | null;
+/** Plain lines for `task show` and `assignment show`. */
+export declare function buildReviewLines(view: BuildReviewView | null): string[];