toolroll 0.9.104 → 0.9.105

package/dist/storage-sweep-schedule.js

@@ -1,55 +1,35 @@
-/**
- * When the automatic storage sweep (storage-sweep.ts) starts, and what `toolroll storage` and Settings → Storage say
- * about it. A sweep is due a day after the last one (an hour after one that failed somewhere). Once due, the
- * long-lived Toolroll service looks at most every 15 minutes and starts it only while nothing is running or waiting:
- * no open run, no live claim and no task a worker could claim now. Work held by an approval, a hold or a provider limit
- * is not waiting to start, so it never defers the sweep. 48 hours after the last automatic sweep it runs anyway: its
- * scans run in a low-priority child, and every removal asks again whether live work uses the folder.
- *
- * Only the service claims a sweep (it passes its owner): a one-shot `toolroll reconcile` exits before a child would
- * finish, and a claim it made would be lost until the next day. The idle gates are asked again inside the transaction
- * that claims the sweep, so work that started since the first look still defers it.
- */
 import { diagnoseTaskDispatch, diagnosisIsDispatchable } from "./dispatch.js";
 import { lastSweep, RETRY_MS, saveSweep, storageSweepOff, sweepFailure, SWEEP_CURSOR, SWEEP_EVERY_MS } from "./storage-sweep.js";
 import { storageSweepSupervisor, SWEEP_KILL_GRACE_MS, SWEEP_TIMEOUT_MS } from "./storage-sweep-process.js";
 import { openStoreNoMigrate } from "./store.js";
-/** How often the service looks again at a due sweep. */
 export const SWEEP_CHECK_MS = 15 * 60_000;
-/** After this long without an automatic sweep, it runs even while work is running or waiting. */
 export const SWEEP_FORCE_MS = 48 * 3_600_000;
-/** What keeps a due sweep waiting now, or null when nothing is running or waiting. */
 export function sweepBusy(store, now) {
     const db = store.handle;
     if (db.prepare("SELECT 1 FROM run WHERE finished_at IS NULL LIMIT 1").get() !== undefined)
         return "run";
     if (db.prepare("SELECT 1 FROM claim WHERE released_at IS NULL AND expires_at > ? LIMIT 1").get(now.toISOString()) !== undefined)
         return "claim";
-    // Ready means a worker could claim it now: the same answer the task page gives, not merely queued.
     if (store.listReady(now).some(ref => diagnosisIsDispatchable(diagnoseTaskDispatch(store, ref.externalId, now))))
         return "ready";
     return null;
 }
-/** Whether a long-lived Toolroll service holds a current lease. Rows from earlier services don't count. */
 export function sweepServiceRunning(store, now) {
     return store.handle.prepare("SELECT 1 FROM watch_lease WHERE owner GLOB 'toolroll-service:*' AND expires_at > ? LIMIT 1").get(now.toISOString()) !== undefined;
 }
 const dueAt = (store) => store.serviceCursor(SWEEP_CURSOR) + SWEEP_EVERY_MS;
-/** Count from the last result, or the durable installation time before the first result. */
 function forcedFrom(store, last) {
     if (last !== null)
         return Date.parse(last.at);
     const installed = store.installationFact("installed-at");
     return installed === null ? null : Date.parse(installed);
 }
-/** The sweep's schedule from what is recorded now; reads only. */
 export function sweepSchedule(store, now, env = process.env) {
     const last = lastSweep(store, "automatic");
     const lastAt = last?.at ?? null;
     if (storageSweepOff(env))
         return { state: "off", lastAt, nextAt: null, busy: null };
     const cursor = store.serviceCursor(SWEEP_CURSOR);
-    // Results record completion time, which may be later than the claim. An older result cannot finish a new claim.
     if (cursor !== 0 && now.getTime() - cursor < SWEEP_TIMEOUT_MS + SWEEP_KILL_GRACE_MS && now.getTime() >= cursor && (lastAt === null || Date.parse(lastAt) < cursor)) {
         return { state: "sweeping", lastAt, nextAt: null, busy: null };
     }
@@ -58,7 +38,6 @@ export function sweepSchedule(store, now, env = process.env) {
     if (!sweepServiceRunning(store, now))
         return { state: "no-service", lastAt, nextAt, busy: null };
     if (nextAt !== null) {
-        // Completion can follow the claim: elapsed sweep time alone does not mean a retry.
         const retry = last !== null && Date.parse(last.at) >= cursor && last.parts.some(one => one.failed > 0 || one.more === true || one.problem !== undefined);
         return { state: retry ? "retry" : "recent", lastAt, nextAt, busy: null };
     }
@@ -69,7 +48,6 @@ export function sweepSchedule(store, now, env = process.env) {
     return { state: busy === null ? "due" : "busy", lastAt, nextAt: null, busy };
 }
 const BUSY_WORDS = { run: "work is running", claim: "a worker is starting a task", ready: "a task is ready to start" };
-/** Why the sweep is waiting or when it is next due, after "Automatic sweep: ". `when` formats a time for the reader. */
 export function sweepScheduleWords(schedule, when) {
     switch (schedule.state) {
         case "off": return "off.";
@@ -82,17 +60,11 @@ export function sweepScheduleWords(schedule, when) {
         case "due": return "due; it starts within 15 minutes while nothing is running.";
     }
 }
-// The last look per flight, so a due sweep is looked at no more than every 15 minutes.
 const looked = new WeakMap();
-/**
- * The service's claim and launch. A one-shot caller has no `owner` and never claims. A hung child never holds
- * reconciliation or the caller's store open; the result is saved by the flight's own connection.
- */
 export function idleStorageSweep(store, deps, now, supervisor = storageSweepSupervisor(deps.databaseFile)) {
     if (deps.owner === undefined || storageSweepOff() || supervisor.running)
         return null;
     const at = now();
-    // Older installations have no creation fact. Anchor once on their first service pass; never backdate a claim.
     if (store.installationFact("installed-at") === null)
         store.recordInstallationFact("installed-at", at.toISOString(), at);
     if (at.getTime() < dueAt(store))
@@ -109,7 +81,6 @@ export function idleStorageSweep(store, deps, now, supervisor = storageSweepSupe
     };
     if (!ready())
         return null;
-    // This handle belongs to the flight, not to the pass that has already returned by the time it finishes.
     const connection = openStoreNoMigrate(deps.databaseFile);
     if (!connection.ok)
         throw new Error("Sweep result store unavailable");
@@ -117,7 +88,6 @@ export function idleStorageSweep(store, deps, now, supervisor = storageSweepSupe
     let completed = null;
     let owned = false;
     try {
-        // Asked again where the cursor moves: work that started since the first look still defers the sweep.
         const mine = store.transact(() => {
             if (!ready())
                 return false;
@@ -134,7 +104,6 @@ export function idleStorageSweep(store, deps, now, supervisor = storageSweepSupe
                     if (!results.schemaCurrent())
                         throw new Error("Sweep result store changed");
                     saveSweep(results, record);
-                    // Only this claim can reschedule itself. A later claim must never be overwritten by a late callback.
                     if (record.parts.some(one => one.failed > 0 || one.more === true || one.problem !== undefined) && results.serviceCursor(SWEEP_CURSOR) === at.getTime()) {
                         results.setServiceCursor(SWEEP_CURSOR, Math.max(1, now().getTime() - SWEEP_EVERY_MS + RETRY_MS), now());
                     }
@@ -142,7 +111,6 @@ export function idleStorageSweep(store, deps, now, supervisor = storageSweepSupe
                 completed = record;
             }
             catch {
-                // No exception/path from a process or database is safe to copy into a log.
                 console.error("Could not save the storage sweep result.");
             }
             finally {

package/dist/storage-sweep.js

@@ -1,28 +1,3 @@
-/**
- * The storage sweep: the plane cleans up after itself without anyone running a command. About once a day, when nothing
- * is running or waiting (storage-sweep-schedule.ts: one service takes it, the cursor moves in the same transaction),
- * it removes test temp folders nothing touched for a day (test-temp.ts), stops orphans Toolroll left running (orphan-sweep.ts), removes finished checkouts the cleanup
- * setting lets go and idle ones past the idle limit (checkout-cleanup.ts), keeps the current, previous and newest staged runtimes (staged-runtimes.ts)
- * and removes shared dependency installs no checkout has used for a week (shared-deps.ts).
- *
- * Nothing live work uses goes (`liveWork`): while a run is open, a lease current or a checkout in use, each removal
- * and each signal first asks again whether that work uses the folder, and when its processes can't be read nothing
- * goes. Every scan and removal runs in a separate child: synchronous disk work must never delay the worker's lease
- * heartbeats (a lease lasts a minute). On Oct 12 the sweep starved those heartbeats and three builds ended interrupted half a second
- * after it finished. Once a run has ended, the next sweep removes what
- * it no longer uses.
- *
- * The everyday work stays where it happens: suites remove their own temp roots and processes, a run's processes stop
- * when it ends and a finished checkout goes on the worker's next pass. This is the net for what slipped through.
- *
- * The last part is rows, not disk: test results and flaky-test observations past their 180 days (check history).
- *
- * What each sweep did is saved (the latest few) and in the ledger: `toolroll storage` and Settings → Storage show it.
- * A clean-up by hand (`storage clean --yes`) is saved the same way. A part that failed, or had more than one pass
- * takes, brings the next sweep forward to an hour later; it still waits for nothing to be running.
- * `TOOLROLL_STORAGE_SWEEP=off` turns the automatic sweep off (the unit tests do, so a test never sweeps the machine
- * it runs on).
- */
 import { realpathSync } from "node:fs";
 import { dirname, join, resolve, sep } from "node:path";
 import { pruneCheckResults } from "./check-facts.js";
@@ -41,13 +16,9 @@ import { worktreeProcessOccupancy } from "./worktree.js";
 import { runSweepChild } from "./storage-sweep-process.js";
 export const SWEEP_CURSOR = "storage-sweep";
 export const SWEEP_EVERY_MS = 86_400_000;
-/** A sweep that failed somewhere, or left work for later, runs again this soon. */
 export const RETRY_MS = 60 * 60_000;
-/** Sweeps kept. */
 const KEEP = 30;
-/** Test temp folders one sweep removes at most (Oct 4 found 107,418). */
 const TEMP_MAX = 20_000;
-/** Paths saved per part, for the disclosure. */
 const ITEMS_MAX = 20;
 export function storageSweepOff(env = process.env) {
     return (env["TOOLROLL_STORAGE_SWEEP"] ?? "").trim().toLowerCase() === "off";
@@ -95,7 +66,6 @@ export function liveWork(store, depsRoot, now, where) {
     if (from === null)
         return { live: true, paths, blind: true };
     paths.push(...from);
-    // A checkout (or a run's folder inside one) links its node_modules to a shared install: that install is in use.
     for (const path of [...paths]) {
         for (let at = resolve(path), hops = 0; hops < 32; at = dirname(at), hops++) {
             const key = linkedKey(at, depsRoot);
@@ -109,7 +79,6 @@ export function liveWork(store, depsRoot, now, where) {
     }
     return { live: true, paths, blind: false };
 }
-/** Where the processes run from, with their groups and every process under them; null when that can't be read. */
 function processFolders(pids, census, locate, scripts) {
     try {
         const rows = census();
@@ -128,7 +97,6 @@ function processFolders(pids, census, locate, scripts) {
         for (const pid of take) {
             if (located.get(pid)?.cwd !== undefined)
                 continue;
-            // A vanished process is fine. An unreadable live working folder is not evidence that it uses nothing.
             try {
                 process.kill(pid, 0);
                 return null;
@@ -149,13 +117,9 @@ const forms = (path) => {
     try {
         out.push(realpathSync(path));
     }
-    catch { /* gone */ }
+    catch { }
     return out;
 };
-/**
- * Whether live work uses `path`, asked again at every call, including process children. A cached process look
- * cannot protect a child launched between the pre-rename and post-rename guards. All this work is in the child.
- */
 export function liveUse(store, deps, now) {
     const census = deps.census ?? (() => processCensus());
     const locate = deps.locate ?? locateProcesses;
@@ -173,7 +137,6 @@ export function liveUse(store, deps, now) {
 const nextTurn = () => new Promise(resolve => setImmediate(resolve));
 const capped = (items) => items.slice(0, ITEMS_MAX);
 const failure = (error) => error instanceof Error ? error.message : String(error);
-/** Parent side: no filesystem/process scans here. The executor seam is for deterministic unit tests only. */
 export async function sweepStorage(store, deps, now, execute = runSweepChild) {
     const at = now().toISOString();
     const actor = deps.actor ?? "worker";
@@ -182,7 +145,6 @@ export async function sweepStorage(store, deps, now, execute = runSweepChild) {
         record = await execute({ version: 1, databaseFile: deps.databaseFile, poolRoot: deps.pool?.root ?? null, tempRoots: [...deps.tempRoots], actor, at });
     }
     catch {
-        // Never save child stdout, argv or exception text: those may contain private process inputs.
         record = sweepFailure(at, actor, deps.pool !== null, "failed");
     }
     return saveSweep(store, record);
@@ -190,7 +152,6 @@ export async function sweepStorage(store, deps, now, execute = runSweepChild) {
 export function sweepKinds(withPool) {
     return ["test temp", "orphans", ...(withPool ? ["checkouts"] : []), "runtimes", "dependencies", "check history"];
 }
-/** Child side (also a focused unit-test seam): every scan and removal, without saving the parent's result. */
 export async function executeSweep(store, deps, now) {
     const actor = deps.actor ?? "worker";
     const read = deps.census ?? (() => processCensus());
@@ -206,12 +167,11 @@ export async function executeSweep(store, deps, now) {
         }
     };
     await part("test temp", async () => {
-        // A root whose owner still runs stays, however old it looks; with no process list, every owned root stays.
         let alive = () => true;
         try {
             alive = ownerRunning(read());
         }
-        catch { /* owned roots stay */ }
+        catch { }
         const done = await removeStaleTestTemp(deps.tempRoots, now(), { ownerAlive: alive, max: TEMP_MAX, spare });
         return { count: done.removed.length, bytes: 0, failed: done.failed.length, ...(done.more ? { more: true } : {}), items: capped(done.removed) };
     });
@@ -228,7 +188,6 @@ export async function executeSweep(store, deps, now) {
     if (deps.pool !== null) {
         const pool = deps.pool;
         await part("checkouts", async () => {
-            // Idle folders go here only: nothing records a person's shell or editor in one, so the OS is asked. Unreadable keeps it.
             const occupied = (path) => { try {
                 return (deps.cwds ?? processesInStrict)([path]).size > 0;
             }
@@ -258,15 +217,12 @@ export async function executeSweep(store, deps, now) {
         const done = await pruneUnusedShared(root, checkouts, now(), SHARED_UNUSED_MS, { spare });
         return { count: done.removed.length, bytes: done.removed.reduce((sum, one) => sum + (sizes.get(one.dir) ?? 0), 0), failed: done.failed.length, items: capped(done.removed.map(one => one.dir)) };
     });
-    // Learning rows past their retention (docs/plans/learning-loops.md): the only DELETE on them. A lesson note's tallies
-    // are written with each check and never pruned, so what they say doesn't change here.
     await part("check history", async () => {
         const count = store.transact(() => pruneCheckResults(store, now()) + pruneObservations(store, now()) + pruneCiObservations(store, now()));
         return { count, bytes: 0, failed: 0, items: [] };
     });
     return { at: now().toISOString(), source: "automatic", actor, parts };
 }
-/** Save what a sweep or a clean-up by hand did (the latest few are kept), with one ledger entry saying it. */
 export function saveSweep(store, record) {
     store.transact(() => {
         store.handle.prepare("INSERT INTO storage_sweep (at, source, actor, result) VALUES (?, ?, ?, ?)").run(record.at, record.source, record.actor, JSON.stringify(record.parts));
@@ -287,7 +243,6 @@ function parseParts(text) {
         return [];
     }
 }
-/** The latest sweep (of `source`, or either), or null when there has been none. */
 export function lastSweep(store, source) {
     const row = store.handle.prepare(`SELECT at, source, actor, result FROM storage_sweep${source === undefined ? "" : " WHERE source = ?"} ORDER BY id DESC LIMIT 1`)
         .get(...(source === undefined ? [] : [source]));
@@ -295,7 +250,6 @@ export function lastSweep(store, source) {
         return null;
     return { at: String(row["at"]), source: row["source"] === "manual" ? "manual" : "automatic", actor: String(row["actor"]), parts: parseParts(String(row["result"])) };
 }
-/** When the next automatic sweep is due, or null when it is off. */
 export function nextSweepAt(store) {
     if (storageSweepOff())
         return null;
@@ -310,7 +264,6 @@ const NOUNS = {
     dependencies: ["unused dependency install", "unused dependency installs"],
     "check history": ["old test result", "old test results"],
 };
-/** What a part looks at, for "Couldn't check …". */
 const CHECKED = { "test temp": "test temp folders", orphans: "processes", checkouts: "task folders", runtimes: "staged runtimes", dependencies: "dependency installs", "check history": "old test results" };
 export function partWords(one) {
     return `${one.count.toLocaleString("en-US")} ${NOUNS[one.kind][one.count === 1 ? 0 : 1]}`;
@@ -318,7 +271,6 @@ export function partWords(one) {
 function list(items) {
     return items.length <= 1 ? items.join("") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
 }
-/** "Removed 120 test temp folders and 2 task folders, about 1.2 GB. Stopped 1 leftover process. 3 couldn't be removed." */
 export function sweepWords(parts) {
     const removed = parts.filter(one => one.kind !== "orphans" && one.count > 0);
     const stopped = parts.find(one => one.kind === "orphans" && one.count > 0);
@@ -333,7 +285,6 @@ export function sweepWords(parts) {
     ];
     return said.length === 0 ? "Nothing was due." : said.join(" ");
 }
-/** The details a disclosure shows: each part's paths, problems and what's left for later, one line each. */
 export function sweepDetails(parts) {
     const lines = [];
     for (const one of parts) {

package/dist/storage-ui.js

@@ -1,11 +1,3 @@
-/**
- * Settings → Storage: how much space task folders (checkouts) use, what a clean-up would free now, what the next sweep's
- * idle cleanup takes and when, the folders with uncommitted changes a person decides about, the clean-up's preview (what
- * goes, what stays and why, with paths) and its Remove behind the password, what the last storage sweep removed and
- * when (its paths in a disclosure) and why the next one waits, what landed work's teardown did and still waits on (in a
- * disclosure, with the one-time command for older work), and when a task's clean folder goes by itself. An instance
- * operator's page, built from the revamp kit; the Settings frame adds the title.
- */
 import { homedir } from "node:os";
 import { basename } from "node:path";
 import { html, joinHtml } from "./html.js";
@@ -16,24 +8,19 @@ import { sweepScheduleWords } from "./storage-sweep-schedule.js";
 import { codeLine, disclose, formRow, icon, infoLine, note, notice, select, settingsRecord, settingsSection } from "./server/kit.js";
 import { kitSectionForm } from "./settings-kit.js";
 const plural = (count, one, many = `${one}s`) => `${count} ${count === 1 ? one : many}`;
-/** The page is kit pieces now; nothing of the old look is left. Kept as an export for the shared stylesheet. */
 export const STORAGE_CSS = "";
-/** A path under the home folder as ~/…. */
 function tilde(path) {
     const home = homedir();
     return home !== "" && home !== "/" && path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
 }
-/** Paths under the home folder as ~/… anywhere in a line, as the checkout list shows them. */
 function homeAsTilde(line) {
     const home = homedir();
     return home === "" || home === "/" ? line : line.split(`${home}/`).join("~/");
 }
-/** "Oct 4, 3:12 AM" in this computer's time. */
 function whenWords(at) {
     const date = new Date(at);
     return Number.isNaN(date.getTime()) ? at : date.toLocaleString("en-US", { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" });
 }
-/** When the last sweep ran and what it did, then why the next one waits or when it is due; paths and problems behind Details. */
 function sweepHtml(sweep) {
     const last = sweep.last;
     const schedule = sweep.schedule === undefined ? (sweep.off ? html `<p class="k-note" data-sweep-state="off">Automatic sweep: off.</p>` : "")
@@ -46,7 +33,6 @@ function sweepHtml(sweep) {
     const said = html `${who} <time datetime="${last.at}">${whenWords(last.at)}</time>. ${sweepWords(last.parts)}`;
     return html `<div data-last-sweep="${last.at}">${problem ? html `<p class="k-notice" role="alert">${icon("alert", true)}<span>${said}</span></p>` : note(said)}${schedule}${details.length === 0 ? "" : disclose("Details", joinHtml(details.map(line => codeLine(homeAsTilde(line)))))}</div>`;
 }
-/** Landed work, on demand: what its teardown did, what it waits on and why, and the one-time command for older work. */
 function landedHtml(landed) {
     const done = landed.completed + landed.checkouts + landed.branches === 0 ? "No landed work cleaned up yet."
         : `${plural(landed.completed, "task")} marked complete; ${plural(landed.checkouts, "task folder")} and ${plural(landed.branches, "local branch", "local branches")} removed.`;
@@ -54,9 +40,7 @@ function landedHtml(landed) {
     return html `<div data-landed>${disclose("Landed work", joinHtml([note(done), waiting,
         note(html `For work that landed before this: <code class="k-mono">toolroll storage clean --landed</code> shows what would go; add <code class="k-mono">--yes</code> to do it.`)]))}</div>`;
 }
-/** One task folder: the task it was for, its size, where it is (the home folder as ~), why it stays, and Discard when it has changes. */
 function item(one) {
-    // Under "Uncommitted changes" the heading already says why it stays.
     const why = one.why === null || one.why === "has changes" ? "" : `${whyWords(one)[0].toUpperCase()}${whyWords(one).slice(1)}`;
     const discard = one.why === "has changes"
         ? disclose("Discard", kitSectionForm({ proof: "storage-discard", action: "/settings/storage/discard", id: `discard-${previewId(one.path)}`, hidden: { path: one.path },
@@ -65,7 +49,6 @@ function item(one) {
     return settingsRecord({ title: one.taskId ?? basename(one.path), attrs: { "data-checkout": one.path }, when: bytesWords(one.bytes),
         sub: html `<span class="k-mono">${tilde(one.path)}</span>${why === "" ? "" : ` · ${why}`}`, more: discard });
 }
-/** A short id for a checkout's form, from its path. */
 const previewId = (path) => path.replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "").slice(-48) || "checkout";
 export function storageHtml(view, said) {
     const { plan } = view;
@@ -88,7 +71,6 @@ export function storageHtml(view, said) {
     const changed = plan.stay.filter(one => one.why === "has changes");
     const others = plan.stay.filter(one => one.why !== "has changes");
     const stays = others.length === 0 ? "" : disclose(`Stays (${others.length})`, html `<div data-stays>${others.map(one => item(one))}</div>`);
-    // Never removed by itself: a person looks at each and keeps it or discards it.
     const changes = changed.length === 0 ? "" : settingsSection({ id: "uncommitted", title: `Uncommitted changes (${changed.length})`,
         lead: `${changed.length === 1 ? "This folder has" : "These folders have"} work that isn't on any branch, about ${bytesWords(changed.reduce((sum, one) => sum + one.bytes, 0))}. Toolroll never removes ${changed.length === 1 ? "it" : "them"} by itself.`,
         body: html `<div data-uncommitted>${changed.map(one => item(one))}</div>` });

package/dist/storage.js

@@ -1,18 +1,8 @@
-/**
- * Where Toolroll's disk goes (`toolroll storage`): the folder
- * beside the database, by kind, and what storage retention takes care of.
- * Build checkouts and staged releases are the big ones; the worker removes a
- * finished task's clean checkout as the checkout cleanup setting says
- * (checkout-cleanup.ts), and the daily storage sweep (storage-sweep.ts) takes
- * idle tasks' clean checkouts and what slips through: stale test temp folders, leftover processes, extra
- * staged runtimes and dependency installs unused for a week.
- */
 import { execFile, spawnSync } from "node:child_process";
 import { lstatSync, readdirSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { DEPS_FOLDER, sharedCopies } from "./shared-deps.js";
 import { checkoutCleanupSchema, checkoutIdleSchema } from "./contracts/storage.js";
-/** Settings → Storage: when a finished task's clean checkout is removed. One row, or none (the default). */
 export const CHECKOUT_CLEANUP_SCHEMA = `
 CREATE TABLE IF NOT EXISTS checkout_cleanup_setting (
   id         INTEGER PRIMARY KEY CHECK (id = 1),
@@ -21,11 +11,6 @@ CREATE TABLE IF NOT EXISTS checkout_cleanup_setting (
   updated_at TEXT NOT NULL
 );
 `;
-/**
- * Landed work's teardown (landed-cleanup.ts): the intent is written first, with the completion it follows, and each
- * checkout and local branch it names is one item, finished at the next reconcile when a crash cut it short. A missing
- * resource finishes its item. New tables only (v121).
- */
 export const LANDED_CLEANUP_SCHEMA = `
 CREATE TABLE IF NOT EXISTS landed_cleanup (
   id          INTEGER PRIMARY KEY,
@@ -56,7 +41,6 @@ CREATE TABLE IF NOT EXISTS landed_cleanup_item (
 CREATE UNIQUE INDEX IF NOT EXISTS landed_cleanup_pending ON landed_cleanup_item(kind, repo, target) WHERE state = 'pending';
 CREATE INDEX IF NOT EXISTS landed_cleanup_item_of ON landed_cleanup_item(cleanup, state);
 `;
-/** What each storage sweep or clean-up by hand did (storage-sweep.ts): the latest few. */
 export const STORAGE_SWEEP_SCHEMA = `
 CREATE TABLE IF NOT EXISTS storage_sweep (
   id     INTEGER PRIMARY KEY,
@@ -73,14 +57,12 @@ export const CLEANUP_CHOICES = [
     { value: "7d", label: "A week after that", days: 7 },
     { value: "never", label: "Never (only when you clean up)", days: null },
 ];
-/** The other words each cleanup value may be typed as. */
 const CLEANUP_ALIASES = {
     finished: ["complete", "completed", "cancelled", "done", "0", "0d"],
     "2d": ["2", "2 days", "2days"],
     "7d": ["7", "7 days", "7days", "week", "a week", "1w"],
     never: ["off"],
 };
-/** `finished` (or complete, cancelled), `2d`, `7d` (or week, 1w), `never` (or off); undefined when it's none of those. */
 export function parseCleanup(text) {
     const value = text.trim().toLowerCase().replace(/\s+/g, " ");
     const named = checkoutCleanupSchema.safeParse(value);
@@ -93,10 +75,6 @@ export function cleanupWords(cleanup) {
         : cleanup === "never" ? "never (only when you clean up)"
             : `${cleanup === "2d" ? "2 days" : "a week"} after its task is complete or cancelled`;
 }
-/**
- * v151: how long a task stays idle (no run, no person's act, no open lease) before its clean folder goes, even with its
- * result waiting for review or the task unfinished (checkout-cleanup.ts). Saved rows read NULL: the default.
- */
 export const V151_ADDED_COLUMNS = Object.freeze({
     checkout_cleanup_setting: { idle: { definition: "TEXT CHECK (idle IN ('7d', '14d', '30d', 'never'))", saved: "NULL" } },
 });
@@ -107,7 +85,6 @@ export const IDLE_CHOICES = [
     { value: "30d", label: "After 30 days idle", days: 30 },
     { value: "never", label: "Never", days: null },
 ];
-/** `7`, `14d`, `30 days`, `never` (or off); undefined when it's none of those. */
 export function parseIdle(text) {
     const value = text.trim().toLowerCase().replace(/\s+/g, " ");
     if (value === "off")
@@ -116,12 +93,10 @@ export function parseIdle(text) {
     const parsed = checkoutIdleSchema.safeParse(days === undefined ? value : `${days}d`);
     return parsed.success ? parsed.data : undefined;
 }
-/** After "A task's clean folder is removed ". */
 export function idleWords(idle) {
     const days = IDLE_CHOICES.find(one => one.value === idle).days;
     return days === null ? "never for being idle" : `after ${days} days idle`;
 }
-/** What the next sweep's idle cleanup takes, for `toolroll storage` and Settings → Storage. The sweep's own line says when. */
 export function idleCleanupWords(plan) {
     if (plan.cleanup === "never" || plan.idle === "never")
         return "Idle cleanup is off.";
@@ -130,7 +105,6 @@ export function idleCleanupWords(plan) {
         return `${limit}, a task's clean folder goes. None are due.`;
     return `${limit}, a task's clean folder goes: the next sweep frees about ${bytesWords(plan.idleBytes)} (${plan.idleCount} folder${plan.idleCount === 1 ? "" : "s"}).`;
 }
-/** Bytes each path holds on disk: one `du` for them all (fast on a 300 MB checkout), a walk where it can't answer. */
 export function diskBytes(paths) {
     const sizes = new Map();
     if (paths.length === 0)
@@ -138,7 +112,6 @@ export function diskBytes(paths) {
     if (process.platform !== "win32") {
         for (let at = 0; at < paths.length; at += 200) {
             const batch = paths.slice(at, at + 200);
-            // Bounded: a slow disk leaves the rest unmeasured rather than holding everything up.
             const du = spawnSync("du", ["-sk", ...batch], { encoding: "utf8", maxBuffer: 16 * 1024 * 1024, timeout: 60_000 });
             for (const line of (du.stdout ?? "").split("\n")) {
                 const match = /^(\d+)\t(.+)$/.exec(line);
@@ -152,7 +125,6 @@ export function diskBytes(paths) {
             sizes.set(path, treeBytes(path));
     return sizes;
 }
-/** Bytes a tree holds on disk (allocated blocks; links not followed). */
 export function treeBytes(path) {
     let total = 0;
     const pending = [path];
@@ -227,8 +199,6 @@ export function bytesWords(bytes) {
         return `${Math.round(bytes / 1024 ** 2)} MB`;
     return `${Math.round(bytes / 1024)} KB`;
 }
-/** diskBytes without holding the event loop: the same one `du` per 200 paths and the same bounds, awaited. A console
- * measuring its checkouts (tens of GB) used to stall every page for as long as `du` took. */
 export async function diskBytesAsync(paths, run = duOnce) {
     const sizes = new Map();
     if (paths.length === 0)
@@ -248,7 +218,6 @@ export async function diskBytesAsync(paths, run = duOnce) {
             sizes.set(path, treeBytes(path));
     return sizes;
 }
-/** `du -sk` over a batch, its output whatever it managed (a slow disk or a failure answers what it has, or nothing). */
 function duOnce(batch) {
     return new Promise(resolve => {
         execFile("du", ["-sk", ...batch], { encoding: "utf8", maxBuffer: 16 * 1024 * 1024, timeout: 60_000 }, (_error, stdout) => resolve(typeof stdout === "string" ? stdout : ""));

package/dist/store-baseline.js

@@ -1,20 +1,6 @@
 import { createHash } from "node:crypto";
-/**
- * Schema v107: the database Toolroll 0.5.0, the first npm release, made for a
- * new installation — every table, index and trigger exactly as that release
- * wrote it (sqlite_master order and text), and the rows it seeded. A new
- * database starts here and takes the same numbered steps up to the current
- * schema that an installation from 0.5.0 takes; an older schema is refused
- * (update through 0.9.x first).
- *
- * Captured from a database 0.5.0 created, never edited by hand: its shape
- * digest below must match one this text creates (store-baseline.slow.test.ts), and
- * the upgrade path compares it with the published 0.5.0 package itself.
- */
 export const BASELINE_SCHEMA_VERSION = 107;
-/** The sha256 of `schemaShape` over a database 0.5.0 created (and over one BASELINE_SCHEMA creates). */
 export const BASELINE_SHAPE_SHA256 = "a8c5a0dad9ef6d73f7e2696203dd3618812d7a3975ca4a1b79c7550e315716ca";
-/** Every schema object, as SQLite keeps it (type, name, table and text), in one deterministic order, hashed. */
 export function schemaShape(db) {
     const rows = db.prepare("SELECT type, name, tbl_name, sql FROM sqlite_master ORDER BY type, name").all();
     return createHash("sha256").update(rows.map(row => JSON.stringify([row["type"], row["name"], row["tbl_name"], row["sql"]])).join("\n")).digest("hex");