toolroll 0.8.1 → 0.8.2

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";
+    }
+}

package/dist/first-run.d.ts

@@ -9,14 +9,17 @@ export type FirstRunAction = {
     kind: "command";
     command: string;
 };
+/** `checking`: the answer is not in yet, so the step is shown neither done nor to do. */
 export type FirstRunStep = {
     key: "agent" | "project" | "task";
     title: string;
     done: boolean;
     action: FirstRunAction | null;
+    checking?: true;
 };
+/** agentSignedIn is null until this machine's first sign-in check has answered. */
 export type FirstRunFacts = {
-    agentSignedIn: boolean;
+    agentSignedIn: boolean | null;
     projects: number;
     hasTask: boolean;
     firstResultAt: string | null;

package/dist/first-run.js

@@ -15,7 +15,8 @@ export function firstRunSteps(facts) {
         return null;
     const project = facts.projects > 0;
     return [
-        { key: "agent", title: "Agent signed in", done: facts.agentSignedIn, action: facts.agentSignedIn ? null : { kind: "command", command: SIGN_IN_COMMAND } },
+        facts.agentSignedIn === null ? { key: "agent", title: "Agent signed in", done: false, action: null, checking: true }
+            : { key: "agent", title: "Agent signed in", done: facts.agentSignedIn, action: facts.agentSignedIn ? null : { kind: "command", command: SIGN_IN_COMMAND } },
         { key: "project", title: "Project added", done: project, action: project ? null : { kind: "link", label: "Add a project", href: "/projects" } },
         { key: "task", title: "Your first task", done: facts.hasTask, action: facts.hasTask ? null : { kind: "link", label: "New task", href: "/tasks/new" } },
     ];

package/dist/mcp.js

@@ -1,5 +1,6 @@
 import { TASK_SCOPE_TEXT_SCHEMA } from "./task-text.js";
 import { dirname, join } from 'node:path';
+import { statSync } from 'node:fs';
 import { repositoryContextRead } from './repository-context.js';
 import { ASSIGNMENT_TOOLS, assignmentForCoordinator } from "./assignment-adapters.js";
 /**
@@ -367,12 +368,30 @@ function proposeTools() {
         make("answer", "Propose an answer to an open decision you read with get_decision, with a rationale. The approver confirms where every consequence and the builder's recommendation are shown; an irreversible option needs their explicit confirmation.", { decision: { type: "integer", minimum: 1 }, option: { type: "string", minLength: 1, maxLength: 64 }, rationale: { type: "string", maxLength: 400 } }, ["decision", "option", "rationale"]),
     ];
 }
+function fileIdentity(path) {
+    if (path === null)
+        return null;
+    try {
+        const at = statSync(path);
+        return { path, dev: at.dev, ino: at.ino };
+    }
+    catch {
+        return null;
+    }
+}
+/** Still the same file at the same path: not moved aside, deleted, or replaced by a rename. */
+function sameFile(was) {
+    const now = fileIdentity(was.path);
+    return now !== null && now.dev === was.dev && now.ino === was.ino;
+}
 /** Serve until EOF. The store is already open through the non-migrating
  * door; the token was startup-verified by the caller (and dies here again
  * if it does not hold). */
 export function serveMcp(store, token, io, clock = () => new Date(), enrolled = null, evidenceRoot) {
     /** Per connection: which decisions this credential read in full (v3). */
     const readDecisions = new Set();
+    /** The database file this server opened, by identity (null in memory). */
+    const database = fileIdentity(store.databaseFile());
     const auth = authenticateCoordinator(store, token);
     if (!auth.ok) {
         return {
@@ -414,6 +433,13 @@ export function serveMcp(store, token, io, clock = () => new Date(), enrolled =
         tools: TOOLS.map(tool => ({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema })),
     });
     const callTool = (id, era, params) => {
+        // A restore or rollback puts a different file at the database's path: this server's connection still reads and
+        // writes the one it replaced, so it answers nothing more and exits (the agent starts it again on the new one).
+        if (database !== null && !sameFile(database)) {
+            error(id, -32000, "the database was replaced underneath this server (a Toolroll restore or rollback) — restart it");
+            io.exit(0);
+            return;
+        }
         // ONE snapshot per call (review finding 3): the version check, the
         // credential re-read, and every data read share a transaction, so a
         // concurrent migration cannot slip between them; filing's own

package/dist/operate.d.ts

@@ -22,10 +22,6 @@ export declare const EXIT: {
     readonly usage: 2;
     readonly refused: 3;
 };
-/** Storage retention: how long a finished task's clean checkout is kept after it was let go, and a result marked
- * complete's or a release candidate's after it was (its checkout holds the build a deploy installs). */
-export declare const CHECKOUT_KEEP_MS: number;
-export declare const RESULT_KEEP_MS: number;
 export type OperateOptions = {
     /** Native-shell proof key, passed in memory rather than command-line arguments. */
     desktopIdentity?: string;

package/dist/operate.js

@@ -3,7 +3,8 @@ import { parseProtectedPaths } from "./approval-policy.js";
 import { rulesSummary } from "./approval-rules-ui.js";
 import { evidencePack, exportDay, ledgerExportChunks, standaloneEvidenceHtml } from "./evidence-pack.js";
 import { matchesOutsideCheckpoint } from "./ledger-chain.js";
-import { bytesWords, storageReport } from "./storage.js";
+import { CLEANUP_CHOICES, bytesWords, cleanupWords, parseCleanup, storageReport } from "./storage.js";
+import { checkoutPlan, cleanCheckouts, discardCheckout, whyWords } from "./checkout-cleanup.js";
 import { MIN_DAYS, RETENTION_KINDS, countWords, dailyRetention, isRetentionKind, lastSweepAt, parsePeriod, periodWords, retentionPlan, sweepWords } from "./retention.js";
 import { checkPolicy, parseList, policyParts } from "./policy.js";
 import { billingOf, budgetHoldWords, budgetLabel, budgetStates, monthNamed, monthOf, spendItems, teammateNames, usd as spendUsd } from "./spend.js";
@@ -193,10 +194,6 @@ import { PACKAGE_VERSION } from "./version.js";
  * caller deciding whether to try the next task or wake somebody up.
  */
 export const EXIT = { ok: 0, failed: 1, usage: 2, refused: 3 };
-/** Storage retention: how long a finished task's clean checkout is kept after it was let go, and a result marked
- * complete's or a release candidate's after it was (its checkout holds the build a deploy installs). */
-export const CHECKOUT_KEEP_MS = 2 * 24 * 60 * 60_000;
-export const RESULT_KEEP_MS = 7 * 24 * 60 * 60_000;
 const STATES = ["queued", "running", "done", "failed", "cancelled"];
 export const OPERATE_HELP = `toolroll — operating the queue
 
@@ -213,6 +210,9 @@ export const OPERATE_HELP = `toolroll — operating the queue
                                         --not-requester on|off, --protect none|project, --protect-paths "a/**,b/**"
   toolroll task evidence <id>        the task's evidence pack as JSON (--html for a printable page; --out <file>)
   toolroll storage                   where the disk goes: database, build checkouts, releases, evidence
+  toolroll storage clean [--yes]     preview removing finished tasks' clean checkouts (their branches stay); --yes removes them
+  toolroll storage cleanup <when>    remove a finished task's clean checkout: finished|2d|7d|never (instance operator)
+  toolroll storage discard <path> --yes   throw away a checkout kept for its changes; its branch stays
   toolroll monitoring                where the audit stream and traces go, and how each destination is doing
   toolroll check-progress <run>      current or final approved check progress
   toolroll spend [--month YYYY-MM] [--csv]   what agent work cost, by project, person, teammate and model
@@ -823,13 +823,8 @@ async function dispatch(command, positional, flags, context) {
             return exportCommand(positional, flags, context);
         case "policy":
             return policyCommand(positional, flags, context);
-        case "storage": {
-            const report = storageReport(context.store, context.databaseFile, context.clock(), CHECKOUT_KEEP_MS);
-            return succeed(context.write, context.json, "storage", report, () => [
-                `${report.folder}: ${bytesWords(report.total)}`,
-                ...report.lines.map(one => `  ${one.what.padEnd(17)} ${bytesWords(one.bytes).padStart(8)}${one.count === undefined ? "" : `  (${one.count})`}${one.note === undefined ? "" : `  ${one.note}`}`),
-            ]);
-        }
+        case "storage":
+            return storageCommand(positional, flags, context);
         case "monitoring": {
             // Where the audit stream and traces go, and how each destination is doing. Settings → Monitoring changes it.
             const settings = readMonitoring(dirname(context.databaseFile));
@@ -4313,13 +4308,9 @@ async function reconcileCommand(flags, context) {
             reaped: reaped.map(claim => claim.leaseId),
         });
     }
-    // Storage retention: finished work's clean checkouts go two days after they were let go (their branches stay); a
-    // result marked complete, or a release candidate, a week after (a deploy installs the build in its checkout).
-    const pruned = await worktrees.prune(repo, clock(), CHECKOUT_KEEP_MS, () => store.keptBranches(repo, clock(), RESULT_KEEP_MS));
-    for (const row of pruned.removed) {
-        store.recordAction({ at: clock().toISOString(), actor: "worker", repo, taskId: row.taskRef === null ? null : store.externalIdFor(row.taskRef), runId: null,
-            action: "checkout removed", outcome: "removed", source: "work", detail: `${basename(row.path)} (released ${row.releasedAt?.slice(0, 10) ?? "?"})` });
-    }
+    // Checkout cleanup (Settings → Storage): finished work's clean checkouts go as the setting says (by default when
+    // the task is complete or cancelled); their branches stay. Each removal is in the ledger.
+    const pruned = await cleanCheckouts(store, worktrees, clock, { manual: false, actor: "worker", repo });
     // Retention (Settings → Retention): once a day, what's older than its setting goes; one ledger entry says what.
     let retention = null;
     try {
@@ -4341,7 +4332,7 @@ async function reconcileCommand(flags, context) {
         reaped: reaped.map(claim => claim.leaseId),
         adopted: adoption.adopted,
         forgotten: adoption.forgotten,
-        checkoutsRemoved: pruned.removed.map(row => row.path),
+        checkoutsRemoved: pruned.removed.map(one => one.path),
         checkoutsKept: pruned.kept,
         liveViewsSwept: liveSwept.removed.length,
         retention: retention === null ? null : { counts: retention.counts, freedBytes: retention.freed },
@@ -4352,7 +4343,7 @@ async function reconcileCommand(flags, context) {
             ...(reaped.length === 0 ? [] : [`Reaped ${reaped.length} expired lease(s).`]),
             ...adoption.adopted.map(path => `Adopted ${path} — released, unverified, somebody should look.`),
             ...adoption.forgotten.map(path => `Forgot ${path} — its directory is gone.`),
-            ...(pruned.removed.length === 0 ? [] : [`Removed ${pruned.removed.length} checkout(s) nobody has used for two days; their branches stay.`]),
+            ...(pruned.removed.length === 0 ? [] : [`Removed ${pruned.removed.length} finished task checkout(s), about ${bytesWords(pruned.freed)}; their branches stay.`]),
             ...(liveSwept.removed.length === 0 ? [] : [`Cleared ${liveSwept.removed.length} finished live view(s).`]),
             ...(retention === null || retained.length === 0 ? [] : [`Retention removed ${sweepWords(retention.counts, retention.freed)}.`]),
         ]);
@@ -11323,6 +11314,97 @@ async function retentionCommand(positional, flags, context) {
     const periods = store.setRetentionPeriod(kind, days, acting.name, context.clock());
     return succeed(context.write, context.json, command, { periods }, () => [`${label(kind)}: kept ${days === null ? "forever" : `for ${periodWords(days)}`}.`]);
 }
+/** `storage`, `storage cleanup [<when>]`, `storage clean [--yes]`, `storage discard <path> --yes`: where the disk goes,
+ * and task checkouts: when a finished task's clean checkout is removed, cleaning up now, and throwing away one kept for
+ * its changes. Changing anything takes an instance operator. */
+async function storageCommand(positional, flags, context) {
+    const [action, ...rest] = positional;
+    const command = `storage ${action ?? ""}`.trim();
+    const store = context.store;
+    const changes = (action === "cleanup" && rest.length > 0) || (action === "clean" && flags.has("yes")) || action === "discard";
+    const allowed = new Set([...(changes ? ["as", "token", "token-file", "token-env"] : []), ...(action === "clean" || action === "discard" ? ["yes"] : []), "db", "json"]);
+    for (const name of flags.keys())
+        if (!allowed.has(name))
+            return fail(context.write, context.json, command, "usage", `--${name} is not a ${command} option.`, EXIT.usage);
+    const pool = new WorktreePool(store, { root: join(dirname(context.databaseFile), "worktrees"), ...(context.gitRunner === undefined ? {} : { runner: context.gitRunner }) });
+    const operator = async () => {
+        const acting = await askCredentials(flags, context);
+        const verified = acting === null ? null : authenticateApprover(store, acting.name, acting.token);
+        return acting !== null && verified !== null && verified.ok && store.isInstanceOperator(acting.name) ? acting.name : null;
+    };
+    const refused = (what) => fail(context.write, context.json, command, "refused", `An instance operator ${what}: pass --as and --token (or use the remembered login).`, EXIT.refused);
+    const summary = (plan) => [
+        `Checkouts: ${plan.count}, ${bytesWords(plan.totalBytes)}. ${plan.waitingReview} waiting for review, ${plan.withChanges} kept because they have changes.`,
+        plan.go.length === 0 ? "A clean up now would free nothing." : `A clean up now would free about ${bytesWords(plan.freeBytes)} (${plan.go.length} checkout${plan.go.length === 1 ? "" : "s"}): toolroll storage clean`,
+        `A finished task's clean checkout is removed ${cleanupWords(plan.cleanup)}; its branch stays.`,
+    ];
+    const itemLine = (one) => `  ${bytesWords(one.bytes).padStart(8)}  ${one.path}${one.why === null ? "" : `  (${whyWords(one)})`}`;
+    if (action === undefined) {
+        const plan = await checkoutPlan(store, pool, context.clock(), { manual: true });
+        const report = storageReport(store, context.databaseFile, plan.go.length === 0 ? "nothing to clean up" : `about ${bytesWords(plan.freeBytes)} to clean up`);
+        return succeed(context.write, context.json, "storage", { ...report, checkouts: checkoutSummary(plan) }, () => [
+            `${report.folder}: ${bytesWords(report.total)}`,
+            ...report.lines.map(one => `  ${one.what.padEnd(17)} ${bytesWords(one.bytes).padStart(8)}${one.count === undefined ? "" : `  (${one.count})`}${one.note === undefined ? "" : `  ${one.note}`}`),
+            ...summary(plan),
+        ]);
+    }
+    if (action === "cleanup") {
+        if (rest.length === 0) {
+            const cleanup = store.checkoutCleanup();
+            return succeed(context.write, context.json, command, { cleanup }, () => [`A finished task's clean checkout is removed ${cleanupWords(cleanup)}; its branch stays.`]);
+        }
+        const cleanup = rest.length === 1 ? parseCleanup(rest[0]) : undefined;
+        if (cleanup === undefined)
+            return fail(context.write, context.json, command, "usage", `Use storage cleanup <${CLEANUP_CHOICES.map(one => one.value).join("|")}>.`, EXIT.usage);
+        const actor = await operator();
+        if (actor === null)
+            return refused("sets checkout cleanup");
+        const saved = store.setCheckoutCleanup(cleanup, actor, context.clock());
+        return succeed(context.write, context.json, command, { cleanup: saved }, () => [`Saved. A finished task's clean checkout is removed ${cleanupWords(saved)}; its branch stays.`]);
+    }
+    if (action === "clean") {
+        if (rest.length > 0)
+            return fail(context.write, context.json, command, "usage", "Use storage clean to preview, then storage clean --yes.", EXIT.usage);
+        if (!flags.has("yes")) {
+            const plan = await checkoutPlan(store, pool, context.clock(), { manual: true });
+            return succeed(context.write, context.json, command, { preview: true, go: plan.go, stay: plan.stay, freeBytes: plan.freeBytes }, () => [
+                ...(plan.go.length === 0 ? ["Nothing to clean up."] : [`Would remove ${plan.go.length} checkout${plan.go.length === 1 ? "" : "s"}, freeing about ${bytesWords(plan.freeBytes)} (their branches stay):`, ...plan.go.map(itemLine)]),
+                ...(plan.stay.length === 0 ? [] : [`Stays (${plan.stay.length}):`, ...plan.stay.map(itemLine)]),
+                plan.go.length === 0 ? "Nothing was removed." : "Nothing was removed. Run toolroll storage clean --yes to remove them.",
+            ]);
+        }
+        const actor = await operator();
+        if (actor === null)
+            return refused("cleans up checkouts");
+        const done = await cleanCheckouts(store, pool, context.clock, { manual: true, actor });
+        return succeed(context.write, context.json, command, { removed: done.removed, kept: done.kept, freedBytes: done.freed }, () => [
+            done.removed.length === 0 ? "Nothing to clean up." : `Removed ${done.removed.length} checkout${done.removed.length === 1 ? "" : "s"}, about ${bytesWords(done.freed)}; their branches stay.`,
+            ...done.removed.map(itemLine),
+            ...done.kept.map(one => `  kept ${one.path} (${whyWords({ why: one.why })})`),
+        ]);
+    }
+    if (action === "discard") {
+        const [path, ...extra] = rest;
+        if (path === undefined || extra.length > 0)
+            return fail(context.write, context.json, command, "usage", "Use storage discard <path> --yes.", EXIT.usage);
+        const target = resolve(path);
+        if (store.getWorktree(target) === null)
+            return fail(context.write, context.json, command, "not-found", `${target} is not a task checkout. toolroll storage clean lists them.`, EXIT.refused);
+        if (!flags.has("yes"))
+            return fail(context.write, context.json, command, "usage", `This throws away ${target} and its uncommitted changes (its branch stays). Add --yes to discard it.`, EXIT.usage);
+        const actor = await operator();
+        if (actor === null)
+            return refused("discards a checkout");
+        const done = await discardCheckout(store, pool, target, context.clock(), actor);
+        if (!done.ok)
+            return fail(context.write, context.json, command, "refused", done.message, EXIT.refused);
+        return succeed(context.write, context.json, command, { discarded: target, freedBytes: done.bytes }, () => [`Discarded ${target}, about ${bytesWords(done.bytes)}; its branch stays.`]);
+    }
+    return fail(context.write, context.json, command, "usage", "Use storage, storage cleanup <when>, storage clean [--yes] or storage discard <path> --yes.", EXIT.usage);
+}
+function checkoutSummary(plan) {
+    return { count: plan.count, totalBytes: plan.totalBytes, waitingReview: plan.waitingReview, withChanges: plan.withChanges, cleanBytes: plan.freeBytes, cleanCount: plan.go.length, cleanup: plan.cleanup };
+}
 /** `policy show | set` (sprint 8): the organisation policy. Setting it takes an instance operator's credentials; each rule
  * that changed is in the ledger, before → after. A flag left out keeps its rule; "any" lifts it. */
 async function policyCommand(positional, flags, context) {

package/dist/prompt.d.ts

@@ -7,12 +7,17 @@
  */
 /** Whether asking is even possible: a human on both ends of the pipe. */
 export declare function interactive(): boolean;
+/** The program names of this process's ancestors, nearest first: each one's command and, for a script run by node
+ * or python, the script's name. Empty where `ps` cannot say. */
+export declare function ancestorPrograms(): string[];
 /**
  * Whether a coding agent is running this command. An agent's shell can be a
  * real terminal, yet whatever is printed lands in its transcript and nobody
- * types at the prompt, so it is treated like no terminal at all.
+ * types at the prompt, so it is treated like no terminal at all. The agent is
+ * known by a variable it sets or, for one that sets none, by the program above
+ * this one. `programs` is read only for this process's own environment.
  */
-export declare function underAgent(env?: Record<string, string | undefined>): boolean;
+export declare function underAgent(env?: Record<string, string | undefined>, programs?: () => readonly string[]): boolean;
 export declare function ask(question: string): Promise<string>;
 /** Like ask, but what is typed never echoes — passwords live here. */
 /**