toolroll 0.9.31 → 0.9.33

package/dist/mate.js

@@ -1,6 +1,7 @@
 import { Buffer } from "node:buffer";
 import { mateToolLabel } from "./mate-progress.js";
 import { createHash } from "node:crypto";
+import { mateTimeoutNotice } from "./store.js";
 import { RESULT_IMAGES_PER_TURN_CAP } from "./chat-evidence.js";
 import { isVerifiedApprover, reproveApprover } from "./principal.js";
 import { MATE_MAX_CALLS_PER_STEP, MATE_MAX_STEPS, MATE_TOOL_RESULT_CAP_BYTES, TURN_WALL_CLOCK_MS, composeMateRequest, credentialKeyOf, isDirectChatProvider, mateWorstCaseForPrice, performMateRequest, priceForConfig, settleForPrice, subscriptionCredentialKey, } from "./converse.js";
@@ -56,7 +57,7 @@ export const MATE_CHANNEL_COPY = {
 export const MATE_FAILURE_COPY = {
     stopped: "This reply was stopped before it finished, from another window or by a newer message. Nothing it proposed was kept. Send your message again if you still need an answer.",
     ended: "Your sign-in or this conversation ended while the lead was answering. Nothing it proposed was kept. Sign in again or start a new chat, then send your message again.",
-    tooLong: "The reply took too long and was stopped. Nothing it proposed was kept. Send your message again, or ask for less at once.",
+    tooLong: mateTimeoutNotice(false),
     secretRead: "Something the lead read looked like a password or key, so it stopped before sending it anywhere. Nothing was kept. Remove the password or key from that task or note, then ask again.",
     secretReply: "The lead's reply contained something that looked like a password or key, so it was thrown away. Nothing was kept. Ask again, without asking for a password or key.",
     paused: "An earlier reply stopped before its cost was known, so chat is paused. This message wasn't answered. Confirm that earlier reply on the Chat page, then send again.",
@@ -65,7 +66,7 @@ export const MATE_FAILURE_COPY = {
     unreadable: "The chat provider sent back an answer that couldn't be read, so it was thrown away. Nothing was kept. Send your message again.",
     signIn: "The chat provider couldn't answer; its sign-in may have expired. Nothing was kept. Sign in to it again on this computer, then send your message again.",
     refused: "The chat provider turned the request down. Nothing was kept or charged. Try again in a minute; if it keeps happening, check the provider in Settings → Lead.",
-    tooLongUnknownCost: "The reply took too long and was stopped, and its cost isn't known yet, so chat is paused. Nothing it proposed was kept. Confirm the cost on the Chat page to turn chat back on.",
+    tooLongUnknownCost: mateTimeoutNotice(false, true),
     lostUnknownCost: "The chat provider stopped responding partway through, and the cost isn't known, so chat is paused. Nothing it proposed was kept. Confirm the cost on the Chat page to turn chat back on.",
     unreadableUnknownCost: "The chat provider sent back an answer that couldn't be read, and its cost isn't known, so chat is paused. Nothing it proposed was kept. Confirm the cost on the Chat page to turn chat back on.",
     empty: "The lead sent back an empty answer. Nothing was kept. Send your message again.",
@@ -74,7 +75,8 @@ export const MATE_FAILURE_COPY = {
 /** A failed turn's saved reason as plain words, for a surface that reads the turn back later (a restart, a delivery retry). */
 export function mateFailureText(reason) {
     switch (reason) {
-        case "timeout": return MATE_FAILURE_COPY.tooLong;
+        case "timeout":
+        case "crashed": return MATE_FAILURE_COPY.tooLong;
         case "malformed-reply": return MATE_FAILURE_COPY.unreadable;
         case "secret-refused": return MATE_FAILURE_COPY.secretReply;
         case "latched": return MATE_FAILURE_COPY.paused;
@@ -84,6 +86,16 @@ export function mateFailureText(reason) {
         default: return "The lead's reply didn't finish. Nothing it proposed was kept. Send your message again.";
     }
 }
+/** How long a provider that ignored its abort at the turn's deadline is waited for before the turn ends without it.
+ * Its process group was already killed at the deadline; this only bounds the wait for the transport to say so. */
+export const MATE_ABORT_GRACE_MS = 5_000;
+const LATE = Symbol("late");
+/** The work's own result, or LATE once `ms` passes: the turn's clock, not the work, decides when the person hears back. */
+function settleBy(work, ms) {
+    let timer;
+    const late = new Promise(resolve => { timer = setTimeout(() => resolve(LATE), Math.max(0, ms)); });
+    return Promise.race([work, late]).finally(() => clearTimeout(timer));
+}
 const READ_TOOLS = new Set(["get_brief", "get_project_context", "get_actions", "get_action_status", "get_skills", "get_acceptance_evidence", "recap", "list_repos", "list_tasks", "get_task", "get_result", "get_result_images", "get_controls", "get_agents", "get_project_knowledge", "get_task_conversation", "get_diff", "get_check_log", "get_project_tools", "get_flows", "get_flow_insights", "list_decisions", "get_decision", "queue"]);
 /** The last messages of the thread as provider-neutral history, newest kept first until the byte cap. */
 export function historyFor(store, thread, queuedMessageId) {
@@ -291,6 +303,20 @@ export async function runMateTurn(input) {
         store.dropMateAsk(turnId);
         return { ok: false, turn: turnId, failed, message, unknownSpend };
     };
+    /** The turn stopped at its deadline: the notice is saved in the thread with whatever its completed tool calls proposed, in
+     * the same write that ends the turn, so a refresh, another device or a restart shows the same outcome. */
+    const timedOut = (unknownSpend) => {
+        now = clock();
+        const message = mateTimeoutNotice(proposals > 0, unknownSpend);
+        const saved = store.finalizeMateTurn(turnId, started.generation, { state: "failed", settledMicrousd: settled, unknownSpend, tokensIn, tokensOut, failureReason: "timeout", keepProposals: true, message: { text: message, activity: activitySummary(reads, proposals, steps) } }, now);
+        store.dropMateAsk(turnId);
+        if (!saved)
+            return { ok: false, turn: turnId, failed: "superseded", message: MATE_FAILURE_COPY.stopped, unknownSpend: false };
+        return { ok: false, turn: turnId, failed: "timeout", message, unknownSpend, saved: true };
+    };
+    const deadlineLeft = () => TURN_WALL_CLOCK_MS - (clock().getTime() - turnStartedAt);
+    /** The channel's standing, bounded by the turn's deadline: a lookup that never answers cannot hold the turn open. */
+    const revalidated = async () => input.revalidate === undefined ? { ok: true } : settleBy(input.revalidate(), deadlineLeft() + MATE_ABORT_GRACE_MS);
     /** The turn's own row, re-read: still running under our generation, or someone ended it under us. */
     const stillOurs = () => {
         const row = store.getMateTurn(turnId);
@@ -301,6 +327,8 @@ export async function runMateTurn(input) {
     const guard = (channel) => {
         if (!stillOurs())
             return { ok: false, turn: turnId, failed: "superseded", message: MATE_FAILURE_COPY.stopped, unknownSpend: false };
+        if (channel === LATE)
+            return timedOut(false);
         if (!channel.ok)
             return fail("revoked", MATE_CHANNEL_COPY[channel.reason] ?? MATE_CHANNEL_COPY["access-changed"], false);
         const standing = reproveApprover(store, who);
@@ -328,13 +356,13 @@ export async function runMateTurn(input) {
         return claim;
     };
     while (steps < maxSteps) {
-        const blocked = guard(input.revalidate === undefined ? { ok: true } : await input.revalidate());
+        const blocked = guard(await revalidated());
         if (blocked !== null)
             return blocked;
         now = clock();
         const remainingMs = TURN_WALL_CLOCK_MS - (now.getTime() - turnStartedAt);
         if (remainingMs <= 0)
-            return fail("timeout", MATE_FAILURE_COPY.tooLong, false);
+            return timedOut(false);
         const request = direct ? composeDirect(input.key) : composeSubscription();
         // Tool results join the outbound body: scanned again before every dispatch.
         const outbound = typeof request === "string" ? request : request.body;
@@ -354,39 +382,34 @@ export async function runMateTurn(input) {
         progress({ kind: "step", turn: turnId, step: steps });
         const requestBytes = Buffer.byteLength(outbound, "utf8");
         let result;
+        // The turn owns its deadline (lead-stall, release check 2438): at the deadline the request is aborted, which ends a
+        // harness's whole process group, and a provider that still has not settled MATE_ABORT_GRACE_MS later is left behind.
+        // Whatever it says after that is never read; the turn has already ended with its notice.
+        const controller = new AbortController();
+        const abortAt = setTimeout(() => controller.abort(), remainingMs);
+        const settle = (work) => settleBy(work, remainingMs + MATE_ABORT_GRACE_MS)
+            .then(value => value === LATE || controller.signal.aborted ? { ok: false, problem: "timeout" } : value)
+            .finally(() => clearTimeout(abortAt));
         if (direct) {
-            const controller = new AbortController();
-            const timer = setTimeout(() => controller.abort(), remainingMs);
-            try {
-                result = await performMateRequest(request, directProvider, controller.signal, fetcher);
-            }
-            catch {
-                result = { ok: false, problem: "network" };
-            }
-            finally {
-                clearTimeout(timer);
-            }
+            result = await settle(performMateRequest(request, directProvider, controller.signal, fetcher)
+                .catch(() => ({ ok: false, problem: "network" })));
         }
         else {
             const runner = input.subscriptionRunner ?? performSubscriptionMateRequest;
-            try {
-                result = await runner({
-                    provider: subscriptionProvider,
-                    model: config.model,
-                    system: MATE_CONTRACT,
-                    dataDocument: document,
-                    history,
-                    tools: MATE_TOOL_SCHEMAS,
-                    timeoutMs: remainingMs,
-                    // The reply as it is written; text that looks like a secret is
-                    // never shown (the finished reply is scanned again before saving).
-                    ...(input.onProgress === undefined ? {} : { onText: (text) => { if (scanForSecrets(text).length === 0)
-                            progress({ kind: "text", turn: turnId, step: steps, text }); } }),
-                });
-            }
-            catch {
-                result = { ok: false, problem: "provider-error" };
-            }
+            result = await settle((async () => runner({
+                provider: subscriptionProvider,
+                model: config.model,
+                system: MATE_CONTRACT,
+                dataDocument: document,
+                history,
+                tools: MATE_TOOL_SCHEMAS,
+                timeoutMs: remainingMs,
+                signal: controller.signal,
+                // The reply as it is written; text that looks like a secret is
+                // never shown (the finished reply is scanned again before saving).
+                ...(input.onProgress === undefined ? {} : { onText: (text) => { if (!controller.signal.aborted && scanForSecrets(text).length === 0)
+                        progress({ kind: "text", turn: turnId, step: steps, text }); } }),
+            }))().catch(() => ({ ok: false, problem: "provider-error" })));
         }
         now = clock();
         const finishStep = (outcome) => store.finalizeChatTurn(step.id, stepStarted.generation, outcome, now);
@@ -400,7 +423,9 @@ export async function runMateTurn(input) {
                         : result.problem === "malformed-reply"
                             ? MATE_FAILURE_COPY.unreadable
                             : MATE_FAILURE_COPY.signIn;
-                return fail(result.problem === "timeout" ? "timeout" : result.problem === "malformed-reply" ? "malformed-reply" : "provider-error", message, false);
+                if (result.problem === "timeout")
+                    return timedOut(false);
+                return fail(result.problem === "malformed-reply" ? "malformed-reply" : "provider-error", message, false);
             }
             if (result.problem.startsWith("status-")) {
                 // The provider ANSWERED with an error: nothing billed for this step.
@@ -409,7 +434,7 @@ export async function runMateTurn(input) {
             }
             if (result.problem === "timeout") {
                 finishStep({ state: "failed", failureReason: "timeout", settledMicrousd: null, unknownSpend: true });
-                return fail("timeout", MATE_FAILURE_COPY.tooLongUnknownCost, true);
+                return timedOut(true);
             }
             if (result.problem === "network") {
                 finishStep({ state: "failed", failureReason: "provider-error", settledMicrousd: null, unknownSpend: true });
@@ -437,7 +462,7 @@ export async function runMateTurn(input) {
         // After the wait (finding 5): the row may have been failed under us by
         // a revocation or the sweep — then nothing the model said runs; and the
         // approver must still stand before any tool runs as them.
-        const changed = guard(input.revalidate === undefined ? { ok: true } : await input.revalidate());
+        const changed = guard(await revalidated());
         if (changed !== null)
             return changed;
         if (answer.calls.length === 0) {
@@ -470,7 +495,7 @@ export async function runMateTurn(input) {
         history.push({ role: "assistant", text: answer.text, calls: answer.calls });
         for (const [index, call] of answer.calls.entries()) {
             if (index > 0) {
-                const changed = guard(input.revalidate === undefined ? { ok: true } : await input.revalidate());
+                const changed = guard(await revalidated());
                 if (changed !== null)
                     return changed;
             }

package/dist/never-index.d.ts

@@ -0,0 +1,3 @@
+export declare const NEVER_INDEX = ".metadata_never_index";
+/** Put the marker in `dir` (an existing folder). False when it couldn't be written. */
+export declare function markNeverIndex(dir: string): boolean;

package/dist/never-index.js

@@ -0,0 +1,21 @@
+/**
+ * Spotlight leaves Toolroll's churn alone: a `.metadata_never_index` file in a folder tells macOS not to index it or
+ * what is inside. Toolroll puts one in the folders it fills and empties all day — the checkouts folder and each
+ * project's folder in it (never inside a checkout, where a build's `git add -A` would commit it), shared dependency
+ * installs, staged runtimes and test temp roots. Measured Oct 4: fseventsd at 15 GB with 107k test temp folders.
+ *
+ * A marker that can't be written is only noted: it never decides whether anything is removed.
+ */
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const NEVER_INDEX = ".metadata_never_index";
+/** Put the marker in `dir` (an existing folder). False when it couldn't be written. */
+export function markNeverIndex(dir) {
+    try {
+        writeFileSync(join(dir, NEVER_INDEX), "", { flag: "a" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/operate.js

@@ -3,6 +3,8 @@ import { leadNameOf } from "./lead-identity.js";
 import { maybeTriggerRepair } from "./dispose.js";
 import { CHECK_LEVEL_HINTS, CHECK_LEVEL_WORDS, isCheckLevel, liveQuickCommand, projectCheckLevel, quickVerifyKey, setProjectCheckLevel, setTaskCheckLevel, suggestQuickCommand } from "./check-levels.js";
 import { fileAddTestsTask, followUpChecksOf, requestFollowUpChecks, runFollowUpCheck, runWaitingChecks } from "./result-follow-ups.js";
+import { runBatchChecks } from "./batch-checks.js";
+import { BATCH_HINT, BATCH_WINDOW_MS, projectBatchChecks, setProjectBatchChecks } from "./batch-policy.js";
 import { buildReviewPass } from "./build-review.js";
 import { buildReviewLines, buildReviewOf } from "./review-switch.js";
 import { parseProtectedPaths } from "./approval-policy.js";
@@ -11,6 +13,7 @@ import { evidencePack, exportDay, ledgerExportChunks, standaloneEvidenceHtml } f
 import { matchesOutsideCheckpoint } from "./ledger-chain.js";
 import { CLEANUP_CHOICES, bytesWords, cleanupWords, diskBytes, parseCleanup, storageReport } from "./storage.js";
 import { removeStaleTestTemp, tempRoots, testTempFolders } from "./test-temp.js";
+import { dailyStorageSweep, lastSweep, nextSweepAt, saveSweep, storageSweepOff as storageSweepOffNow, sweepDetails, sweepWords as storageSweepWords } from "./storage-sweep.js";
 import { removeShared, sharedDepsRoot, sharedUse, unusedShared } from "./shared-deps.js";
 import { checkoutPlan, cleanCheckouts, discardCheckout, finishedCheckouts, slimKeptCheckouts, whyWords } from "./checkout-cleanup.js";
 import { closeOutCheckouts, closeOutRuns, stoppedWords } from "./run-closeout.js";
@@ -45,7 +48,7 @@ import { loadSlackCredentials } from "./slack-api.js";
 import { followSlack } from "./slack.js";
 import { validateScopeText } from "./task-text.js";
 import { runMemoryCommand } from "./memory-cli.js";
-import { runKnowledgeCommand } from "./knowledge-cli.js";
+import { runKnowledgeApply, runKnowledgeCommand } from "./knowledge-cli.js";
 import { FLOWS_VALUE_FLAGS, runFlowsCommand } from "./flows-cli.js";
 import { runAssignmentCommand } from "./assignment-adapters.js";
 import { applyProjectProfile, runProjectCommand } from "./project-cli.js";
@@ -996,6 +999,8 @@ async function dispatch(command, positional, flags, context) {
                 return projectDeleteCommand(positional, flags, context);
             if (positional[0] === "concurrency")
                 return projectConcurrencyCommand(positional, flags, context);
+            if (positional[0] === "checks")
+                return projectChecksCommand(positional, flags, context);
             if (positional[0] === "demo")
                 return projectDemoCommand(positional, flags, context);
             return runProjectCommand(positional, flags, context);
@@ -1004,8 +1009,18 @@ async function dispatch(command, positional, flags, context) {
             if (positional[0] === "claim" && currentActor()?.lead === true && !flags.has("token-env") && !flags.has("token-file"))
                 return leadClaimCommand(positional, flags, context);
             return runAssignmentCommand(positional, flags, context);
-        case "knowledge":
-            return runKnowledgeCommand(positional, flags, { ...context, now: context.clock() });
+        case "knowledge": {
+            if (positional[0] !== "apply")
+                return runKnowledgeCommand(positional, flags, { ...context, now: context.clock() });
+            if (positional.length !== 1)
+                return fail(context.write, context.json, "knowledge apply", "usage", "knowledge apply takes no query.", EXIT.usage);
+            // A person's password, never the lead's token: the lead may not carry knowledge forward.
+            const acting = currentActor()?.lead === true ? null : await askCredentials(flags, context);
+            const repo = text(flags, "repo");
+            const lead = acting !== null && parseLeadToken(acting.token) !== null;
+            const verified = acting === null || lead ? null : authenticateApprover(context.store, acting.name, acting.token, repo === undefined ? null : resolve(repo));
+            return runKnowledgeApply(flags, { ...context, now: context.clock(), actor: verified !== null && verified.ok ? acting.name : null });
+        }
         case "models": {
             const acting = await askCredentials(flags, context);
             const verified = acting === null ? null : authenticateApprover(context.store, acting.name, acting.token);
@@ -4541,7 +4556,18 @@ async function reconcileCommand(flags, context) {
         retention = null; /* the next pass tries again */
     }
     const retained = retention === null ? [] : retention.counts.filter(one => one.count > 0);
+    // The daily storage sweep (storage-sweep.ts): stale test temp folders, orphans Toolroll left running, finished
+    // checkouts, extra staged runtimes and dependency installs unused for a week; saved for Settings → Storage.
+    let storageSwept = null;
+    try {
+        storageSwept = await dailyStorageSweep(store, { databaseFile: context.databaseFile, pool: worktrees, tempRoots: context.tempRoots ?? tempRoots() }, clock);
+    }
+    catch {
+        storageSwept = null; /* the next pass tries again */
+    }
+    const swept = storageSwept === null ? [] : storageSwept.parts.filter(one => one.count > 0);
     const nothing = retained.length === 0 &&
+        swept.length === 0 &&
         recovered.length === 0 &&
         reaped.length === 0 &&
         adoption.adopted.length === 0 &&
@@ -4562,6 +4588,7 @@ async function reconcileCommand(flags, context) {
         checkoutsSlimmed: slimmed.slimmed.map(one => one.path),
         liveViewsSwept: liveSwept.removed.length,
         retention: retention === null ? null : { counts: retention.counts, freedBytes: retention.freed },
+        storageSweep: storageSwept,
     }, () => nothing
         ? ["Nothing to reconcile. Everything is where it should be."]
         : [
@@ -4575,6 +4602,7 @@ async function reconcileCommand(flags, context) {
             ...(slimmed.slimmed.length === 0 ? [] : [`Dropped dependencies and build output from ${slimmed.slimmed.length} kept checkout(s), about ${bytesWords(slimmed.slimmed.reduce((sum, one) => sum + one.bytes, 0))}.`]),
             ...(liveSwept.removed.length === 0 ? [] : [`Cleared ${liveSwept.removed.length} finished live view(s).`]),
             ...(retention === null || retained.length === 0 ? [] : [`Retention removed ${sweepWords(retention.counts, retention.freed)}.`]),
+            ...(storageSwept === null || swept.length === 0 ? [] : [`Storage sweep: ${storageSweepWords(storageSwept.parts)}`]),
         ]);
 }
 // ---- gaps -----------------------------------------------------------------
@@ -7658,11 +7686,15 @@ async function runWatchLoop(args) {
         run: async () => {
             if (store.isDemo())
                 return;
+            // Batch checks first: a cohort that is ready runs one check for all its results.
+            const batched = await runBatchChecks(store, context.evidenceRoot, { now: context.clock, shouldStop: stopping });
+            if (batched > 0)
+                progress(`watch: settled ${batched} batch-checked result(s)`);
             const ran = await runWaitingChecks(store, context.evidenceRoot, { now: context.clock, shouldStop: stopping });
             if (ran > 0)
                 progress(`watch: ran ${ran} follow-up check(s)`);
             // A finished check may send a build's card down its failure path: now, not on the next beat.
-            if (ran > 0)
+            if (ran + batched > 0)
                 moveCards(store, repo, context.clock(), context.evidenceRoot);
         },
     });
@@ -12231,6 +12263,45 @@ async function projectConcurrencyCommand(positional, flags, context) {
         ...(changed.before > changed.after ? ["Builds already running carry on; the new number applies to the next one."] : []),
     ]);
 }
+/** `project checks [--batch on|off] --repo <p>`: whether the project's results share one full check when they
+ * finish close together (batch-checks.ts). Off by default; changing it is an approver's act, in the ledger. */
+async function projectChecksCommand(positional, flags, context) {
+    const command = "project checks";
+    const allowed = new Set(["repo", "batch", "as", "token", "token-file", "token-env", "db", "json"]);
+    for (const name of flags.keys())
+        if (!allowed.has(name))
+            return fail(context.write, context.json, command, "usage", `--${name} is not a project checks option.`, EXIT.usage);
+    const repoFlag = text(flags, "repo");
+    const wanted = flags.get("batch");
+    if (positional.length > 1 || repoFlag === undefined || (wanted !== undefined && wanted !== "on" && wanted !== "off")) {
+        return fail(context.write, context.json, command, "usage", "Use project checks [--batch on|off] --repo <project path>.", EXIT.usage);
+    }
+    const registered = await loadRepos(registryPathOf(context)).catch(() => ({ error: "unreadable" }));
+    const known = [...new Set([...context.store.knownRepos(), ...context.store.listProjects().map(one => one.path), ...("error" in registered ? [] : registered.repos)])];
+    const repo = known.find(one => one === repoFlag || one === resolve(repoFlag) || one === canonicalProject(repoFlag));
+    if (repo === undefined)
+        return fail(context.write, context.json, command, "not-found", "That isn't a project Toolroll knows.", EXIT.refused);
+    const level = projectCheckLevel(context.store, repo).level;
+    const words = (on) => [
+        `${repo}: batch checks are ${on ? "on" : "off"}. ${on ? BATCH_HINT : "Each result runs its own full check."}`,
+        ...(on && level !== "full" ? [`Checks are ${CHECK_LEVEL_WORDS[level]} for this project, so nothing is batched until they are Full.`] : []),
+    ];
+    if (wanted === undefined) {
+        const current = projectBatchChecks(context.store, repo);
+        return succeed(context.write, context.json, command, { repo, batch: current.on, windowMinutes: current.windowMs / 60_000, level, setBy: current.setBy }, () => words(current.on));
+    }
+    const acting = await askCredentials(flags, context);
+    const verified = acting === null ? null : authenticateApprover(context.store, acting.name, acting.token, repo);
+    if (acting === null || verified === null || !verified.ok || !context.store.accountCanAccess(acting.name, repo)) {
+        return fail(context.write, context.json, command, "refused", "An approver for this project changes batch checks: pass --as and --token (or use the remembered login).", EXIT.refused);
+    }
+    const on = wanted === "on";
+    const changed = setProjectBatchChecks(context.store, repo, on, acting.name, context.clock());
+    return succeed(context.write, context.json, command, { repo, batch: on, before: changed.before, changed: changed.changed, windowMinutes: BATCH_WINDOW_MS / 60_000, level }, () => [
+        ...words(on),
+        ...(changed.changed && !on ? ["Results already waiting are checked now."] : []),
+    ]);
+}
 /** `project demo [<url>|off] --repo <p>` (review 827): the project's own demo or dev server, which its scouts may
  * screenshot. Changing it is an approver's act. */
 async function projectDemoCommand(positional, flags, context) {
@@ -12625,17 +12696,33 @@ async function storageCommand(positional, flags, context) {
         return copies.map(one => ({ key: one.key, repo: one.repo, path: one.dir, bytes: sizes.get(one.dir) ?? 0, checkouts: one.checkouts.length, usedBy: one.checkouts, retired: one.retired, node: one.node, createdAt: one.createdAt, usedAt: one.usedAt }));
     };
     const sharedLine = (one) => `  ${bytesWords(one.bytes).padStart(8)}  ${projectName(one.repo)} ${one.key.slice(0, 8)}: ${one.checkouts === 1 ? "1 checkout uses it" : `${one.checkouts} checkouts use it`}${one.retired ? " (changed after install; never linked again)" : ""}`;
+    // What the latest sweep (automatic, or a clean-up by hand) did and when (storage-sweep.ts).
+    const sweepFacts = () => {
+        const last = lastSweep(store);
+        const automatic = last?.source === "automatic" ? last : lastSweep(store, "automatic");
+        return { last, lastAutomatic: automatic, next: nextSweepAt(store) };
+    };
+    const sweepLines = (facts) => {
+        const when = (at) => new Date(at).toLocaleString("en-US", { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" });
+        const one = facts.last;
+        const head = one === null ? (facts.next === null && storageSweepOffNow() ? "Automatic sweep: off." : "Automatic sweep: not run yet; it runs once a day.")
+            : `Last swept ${when(one.at)}${one.source === "manual" ? ` by ${one.actor}` : " automatically"}: ${storageSweepWords(one.parts)}`;
+        const auto = one !== null && one.source === "manual" && facts.lastAutomatic !== null ? [`Last automatic sweep ${when(facts.lastAutomatic.at)}: ${storageSweepWords(facts.lastAutomatic.parts)}`] : [];
+        return [head, ...auto, ...(one === null ? [] : sweepDetails(one.parts).slice(0, 8).map(line => `  ${line}`))];
+    };
     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`);
         const { staleBytes: _, ...temp } = leftovers(false);
         const shared = sharedFacts(sharedUse(depsRoot, checkoutRows()));
-        return succeed(context.write, context.json, "storage", { ...report, checkouts: checkoutSummary(plan), testTemp: temp, shared }, () => [
+        const sweep = sweepFacts();
+        return succeed(context.write, context.json, "storage", { ...report, checkouts: checkoutSummary(plan), testTemp: temp, shared, sweep }, () => [
             `${report.folder}: ${bytesWords(report.total)}`,
             ...report.lines.map(one => `  ${one.what.padEnd(19)} ${bytesWords(one.bytes).padStart(8)}${one.count === undefined ? "" : `  (${one.count})`}${one.note === undefined ? "" : `  ${one.note}`}`),
             ...(shared.length === 0 ? [] : ["Shared dependencies:", ...shared.map(sharedLine)]),
             ...summary(plan),
             leftoverLine({ ...temp, staleBytes: 0 }),
+            ...sweepLines(sweep),
         ]);
     }
     if (action === "cleanup") {
@@ -12692,6 +12779,13 @@ async function storageCommand(positional, flags, context) {
         for (const debris of unused.debris)
             removeShared(debris);
         const sharedFreed = sharedRemoved.reduce((sum, one) => sum + one.bytes, 0);
+        // Saved like an automatic sweep, so Storage shows what this clean-up did and when.
+        const parts = [
+            { kind: "checkouts", count: done.removed.length, bytes: done.freed, failed: done.kept.filter(one => one.why === "git refused").length, items: done.removed.slice(0, 20).map(one => one.path) },
+            { kind: "test temp", count: swept.removed.length, bytes: temp.staleBytes, failed: swept.failed.length, items: swept.removed.slice(0, 20) },
+            { kind: "dependencies", count: sharedRemoved.length, bytes: sharedFreed, failed: unused.copies.length - sharedRemoved.length, items: sharedRemoved.slice(0, 20).map(one => one.path) },
+        ];
+        saveSweep(store, { at: context.clock().toISOString(), source: "manual", actor, parts });
         return succeed(context.write, context.json, command, { removed: done.removed, kept: done.kept, freedBytes: done.freed, testTempRemoved: swept.removed.length, testTempFailed: swept.failed, sharedRemoved, sharedFreedBytes: sharedFreed }, () => [
             done.removed.length === 0 ? (swept.removed.length === 0 && sharedRemoved.length === 0 ? "Nothing to clean up." : "No checkouts to clean up.") : `Removed ${done.removed.length} checkout${done.removed.length === 1 ? "" : "s"}, about ${bytesWords(done.freed)}; their branches stay.`,
             ...done.removed.map(itemLine),

package/dist/orphan-sweep.d.ts

@@ -0,0 +1,63 @@
+import { type ProcessRow, type StopOptions } from "./run-closeout.js";
+import type { Store } from "./store.js";
+import { type TempOwner } from "./test-temp.js";
+import type { WorktreePool } from "./worktree.js";
+/** Where a process runs from: its working folder and executable, when the OS says. */
+export type Located = {
+    cwd?: string;
+    exe?: string;
+};
+/** Working folder and executable of each pid: /proc on Linux, lsof on macOS. Throws when the OS can't be asked. */
+export declare function locateProcesses(pids: readonly number[]): Map<number, Located>;
+/** A folder an orphan may be stopped from: a let-go checkout (only what was born before it was let go) or a temp root. */
+export type SweepRoot = {
+    path: string;
+    kind: "checkout" | "test temp";
+    bornBefore?: number;
+    repo?: string | null;
+    taskId?: string | null;
+};
+/** The root `located` runs from inside of, if any (its working folder first, then its executable). */
+export declare function rootOf(located: Located | undefined, roots: readonly SweepRoot[]): SweepRoot | null;
+export type OrphanTarget = {
+    row: ProcessRow;
+    root: SweepRoot;
+    orphan: number;
+};
+/**
+ * Which processes go: each orphan (parent 1, no terminal, not protected) running from inside a root — for a checkout,
+ * born before it was let go — and every process descending from one that goes (none at a terminal or protected).
+ */
+export declare function orphanTargets(census: readonly ProcessRow[], located: ReadonlyMap<number, Located>, roots: readonly SweepRoot[], guard: {
+    pids: ReadonlySet<number>;
+    groups: ReadonlySet<number>;
+}): OrphanTarget[];
+/** Whether a temp root's owner (pid and start) is still the running process. */
+export declare function ownerRunning(census: readonly ProcessRow[]): (owner: TempOwner) => boolean;
+/**
+ * The roots orphans may be stopped from now: every checkout let go with no live run on its task and not held, and
+ * every test temp root whose owner is gone or that nothing touched for a day.
+ */
+export declare function sweepRoots(store: Store, pool: WorktreePool | null, census: readonly ProcessRow[], tempRoots: readonly string[], now: Date): SweepRoot[];
+export type OrphanStop = {
+    pid: number;
+    name: string;
+    where: string;
+    kind: SweepRoot["kind"];
+    ranMs: number;
+    killed: boolean;
+};
+export type OrphanSweep = {
+    stopped: OrphanStop[];
+    failed: string[];
+};
+export type OrphanOptions = StopOptions & {
+    actor?: string;
+    pool?: WorktreePool | null;
+    tempRoots?: readonly string[];
+    locate?: (pids: readonly number[]) => Map<number, Located>;
+    self?: number;
+};
+/** Stop the orphans Toolroll left (see the top of this file), each in the ledger. */
+export declare function sweepOrphans(store: Store, now: () => Date, options?: OrphanOptions): Promise<OrphanSweep>;
+export declare function durationWords(ms: number): string;