toolroll 0.9.8 → 0.9.9

package/dist/needs-you.js

@@ -0,0 +1,83 @@
+/** Every reason a task, result or flow card can wait on a person, in one
+ * place: the plain sentence it shows and the one action that resolves it
+ * (task-status.ts reads it for every surface). A reason no person can act
+ * on is not Needs you: it is a Waiting reason, worded as what it waits for.
+ *
+ * The words never name the machine's internals; `plainSentence` keeps a
+ * recorded reason only when it is free of them. */
+const always = () => true;
+const build = (context) => context.build == null ? "the last build" : `build #${context.build}`;
+const Build = (context) => context.build == null ? "The last build" : `Build #${context.build}`;
+export const NEEDS = {
+    approval: { sentence: () => "Review the plan and approve it to start.", action: { code: "approve-scope", label: "Approve plan" } },
+    card: { sentence: () => "This card is waiting for your approval.", action: { code: "approve-card", label: "Approve card" } },
+    answer: { sentence: () => "Answer the question so the work can continue.", action: { code: "answer-decision", label: "Answer the question" }, useReason: always },
+    questions: { sentence: () => "Too many questions are open. Answer one so this task can start.", action: { code: "inspect-decisions", label: "Answer questions" } },
+    "sign-in": { sentence: context => `${context.provider ?? "Your agent"} needs you to sign in again. The task starts on its own after.`, action: { code: "sign-in", label: "Sign in again" }, useReason: reason => /sign in|API key/i.test(reason) },
+    "confirm-stopped": { sentence: context => `Toolroll can't confirm ${build(context)} stopped. Nothing from it is running.`, action: { code: "confirm-stopped", label: "Confirm it stopped" } },
+    // Toolroll can't look at all: never "nothing is running"; the person checks, says so, then confirms.
+    "check-stopped": { sentence: context => `Toolroll can't check whether ${build(context)} stopped. Make sure nothing from it is running, then confirm.`, action: { code: "confirm-stopped", label: "Confirm it stopped" } },
+    hold: { sentence: () => "A hold is keeping this task from starting. Review it to release it.", action: { code: "inspect-hold", label: "Review hold" } },
+    "choose-project": { sentence: () => "Choose a project so a builder can start.", action: { code: "place-task", label: "Choose a project" } },
+    "define-task": { sentence: () => "Say what the task should do so it can be planned.", action: { code: "write-scope", label: "Define the task" } },
+    "fix-request": { sentence: () => "The request can't be planned as written. Edit it so the planner can start.", action: { code: "write-scope", label: "Edit the request" } },
+    "choose-agent": { sentence: () => "Choose an agent to build this.", action: { code: "select-agent", label: "Choose an agent" } },
+    "fix-dependency": { sentence: () => "A task this one waits on didn't finish. Fix or remove it so this one can start.", action: { code: "repair-dependency", label: "Fix the required task" },
+        useReason: reason => /didn't finish|did not finish|before it finished/i.test(reason), withReason: reason => `${reason.replace(/[.\s]*$/, ".")} Fix or remove it so this one can start.` },
+    "add-requirement": { sentence: () => "This project is missing something the task needs. Add it so a builder can start.", action: { code: "repair-capability", label: "Add the requirement" } },
+    "connect-builder": { sentence: () => "No builder works on this project yet. Connect one so the task can start.", action: { code: "start-worker", label: "Connect a builder" } },
+    "start-builder": { sentence: () => "The builder for this project is offline. Start it and the task begins on its own.", action: { code: "start-worker", label: "Start the builder" } },
+    vanished: { sentence: context => `${Build(context)} stopped without finishing. Check it, then retry.`, action: { code: "reconcile-run", label: "Check the build" } },
+    "review-result": { sentence: () => "Check the result, then accept it or ask for changes.", action: { code: "open-result", label: "Review result" } },
+    // Accepting it would not help: it was built to terms that are no longer the plan.
+    rebuild: { sentence: context => `${Build(context)} was made to an earlier plan. Build it again to the current plan.`, action: { code: "retry-task", label: "Build again" } },
+    "earlier-version": { sentence: () => "An earlier version of this task still needs you. Finish it first.", action: { code: "inspect-task", label: "Open earlier version" } },
+    other: { sentence: () => "Open the task to see what it needs from you.", action: { code: "inspect-task", label: "Open the task" }, useReason: always },
+};
+export const WAITS = {
+    "build-stopping": context => `Waiting for ${build(context)} to stop. Nothing is needed from you.`,
+    "other-computer": context => `Waiting for the computer that ran ${build(context)} to confirm it stopped.`,
+    "card-reply": () => "Waiting for a reply.",
+    "card-time": () => "Waiting before moving on.",
+    "card-ci": () => "Waiting for the pull request's checks.",
+};
+/** Words that name the machine's internals; no Needs you or Waiting sentence carries them. */
+export const BANNED_WORDS = ["witness", "unproven", "quiescence", "quiescent", "digest", "scope digest"];
+const BANNED = new RegExp(`\\b(?:${BANNED_WORDS.join("|")})\\b`, "i");
+export const hasInternalWords = (text) => BANNED.test(text);
+/** The sentence for a need: its recorded reason when the need keeps one and
+ * it reads plainly, otherwise the need's own words. */
+export function needSentence(key, reason, context = {}) {
+    const need = NEEDS[key];
+    const plain = reason?.trim() || null;
+    if (need.useReason === undefined || plain === null || !need.useReason(plain) || hasInternalWords(plain))
+        return need.sentence(context);
+    return need.withReason === undefined ? plain : need.withReason(plain);
+}
+export function waitSentence(key, reason, context = {}) {
+    if (key !== undefined)
+        return WAITS[key](context);
+    const plain = reason?.trim() || null;
+    return plain !== null && !hasInternalWords(plain) ? plain : "Waiting for the work to continue on its own.";
+}
+/** A finished run Toolroll can't prove stopped (store.stopQuiescenceFact):
+ * a person can confirm it only when nothing of it may still be running.
+ * `unknown`: Toolroll can't check, so the person confirms they checked. */
+export function processNeedOf(fact) {
+    if (fact === null)
+        return null;
+    if (fact.kind === "unprovable")
+        return { need: "confirm-stopped", build: fact.run };
+    if (fact.kind === "unknown")
+        return { need: "check-stopped", build: fact.run };
+    return { wait: fact.kind === "elsewhere" ? "other-computer" : "build-stopping", build: fact.run };
+}
+/** Dispatch and work-index codes that wait on a person, as their need. */
+export const CODE_NEED = {
+    "signed-out": "sign-in", "needs-approval": "approval", "waiting-decision": "answer", "decision-queue": "answer",
+    "needs-project": "choose-project", "needs-scope": "define-task", "planner-source": "fix-request", "needs-agent-profile": "choose-agent",
+    "terminal-dependency": "fix-dependency", "missing-requirement": "add-requirement", "no-worker-registered": "connect-builder",
+    "no-worker-online": "start-builder", "vanished-run": "vanished", "needs-verification": "review-result", "proof-refuted": "review-result",
+    "no-build-record": "review-result", "verification-needed": "review-result", "evidence-mismatch": "review-result",
+    "record-incomplete": "review-result", "evidence-damaged": "review-result",
+};

package/dist/operate.d.ts

@@ -37,6 +37,8 @@ export type OperateOptions = {
     releaseIo?: ReleaseIo;
     /** Injected by tests: the bin whose real path says how Toolroll was installed. */
     installBin?: string;
+    /** Injected by tests: where `storage` looks for leftover test temp folders (default: the temp folder and /tmp). */
+    tempRoots?: readonly string[];
     openDatabase?: (file: string) => Store;
     now?: Date;
     /**

package/dist/operate.js

@@ -7,8 +7,11 @@ 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 { CLEANUP_CHOICES, bytesWords, cleanupWords, parseCleanup, storageReport } from "./storage.js";
-import { checkoutPlan, cleanCheckouts, discardCheckout, whyWords } from "./checkout-cleanup.js";
+import { CLEANUP_CHOICES, bytesWords, cleanupWords, diskBytes, parseCleanup, storageReport } from "./storage.js";
+import { removeStaleTestTemp, tempRoots, testTempFolders } from "./test-temp.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";
 import { MIN_DAYS, RETENTION_KINDS, countWords, dailyRetention, isRetentionKind, lastSweepAt, parsePeriod, periodLabel, 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";
@@ -73,6 +76,7 @@ import { pullRequestLines, runTaskMergeCommand, runTaskOutcomeCommand } from "./
  */
 import { homedir, hostname, tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
+import { releaseStalledUpdate, waitingUpdate } from "./toolroll-update.js";
 import { openStore, openStoreNoMigrate, CONCURRENT_WRITER_WAIT_MS, isDatabaseBusy, databasePath, BUILT_IN, DEFAULT_ACTOR, parseCapabilityKey, verifiedAuthor, contestantProfileOf, isDigestTime, } from "./store.js";
 import { randomBytes, randomInt, randomUUID } from "node:crypto";
 import { authorizePlanUnderMode } from "./plan-auto.js";
@@ -193,7 +197,7 @@ import { runModelsCommand } from "./models-cli.js";
 import { updateAdmissionPaused, UPDATE_PAUSED } from "./desktop-update-gate.js";
 import { beads } from "./beads.js";
 import { githubIssues } from "./issues.js";
-import { installationStatus, renderInstallationStatus, renderTaskWait, taskWaitSnapshot } from "./lead-status.js";
+import { installationStatus, renderInstallationStatus, renderTaskWait, repairStaleStatuses, taskWaitSnapshot } from "./lead-status.js";
 import { latestRelease, newerRelease, notifySecurityRelease, recordRunnerVersion, startUpdateChecks, updateLine } from "./releases.js";
 import { installMethod } from "./install-method.js";
 import { PACKAGE_VERSION } from "./version.js";
@@ -227,8 +231,8 @@ export const OPERATE_HELP = `toolroll — operating the queue
                                         how many of a project's tasks build at once (default 2, never past the
                                         worker's capacity); an approver changes it with <n>
   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                   where the disk goes: database, build checkouts, releases, evidence, leftover test temp folders
+  toolroll storage clean [--yes]     preview removing finished tasks' clean checkouts (their branches stay) and test temp folders older than a day; --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 integrations [--json]     which integrations work: Connected, Not set up or Broken, and what to do (--saved: no new checks)
@@ -807,6 +811,7 @@ export async function runOperate(command, argv, write, options = {}) {
             // it matters.
             evidenceRoot: join(dirname(file), "evidence"),
             databaseFile: file,
+            ...(options.tempRoots === undefined ? {} : { tempRoots: options.tempRoots }),
             // The bot token's file home. Never a column; see telegram.ts.
             telegramTokenFile: join(dirname(file), "telegram-token"),
             ...(options.desktopIdentity === undefined ? {} : { desktopIdentity: options.desktopIdentity }),
@@ -4397,10 +4402,21 @@ async function reconcileCommand(flags, context) {
         }
     }
     const recovered = recoverDead(store, clock());
+    // A run that ended, whatever its outcome, leaves nothing running: what is still in its process groups is stopped
+    // (SIGTERM, then SIGKILL after 10 s) and the ledger names it. Never the live service.
+    const closedRuns = await closeOutRuns(store, clock, { repo });
+    // A finished run's processes that have since gone get their exits recorded,
+    // so its task stops waiting on a person by itself.
+    store.recordFinishedRunExits(clock());
     // A witness reserved for a spawn that never made a process (a crash or a
     // thrown spawn) settles once its run's process groups are proven gone.
     store.settleUnspawnedWitnesses(clock());
     store.settleQuiescentStops(clock());
+    // An update whose updater ended while letting work finish must not leave new work paused.
+    try {
+        releaseStalledUpdate(dirname(context.databaseFile), clock());
+    }
+    catch { /* status and the console say it */ }
     for (const one of recovered) {
         for (const leaseId of one.claims) {
             // Lease ids are unique forever, so each recovery is its own episode.
@@ -4452,7 +4468,11 @@ async function reconcileCommand(flags, context) {
     }
     // 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.
+    // Completing or cancelling a task stops anything still running from its checkout first.
+    const closedCheckouts = await closeOutCheckouts(store, clock, finishedCheckouts(store, clock(), repo));
     const pruned = await cleanCheckouts(store, worktrees, clock, { manual: false, actor: "worker", repo });
+    // What stays for review or for its changes drops its dependencies and build output; the next run's setup restores them.
+    const slimmed = await slimKeptCheckouts(store, worktrees, clock, { 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 {
@@ -4468,6 +4488,9 @@ async function reconcileCommand(flags, context) {
         adoption.adopted.length === 0 &&
         adoption.forgotten.length === 0 &&
         pruned.removed.length === 0 &&
+        closedRuns.length === 0 &&
+        closedCheckouts.length === 0 &&
+        slimmed.slimmed.length === 0 &&
         liveSwept.removed.length === 0;
     return succeed(write, json, "reconcile", {
         recovered,
@@ -4476,6 +4499,8 @@ async function reconcileCommand(flags, context) {
         forgotten: adoption.forgotten,
         checkoutsRemoved: pruned.removed.map(one => one.path),
         checkoutsKept: pruned.kept,
+        processesStopped: [...closedRuns.map(one => ({ run: one.runId, pids: one.done.stopped.map(row => row.pid) })), ...closedCheckouts.map(one => ({ checkout: one.path, pids: one.done.stopped.map(row => row.pid) }))],
+        checkoutsSlimmed: slimmed.slimmed.map(one => one.path),
         liveViewsSwept: liveSwept.removed.length,
         retention: retention === null ? null : { counts: retention.counts, freedBytes: retention.freed },
     }, () => nothing
@@ -4486,6 +4511,9 @@ async function reconcileCommand(flags, context) {
             ...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} finished task checkout(s), about ${bytesWords(pruned.freed)}; their branches stay.`]),
+            ...closedRuns.map(one => `Run #${one.runId} ended; stopped ${stoppedWords(one.done)}.`),
+            ...closedCheckouts.map(one => `${one.path}: its task finished; stopped ${stoppedWords(one.done)}.`),
+            ...(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)}.`]),
         ]);
@@ -7259,6 +7287,8 @@ async function daemonCommand(positional, flags, context) {
 // ---- the watch loop --------------------------------------------------------
 const WATCH_LEASE_MS = 90_000;
 const WATCH_HEARTBEAT_MS = 30_000;
+/** The start repair runs once per process, not once per project loop. */
+let staleStatusesRepaired = false;
 async function runWatchLoop(args) {
     const { context, flags, runner, token, repo, progress } = args;
     const { store } = context;
@@ -7296,6 +7326,14 @@ async function runWatchLoop(args) {
     store.startWatchEpisode({ repo, runner, incarnation }, new Date());
     recordRunnerVersion(dirname(context.databaseFile), runner, PACKAGE_VERSION, new Date());
     args.onReady?.();
+    // Once per worker start, before any pass: statuses an older build left
+    // stale (unrecorded exits of finished runs) are re-derived and clear.
+    if (!staleStatusesRepaired) {
+        staleStatusesRepaired = true;
+        const repaired = repairStaleStatuses(store, new Date());
+        if (repaired.exitsRecorded > 0)
+            progress(`watch: recorded ${repaired.exitsRecorded} finished process exit(s) left open by an earlier version`);
+    }
     // A false renewal is FATAL (arc 2 finding 15): the lease or the
     // credential is gone, and admitting one more pass would be work done for
     // an authority this process no longer holds.
@@ -7792,7 +7830,8 @@ async function watchCommand(flags, context) {
             token,
             repo,
             progress,
-            isStopping: () => stopping,
+            // An injected fence (tests) stops admission exactly as a signal does.
+            isStopping: () => stopping || context.shouldStop?.() === true,
             onFollowController: controller => {
                 followAbort = controller;
             },
@@ -8836,6 +8875,10 @@ async function bridgeCommand(positional, flags, context) {
         const runFor = text(flags, "for");
         const timer = runFor === undefined ? null : setTimeout(() => controller.abort(), Number(runFor));
         timer?.unref?.();
+        // An injected fence (tests) ends the follow exactly as a signal does.
+        const fence = context.shouldStop === undefined ? null : setInterval(() => { if (context.shouldStop?.() === true)
+            controller.abort(); }, 50);
+        fence?.unref?.();
         if (!json)
             write(`Following bot ${source.botId} — taps apply as they arrive. Ctrl-C stops it.`);
         try {
@@ -8865,6 +8908,8 @@ async function bridgeCommand(positional, flags, context) {
         finally {
             if (timer !== null)
                 clearTimeout(timer);
+            if (fence !== null)
+                clearInterval(fence);
             process.removeListener("SIGINT", stop);
             process.removeListener("SIGTERM", stop);
         }
@@ -9528,10 +9573,13 @@ async function statusCommand(positional, flags, context) {
     const brokenIntegrations = await savedIntegrations(context).then(list => list.filter(one => one.state === "broken"), () => []);
     const brokenLine = integrationsBrokenLine(brokenIntegrations);
     const integrations = brokenIntegrations.length === 0 ? {} : { integrations: { broken: brokenIntegrations.map(one => ({ key: one.key, name: one.name, fix: one.action.kind === "fix" ? one.action.words : null })) } };
+    // An update waiting, on what, and the action: before anything else, as it holds up new work.
+    const waiting = waitingUpdate(context.databaseFile, run => context.store.stopQuiescenceProblem(run) !== null, context.clock());
+    const updateWaiting = waiting === null ? {} : { updateWaiting: { app: waiting.app, version: waiting.version, stopped: waiting.stopped, run: waiting.run, on: waiting.on, action: waiting.action } };
     const projects = projectBuildsStatus(context);
     const projectsLine = projects.length === 0 ? null
         : `Builds by project: ${projects.slice(0, 8).map(one => `${one.name} ${one.running} of ${one.limit}`).join(", ")}${projects.length > 8 ? ", …" : ""}`;
-    return succeed(context.write, context.json, command, { ...status, projects, ...update, ...integrations }, () => [...renderInstallationStatus(status), ...(projectsLine === null ? [] : [projectsLine]), ...(line === null ? [] : [line]), ...(brokenLine === null ? [] : [brokenLine])]);
+    return succeed(context.write, context.json, command, { ...status, projects, ...update, ...integrations, ...updateWaiting }, () => [...(waiting === null ? [] : [waiting.words]), ...renderInstallationStatus(status), ...(projectsLine === null ? [] : [projectsLine]), ...(line === null ? [] : [line]), ...(brokenLine === null ? [] : [brokenLine])]);
 }
 /** Each known project's running builds against its limit: its own number, never past its workers' capacity. */
 function projectBuildsStatus(context) {
@@ -12145,13 +12193,35 @@ async function storageCommand(positional, flags, context) {
         `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)})`}`;
+    // Test temp folders the tests, journeys and scripts left (a killed run, an older version): those nothing touched for a day go.
+    const roots = context.tempRoots ?? tempRoots();
+    // Counting is quick; sizing thousands of folders isn't, so only a clean-up measures them.
+    const leftovers = (measure) => {
+        const found = testTempFolders(roots, context.clock());
+        const sizes = measure ? diskBytes(found.stale.map(one => one.path)) : new Map();
+        return { count: found.all.length, stale: found.stale.length, staleBytes: [...sizes.values()].reduce((sum, one) => sum + one, 0) };
+    };
+    const leftoverLine = (temp) => temp.count === 0 ? "Test temp folders: none." :
+        `Test temp folders: ${temp.count}; ${temp.stale === 0 ? "none older than a day." : `${temp.stale} older than a day: toolroll storage clean removes them.`}`;
+    // Shared dependencies (shared-deps.ts): one install per lockfile, linked into checkouts.
+    const depsRoot = sharedDepsRoot(context.databaseFile);
+    const checkoutRows = () => store.listWorktrees().map(row => ({ path: row.path, repo: row.repo }));
+    const sharedFacts = (copies) => {
+        const sizes = diskBytes(copies.map(one => one.dir));
+        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)" : ""}`;
     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) }, () => [
+        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 }, () => [
             `${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}`}`),
+            ...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 }),
         ]);
     }
     if (action === "cleanup") {
@@ -12173,20 +12243,48 @@ async function storageCommand(positional, flags, context) {
             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)]),
+            const temp = leftovers(true);
+            // A shared copy goes when no checkout uses it, counting the checkouts this clean-up would remove.
+            const leaving = new Set(plan.go.map(one => one.path));
+            const unused = unusedShared(depsRoot, checkoutRows().filter(row => !leaving.has(row.path)), context.clock());
+            const sharedGo = sharedFacts(unused.copies);
+            const sharedBytes = sharedGo.reduce((sum, one) => sum + one.bytes, 0);
+            const anything = plan.go.length > 0 || temp.stale > 0 || sharedGo.length > 0;
+            return succeed(context.write, context.json, command, { preview: true, go: plan.go, stay: plan.stay, freeBytes: plan.freeBytes, testTemp: temp, sharedGo, sharedFreeBytes: sharedBytes }, () => [
+                ...(plan.go.length === 0 ? [anything ? "No checkouts to clean up." : "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)]),
+                ...(sharedGo.length === 0 ? [] : [`Would remove ${sharedGo.length} shared dependency install${sharedGo.length === 1 ? "" : "s"} no checkout uses, about ${bytesWords(sharedBytes)}:`, ...sharedGo.map(sharedLine)]),
                 ...(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.",
+                ...(temp.stale === 0 ? [] : [`Would remove ${temp.stale} test temp folder${temp.stale === 1 ? "" : "s"} older than a day, about ${bytesWords(temp.staleBytes)}.`]),
+                anything ? "Nothing was removed. Run toolroll storage clean --yes to remove them." : "Nothing was removed.",
             ]);
         }
         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.`,
+        const temp = leftovers(true);
+        const swept = removeStaleTestTemp(roots, context.clock());
+        if (swept.removed.length > 0) {
+            store.recordAction({ at: context.clock().toISOString(), actor, repo: null, taskId: null, runId: null, action: "test temp folders removed", outcome: "removed", source: "request",
+                detail: `${swept.removed.length} older than a day, about ${bytesWords(temp.staleBytes)}${swept.failed.length === 0 ? "" : `; ${swept.failed.length} couldn't be removed`}` });
+        }
+        // After the checkouts go: a shared copy none of the remaining ones uses goes too.
+        const unused = unusedShared(depsRoot, checkoutRows(), context.clock());
+        const sharedRemoved = sharedFacts(unused.copies).filter(one => removeShared(one.path));
+        for (const one of sharedRemoved) {
+            store.recordAction({ at: context.clock().toISOString(), actor, repo: one.repo, taskId: null, runId: null, action: "shared dependencies removed", outcome: "removed", source: "request",
+                detail: `${one.key} (about ${bytesWords(one.bytes)}); no checkout used it` });
+        }
+        for (const debris of unused.debris)
+            removeShared(debris);
+        const sharedFreed = sharedRemoved.reduce((sum, one) => sum + one.bytes, 0);
+        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),
+            ...(sharedRemoved.length === 0 ? [] : [`Removed ${sharedRemoved.length} shared dependency install${sharedRemoved.length === 1 ? "" : "s"} no checkout used, about ${bytesWords(sharedFreed)}.`, ...sharedRemoved.map(sharedLine)]),
             ...done.kept.map(one => `  kept ${one.path} (${whyWords({ why: one.why })})`),
+            ...(swept.removed.length === 0 ? [] : [`Removed ${swept.removed.length} test temp folder${swept.removed.length === 1 ? "" : "s"} older than a day, about ${bytesWords(temp.staleBytes)}.`]),
+            ...(swept.failed.length === 0 ? [] : [`Couldn't remove ${swept.failed.length} test temp folder${swept.failed.length === 1 ? "" : "s"}: ${swept.failed.slice(0, 3).join(", ")}${swept.failed.length > 3 ? " …" : ""}`]),
         ]);
     }
     if (action === "discard") {

package/dist/plane-review.js

@@ -148,6 +148,10 @@ export function reviewPlane(store, now, canSee = () => true) {
     for (const row of tasks) {
         if (!canSee(str(row["repo"])))
             continue;
+        // A version a later revision replaced never waits on its own.
+        const family = store.taskFamilyOf(String(row["id"]), null, true);
+        if (family !== null && family.current.id !== String(row["id"]))
+            continue;
         const snapshot = taskWaitSnapshot(store, String(row["id"]), now);
         if (snapshot === null || (snapshot.reason !== "needs-person" && snapshot.reason !== "ready"))
             continue;

package/dist/process-recovery-eligibility.d.ts

@@ -95,6 +95,7 @@ export declare function preparedCandidateObserverGapEligibility(store: Store, in
                     readonly items: readonly string[];
                     readonly gaps: readonly string[];
                     readonly priorSupport: "eligible" | "invalid" | "none";
+                    readonly assets?: string;
                 };
             }[];
             readonly machineVerdict: import("./store.js").ProofVerdictRow["verdict"] | null;

package/dist/project-learning.d.ts

@@ -48,9 +48,9 @@ export type LearningEvent = {
 };
 export declare const learningSha: (text: string) => string;
 /** Path plus the physical shared Git database: replacing a repository does not inherit its lessons. */
-export declare function learningIdentity(repo: string): string;
+export declare function learningIdentity(repo: string, seen?: Map<string, string>): string;
 /** Compare the applicable code and configuration, not model confidence or a claimed passing command. */
-export declare function learningFingerprint(repo: string, head: string, paths: readonly string[]): string;
+export declare function learningFingerprint(repo: string, head: string, paths: readonly string[], seen?: Map<string, string>): string;
 export declare function parseLearning(value: unknown): LearningCandidate[];
 /** A write problem is optional: preserve core completion, leave a visible diagnostic, retry on the next read/admission. */
 export declare function learningFailure(store: Store, repo: string, run: number | null, now: Date): void;
@@ -60,7 +60,7 @@ export declare function queueLearning(store: Store, source: number, reviewer: nu
     sha256: string;
 }[], now: Date, assessment?: unknown): void;
 /** Validate after core commit; both suggestions commit or neither. */
-export declare function recoverLearning(store: Store, root: string, repo: string, now?: Date): void;
+export declare function recoverLearning(store: Store, root: string, repo: string, now?: Date, seen?: Map<string, string>): void;
 export declare function learningView(store: Store, root: string, repo: string, actor: string, before?: number): {
     repo: string;
     identity: string;

package/dist/project-learning.js

@@ -44,12 +44,21 @@ CREATE TRIGGER IF NOT EXISTS learning_capture_no_delete BEFORE DELETE ON learnin
 export const learningSha = (text) => createHash('sha256').update(text).digest('hex');
 const text = (x, max) => typeof x === 'string' && x.trim().length > 0 && Buffer.byteLength(x) <= max && !/[\x00-\x1f\x7f]/.test(x);
 const pathOk = (x) => text(x, 300) && !x.startsWith('/') && !x.includes('\\') && !/^[A-Za-z]:/.test(x) && x.split('/').every(p => p !== '.' && p !== '..' && p !== '') && !/[\*?\[\]:]/.test(x);
-const git = (repo, args) => execFileSync('git', ['--no-optional-locks', '-C', repo, ...args], { encoding: 'utf8', maxBuffer: 2 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] }).trimEnd();
+/** One read per distinct command within a single selection pass (`seen`), so a pass over many lessons reads the repository once. */
+const git = (repo, args, seen) => {
+    const key = JSON.stringify([repo, args]);
+    const known = seen?.get(key);
+    if (known !== undefined)
+        return known;
+    const out = execFileSync('git', ['--no-optional-locks', '-C', repo, ...args], { encoding: 'utf8', maxBuffer: 2 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] }).trimEnd();
+    seen?.set(key, out);
+    return out;
+};
 /** Path plus the physical shared Git database: replacing a repository does not inherit its lessons. */
-export function learningIdentity(repo) {
+export function learningIdentity(repo, seen) {
     if (canonicalProject(repo) !== repo)
         throw new Error('Project identity changed.');
-    const common = realpathSync(resolve(repo, git(repo, ['rev-parse', '--git-common-dir'])));
+    const common = realpathSync(resolve(repo, git(repo, ['rev-parse', '--git-common-dir'], seen)));
     const st = statSync(common);
     return learningSha(JSON.stringify([repo, common, st.dev, st.ino, st.birthtimeMs]));
 }
@@ -59,10 +68,10 @@ function environmentFingerprint(store, repo) {
 }
 const configPath = (p) => /(^|\/)(AGENTS\.md|package(-lock)?\.json|[^/]*lock[^/]*|[^/]*config[^/]*|Cargo\.toml|go\.mod|pyproject\.toml|\.tool-versions|\.nvmrc)$/.test(p);
 /** Compare the applicable code and configuration, not model confidence or a claimed passing command. */
-export function learningFingerprint(repo, head, paths) {
+export function learningFingerprint(repo, head, paths, seen) {
     if (!/^[a-f0-9]{40,64}$/.test(head))
         throw new Error('No exact source revision.');
-    const entries = git(repo, ['ls-tree', '-r', head]).split('\n').filter(line => {
+    const entries = git(repo, ['ls-tree', '-r', head], seen).split('\n').filter(line => {
         const p = line.slice(line.indexOf('\t') + 1);
         return paths.includes(p) || configPath(p);
     });
@@ -198,7 +207,7 @@ function verifyEvidence(store, root, source, evidence, catalog) {
 // missing work, so newer reviews cannot starve an older recovery.
 const recoveryCursors = new WeakMap();
 /** Validate after core commit; both suggestions commit or neither. */
-export function recoverLearning(store, root, repo, now = new Date()) {
+export function recoverLearning(store, root, repo, now = new Date(), seen = new Map()) {
     let projects = recoveryCursors.get(store);
     if (!projects)
         recoveryCursors.set(store, projects = new Map());
@@ -225,7 +234,7 @@ export function recoverLearning(store, root, repo, now = new Date()) {
             if (!source || !reviewer || source.taskRef !== reviewer.taskRef)
                 continue;
             const snapshot = reviewSnapshot(store, reviewer.id);
-            if (!snapshot || snapshot['identity'] !== learningIdentity(repo))
+            if (!snapshot || snapshot['identity'] !== learningIdentity(repo, seen))
                 continue;
             const response = store.artifactsFor(reviewer.id).find(a => a.kind === 'structured-output' && a.captureStatus === 'ok');
             const read = response && readVerifiedArtifact(root, response);
@@ -260,7 +269,7 @@ export function recoverLearning(store, root, repo, now = new Date()) {
                 if (!run || !reviewed || reviewed.outcome !== 'no-change' || reviewed.taskRef !== run.taskRef || reviewed.role !== 'reviewer' || reviewedSource(store, reviewer) !== source || store.refForId(run.taskRef)?.repo !== repo)
                     throw new Error('Learning review provenance is unavailable.');
                 const candidates = parseLearning(JSON.parse(String(row['payload'])));
-                const identity = learningIdentity(repo);
+                const identity = learningIdentity(repo, seen);
                 if (identity !== row['identity'])
                     throw new Error('Learning project identity changed.');
                 const head = run.headRevision ?? run.baseRevision ?? '';
@@ -273,7 +282,7 @@ export function recoverLearning(store, root, repo, now = new Date()) {
                     verifyEvidence(store, root, source, c.evidence, JSON.parse(String(row['catalog'])));
                     if (c.paths.some(p => !patch.split('\n').some(l => l === `+++ b/${p}` || l === `--- a/${p}`)))
                         throw new Error('Learning applicability must name reviewed files.');
-                    const payload = JSON.stringify({ ...c, environment: String(row['environment']), fingerprint: learningFingerprint(repo, head, c.paths), platform: process.platform, head });
+                    const payload = JSON.stringify({ ...c, environment: String(row['environment']), fingerprint: learningFingerprint(repo, head, c.paths, seen), platform: process.platform, head });
                     const finding = learningSha(JSON.stringify(c));
                     store.handle.prepare("INSERT OR IGNORE INTO project_lesson(repo,identity,source,reviewer,finding,payload,sha,status) VALUES (?,?,?,?,?,?,?,'proposed')").run(repo, identity, source, reviewer, finding, payload, learningSha(payload));
                     const id = Number(store.handle.prepare('SELECT id FROM project_lesson WHERE source=? AND finding=?').get(source, finding)['id']);
@@ -302,15 +311,15 @@ function lessonOf(row) {
     parseLearning([payload]);
     return { id: Number(row['id']), repo: String(row['repo']), source: Number(row['source']), reviewer: Number(row['reviewer']), status: String(row['status']), version: Number(row['version']), payload, sha: String(row['sha']), identity: String(row['identity']), adoptedBy: row['adopted_by'] == null ? null : String(row['adopted_by']) };
 }
-function supported(store, root, lesson) {
-    if (lesson.identity !== learningIdentity(lesson.repo))
+function supported(store, root, lesson, seen) {
+    if (lesson.identity !== learningIdentity(lesson.repo, seen))
         throw new Error('Project identity changed.');
     const capture = store.handle.prepare('SELECT catalog FROM learning_capture WHERE source=? AND reviewer=? AND repo=?').get(lesson.source, lesson.reviewer, lesson.repo);
     if (!capture || reviewedSource(store, lesson.reviewer) !== lesson.source)
         throw new Error('Learning source is unavailable.');
     verifyEvidence(store, root, lesson.source, lesson.payload.evidence, JSON.parse(String(capture['catalog'])));
     const run = store.getRun(lesson.source);
-    if ((run?.headRevision ?? run?.baseRevision) !== lesson.payload.head || learningFingerprint(lesson.repo, lesson.payload.head, lesson.payload.paths) !== lesson.payload.fingerprint)
+    if ((run?.headRevision ?? run?.baseRevision) !== lesson.payload.head || learningFingerprint(lesson.repo, lesson.payload.head, lesson.payload.paths, seen) !== lesson.payload.fingerprint)
         throw new Error('Learning source changed.');
 }
 export function learningView(store, root, repo, actor, before = 0) {
@@ -377,15 +386,17 @@ export function learningContext(store, root, runId, phase, now = new Date(), val
     const run = store.getRun(runId), ref = run && store.refForId(run.taskRef), repo = ref?.repo;
     if (!run || !repo)
         return '';
+    // One read of the repository per command for this whole pass, recovery included.
+    const seen = new Map();
     try {
-        recoverLearning(store, root, repo, now);
+        recoverLearning(store, root, repo, now, seen);
         return store.transact(() => {
             if (!store.schemaCurrent() || run.outcome !== null || !['planner', 'builder', 'repair', 'reviewer'].includes(run.role))
                 return '';
             const runner = store.getRunner(run.runner)?.runner;
             if (!runner || runner.retiredAt !== null || !runner.repos.includes(repo) || (phase === 'review') !== (run.role === 'reviewer') || (phase === 'plan') !== (run.role === 'planner'))
                 return '';
-            const identity = learningIdentity(repo);
+            const identity = learningIdentity(repo, seen);
             const existing = store.handle.prepare('SELECT * FROM learning_snapshot WHERE run=?').get(runId);
             if (existing) {
                 if (existing['repo'] !== repo || existing['identity'] !== identity || learningSha(String(existing['payload'])) !== existing['sha'])
@@ -409,11 +420,11 @@ export function learningContext(store, root, runId, phase, now = new Date(), val
                         const l = lessonOf(row);
                         if (!store.handle.prepare("SELECT 1 FROM learning_event WHERE lesson=? AND action='adopt' AND actor=?").get(l.id, l.adoptedBy ?? '') || l.source === source?.id || l.payload.kind !== 'project' || !l.adoptedBy || !store.accountCanAccess(l.adoptedBy, repo) || store.accountOf(l.adoptedBy)?.role !== 'approver' || !l.payload.phases.includes(phase) || l.payload.platform !== process.platform || (!unscopedPlan && !l.payload.paths.some(p => paths.some(t => p === t || p.startsWith(t.replace(/\/$/, '') + '/')))))
                             continue;
-                        supported(store, root, l);
-                        if (l.payload.environment !== environmentFingerprint(store, repo) || learningFingerprint(repo, head, l.payload.paths) !== l.payload.fingerprint)
+                        supported(store, root, l, seen);
+                        if (l.payload.environment !== environmentFingerprint(store, repo) || learningFingerprint(repo, head, l.payload.paths, seen) !== l.payload.fingerprint)
                             continue;
                         const cwd = run.worktree ?? repo;
-                        const dirty = git(cwd, ['status', '--porcelain', '--untracked-files=all']).split('\n').some(line => { const p = line.slice(3); return configPath(p) || l.payload.paths.includes(p); });
+                        const dirty = git(cwd, ['status', '--porcelain', '--untracked-files=all'], seen).split('\n').some(line => { const p = line.slice(3); return configPath(p) || l.payload.paths.includes(p); });
                         if (!dirty)
                             eligible.push(l);
                     }

package/dist/proof.d.ts

@@ -266,7 +266,7 @@ export type VerifyCommandFacts = {
     configured: true;
     ran: false;
     attemptFailed: true;
-    failure?: "spawn-failed" | "timed-out" | "dependency-missing" | "setup-stale" | "setup-failed" | "tracked-files-changed" | "setup-changed-files" | "checkout-moved" | "cleanliness-unavailable" | "dependency-still-missing" | "retry-spawn-failed" | "retry-timed-out" | "custody-lost";
+    failure?: "spawn-failed" | "timed-out" | "dependency-missing" | "setup-stale" | "setup-failed" | "own-install-failed" | "tracked-files-changed" | "setup-changed-files" | "checkout-moved" | "cleanliness-unavailable" | "dependency-still-missing" | "retry-spawn-failed" | "retry-timed-out" | "custody-lost";
 } | {
     configured: true;
     ran: true;
@@ -390,6 +390,8 @@ export type CriterionCoverage = {
      * context: eligible only with the same text, verified ancestry, and
      * byte-identical relevant code. Never a judgement on this run. */
     priorSupport: "eligible" | "invalid" | "none";
+    /** The change's images and other binary files in one line, when it has any. */
+    assets?: string;
 };
 /** v40: the three words an evidence reviewer can say about one signed
  * criterion, and nothing else — `cannot-tell` is a CORRECT answer whenever

package/dist/proof.js

@@ -722,7 +722,7 @@ function assessCapturedEvidence(input) {
             id: criterion.id, statement: criterion.statement, requiredEvidence: criterion.evidence,
             assessment: { evidenceState, detail }, state: evidenceState === "pass" ? "missing" : evidenceState,
             detail: [...detail, `criterion "${criterion.id}" awaits independent goal assessment`], answered, review: null,
-            ...(coverage === undefined ? {} : { coverage: { state: coverage.state, inherited: coverage.inherited, items: [...coverage.items], gaps: [...coverage.gaps], priorSupport: coverage.priorSupport } }),
+            ...(coverage === undefined ? {} : { coverage: { state: coverage.state, inherited: coverage.inherited, items: [...coverage.items], gaps: [...coverage.gaps], priorSupport: coverage.priorSupport, ...(coverage.assets === undefined ? {} : { assets: coverage.assets }) } }),
         };
     });
     return { machineVerdict, verdict: machineVerdict === "refuted" ? "refuted" : "short", matrix,
@@ -761,6 +761,8 @@ function verificationFailureWords(failure) {
                 return "automatic recovery stopped because the project setup or check changed";
             case "setup-failed":
                 return "the approved setup command failed during automatic recovery";
+            case "own-install-failed":
+                return "the checkout's own dependency install failed after its package.json or lockfile changed";
             case "tracked-files-changed":
                 return "automatic recovery stopped because tracked files no longer matched the built result";
             case "setup-changed-files":
@@ -828,7 +830,7 @@ export function adjudicate(input) {
         // must show, never a silent "judged from the patch".
         const coverage = found === undefined
             ? { state: "gap", inherited: false, items: [], gaps: ["the sealed review context carries no coverage entry for this criterion"], priorSupport: "none" }
-            : { state: found.state, inherited: found.inherited, items: [...found.items], gaps: [...found.gaps], priorSupport: found.priorSupport };
+            : { state: found.state, inherited: found.inherited, items: [...found.items], gaps: [...found.gaps], priorSupport: found.priorSupport, ...(found.assets === undefined ? {} : { assets: found.assets }) };
         return { ...row, coverage };
     });
     if (!input.proofArtifactPresent) {

package/dist/result-completion.d.ts

@@ -6,6 +6,10 @@
 import type { Store } from "./store.js";
 /** The ledger action a person's (or lead's) completion of a result writes. */
 export declare const COMPLETION_ACTION = "assignment handoff checked";
+/** Whether a task's family is marked complete. Completion is recorded on the
+ * family's root against its current version's latest result, so the root, a
+ * superseded revision and the current version all read Complete together. */
+export declare function familyCompleted(store: Store, taskId: string): boolean;
 /** The files a build changed, renames on both sides; null when the inventory can't be read whole. */
 export declare function changedFilesOf(store: Store, runId: number, root: string): string[] | null;
 /** Everything a result's branch carries: this build's changes and every build of every task it revises (a