toolroll 0.9.31 → 0.9.32

package/dist/serve.js

@@ -3,6 +3,7 @@ import { aboutYouOf, checkAboutYou, saveAboutYou, ABOUT_YOU_LINE_MAX, ABOUT_YOU_
 import { withActor } from "./actor.js";
 import { repositoryContext, repositoryContextRead } from './repository-context.js';
 import { ADD_TESTS_ACTION, followUpChecksOf, requestFollowUpChecks, fileAddTestsTask, resultCheckLevel } from './result-follow-ups.js';
+import { projectBatchChecks, setProjectBatchChecks } from './batch-policy.js';
 import { CHECK_LEVEL_WORDS, isCheckLevel, liveQuickCommand, projectCheckLevel, quickVerifyKey, setProjectCheckLevel, suggestQuickCommand } from './check-levels.js';
 import { repositoryContextHtml } from './repository-context-ui.js';
 import { browserAssetsAvailable, browserWorkspaceDocument, serveBrowserAsset } from './browser-shell.js';
@@ -235,6 +236,7 @@ import { prometheusMetrics } from "./metrics.js";
 import { SPEND_CSS, spendCsv, spendHtml } from "./spend-ui.js";
 import { RETENTION_CSS, retentionHtml } from "./retention-ui.js";
 import { STORAGE_CSS, storageHtml } from "./storage-ui.js";
+import { lastSweep, saveSweep, storageSweepOff } from "./storage-sweep.js";
 import { bytesWords, parseCleanup } from "./storage.js";
 import { checkoutPlan, cleanCheckouts, discardCheckout, previewDigest } from "./checkout-cleanup.js";
 import { UPDATES_CSS, newerThan, updateStepsHtml, updatesHtml, updatesScript } from "./toolroll-update-ui.js";
@@ -4028,7 +4030,8 @@ export function createDecisionServer(options) {
             if (who.via !== "cookie" || !store.isInstanceOperator(who.name) || databaseFile === null)
                 return refuse(response, who, 403, "An instance operator looks after storage.", "/settings");
             const plan = await checkoutPlan(store, storagePool(databaseFile), now, { manual: true });
-            return sendScreen(response, 200, screen("Storage", `<p><a href="/settings">Settings</a></p><h1>Storage</h1>${storageHtml({ plan, csrf: who.session.csrf }, { said: url.searchParams.get("said"), problem: url.searchParams.get("problem") })}`, { chrome: chromeFor(project, "settings") }));
+            const sweep = { last: lastSweep(store), off: storageSweepOff() };
+            return sendScreen(response, 200, screen("Storage", `<p><a href="/settings">Settings</a></p><h1>Storage</h1>${storageHtml({ plan, csrf: who.session.csrf, sweep }, { said: url.searchParams.get("said"), problem: url.searchParams.get("problem") })}`, { chrome: chromeFor(project, "settings") }));
         }
         // Settings → Projects → Pull requests: one project's setup. Off, the checks run on open, so the page says
         // exactly what turning on would do, or what to fix first.
@@ -4053,7 +4056,7 @@ export function createDecisionServer(options) {
             const quick = liveQuickCommand(store, repo);
             const html = checkSettingsHtml({ repo, name: projectName(repo), csrf: who.session.csrf, canChange: who.role === "approver" && !store.isDemo(),
                 level: projectCheckLevel(store, repo).level, full: store.liveVerifyCommand(repo), quick, suggestion: quick === null ? suggestQuickCommand(repo) : null,
-                review: (({ on, source }) => ({ on, source }))(store.reviewSwitch(repo, clock())),
+                review: (({ on, source }) => ({ on, source }))(store.reviewSwitch(repo, clock())), batch: { on: projectBatchChecks(store, repo).on },
                 said: url.searchParams.get("said"), problem: url.searchParams.get("problem") });
             return sendScreen(response, 200, screen("Checks", `<p><a href="/projects">Projects</a></p><h1>Checks</h1>${html}`, { chrome: chromeFor(project, "projects") }));
         }
@@ -7541,6 +7544,7 @@ export function createDecisionServer(options) {
                 if (body.get("preview") !== previewDigest(plan))
                     return back("problem", "What a clean-up would remove changed since you looked. Check the list again.");
                 const done = await cleanCheckouts(store, pool, clock, { manual: true, actor: who.name, only: new Set(plan.go.map(one => one.path)) });
+                saveSweep(store, { at: clock().toISOString(), source: "manual", actor: who.name, 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) }] });
                 return back("said", done.removed.length === 0 ? "Nothing was removed: those checkouts are no longer ready to go." : `Removed ${done.removed.length} checkout${done.removed.length === 1 ? "" : "s"}, about ${bytesWords(done.freed)}. Their branches stay.`);
             }
             const done = await discardCheckout(store, pool, body.get("path") ?? "", now, who.name);
@@ -7602,6 +7606,12 @@ export function createDecisionServer(options) {
                 store.setReviewSwitch(repo, on, who.name, now);
                 return back("said", on ? "Automatic review is on." : "Automatic review is off.");
             }
+            // Batch checks: off by default; the ledger keeps before → after.
+            if (act === "batch") {
+                const on = body.get("on") === "1";
+                const changed = setProjectBatchChecks(store, repo, on, who.name, now);
+                return back("said", !changed.changed ? "Saved." : on ? "Batch checks are on." : "Batch checks are off.");
+            }
             if (act === "level") {
                 const level = body.get("level");
                 if (!isCheckLevel(level))
@@ -9672,7 +9682,8 @@ export function createDecisionServer(options) {
                 const onProgress = beginLiveTurn(opened.thread.id);
                 void runMateTurn({ store, who: principal, session: mateSession, thread: opened.thread, config: enabled.config, key: enabled.key, message, onProgress, channel: "console", ...(requestId === null ? {} : { requestId }), ...(focusTask === null && chatProject !== null ? { context: `Current project: ${projectName(chatProject)} (${chatProject}). Keep this conversation about that project unless the operator explicitly asks to broaden it; use it as the repo for project tools.` } : {}), ...(focusTask === null ? {} : { context: `Current task: ${focusTask.id}. Read it with get_task before answering or proposing changes. Read its currentExecution next and bind new actions to that exact execution. Never replace the target of a prior proposal with a newer revision. Keep this turn about that task unless the operator explicitly asks to broaden it.${resultContext}${modeContext}` }), fetcher: chatFetcher, ...(options.subscriptionChatRunner === undefined ? {} : { subscriptionRunner: options.subscriptionChatRunner }), clock, evidenceRoot })
                     .then(outcome => {
-                    if (!outcome.ok)
+                    // A turn that saved its outcome in the thread (one stopped at its deadline) is said there, once.
+                    if (!outcome.ok && !("saved" in outcome && outcome.saved === true))
                         noteMate(who.session.csrf, "turn" in outcome ? outcome.turn : null, outcome.message);
                     endLiveTurn(opened.thread.id, outcome.ok);
                 })
@@ -18282,7 +18293,8 @@ function mateBrowserMessages(rows, csrf, back, target = { task: null, project: n
         html: message.role === 'operator' ? `<p>${escape(message.text)}</p>` : renderChatText(message.text, askedBy.get(message.id)) + asked(message.turn),
         activity: message.activity, createdAt: message.createdAt,
         ...(() => {
-            const parts = message.turn === null ? [] : rows.proposals.filter(one => one.turn === message.turn)
+            // Under the lead's message only, as the server-rendered thread does: the person's message shares the turn.
+            const parts = message.turn === null || message.role === 'operator' ? [] : rows.proposals.filter(one => one.turn === message.turn)
                 .map(one => mateProposalCardParts(one, csrf, rows.pending !== null, rows.decisions.get(typeof one.payload['decision'] === 'number' ? one.payload['decision'] : -1) ?? null, back));
             return { cardsHtml: parts.map(one => one.html).join(''), cards: parts.map(one => one.card) };
         })(),
@@ -23024,9 +23036,16 @@ function followUpsFor(store, evidenceRoot, run, now) {
 const FOLLOW_UP_WORDS = { waiting: "waiting for a worker", running: "running", passed: "passed", failed: "failed", "not-run": "didn't run" };
 /** Run checks and Add tests, under the result's Checks: what ran since, then the two acts. */
 function followUpsHtml(followUps, runId, o) {
-    const rows = followUps.checks.map(one => `<li data-follow-up-check="${one.state}">${escape(CHECK_LEVEL_WORDS[one.level])} checks ${escape(FOLLOW_UP_WORDS[one.state])}` +
-        `${one.exitCode === null || one.state === "passed" ? "" : ` (exit ${one.exitCode})`} on <span class="mono">${escape(one.head.slice(0, 7))}</span>` +
-        `<span class="meta"> · ${one.why === "pull-request" ? "for the pull request" : escape(one.actor)}${one.note === null ? "" : ` · ${escape(one.note)}`}</span>` +
+    // A batch check names every result it ran with and the exact commit it tested (batch-checks.ts).
+    const batchHow = (one) => {
+        const peers = one.batch?.members.filter(member => member.run !== runId).map(member => member.task) ?? [];
+        return one.batch?.mode === "together" && peers.length > 0 ? ` together with ${peers.map(escape).join(", ")}`
+            : one.batch?.mode === "split" ? " on its own after its batch failed" : one.batch?.mode === "conflict" ? " on its own (it conflicted with another result)" : "";
+    };
+    const rows = followUps.checks.map(one => `<li data-follow-up-check="${one.state}"${one.why === "batch" ? ` data-batch="${escape(one.batch?.mode ?? "waiting")}"` : ""}>${escape(CHECK_LEVEL_WORDS[one.level])} checks ` +
+        `${escape(one.why === "batch" && one.state === "waiting" ? "waiting to check with other results" : FOLLOW_UP_WORDS[one.state])}${batchHow(one)}` +
+        `${one.exitCode === null || one.state === "passed" ? "" : ` (exit ${one.exitCode})`} on <span class="mono">${escape((one.tested ?? one.head).slice(0, 7))}</span>` +
+        `<span class="meta"> · ${one.why === "pull-request" ? "for the pull request" : one.why === "batch" ? "batch check" : escape(one.actor)}${one.note === null ? "" : ` · ${escape(one.note)}`}</span>` +
         `${one.logArtifactId === null ? "" : ` <a href="/r/${runId}/evidence/${one.logArtifactId}">Log</a>`}</li>`).join("");
     const hidden = `<input type="hidden" name="csrf" value="${escape(o.csrf)}"><input type="hidden" name="return" value="${escape(o.returnTo)}">`;
     const canCheck = followUps.quick || followUps.full;

package/dist/shared-deps.d.ts

@@ -1,12 +1,14 @@
 export declare const DEPS_FOLDER = "deps";
 /** A copy linked or made this recently is never removed by a clean-up: a lease may be about to link it. */
 export declare const SHARED_GRACE_MS: number;
+/** The daily storage sweep removes a copy no checkout uses and none has linked for this long. */
+export declare const SHARED_UNUSED_MS: number;
 export type SharedCopy = {
     key: string;
     /** The copy's folder, holding node_modules and ready.json. */
     dir: string;
     repo: string;
-    /** sha256 of the lockfile and package.json it was installed from. */
+    /** sha256 of the lockfile and package.json, excluding the project's own version (raw bytes in old copies). */
     lock: string;
     node: string;
     createdAt: string;
@@ -19,7 +21,8 @@ export declare function sharedDepsRoot(databaseFile: string): string;
 /** A setup whose whole effect is node_modules: `npm ci` or `npm install`, with plain flags only. */
 export declare function installsOnly(command: string): boolean;
 /**
- * The checkout's dependency identity: its npm lockfile and package.json, hashed together. null when there is no
+ * The checkout's dependency identity: its npm lockfile and package.json, hashed together without the root
+ * package's own version, as in release-check.mjs versionOnly(). null when either JSON file is invalid, there is no
  * lockfile, or the lockfile links local folders (workspaces, `file:`), whose links would point into the shared
  * folder instead of the checkout.
  */
@@ -35,6 +38,7 @@ export declare function sharingFor(args: {
         command: string;
         digest: string;
     };
+    root?: string;
 }): {
     key: string;
     lock: string;
@@ -92,3 +96,15 @@ export declare function unusedShared(root: string, checkouts: readonly {
 };
 /** Remove one copy or debris folder (read-only on disk, so made writable first). */
 export declare function removeShared(path: string): boolean;
+/**
+ * The daily sweep: remove each copy no checkout uses and none has linked for `unusedMs` (a week), and old debris.
+ * Right before a copy goes, who uses it and when it was last linked are read again; a copy a checkout picked up in
+ * between stays.
+ */
+export declare function pruneUnusedShared(root: string, checkouts: () => readonly {
+    path: string;
+    repo: string;
+}[], now: Date, unusedMs?: number): {
+    removed: SharedUse[];
+    failed: string[];
+};

package/dist/shared-deps.js

@@ -14,12 +14,13 @@
  * The link is read-only to the build. A checkout whose package.json or lockfile no longer matches the copy it links
  * gets its own install (the link goes, the approved setup runs there) and the shared copy is never touched; a copy
  * whose installed tree changed anyway is retired, never linked again. `toolroll storage clean` removes a copy no
- * checkout links or matches.
+ * checkout links or matches; the plane's daily storage sweep removes one no checkout has used for a week.
  */
 import { createHash, randomBytes } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, symlinkSync, utimesSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { markNeverIndex } from "./never-index.js";
 export const DEPS_FOLDER = "deps";
 const READY = "ready.json";
 const RETIRED = "retired";
@@ -28,6 +29,8 @@ const LINK_NOTE = ".toolroll-shared";
 const NODE_MODULES = "node_modules";
 /** A copy linked or made this recently is never removed by a clean-up: a lease may be about to link it. */
 export const SHARED_GRACE_MS = 60 * 60_000;
+/** The daily storage sweep removes a copy no checkout uses and none has linked for this long. */
+export const SHARED_UNUSED_MS = 7 * 24 * 60 * 60_000;
 /** A half-made copy (a crash mid-promotion) is debris after this long. */
 const PARTIAL_STALE_MS = 24 * 60 * 60_000;
 export function sharedDepsRoot(databaseFile) {
@@ -38,15 +41,20 @@ export function installsOnly(command) {
     return /^\s*npm\s+(?:ci|install|i)(?:\s+--?[A-Za-z][\w-]*(?:=[\w.@/:+-]+)?)*\s*$/.test(command);
 }
 /**
- * The checkout's dependency identity: its npm lockfile and package.json, hashed together. null when there is no
+ * The checkout's dependency identity: its npm lockfile and package.json, hashed together without the root
+ * package's own version, as in release-check.mjs versionOnly(). null when either JSON file is invalid, there is no
  * lockfile, or the lockfile links local folders (workspaces, `file:`), whose links would point into the shared
  * folder instead of the checkout.
  */
 export function lockDigest(checkout) {
+    return dependencyInputs(checkout)?.digest ?? null;
+}
+const digestPair = (lock, manifest) => createHash("sha256").update(lock).update("\u0000").update(manifest).digest("hex");
+function dependencyInputs(checkout) {
     let lock = null;
     for (const name of ["npm-shrinkwrap.json", "package-lock.json"]) {
         try {
-            lock = readFileSync(join(checkout, name));
+            lock = readFileSync(join(checkout, name), "utf8");
             break;
         }
         catch {
@@ -55,16 +63,75 @@ export function lockDigest(checkout) {
     }
     if (lock === null)
         return null;
-    let manifest;
     try {
-        manifest = readFileSync(join(checkout, "package.json"));
+        const manifest = readFileSync(join(checkout, "package.json"), "utf8");
+        const normalized = (text, isLock) => {
+            const json = JSON.parse(text);
+            if (json === null || typeof json !== "object" || Array.isArray(json))
+                throw Error("not an object");
+            delete json.version;
+            if (isLock && json.packages?.[""] !== undefined)
+                delete json.packages[""].version;
+            return JSON.stringify(json);
+        };
+        if (/"link"\s*:\s*true/.test(lock))
+            return null;
+        return { lock, manifest, digest: digestPair(normalized(lock, true), normalized(manifest, false)) };
     }
     catch {
         return null;
     }
-    if (/"link"\s*:\s*true/.test(lock.toString("utf8")))
-        return null;
-    return createHash("sha256").update(lock).update("\u0000").update(manifest).digest("hex");
+}
+/** Replace only root version values, preserving every other byte for comparison with a pre-normalization hash.
+ * The caller already parsed the JSON. Token offsets let compact and indented files keep their original layout. */
+function withRootVersion(text, version, isLock) {
+    const tokens = [...text.matchAll(/"(?:[^"\\]|\\.)*"|[{}[\]:,]|[^\s{}[\]:,]+/g)];
+    let cursor = 0;
+    const edits = [];
+    const value = (path) => {
+        const start = tokens[cursor++];
+        if (start[0] === "{") {
+            while (tokens[cursor][0] !== "}") {
+                const key = JSON.parse(tokens[cursor++][0]);
+                cursor++; // colon
+                value([...path, key]);
+                if (tokens[cursor][0] === ",")
+                    cursor++;
+            }
+            cursor++;
+        }
+        else if (start[0] === "[") {
+            let index = 0;
+            while (tokens[cursor][0] !== "]") {
+                value([...path, String(index++)]);
+                if (tokens[cursor][0] === ",")
+                    cursor++;
+            }
+            cursor++;
+        }
+        if ((path.length === 1 && path[0] === "version") ||
+            (isLock && path.length === 3 && path[0] === "packages" && path[1] === "" && path[2] === "version")) {
+            const end = tokens[cursor - 1];
+            edits.push({ start: start.index, end: end.index + end[0].length });
+        }
+    };
+    value([]);
+    for (const edit of edits.sort((a, b) => b.start - a.start))
+        text = text.slice(0, edit.start) + JSON.stringify(version) + text.slice(edit.end);
+    return text;
+}
+/** Old copies did not save the manifests. npm's hidden lock records their root version; reconstruct only those
+ * version fields and require the exact old raw digest. Never infer equality from the installed packages alone. */
+function matchesInputs(dir, ready, inputs) {
+    if (ready.lock === inputs.digest || ready.lock === digestPair(inputs.lock, inputs.manifest))
+        return true;
+    try {
+        const version = JSON.parse(readFileSync(join(dir, NODE_MODULES, ".package-lock.json"), "utf8")).version;
+        return typeof version === "string" && ready.lock === digestPair(withRootVersion(inputs.lock, version, true), withRootVersion(inputs.manifest, version, false));
+    }
+    catch {
+        return false;
+    }
 }
 const nodeSeen = new Map();
 /** The node a setup on this PATH would install with: version, platform and architecture (native modules differ). */
@@ -85,13 +152,32 @@ export function depsKey(repo, setupDigest, lock, node) {
 export function sharingFor(args) {
     if (!installsOnly(args.setup.command))
         return null;
-    const lock = lockDigest(args.worktree);
-    if (lock === null)
+    const inputs = dependencyInputs(args.worktree);
+    if (inputs === null)
         return null;
+    const lock = inputs.digest;
     const node = nodeIdentity();
     if (node === null)
         return null;
-    return { key: depsKey(args.repo, args.setup.digest, lock, node), lock, node };
+    const key = depsKey(args.repo, args.setup.digest, lock, node);
+    if (args.root !== undefined) {
+        let names = [];
+        try {
+            names = readdirSync(args.root).filter(name => /^[0-9a-f]{24}$/.test(name));
+        }
+        catch { /* no copies yet */ }
+        // Keep a currently linked copy first. Reusing its old directory preserves every existing checkout's links.
+        for (const name of new Set([linkedKey(args.worktree, args.root), key, ...names])) {
+            if (name === null)
+                continue;
+            const dir = join(args.root, name);
+            const ready = readReady(dir);
+            if (ready?.repo === args.repo && ready.setup === args.setup.digest && ready.node === node &&
+                readyCopy(args.root, name) !== null && matchesInputs(dir, ready, inputs))
+                return { key: name, lock, node };
+        }
+    }
+    return { key, lock, node };
 }
 function readReady(dir) {
     try {
@@ -179,6 +265,7 @@ export function linkInto(worktree, shared) {
             symlinkSync(join(shared, entry.name), join(at, entry.name), entry.isDirectory() ? (process.platform === "win32" ? "junction" : "dir") : "file");
         }
         writeFileSync(join(at, LINK_NOTE), `${shared}\n`, "utf8");
+        markNeverIndex(at);
         touch(dirname(shared));
         return "link";
     }
@@ -234,6 +321,8 @@ export function promoteInstall(args) {
     const partial = join(args.root, `${args.key}.partial-${process.pid}-${randomBytes(4).toString("hex")}`);
     try {
         mkdirSync(partial, { recursive: true });
+        // Spotlight leaves shared installs alone (never-index.ts).
+        markNeverIndex(args.root);
         renameSync(own, join(partial, NODE_MODULES));
     }
     catch {
@@ -317,12 +406,14 @@ export function sharedUse(root, checkouts) {
         }
         if (!existsSync(checkout.path))
             continue;
-        const lock = lockDigest(checkout.path);
-        if (lock === null)
+        const inputs = dependencyInputs(checkout.path);
+        if (inputs === null)
             continue;
-        for (const copy of copies)
-            if (!copy.retired && copy.repo === checkout.repo && copy.lock === lock)
+        for (const copy of copies) {
+            const ready = readReady(copy.dir);
+            if (!copy.retired && copy.repo === checkout.repo && ready !== null && matchesInputs(copy.dir, ready, inputs))
                 users.get(copy.key).add(checkout.path);
+        }
     }
     return copies.map(one => ({ ...one, checkouts: [...users.get(one.key)].sort() }));
 }
@@ -363,3 +454,26 @@ export function removeShared(path) {
         return false;
     }
 }
+/**
+ * The daily sweep: remove each copy no checkout uses and none has linked for `unusedMs` (a week), and old debris.
+ * Right before a copy goes, who uses it and when it was last linked are read again; a copy a checkout picked up in
+ * between stays.
+ */
+export function pruneUnusedShared(root, checkouts, now, unusedMs = SHARED_UNUSED_MS) {
+    const stale = (one) => one.checkouts.length === 0 && now.getTime() - Date.parse(one.usedAt) > unusedMs;
+    const removed = [];
+    const failed = [];
+    for (const one of sharedUse(root, checkouts()).filter(stale)) {
+        const fresh = sharedUse(root, checkouts()).find(other => other.key === one.key);
+        if (fresh === undefined || !stale(fresh))
+            continue;
+        if (removeShared(fresh.dir))
+            removed.push(fresh);
+        else
+            failed.push(fresh.dir);
+    }
+    for (const debris of sharedDebris(root, now))
+        if (!removeShared(debris))
+            failed.push(debris);
+    return { removed, failed };
+}

package/dist/staged-runtimes.d.ts

@@ -0,0 +1,42 @@
+/** A deploy or update that never finished keeps its stage this long (it may be resumed). */
+export declare const UNFINISHED_KEEP_MS: number;
+export declare const STAGED_FOLDER = "staged-upgrades";
+export type Stage = {
+    path: string;
+    name: string;
+    at: number;
+    finished: boolean;
+    prior: string | null;
+    keptAside: boolean;
+};
+export type StageKeep = "current" | "previous" | "newest" | "under way" | "kept-aside database";
+export type StagePlan = {
+    keep: {
+        path: string;
+        why: StageKeep;
+    }[];
+    go: Stage[];
+    refused: string | null;
+};
+/** The `browser-*` and `release-*` stages: real folders directly in staged-upgrades, newest first. */
+export declare function stagedRuntimes(stateDir: string): Stage[];
+/**
+ * Paths a runtime may be running from: the launchd services' definitions, every `toolroll` (or older
+ * `standing-orders`) command on PATH or under nvm, this process, and `extra`.
+ */
+export declare function runtimesInUse(extra?: readonly string[], home?: string, path?: string): string[];
+/** What stays and what goes now, and why. */
+export declare function stagePlan(stateDir: string, inUse: readonly string[], now: Date): StagePlan;
+export type StagePrune = {
+    removed: string[];
+    failed: string[];
+    refused: string | null;
+};
+/**
+ * Remove the stages that go. Right before each goes, the plan is made again (what's in use now) and the stage must
+ * still be a real folder directly in staged-upgrades.
+ */
+export declare function pruneStagedRuntimes(stateDir: string, now: Date, options?: {
+    inUse?: () => string[];
+    remove?: (path: string) => void;
+}): StagePrune;

package/dist/staged-runtimes.js

@@ -0,0 +1,191 @@
+/**
+ * Staged runtimes (`staged-upgrades/`): each deploy (scripts/deploy-browser.mjs, `browser-*`) and each `toolroll
+ * update` (`release-*`) stages a whole runtime, a few hundred MB with its database backup. Oct 4: 9 of them, 2.2 GB.
+ *
+ * Kept: the current runtime (one the service, a `toolroll` command or this process runs from), the one before it
+ * (its journal's way back), the newest stage, a deploy or update still under way (no finished journal) for a week,
+ * and a stage holding a database a failed update kept aside. Everything else of those two kinds goes — after a deploy
+ * and in the plane's daily storage sweep. `rollback-*` records and anything else in the folder are never touched.
+ * With no current runtime found, nothing goes: which one is safe to remove is then unknown.
+ */
+import { lstatSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve, sep } from "node:path";
+const DAY_MS = 86_400_000;
+/** A deploy or update that never finished keeps its stage this long (it may be resumed). */
+export const UNFINISHED_KEEP_MS = 7 * DAY_MS;
+export const STAGED_FOLDER = "staged-upgrades";
+/** The canonical path, even of something that doesn't exist (yet): its nearest existing folder, resolved, plus the rest. */
+function real(path) {
+    let at = resolve(path);
+    const rest = [];
+    for (let hops = 0; hops < 256; hops++) {
+        try {
+            return join(realpathSync(at), ...rest.reverse());
+        }
+        catch { /* not there */ }
+        const up = dirname(at);
+        if (up === at)
+            break;
+        rest.push(basename(at));
+        at = up;
+    }
+    return resolve(path);
+}
+const readJson = (file) => {
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        return parsed !== null && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** The `browser-*` and `release-*` stages: real folders directly in staged-upgrades, newest first. */
+export function stagedRuntimes(stateDir) {
+    const root = real(join(stateDir, STAGED_FOLDER));
+    let names = [];
+    try {
+        names = readdirSync(root);
+    }
+    catch {
+        return [];
+    }
+    const stages = [];
+    for (const name of names) {
+        if (!/^(browser|release)-/.test(name))
+            continue;
+        const path = join(root, name);
+        try {
+            if (!lstatSync(path).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const deploy = name.startsWith("browser-") ? readJson(join(path, "deployment.json")) : null;
+        const update = name.startsWith("release-") ? readJson(join(path, "update.json")) : null;
+        const journal = deploy ?? update;
+        const stamp = String(journal?.["deployedAt"] ?? journal?.["startedAt"] ?? journal?.["createdAt"] ?? "");
+        let at = Date.parse(stamp);
+        if (!Number.isFinite(at)) {
+            try {
+                at = statSync(path).mtimeMs;
+            }
+            catch {
+                at = 0;
+            }
+        }
+        const finished = deploy !== null ? deploy["phase"] === "deployed" : update !== null ? typeof update["finishedAt"] === "string" : false;
+        const from = update?.["from"];
+        const prior = typeof deploy?.["priorRuntime"] === "string" ? deploy["priorRuntime"] : typeof from?.dist === "string" ? from.dist : null;
+        let keptAside = false;
+        try {
+            keptAside = readdirSync(path).some(one => /^orders\.(?:kept|unreadable)\./.test(one));
+        }
+        catch {
+            keptAside = true;
+        }
+        stages.push({ path, name, at, finished, prior, keptAside });
+    }
+    return stages.sort((a, b) => b.at - a.at);
+}
+/**
+ * Paths a runtime may be running from: the launchd services' definitions, every `toolroll` (or older
+ * `standing-orders`) command on PATH or under nvm, this process, and `extra`.
+ */
+export function runtimesInUse(extra = [], home = homedir(), path = process.env["PATH"] ?? "") {
+    const found = [...extra];
+    const agents = join(home, "Library", "LaunchAgents");
+    try {
+        for (const name of readdirSync(agents).filter(one => one.startsWith("com.toolroll.") || one.startsWith("com.standing-orders."))) {
+            for (const match of readFileSync(join(agents, name), "utf8").matchAll(/<string>([^<]*staged-upgrades[^<]*)<\/string>/g))
+                found.push(match[1]);
+        }
+    }
+    catch { /* no launch agents here */ }
+    const commands = path.split(":").filter(Boolean).flatMap(dir => ["toolroll", "standing-orders"].map(bin => join(dir, bin)));
+    try {
+        for (const version of readdirSync(join(home, ".nvm", "versions", "node")))
+            for (const bin of ["toolroll", "standing-orders"])
+                commands.push(join(home, ".nvm", "versions", "node", version, "bin", bin));
+    }
+    catch { /* no nvm */ }
+    for (const command of commands) {
+        try {
+            lstatSync(command);
+            found.push(command);
+        }
+        catch { /* not there */ }
+    }
+    if (process.argv[1] !== undefined)
+        found.push(process.argv[1]);
+    return found;
+}
+/** The stage `path` lies in, or null. */
+function stageOf(stages, path) {
+    if (path === null || path === undefined || path === "")
+        return null;
+    for (const at of new Set([resolve(path), real(path)])) {
+        for (const stage of stages)
+            for (const base of new Set([stage.path, real(stage.path)])) {
+                if (at === base || at.startsWith(base + sep))
+                    return stage;
+            }
+    }
+    return null;
+}
+/** What stays and what goes now, and why. */
+export function stagePlan(stateDir, inUse, now) {
+    const stages = stagedRuntimes(stateDir);
+    const keep = new Map();
+    const current = inUse.map(path => stageOf(stages, path)).filter((one) => one !== null);
+    if (stages.length > 0 && current.length === 0)
+        return { keep: [], go: [], refused: "no staged runtime is in use, so which one runs now is unknown" };
+    for (const one of current)
+        keep.set(one.path, "current");
+    for (const one of current) {
+        const prior = stageOf(stages, one.prior) ?? stages.find(other => other.finished && other.path !== one.path && other.at < one.at) ?? null;
+        if (prior !== null && !keep.has(prior.path))
+            keep.set(prior.path, "previous");
+    }
+    if (stages[0] !== undefined && !keep.has(stages[0].path))
+        keep.set(stages[0].path, "newest");
+    for (const one of stages) {
+        if (keep.has(one.path))
+            continue;
+        if (one.keptAside)
+            keep.set(one.path, "kept-aside database");
+        else if (!one.finished && now.getTime() - one.at < UNFINISHED_KEEP_MS)
+            keep.set(one.path, "under way");
+    }
+    return { keep: [...keep].map(([path, why]) => ({ path, why })), go: stages.filter(one => !keep.has(one.path)), refused: null };
+}
+/**
+ * Remove the stages that go. Right before each goes, the plan is made again (what's in use now) and the stage must
+ * still be a real folder directly in staged-upgrades.
+ */
+export function pruneStagedRuntimes(stateDir, now, options = {}) {
+    const inUse = options.inUse ?? (() => runtimesInUse());
+    const first = stagePlan(stateDir, inUse(), now);
+    if (first.refused !== null)
+        return { removed: [], failed: [], refused: first.refused };
+    const root = real(join(stateDir, STAGED_FOLDER));
+    const removed = [];
+    const failed = [];
+    for (const one of first.go) {
+        const again = stagePlan(stateDir, inUse(), now);
+        if (again.refused !== null || !again.go.some(other => other.path === one.path))
+            continue;
+        try {
+            if (lstatSync(one.path).isSymbolicLink() || dirname(one.path) !== root)
+                continue;
+            (options.remove ?? (path => rmSync(path, { recursive: true, force: true, maxRetries: 3 })))(one.path);
+            removed.push(one.path);
+        }
+        catch {
+            failed.push(one.path);
+        }
+    }
+    return { removed, failed, refused: null };
+}

package/dist/storage-sweep.d.ts

@@ -0,0 +1,50 @@
+import { type Located } from "./orphan-sweep.js";
+import { type ProcessRow } from "./run-closeout.js";
+import type { Store } from "./store.js";
+import type { WorktreePool } from "./worktree.js";
+export declare const SWEEP_EVERY_MS = 86400000;
+/** A sweep that failed somewhere, or left work for later, runs again this soon. */
+export declare const RETRY_MS: number;
+export type SweepKind = "test temp" | "orphans" | "checkouts" | "runtimes" | "dependencies";
+export type SweepPart = {
+    kind: SweepKind;
+    count: number;
+    bytes: number;
+    failed: number;
+    more?: boolean;
+    problem?: string;
+    items: string[];
+};
+export type SweepRecord = {
+    at: string;
+    source: "automatic" | "manual";
+    actor: string;
+    parts: SweepPart[];
+};
+export type SweepDeps = {
+    databaseFile: string;
+    pool: WorktreePool | null;
+    tempRoots: readonly string[];
+    actor?: string;
+    census?: () => ProcessRow[];
+    locate?: (pids: readonly number[]) => Map<number, Located>;
+    inUse?: () => string[];
+    graceMs?: number;
+};
+export declare function storageSweepOff(env?: NodeJS.ProcessEnv): boolean;
+export declare function storageSweepDue(store: Store, now: Date): boolean;
+/** The daily sweep, when it's due and on: one worker takes it. Null when it wasn't this pass's to run. */
+export declare function dailyStorageSweep(store: Store, deps: SweepDeps, now: () => Date): Promise<SweepRecord | null>;
+/** One sweep, now, every part; saved and in the ledger. Each part's failure is its own: the others still run. */
+export declare function sweepStorage(store: Store, deps: SweepDeps, now: () => Date): Promise<SweepRecord>;
+/** Save what a sweep or a clean-up by hand did (the latest few are kept), with one ledger entry saying it. */
+export declare function saveSweep(store: Store, record: SweepRecord): SweepRecord;
+/** The latest sweep (of `source`, or either), or null when there has been none. */
+export declare function lastSweep(store: Store, source?: SweepRecord["source"]): SweepRecord | null;
+/** When the next automatic sweep is due, or null when it is off. */
+export declare function nextSweepAt(store: Store): string | null;
+export declare function partWords(one: Pick<SweepPart, "kind" | "count">): string;
+/** "Removed 120 test temp folders and 2 finished checkouts, about 1.2 GB. Stopped 1 leftover process. 3 couldn't be removed." */
+export declare function sweepWords(parts: readonly SweepPart[]): string;
+/** The details a disclosure shows: each part's paths, problems and what's left for later, one line each. */
+export declare function sweepDetails(parts: readonly SweepPart[]): string[];