toolroll 0.8.1 → 0.9.0

package/dist/browser-workspace.d.ts

@@ -201,6 +201,11 @@ export type BrowserSettingsView = {
             removable: boolean;
         }[];
     } | null;
+    /** Quiet chat: how chats reach this person, and their evening digest time (null: off). */
+    chat?: {
+        mode: 'quiet' | 'all';
+        digestAt: string | null;
+    } | null;
     digest: {
         every: string;
         held: string | null;
@@ -327,6 +332,11 @@ export type BrowserProjectRow = {
     /** When it was last opened here; null for a project only seen in the queue. */
     openedAt: string | null;
     knowledgeHref: string;
+    /** Settings → Projects → Pull requests for this project, and whether they are on. */
+    pullRequests?: {
+        href: string;
+        on: boolean;
+    };
     /** What waits, runs, queues or finished today; null when not scanned. */
     peek: {
         label: string;

package/dist/chat-delivery.js

@@ -9,6 +9,7 @@ import { answerChatFlowPrompt, applyChatFlowTap, flowDecisionParts } from "./cha
 import { connectChannel, FLOW_WORDS, takeChannelMessage, watchedChannel } from "./chat-inbox.js";
 import { triggerConfigOf } from "./flow-triggers.js";
 import { telegramProgressCard } from "./telegram-progress.js";
+import { enqueueEveningDigests, isTaskFact, needsPerson, quietCardView, readyPingView } from "./chat-quiet.js";
 import { phoneText, PHONE_HELP, phoneCommand, phoneStatus, phoneTaskView, phoneTaskChoices, phoneTaskListText, resolvePhoneTask, phoneFocusText, PHONE_NO_MATCH, PHONE_BACK_TO_LEAD } from "./telegram-status.js";
 import { applyRoomInbound, conversationRow, roomCardApprover, roomCommand, roomGrantAllowed, roomMessagesAfter, roomMessageText, teamDomain } from "./chat-rooms.js";
 import { isTelegramProgressNotification, proposalTaskOf } from "./store.js";
@@ -574,6 +575,33 @@ export async function planRoomMessages(options) {
         }
     }
 }
+/** Quiet mode: the task's one card (or its group's) in this person's chat, planned once and then repainted in
+ * place whenever what it says changes. */
+function planQuietCard(options, binding, notification, now) {
+    const { state, store, identity } = options;
+    if (notification.taskRef === null || notification.taskId === null)
+        return;
+    const card = store.chatCardFor(`${state.channel}:${binding.id}`, notification.taskRef, store.getTask(notification.taskId)?.createdAt ?? notification.createdAt, now);
+    const view = quietCardView(store, card.tasks, now, options.evidenceRoot);
+    if (view === null)
+        return;
+    const content = { text: view.text, link: view.link, ...(card.tasks.length === 1 ? { task: notification.taskId } : {}) };
+    const shown = chatHash(JSON.stringify(content));
+    if (card.message !== null) {
+        if (card.digest === shown)
+            return;
+        state.prepare("UPDATE chat_part SET payload=?,state='pending',created=?,next_at=NULL WHERE id=? AND state!='dropped'").run(JSON.stringify(content), now.toISOString(), Number(card.message));
+        store.setChatCardMessage(card.id, card.message, shown);
+        return;
+    }
+    const id = chatHash(`${state.channel}:card:${binding.id}:${card.id}`);
+    state.enqueue({ id, installation: identity.installation, binding: binding.id, kind: "notice", channel: binding.channel, member: binding.member,
+        ts: "", thread: "", payload: "{}", created: now.toISOString() });
+    state.plan(id, [content], now);
+    const part = state.prepare("SELECT id FROM chat_part WHERE event=?").get(id);
+    if (part !== undefined)
+        store.setChatCardMessage(card.id, String(part.id), shown);
+}
 /** One progress card per exact result; separate urgent facts retain their own review link. */
 export async function planChatNotifications(options) {
     const state = options.state, { store, identity } = options, bindings = state.bindings(identity.installation).filter(one => state.live(one));
@@ -582,6 +610,11 @@ export async function planChatNotifications(options) {
         !options.current())
         return;
     const registry = await options.readProjects();
+    // An evening digest someone asked for is due: record it as their own notification, delivered below.
+    try {
+        enqueueEveningDigests(store, nowOf(options), options.evidenceRoot);
+    }
+    catch { /* Retried on the next pass. */ }
     const cursor = Number(state
         .prepare("SELECT notification FROM chat_runtime WHERE installation=?")
         .get(identity.installation)?.notification ?? 0);
@@ -602,7 +635,22 @@ export async function planChatNotifications(options) {
                         : (notification.taskId || notification.kind === "flow-decision") && notification.project !== null && repos.includes(notification.project))) {
                     const run = store.telegramProgressRun(notification);
                     const id = chatHash(`${options.state.channel}:notice:${binding.id}:${notification.id}`), now = nowOf(options);
-                    if (run && notification.taskId && notification.project !== null && isTelegramProgressNotification(notification)) {
+                    // Only when I'm needed (the default): the task's one card is edited in place, and a new message
+                    // follows only when this person is needed. Every step keeps the branches below unchanged.
+                    const quiet = !personal && isTaskFact(notification) && store.notificationPreference(binding.approver).mode === "quiet";
+                    if (quiet) {
+                        planQuietCard(options, binding, notification, now);
+                        if (!needsPerson(notification))
+                            return;
+                        if (notification.kind === "run-finished" && run) {
+                            const ping = readyPingView(store, store.getRun(run.id), notification.taskId, notification.project, now, options.evidenceRoot);
+                            state.enqueue({ id, installation: identity.installation, binding: binding.id, kind: "notice", channel: binding.channel, member: binding.member,
+                                ts: "", thread: "", payload: "{}", created: now.toISOString() });
+                            state.plan(id, [{ text: ping.text, task: notification.taskId, run: run.id, link: ping.link }], now);
+                            return;
+                        }
+                    }
+                    if (!quiet && run && notification.taskId && notification.project !== null && isTelegramProgressNotification(notification)) {
                         const card = telegramProgressCard(store, store.getRun(run.id), notification.taskId, notification.project, now, options.evidenceRoot);
                         const content = {
                             text: card.text,
@@ -661,7 +709,7 @@ export async function planChatNotifications(options) {
                             ts: "", thread: "", payload: "{}", created: now.toISOString() });
                         state.plan(id, questionParts(store, notification, binding), now);
                     }
-                    else if (notification.pushClass !== null || personal) {
+                    else if (notification.pushClass !== null || personal || quiet) {
                         state.enqueue({
                             id,
                             installation: identity.installation,
@@ -680,7 +728,7 @@ export async function planChatNotifications(options) {
                                 ...(notification.taskId ? { task: notification.taskId } : {}),
                                 ...(run ? { run: run.id } : {}),
                                 ...(notification.link
-                                    ? { link: { label: personal ? "Open" : "Review", path: notification.link } }
+                                    ? { link: { label: notification.kind === "pull-request-ready" ? "Merge" : personal ? "Open" : "Review", path: notification.link } }
                                     : {}),
                             },
                         ], now);

package/dist/chat-quiet.d.ts

@@ -0,0 +1,28 @@
+import { type ProgressEntity } from "./telegram-progress.js";
+import { type PhoneTaskLink } from "./telegram-status.js";
+import { type Notification, type Run, type Store } from "./store.js";
+export type QuietView = {
+    text: string;
+    entities: ProgressEntity[];
+    link: PhoneTaskLink;
+};
+export declare function needsPerson(row: Pick<Notification, "dedupeKey" | "kind" | "pushClass" | "recipient">): boolean;
+/** A fact about one placed task: in quiet mode it lands on that task's card. */
+export declare function isTaskFact(row: Pick<Notification, "taskRef" | "taskId" | "project">): row is typeof row & {
+    taskRef: number;
+    taskId: string;
+    project: string;
+};
+/** The card's words now: one task's progress card, or one line per task when several were filed together. */
+export declare function quietCardView(store: Store, taskRefs: readonly number[], now: Date, root?: string): QuietView | null;
+/** The one ping for a Ready result: its state and title, what to do next, and a link to that exact result. */
+export declare function readyPingView(store: Store, run: Run, taskId: string, project: string, now: Date, root?: string): QuietView;
+/** This computer's local day and time, which is what a person means by "the evening". */
+export declare function localDay(now: Date): string;
+export declare function localTime(now: Date): string;
+/** One person's evening: what finished and what failed in the last day, and what waits for them now. Null when
+ * nothing happened, so a quiet day sends nothing. */
+export declare function eveningDigestText(store: Store, account: string, now: Date, root?: string): string | null;
+/** Record each due evening digest once per person per local day, as one notification addressed to that person:
+ * every chat they paired delivers it with the usual receipts, and the console keeps it. */
+export declare function enqueueEveningDigests(store: Store, now: Date, root?: string): number;

package/dist/chat-quiet.js

@@ -0,0 +1,161 @@
+/** Quiet chat: a task's whole life is one chat message edited in place, and a
+ * new message arrives only when a person is needed. Every transport (Telegram,
+ * Slack, Discord, Teams) asks the same questions here: does this fact need a
+ * person, what does the task's card say now, and what does the Ready ping say.
+ * Delivery receipts, claims and retries stay with each transport; the
+ * console's activity keeps every fact whatever a chat showed. */
+import { assignmentOf } from "./assignment.js";
+import { chatControlHref } from "./chat-controls.js";
+import { telegramProgressCard } from "./telegram-progress.js";
+import { phoneText, projectLabel } from "./telegram-status.js";
+import { isLifecycleNotification } from "./store.js";
+/** What always makes a new message, even in quiet mode: a question or approval waiting, a failure or other
+ * attention fact, a result Ready for review, a security alert or release, and anything addressed to one person
+ * (a sign-in or plan-limit pause, an evening digest). */
+const NEEDED_KINDS = new Set([
+    "acceptance-ready", "acceptance-evidence", "flow-decision", "flow-card", "plan-ready", "report-ready",
+    "stale-approval", "security-release", "secret-detected",
+]);
+export function needsPerson(row) {
+    if (row.recipient !== null)
+        return true;
+    if (/^decision:\d+$/.test(row.dedupeKey))
+        return true;
+    if (row.pushClass !== null && row.pushClass !== "progress")
+        return true;
+    if (NEEDED_KINDS.has(row.kind))
+        return true;
+    // A built or unchanged result is Ready: the one lifecycle step that asks for a person.
+    return isLifecycleNotification(row) && row.kind === "run-finished";
+}
+/** A fact about one placed task: in quiet mode it lands on that task's card. */
+export function isTaskFact(row) {
+    return row.taskRef !== null && row.taskId !== null && row.project !== null;
+}
+/** The attempt a task's card follows: its newest builder attempt, outside any contest. */
+function cardRun(store, taskRef) {
+    return store.runsFor(taskRef).find(run => run.role === "builder" && run.contestant === null) ?? null;
+}
+/** Before any attempt starts, the card says where the task stands in the words of its last lifecycle fact. */
+const BEFORE_RUN = {
+    "task-filed": { icon: "📝", status: "Filed" },
+    "scope-approved": { icon: "✓", status: "Approved · Waiting to start" },
+    "approval-withdrawn": { icon: "📝", status: "Approval withdrawn" },
+    "task-held": { icon: "⏸", status: "Paused" },
+    "task-released": { icon: "✓", status: "Waiting to start" },
+    "task-queued": { icon: "✓", status: "Waiting to start" },
+    "task-requeued": { icon: "✓", status: "Waiting to start" },
+    "task-cancelled": { icon: "⏹", status: "Cancelled" },
+};
+function taskLine(store, taskRef, now, root) {
+    const ref = store.refById(taskRef);
+    if (ref === null || ref.repo === null)
+        return null;
+    const task = store.getTask(ref.externalId);
+    const title = phoneText(task?.title ?? ref.externalId, 88);
+    const run = cardRun(store, taskRef);
+    if (run !== null) {
+        const view = telegramProgressCard(store, run, ref.externalId, ref.repo, now, root);
+        const heading = view.entities[1] === undefined ? "" : view.text.slice(view.entities[1].offset, view.entities[1].offset + view.entities[1].length);
+        const split = heading.indexOf(" ");
+        return { title, icon: heading.slice(0, split), status: heading.slice(split + 1), project: ref.repo, view };
+    }
+    const fact = store.latestTaskFact(taskRef);
+    const words = task?.state === "cancelled" ? BEFORE_RUN["task-cancelled"] : BEFORE_RUN[fact?.kind ?? ""] ?? BEFORE_RUN["task-filed"];
+    const heading = `${words.icon} ${words.status}`;
+    const text = [title, heading, "", `${projectLabel(ref.repo)} · ${ref.externalId}`].join("\n");
+    return { title, icon: words.icon, status: words.status, project: ref.repo, view: {
+            text, entities: [{ type: "bold", offset: 0, length: title.length }, { type: "bold", offset: title.length + 1, length: heading.length }],
+            link: { label: "Open task", path: chatControlHref("task", ref.externalId) },
+        } };
+}
+/** The card's words now: one task's progress card, or one line per task when several were filed together. */
+export function quietCardView(store, taskRefs, now, root) {
+    const lines = taskRefs.map(ref => taskLine(store, ref, now, root)).filter((one) => one !== null);
+    if (lines.length === 0)
+        return null;
+    if (lines.length === 1)
+        return lines[0].view;
+    const heading = `${lines.length} tasks`;
+    const projects = [...new Set(lines.map(one => projectLabel(one.project)))];
+    const text = [heading, ...lines.map(one => `${one.icon} ${phoneText(one.title, 60)} · ${one.status}`), "", projects.join(", ")].join("\n");
+    return { text, entities: [{ type: "bold", offset: 0, length: heading.length }], link: { label: "Open tasks", path: "/tasks" } };
+}
+/** The one ping for a Ready result: its state and title, what to do next, and a link to that exact result. */
+export function readyPingView(store, run, taskId, project, now, root) {
+    const card = telegramProgressCard(store, run, taskId, project, now, root);
+    const [title = "", shown = ""] = card.entities.map(one => card.text.slice(one.offset, one.offset + one.length));
+    // A saved result is Ready even in the moment before its worker lets go of the task.
+    const saved = shown.endsWith(" Result saved");
+    const heading = saved ? "✅ Ready" : shown;
+    const next = card.next !== "" ? card.next : saved ? "Next: open the result, then mark it complete or request changes." : "";
+    const first = `${heading} · ${title}`;
+    return { text: next === "" ? first : `${first}\n${next}`, entities: [{ type: "bold", offset: 0, length: heading.length }], link: card.link };
+}
+// ---- the evening digest ----------------------------------------------------------
+const FAILURE = /fail|exhausted|fenced/;
+const pad = (n) => String(n).padStart(2, "0");
+/** This computer's local day and time, which is what a person means by "the evening". */
+export function localDay(now) {
+    return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+export function localTime(now) {
+    return `${pad(now.getHours())}:${pad(now.getMinutes())}`;
+}
+/** One person's evening: what finished and what failed in the last day, and what waits for them now. Null when
+ * nothing happened, so a quiet day sends nothing. */
+export function eveningDigestText(store, account, now, root) {
+    const since = new Date(now.getTime() - 86_400_000).toISOString();
+    const recent = new Date(now.getTime() - 14 * 86_400_000).toISOString();
+    const visible = (row) => row.project !== null && store.accountCanAccess(account, row.project);
+    const title = (taskId) => phoneText(store.getTask(taskId)?.title ?? taskId, 80);
+    const finished = new Map(), failed = new Map(), waits = new Map();
+    const facts = store.taskFactsSince(recent).filter(visible);
+    for (const row of facts) {
+        if (row.createdAt < since || row.taskId === null)
+            continue;
+        if (isLifecycleNotification(row) && row.kind === "run-finished")
+            finished.set(row.taskId, title(row.taskId));
+        else if (FAILURE.test(row.kind))
+            failed.set(row.taskId, title(row.taskId));
+    }
+    for (const taskId of new Set(facts.map(row => row.taskId).filter((one) => one !== null))) {
+        let state = null;
+        try {
+            const project = facts.find(row => row.taskId === taskId).project;
+            state = assignmentOf(store, taskId, now, { principal: "operator", repos: [project] }, root)?.state ?? null;
+        }
+        catch {
+            state = null;
+        }
+        if (state === "ready-to-check")
+            waits.set(taskId, `${title(taskId)} · Ready for review`);
+        else if (state === "needs-decision")
+            waits.set(taskId, `${title(taskId)} · Needs your decision`);
+    }
+    if (finished.size + failed.size + waits.size === 0)
+        return null;
+    const section = (name, items) => items.size === 0 ? [] : ["", `${name} (${items.size})`, ...[...items.values()].slice(0, 12).map(one => `• ${one}`), ...(items.size > 12 ? [`• and ${items.size - 12} more`] : [])];
+    return [...section("Finished", finished), ...section("Waiting for you", waits), ...section("Failed", failed)].slice(1).join("\n");
+}
+/** Record each due evening digest once per person per local day, as one notification addressed to that person:
+ * every chat they paired delivers it with the usual receipts, and the console keeps it. */
+export function enqueueEveningDigests(store, now, root) {
+    const day = localDay(now), time = localTime(now);
+    let queued = 0;
+    for (const person of store.eveningDigestPeople()) {
+        if (person.digestAt > time || (person.digestOn !== null && person.digestOn >= day))
+            continue;
+        store.transact(() => {
+            if (!store.claimEveningDigestDay(person.account, day))
+                return;
+            const body = eveningDigestText(store, person.account, now, root);
+            if (body === null)
+                return;
+            if (store.enqueueNotification({ dedupeKey: `digest:evening:${person.account}:${day}`, kind: "evening-digest", subject: "Evening digest", body,
+                link: "/tasks", source: { installation: true }, recipient: person.account }, now))
+                queued++;
+        });
+    }
+    return queued;
+}

package/dist/checkout-cleanup.d.ts

@@ -0,0 +1,84 @@
+import { type CheckoutCleanup } from "./storage.js";
+import type { Store } from "./store.js";
+import { type WorktreePool } from "./worktree.js";
+/** A release candidate's checkout holds the build a deploy installs: kept a week after its task was done. */
+export declare const CANDIDATE_KEEP_MS: number;
+/** The worker's pass removes at most this many; a clean-up by hand has no cap. */
+export declare const AUTO_MAX = 20;
+export type KeepWhy = "in use" | "task not finished" | "waiting for review" | "release candidate" | "has changes" | "has commits" | "unreadable" | "git refused" | "not due yet" | "cleanup is off" | "no task";
+export type CheckoutItem = {
+    path: string;
+    repo: string;
+    branch: string;
+    taskId: string | null;
+    bytes: number;
+    releasedAt: string | null;
+    /** null: it goes. */
+    why: KeepWhy | null;
+    /** With "not due yet" or "release candidate": when it may go. */
+    dueAt?: string;
+};
+export type CheckoutPlan = {
+    at: string;
+    cleanup: CheckoutCleanup;
+    manual: boolean;
+    go: CheckoutItem[];
+    stay: CheckoutItem[];
+    /** Every checkout on disk. */
+    count: number;
+    totalBytes: number;
+    freeBytes: number;
+    waitingReview: number;
+    withChanges: number;
+};
+type Status = {
+    keep: KeepWhy | null;
+    taskId: string;
+    finishedAt: string | null;
+    dueAt?: string;
+};
+/** Where every task stands for cleanup, by task_ref id and by each branch it or its runs used. */
+export declare function taskStatuses(store: Store, now: Date): {
+    byRef: Map<number, Status>;
+    byBranch: Map<string, Status>;
+};
+/**
+ * What a clean-up would remove now, how much space it would free, and what stays and why. `manual` is a clean-up by
+ * hand (it doesn't wait for the setting); otherwise it is the worker's pass under the setting. Reads only.
+ */
+export declare function checkoutPlan(store: Store, pool: WorktreePool, now: Date, options: {
+    manual: boolean;
+    repo?: string;
+}): Promise<CheckoutPlan>;
+/** Names exactly what a preview would remove, so a confirmation removes that and nothing else. */
+export declare function previewDigest(plan: Pick<CheckoutPlan, "go">): string;
+export type CleanResult = {
+    removed: CheckoutItem[];
+    kept: {
+        path: string;
+        why: KeepWhy;
+    }[];
+    freed: number;
+};
+/**
+ * Remove what may go: the worker's pass (`manual` false: under the setting, at most AUTO_MAX, one repository) or a
+ * clean-up by hand (no cap, every repository). Each checkout is asked again right before it goes; each removal is in
+ * the ledger.
+ */
+export declare function cleanCheckouts(store: Store, pool: WorktreePool, now: () => Date, options: {
+    manual: boolean;
+    actor: string;
+    repo?: string;
+    only?: ReadonlySet<string>;
+}): Promise<CleanResult>;
+/** Throw away a checkout kept for its changes, on purpose; its branch stays. In the ledger. */
+export declare function discardCheckout(store: Store, pool: WorktreePool, path: string, now: Date, actor: string): Promise<{
+    ok: true;
+    bytes: number;
+} | {
+    ok: false;
+    message: string;
+}>;
+/** "Waiting for review", "Has changes" … as a sentence fragment for a person. */
+export declare function whyWords(item: Pick<CheckoutItem, "why" | "dueAt">): string;
+export {};

package/dist/checkout-cleanup.js

@@ -0,0 +1,245 @@
+/**
+ * Checkout cleanup (Settings → Storage, `toolroll storage clean`): which task checkouts can go, and removing them.
+ *
+ * A finished task's clean checkout goes as the setting says: when its task is complete or cancelled (the default),
+ * 2 days or a week after that, or never (only a clean-up by hand). A clean-up by hand doesn't wait for the setting.
+ * Only the working copy goes: its branch, and so every commit, stays, and a later lease of the branch makes a new one.
+ *
+ * Always kept: a checkout in use, one whose task isn't finished (on hold, failed, a revision under way), a result
+ * still waiting for review, a release candidate for a week after it was done (a deploy installs from it), a checkout
+ * with changes (files Toolroll wrote itself aside), and one with commits on no branch. A checkout no task names
+ * (adopted after a crash) goes only in a clean-up by hand. Every removal is in the ledger.
+ */
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { basename } from "node:path";
+import { taskBranches } from "./names.js";
+import { COMPLETION_ACTION } from "./result-completion.js";
+import { CLEANUP_CHOICES, bytesWords, diskBytes } from "./storage.js";
+import { worktreePath } from "./worktree.js";
+const DAY_MS = 86_400_000;
+/** A release candidate's checkout holds the build a deploy installs: kept a week after its task was done. */
+export const CANDIDATE_KEEP_MS = 7 * DAY_MS;
+/** The worker's pass removes at most this many; a clean-up by hand has no cap. */
+export const AUTO_MAX = 20;
+/** Git inspections at once. */
+const INSPECT_AT_ONCE = 8;
+const STRENGTH = { "in use": 5, "task not finished": 4, "waiting for review": 3, "release candidate": 2 };
+const strength = (one) => one === undefined ? -1 : one.keep === null ? 0 : STRENGTH[one.keep] ?? 1;
+const stronger = (a, b) => strength(b) > strength(a) || (strength(b) === 0 && strength(a) === 0 && (b.finishedAt ?? "") > (a.finishedAt ?? "")) ? b : a;
+/** Where every task stands for cleanup, by task_ref id and by each branch it or its runs used. */
+export function taskStatuses(store, now) {
+    const db = store.handle;
+    const refs = db.prepare(`SELECT r.id AS ref, r.external_id AS id, r.revision_of AS revision_of, t.state AS state, t.updated_at AS updated_at,
+      EXISTS (SELECT 1 FROM hold h WHERE h.task_ref = r.id) AS held,
+      EXISTS (SELECT 1 FROM run live WHERE live.task_ref = r.id AND live.finished_at IS NULL) AS live,
+      EXISTS (SELECT 1 FROM task_scope s WHERE s.task_id = r.external_id AND s.candidate IS NOT NULL) AS candidate
+    FROM task_ref r LEFT JOIN task t ON t.id = r.external_id AND r.backend = 'built-in'`).all();
+    const runs = db.prepare("SELECT id, task_ref, branch FROM run").all();
+    const refOfRun = new Map(runs.map(row => [Number(row["id"]), Number(row["task_ref"])]));
+    // The completion names its family's root; its run names the result it completes.
+    const completed = new Map();
+    const completedRef = new Map();
+    for (const row of db.prepare("SELECT task_id, run_id, at FROM action_ledger WHERE action = ?").all(COMPLETION_ACTION)) {
+        const at = String(row["at"]);
+        if (row["task_id"] !== null) {
+            const id = String(row["task_id"]);
+            if ((completed.get(id) ?? "") < at)
+                completed.set(id, at);
+        }
+        const ref = row["run_id"] === null ? undefined : refOfRun.get(Number(row["run_id"]));
+        if (ref !== undefined && (completedRef.get(ref) ?? "") < at)
+            completedRef.set(ref, at);
+    }
+    const byRef = new Map();
+    const byId = new Map();
+    const parentOf = new Map();
+    for (const row of refs) {
+        const ref = Number(row["ref"]);
+        const id = String(row["id"]);
+        const state = row["state"] === null ? null : String(row["state"]);
+        const updated = row["updated_at"] === null ? null : String(row["updated_at"]);
+        let status;
+        if (Number(row["live"]) === 1)
+            status = { keep: "in use", taskId: id, finishedAt: null };
+        else if (state === null || Number(row["held"]) === 1 || (state !== "done" && state !== "cancelled"))
+            status = { keep: "task not finished", taskId: id, finishedAt: null };
+        else if (state === "cancelled")
+            status = { keep: null, taskId: id, finishedAt: updated };
+        else {
+            const completedAt = [completed.get(id), completedRef.get(ref)].filter((one) => one !== undefined).sort().at(-1) ?? null;
+            if (Number(row["candidate"]) === 1) {
+                const since = completedAt ?? updated ?? now.toISOString();
+                const until = new Date(Date.parse(since) + CANDIDATE_KEEP_MS).toISOString();
+                status = until > now.toISOString() ? { keep: "release candidate", taskId: id, finishedAt: since, dueAt: until } : { keep: null, taskId: id, finishedAt: since };
+            }
+            else
+                status = completedAt === null ? { keep: "waiting for review", taskId: id, finishedAt: null } : { keep: null, taskId: id, finishedAt: completedAt };
+        }
+        byRef.set(ref, status);
+        byId.set(id, stronger(byId.get(id), status));
+        if (row["revision_of"] !== null)
+            parentOf.set(id, String(row["revision_of"]));
+    }
+    // A revision under way keeps what its ancestors worked on: it builds on their branch.
+    for (const [id, status] of byId) {
+        if (status.keep === null || status.keep === "release candidate")
+            continue;
+        const seen = new Set([id]);
+        for (let parent = parentOf.get(id); parent !== undefined && !seen.has(parent); parent = parentOf.get(parent)) {
+            seen.add(parent);
+            const lifted = { ...status, taskId: parent };
+            byId.set(parent, stronger(byId.get(parent), lifted));
+        }
+    }
+    for (const row of refs)
+        byRef.set(Number(row["ref"]), stronger(byRef.get(Number(row["ref"])), { ...byId.get(String(row["id"])), taskId: String(row["id"]) }));
+    const byBranch = new Map();
+    const note = (branch, status) => byBranch.set(branch, stronger(byBranch.get(branch), status));
+    for (const row of refs)
+        for (const branch of taskBranches(String(row["id"])))
+            note(branch, byRef.get(Number(row["ref"])));
+    for (const row of runs) {
+        if (row["branch"] === null)
+            continue;
+        const status = byRef.get(Number(row["task_ref"]));
+        if (status !== undefined)
+            note(String(row["branch"]), status);
+    }
+    return { byRef, byBranch };
+}
+/** Where one checkout's task stands: by its task, its branch, or (branch unknown) the name a lease of a branch would give it. */
+function statusOf(row, statuses) {
+    let found = stronger(row.taskRef === null ? undefined : statuses.byRef.get(row.taskRef), statuses.byBranch.get(row.branch));
+    if (found === undefined) {
+        const name = basename(row.path);
+        for (const [branch, status] of statuses.byBranch)
+            if (basename(worktreePath("/", row.repo, branch)) === name)
+                found = stronger(found, status);
+    }
+    return found;
+}
+/** Why a checkout stays before anyone looks at its files, or null: it may go (as far as its task and the setting say). */
+function keptFor(pool, row, statuses, now, cleanup) {
+    const status = statusOf(row, statuses);
+    const taskId = status?.taskId ?? null;
+    if (row.releasedAt === null || row.runner !== null || pool.inUse(row.path).held)
+        return { why: "in use", taskId };
+    if (status !== undefined && status.keep !== null)
+        return { why: status.keep, taskId, ...(status.dueAt === undefined ? {} : { dueAt: status.dueAt }) };
+    if (cleanup === "manual")
+        return { why: null, taskId };
+    // A checkout no task names (adopted after a crash, say) has no task to finish: only a clean-up by hand takes it.
+    if (status === undefined)
+        return { why: "no task", taskId };
+    if (cleanup === "finished")
+        return { why: null, taskId };
+    if (cleanup === "never")
+        return { why: "cleanup is off", taskId };
+    const days = CLEANUP_CHOICES.find(one => one.value === cleanup).days;
+    const since = [status.finishedAt, row.releasedAt].filter((one) => one !== null).sort().at(-1);
+    const dueAt = new Date(Date.parse(since) + days * DAY_MS).toISOString();
+    return dueAt > now.toISOString() ? { why: "not due yet", taskId, dueAt } : { why: null, taskId };
+}
+async function eachAtMost(items, limit, work) {
+    const out = new Array(items.length);
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (next < items.length) {
+            const at = next++;
+            out[at] = await work(items[at]);
+        }
+    }));
+    return out;
+}
+/**
+ * What a clean-up would remove now, how much space it would free, and what stays and why. `manual` is a clean-up by
+ * hand (it doesn't wait for the setting); otherwise it is the worker's pass under the setting. Reads only.
+ */
+export async function checkoutPlan(store, pool, now, options) {
+    const cleanup = store.checkoutCleanup();
+    const rows = store.listWorktrees().filter(row => existsSync(row.path) && (options.repo === undefined || row.repo === options.repo));
+    const sizes = diskBytes(rows.map(row => row.path));
+    const statuses = taskStatuses(store, now);
+    const items = await eachAtMost(rows, INSPECT_AT_ONCE, async (row) => {
+        const kept = keptFor(pool, row, statuses, now, options.manual ? "manual" : cleanup);
+        let why = kept.why;
+        if (why === null) {
+            const found = await pool.inspect(row.path);
+            why = found === "clean" ? null : found;
+        }
+        return { path: row.path, repo: row.repo, branch: row.branch, taskId: kept.taskId, bytes: sizes.get(row.path) ?? 0, releasedAt: row.releasedAt, why, ...(kept.dueAt === undefined ? {} : { dueAt: kept.dueAt }) };
+    });
+    const go = items.filter(one => one.why === null).sort((a, b) => b.bytes - a.bytes);
+    const stay = items.filter(one => one.why !== null).sort((a, b) => (a.why ?? "").localeCompare(b.why ?? "") || b.bytes - a.bytes);
+    return {
+        at: now.toISOString(), cleanup, manual: options.manual, go, stay,
+        count: items.length, totalBytes: items.reduce((sum, one) => sum + one.bytes, 0), freeBytes: go.reduce((sum, one) => sum + one.bytes, 0),
+        waitingReview: stay.filter(one => one.why === "waiting for review").length, withChanges: stay.filter(one => one.why === "has changes").length,
+    };
+}
+/** Names exactly what a preview would remove, so a confirmation removes that and nothing else. */
+export function previewDigest(plan) {
+    return createHash("sha256").update(plan.go.map(one => one.path).sort().join("\u0000"), "utf8").digest("hex").slice(0, 32);
+}
+/**
+ * Remove what may go: the worker's pass (`manual` false: under the setting, at most AUTO_MAX, one repository) or a
+ * clean-up by hand (no cap, every repository). Each checkout is asked again right before it goes; each removal is in
+ * the ledger.
+ */
+export async function cleanCheckouts(store, pool, now, options) {
+    const cleanup = store.checkoutCleanup();
+    if (!options.manual && cleanup === "never")
+        return { removed: [], kept: [], freed: 0 };
+    // `only`: the checkouts a person saw in the preview; nothing they didn't see goes.
+    const rows = store.listWorktrees().filter(row => existsSync(row.path) && (options.repo === undefined || row.repo === options.repo) && (options.only === undefined || options.only.has(row.path)));
+    let statuses = taskStatuses(store, now());
+    const sizes = new Map();
+    const wanted = (row, fresh) => {
+        // Right before a checkout goes, where its task stands is read afresh, and its size taken for the ledger.
+        if (fresh)
+            statuses = taskStatuses(store, now());
+        const go = keptFor(pool, row, statuses, now(), options.manual ? "manual" : cleanup).why === null;
+        if (go && fresh)
+            sizes.set(row.path, diskBytes([row.path]).get(row.path) ?? 0);
+        return go;
+    };
+    const pruned = await pool.prune(rows, wanted, options.manual ? Infinity : AUTO_MAX);
+    const removed = [];
+    for (const row of pruned.removed) {
+        const taskId = row.taskRef === null ? null : store.externalIdFor(row.taskRef);
+        const bytes = sizes.get(row.path) ?? 0;
+        removed.push({ path: row.path, repo: row.repo, branch: row.branch, taskId, bytes, releasedAt: row.releasedAt, why: null });
+        store.recordAction({ at: now().toISOString(), actor: options.actor, repo: row.repo, taskId, runId: null, action: "checkout removed", outcome: "removed",
+            source: options.manual ? "request" : "work", detail: `${basename(row.path)} (released ${row.releasedAt?.slice(0, 10) ?? "?"}, about ${bytesWords(bytes)}); branch ${row.branch} kept` });
+    }
+    return { removed, kept: pruned.kept, freed: removed.reduce((sum, one) => sum + one.bytes, 0) };
+}
+/** Throw away a checkout kept for its changes, on purpose; its branch stays. In the ledger. */
+export async function discardCheckout(store, pool, path, now, actor) {
+    const bytes = existsSync(path) ? diskBytes([path]).get(path) ?? 0 : 0;
+    const done = await pool.discardChanges(path);
+    if (!done.ok)
+        return done;
+    const taskId = done.row.taskRef === null ? null : store.externalIdFor(done.row.taskRef);
+    store.recordAction({ at: now.toISOString(), actor, repo: done.row.repo, taskId, runId: null, action: "checkout discarded", outcome: "removed", source: "request",
+        detail: `${basename(path)} and its uncommitted changes (about ${bytesWords(bytes)}); branch ${done.row.branch} kept` });
+    return { ok: true, bytes };
+}
+/** "Waiting for review", "Has changes" … as a sentence fragment for a person. */
+export function whyWords(item) {
+    switch (item.why) {
+        case null: return "goes";
+        case "in use": return "in use";
+        case "task not finished": return "its task isn't finished";
+        case "waiting for review": return "its result is waiting for review";
+        case "release candidate": return `release candidate, kept until ${item.dueAt?.slice(0, 10) ?? "a week after"}`;
+        case "has changes": return "has changes";
+        case "has commits": return "has commits on no branch";
+        case "unreadable": return "git couldn't read it";
+        case "git refused": return "git wouldn't remove it";
+        case "not due yet": return `due ${item.dueAt?.slice(0, 10) ?? "later"}`;
+        case "cleanup is off": return "automatic cleanup is off";
+        case "no task": return "no task names it; only a clean-up by hand removes it";
+    }
+}