toolroll 0.9.60 → 0.9.62

package/dist/storage-sweep.js

@@ -1,27 +1,39 @@
 /**
- * The daily storage sweep: the plane cleans up after itself without anyone running a command. Once a day (one worker
- * takes the day: 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
+ * 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 (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 (90 s). 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.
  *
  * 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. `TOOLROLL_STORAGE_SWEEP=off` turns the automatic sweep off
- * (the unit tests do, so a test never sweeps the machine it runs on).
+ * 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 { dirname } from "node:path";
+import { realpathSync } from "node:fs";
+import { hostname } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
 import { cleanCheckouts } from "./checkout-cleanup.js";
-import { durationWords, sweepOrphans, ownerRunning } from "./orphan-sweep.js";
+import { durationWords, locateProcesses, sweepOrphans, ownerRunning } from "./orphan-sweep.js";
 import { processCensus } from "./run-closeout.js";
-import { pruneUnusedShared, sharedDepsRoot, sharedUse, SHARED_UNUSED_MS } from "./shared-deps.js";
-import { pruneStagedRuntimes, runtimesInUse, stagePlan } from "./staged-runtimes.js";
+import { linkedKey, pruneUnusedShared, sharedDepsRoot, sharedUse, SHARED_UNUSED_MS } from "./shared-deps.js";
+import { pruneStagedRuntimes, runtimesInUse, runtimeScriptPaths, stagePlan } from "./staged-runtimes.js";
 import { bytesWords, diskBytes } from "./storage.js";
 import { removeStaleTestTemp } from "./test-temp.js";
-const CURSOR = "storage-sweep";
+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;
@@ -34,37 +46,151 @@ const ITEMS_MAX = 20;
 export function storageSweepOff(env = process.env) {
     return (env["TOOLROLL_STORAGE_SWEEP"] ?? "").trim().toLowerCase() === "off";
 }
-export function storageSweepDue(store, now) {
-    return now.getTime() - store.serviceCursor(CURSOR) >= SWEEP_EVERY_MS;
+export function sweepFailure(at, actor, withPool, reason) {
+    const problem = reason === "timeout" ? "The sweep process exceeded its time limit; some cleanup may have completed. Cleanup will retry later."
+        : reason === "stopped" ? "The sweep process was stopped; some cleanup may have completed. Cleanup will retry later."
+            : "The sweep process did not return a valid result; some cleanup may have completed.";
+    return { at, source: "automatic", actor, parts: sweepKinds(withPool).map(kind => ({ kind, count: 0, bytes: 0, failed: 0, items: [], problem })) };
 }
-/** The daily sweep, when it's due and on: one worker takes it. Null when it wasn't this pass's to run. */
-export async function dailyStorageSweep(store, deps, now) {
-    if (storageSweepOff())
-        return null;
-    const at = now();
-    const mine = store.transact(() => {
-        if (!storageSweepDue(store, at))
-            return false;
-        store.setServiceCursor(CURSOR, at.getTime(), at);
-        return true;
-    });
-    if (!mine)
+export function liveWork(store, depsRoot, now, where) {
+    const db = store.handle;
+    const tasks = new Set();
+    const paths = [];
+    for (const row of db.prepare("SELECT task_ref, worktree FROM run WHERE finished_at IS NULL").all()) {
+        tasks.add(Number(row["task_ref"]));
+        if (typeof row["worktree"] === "string" && row["worktree"] !== "")
+            paths.push(row["worktree"]);
+    }
+    for (const row of db.prepare("SELECT task_ref FROM claim WHERE released_at IS NULL AND expires_at > ?").all(now.toISOString()))
+        tasks.add(Number(row["task_ref"]));
+    const pids = new Set();
+    for (const row of store.listWorktrees()) {
+        let held;
+        try {
+            held = worktreeProcessOccupancy(row.path);
+        }
+        catch {
+            held = { held: true, by: 0 };
+        }
+        if (row.releasedAt !== null && row.runner === null && !held.held && (row.taskRef === null || !tasks.has(row.taskRef)))
+            continue;
+        paths.push(row.path);
+        if (held.held && held.by > 1)
+            pids.add(held.by);
+    }
+    if (tasks.size === 0 && paths.length === 0)
+        return { live: false, paths: [], blind: false };
+    const witnessed = db.prepare(`SELECT p.pid AS pid FROM run_process p JOIN run r ON r.id = p.run
+    WHERE r.finished_at IS NULL AND p.exited_at IS NULL AND p.pid IS NOT NULL AND p.host = ?`).all(hostname());
+    for (const row of witnessed)
+        pids.add(Number(row["pid"]));
+    const from = pids.size === 0 ? [] : where([...pids].sort((a, b) => a - b));
+    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);
+            if (key !== null) {
+                paths.push(join(depsRoot, key));
+                break;
+            }
+            if (dirname(at) === at)
+                break;
+        }
+    }
+    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();
+        const take = new Set(rows.filter(row => pids.includes(row.pid) || pids.includes(row.pgid)).map(row => row.pid));
+        for (let grew = true; grew;) {
+            grew = false;
+            for (const row of rows)
+                if (!take.has(row.pid) && take.has(row.ppid) && row.ppid > 1) {
+                    take.add(row.pid);
+                    grew = true;
+                }
+        }
+        if (take.size === 0)
+            return [];
+        const located = locate([...take]);
+        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;
+            }
+            catch (error) {
+                if (error.code !== "ESRCH")
+                    return null;
+            }
+        }
+        return [...[...located.values()].flatMap(one => [one.cwd, one.exe]).filter((one) => one !== undefined && one !== ""), ...scripts([...take])];
+    }
+    catch {
         return null;
-    const record = await sweepStorage(store, deps, now);
-    // Something failed or was left for later: the next sweep comes an hour from now, not tomorrow.
-    if (record.parts.some(one => one.failed > 0 || one.more === true || one.problem !== undefined)) {
-        store.setServiceCursor(CURSOR, Math.max(0, at.getTime() - SWEEP_EVERY_MS + RETRY_MS), now());
     }
-    return record;
 }
+const forms = (path) => {
+    const out = [resolve(path)];
+    try {
+        out.push(realpathSync(path));
+    }
+    catch { /* gone */ }
+    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;
+    const where = (pids) => processFolders(pids, census, locate, deps.scripts ?? (pids => runtimeScriptPaths(dirname(deps.databaseFile), pids)));
+    return path => {
+        const work = liveWork(store, sharedDepsRoot(deps.databaseFile), now(), where);
+        if (!work.live)
+            return false;
+        if (work.blind)
+            return true;
+        const outer = forms(path);
+        return work.paths.some(one => forms(one).some(inner => outer.some(base => inner === base || inner.startsWith(base + sep))));
+    };
+}
+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);
-/** One sweep, now, every part; saved and in the ledger. Each part's failure is its own: the others still run. */
-export async function sweepStorage(store, deps, now) {
+/** 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";
+    let record;
+    try {
+        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);
+}
+export function sweepKinds(withPool) {
+    return ["test temp", "orphans", ...(withPool ? ["checkouts"] : []), "runtimes", "dependencies"];
+}
+/** 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());
     const parts = [];
+    const spare = liveUse(store, deps, now);
     const part = async (kind, work) => {
+        await nextTurn();
         try {
             parts.push({ kind, ...await work() });
         }
@@ -79,12 +205,12 @@ export async function sweepStorage(store, deps, now) {
             alive = ownerRunning(read());
         }
         catch { /* owned roots stay */ }
-        const done = removeStaleTestTemp(deps.tempRoots, now(), { ownerAlive: alive, max: TEMP_MAX });
+        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) };
     });
     await part("orphans", async () => {
         const done = await sweepOrphans(store, now, {
-            actor, pool: deps.pool, tempRoots: deps.tempRoots, census: read,
+            actor, pool: deps.pool, tempRoots: deps.tempRoots, census: read, spare,
             ...(deps.locate === undefined ? {} : { locate: deps.locate }), ...(deps.graceMs === undefined ? {} : { graceMs: deps.graceMs }),
         });
         return {
@@ -95,16 +221,16 @@ export async function sweepStorage(store, deps, now) {
     if (deps.pool !== null) {
         const pool = deps.pool;
         await part("checkouts", async () => {
-            const done = await cleanCheckouts(store, pool, now, { manual: false, actor });
+            const done = await cleanCheckouts(store, pool, now, { manual: false, actor, spare });
             return { count: done.removed.length, bytes: done.freed, failed: done.kept.filter(one => one.why === "git refused").length, items: capped(done.removed.map(one => one.path)) };
         });
     }
     const stateDir = dirname(deps.databaseFile);
     await part("runtimes", async () => {
-        const inUse = deps.inUse ?? (() => runtimesInUse());
+        const inUse = deps.inUse ?? (() => runtimesInUse([], undefined, undefined, stateDir));
         const plan = stagePlan(stateDir, inUse(), now());
         const sizes = diskBytes(plan.go.map(one => one.path));
-        const done = pruneStagedRuntimes(stateDir, now(), { inUse });
+        const done = pruneStagedRuntimes(stateDir, now(), { inUse, spare });
         return {
             count: done.removed.length, bytes: done.removed.reduce((sum, path) => sum + (sizes.get(path) ?? 0), 0), failed: done.failed.length,
             ...(done.refused === null ? {} : { problem: `kept every staged runtime: ${done.refused}` }), items: capped(done.removed),
@@ -115,10 +241,10 @@ export async function sweepStorage(store, deps, now) {
         const checkouts = () => store.listWorktrees().map(row => ({ path: row.path, repo: row.repo }));
         const candidates = sharedUse(root, checkouts()).filter(one => one.checkouts.length === 0 && now().getTime() - Date.parse(one.usedAt) > SHARED_UNUSED_MS);
         const sizes = diskBytes(candidates.map(one => one.dir));
-        const done = pruneUnusedShared(root, checkouts, 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)) };
     });
-    return saveSweep(store, { at: now().toISOString(), source: "automatic", actor, parts });
+    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) {
@@ -153,7 +279,7 @@ export function lastSweep(store, source) {
 export function nextSweepAt(store) {
     if (storageSweepOff())
         return null;
-    const last = store.serviceCursor(CURSOR);
+    const last = store.serviceCursor(SWEEP_CURSOR);
     return last === 0 ? null : new Date(last + SWEEP_EVERY_MS).toISOString();
 }
 const NOUNS = {

package/dist/storage-ui.d.ts

@@ -1,6 +1,8 @@
 import { type Html } from "./html.js";
 import { type CheckoutPlan } from "./checkout-cleanup.js";
 import { type SweepRecord } from "./storage-sweep.js";
+import { type SweepSchedule } from "./storage-sweep-schedule.js";
+import type { LandedSummary } from "./landed-cleanup.js";
 export declare const STORAGE_CSS: string;
 export type StorageView = {
     plan: CheckoutPlan;
@@ -8,7 +10,9 @@ export type StorageView = {
     sweep?: {
         last: SweepRecord | null;
         off: boolean;
+        schedule?: SweepSchedule;
     };
+    landed?: LandedSummary;
 };
 export declare function storageHtml(view: StorageView, notice: {
     said?: string | null;

package/dist/storage-ui.js

@@ -1,8 +1,8 @@
 /**
  * Settings → Storage: how much space task checkouts use, what a clean-up would free now, a Clean up button whose
  * preview (what goes, what stays and why, with paths) sits behind the password, what the last storage sweep removed
- * and when (its paths in a disclosure), and when a finished task's clean checkout goes by itself. An instance
- * operator's page.
+ * 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 finished task's clean checkout goes by itself. An instance operator's page.
  */
 import { homedir } from "node:os";
 import { basename } from "node:path";
@@ -10,6 +10,7 @@ import { html, postForm } from "./html.js";
 import { previewDigest, whyWords } from "./checkout-cleanup.js";
 import { CLEANUP_CHOICES, bytesWords } from "./storage.js";
 import { sweepDetails, sweepWords } from "./storage-sweep.js";
+import { sweepScheduleWords } from "./storage-sweep-schedule.js";
 const plural = (count, one, many = `${one}s`) => `${count} ${count === 1 ? one : many}`;
 export const STORAGE_CSS = `.storage{max-width:720px;min-width:0;overflow-wrap:anywhere}.storage h2{font-size:1.0625rem;margin:24px 0 4px}` +
     `.storage .storage-state{display:grid;gap:12px}.storage .storage-state h2{margin:0}.storage .storage-state p{margin:0}` +
@@ -29,8 +30,12 @@ export const STORAGE_CSS = `.storage{max-width:720px;min-width:0;overflow-wrap:a
     `.storage form.setting button[type=submit],.storage .preview form.remove button[type=submit]{background:var(--primary);color:var(--primary-foreground);border-color:var(--primary);font-weight:600}` +
     `.storage .sweep{display:grid;gap:4px}.storage .sweep p{margin:0}.storage .sweep .problem{color:var(--destructive)}` +
     `.storage details.sweep-details>summary{cursor:pointer;min-height:2.25rem;display:inline-flex;align-items:center;font-size:.8125rem;color:var(--muted-foreground)}` +
+    `.storage details.landed>summary{cursor:pointer;min-height:2.25rem;display:inline-flex;align-items:center;font-size:.8125rem;color:var(--muted-foreground)}` +
+    `.storage details.landed .landed-body{display:grid;gap:6px;margin-top:4px;font-size:.8125rem}.storage details.landed p{margin:0}` +
+    `.storage details.landed ul{margin:0;padding-left:18px;overflow-wrap:anywhere}.storage details.landed .target{font-family:var(--font-mono, ui-monospace, monospace);font-size:.6875rem}` +
+    `.storage details.landed code{font-family:var(--font-mono, ui-monospace, monospace);font-size:.75rem;overflow-wrap:anywhere}` +
     `.storage details.sweep-details ul{margin:4px 0 0;padding-left:18px;font-family:var(--font-mono, ui-monospace, monospace);font-size:.6875rem;color:var(--muted-foreground);overflow-wrap:anywhere}` +
-    `@media (max-width:900px){.storage details.sweep-details>summary{min-height:44px}.storage details.clean-up>summary,.storage form button{min-height:44px}.storage label{max-width:none}.storage select,.storage input[type=password]{min-height:44px;font-size:16px}.storage .preview form.remove button{width:100%}}`;
+    `@media (max-width:900px){.storage details.sweep-details>summary,.storage details.landed>summary{min-height:44px}.storage details.clean-up>summary,.storage form button{min-height:44px}.storage label{max-width:none}.storage select,.storage input[type=password]{min-height:44px;font-size:16px}.storage .preview form.remove button{width:100%}}`;
 /** Paths under the home folder as ~/…, as the checkout list shows them. */
 function homeAsTilde(line) {
     const home = homedir();
@@ -41,15 +46,25 @@ 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" });
 }
-/** One line: when the last sweep ran and what it did; its paths and problems behind Details. */
+/** 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="meta" data-sweep-state="off">Automatic sweep: off.</p>` : "")
+        : html `<p class="meta" data-sweep-state="${sweep.schedule.state}">Automatic sweep: ${sweepScheduleWords(sweep.schedule, whenWords)}</p>`;
     if (last === null)
-        return html `<p class="meta" data-last-sweep="">${sweep.off ? "Automatic sweep is off." : html `Toolroll sweeps leftovers once a day. It hasn't run yet.`}</p>`;
+        return html `<div class="sweep" data-last-sweep=""><p>Not swept yet.</p>${schedule}</div>`;
     const who = last.source === "manual" ? `Cleaned up by ${last.actor}` : "Swept";
     const details = sweepDetails(last.parts);
     const problem = last.parts.some(one => one.failed > 0 || one.problem !== undefined);
-    return html `<div class="sweep" data-last-sweep="${last.at}"><p${problem ? html ` class="problem"` : ""}>${who} <time datetime="${last.at}">${whenWords(last.at)}</time>. ${sweepWords(last.parts)}</p>${details.length === 0 ? "" : html `<details class="sweep-details"><summary>Details</summary><ul>${details.map(line => html `<li>${homeAsTilde(line)}</li>`)}</ul></details>`}</div>`;
+    return html `<div class="sweep" data-last-sweep="${last.at}"><p${problem ? html ` class="problem"` : ""}>${who} <time datetime="${last.at}">${whenWords(last.at)}</time>. ${sweepWords(last.parts)}</p>${schedule}${details.length === 0 ? "" : html `<details class="sweep-details"><summary>Details</summary><ul>${details.map(line => html `<li>${homeAsTilde(line)}</li>`)}</ul></details>`}</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 home = homedir();
+    const done = landed.completed + landed.checkouts + landed.branches === 0 ? "No landed work cleaned up yet."
+        : `${plural(landed.completed, "task")} marked complete; ${plural(landed.checkouts, "checkout")} and ${plural(landed.branches, "local branch", "local branches")} removed.`;
+    const waiting = landed.waiting.length === 0 ? "" : html `<p>Waiting (${landed.waiting.length}):</p><ul data-landed-waiting>${landed.waiting.map(one => html `<li><span class="target">${home !== "" && one.target.startsWith(`${home}/`) ? `~${one.target.slice(home.length)}` : one.target}</span>${one.why === null ? "" : html `: ${one.why}`}</li>`)}</ul>`;
+    return html `<details class="landed" data-landed><summary>Landed work</summary><div class="landed-body"><p>${done}</p>${waiting}<p class="meta">For work that landed before this: <code>toolroll storage clean --landed</code> shows what would go; add <code>--yes</code> to do it.</p></div></details>`;
 }
 function item(one) {
     const discard = one.why === "has changes"
@@ -70,5 +85,5 @@ export function storageHtml(view, notice) {
     const preview = html `<details class="clean-up" data-clean-up${notice.problem?.startsWith("Enter your Toolroll password to clean") ? html ` open` : ""}><summary>Clean up</summary><div class="preview">${plan.go.length === 0 ? html `<p>Nothing to remove now.</p>` :
         html `<h3>Removes ${plural(plan.go.length, "checkout")}, about ${bytesWords(plan.freeBytes)}</h3><p class="meta">Their branches stay, so nothing committed is lost.</p><ul class="checkouts" data-goes>${plan.go.map(one => item(one))}</ul>`}${plan.stay.length === 0 ? "" : html `<h3>Stays (${plan.stay.length})</h3><ul class="checkouts" data-stays>${plan.stay.map(one => item(one))}</ul>`}${remove}</div></details>`;
     const options = CLEANUP_CHOICES.map(one => html `<option value="${one.value}"${one.value === plan.cleanup ? html ` selected` : ""}>${one.label}</option>`);
-    return html `<section class="storage">${note}<div class="card storage-state"><h2 data-checkout-bytes="${plan.totalBytes}">Checkouts use ${bytesWords(plan.totalBytes)}</h2><p class="meta">${facts}</p><p data-clean-bytes="${plan.freeBytes}">${frees}</p>${view.sweep === undefined ? "" : sweepHtml(view.sweep)}${preview}</div><h2>Automatic cleanup</h2>${postForm("/settings/storage", html `<label>Remove a finished task's clean checkout<select name="cleanup">${options}</select></label><p class="meta">Its branch always stays. Checkouts with changes, commits on no branch, in use, or waiting for review are kept.</p><label>Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label><button type="submit">Save</button>`, { attrs: { class: "setting" } })}</section>`;
+    return html `<section class="storage">${note}<div class="card storage-state"><h2 data-checkout-bytes="${plan.totalBytes}">Checkouts use ${bytesWords(plan.totalBytes)}</h2><p class="meta">${facts}</p><p data-clean-bytes="${plan.freeBytes}">${frees}</p>${view.sweep === undefined ? "" : sweepHtml(view.sweep)}${view.landed === undefined ? "" : landedHtml(view.landed)}${preview}</div><h2>Automatic cleanup</h2>${postForm("/settings/storage", html `<label>Remove a finished task's clean checkout<select name="cleanup">${options}</select></label><p class="meta">Its branch stays. Checkouts with changes, commits on no branch, in use, or waiting for review are kept. When a task's work is already in main, Toolroll marks it complete and removes its checkout and local branches.</p><label>Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label><button type="submit">Save</button>`, { attrs: { class: "setting" } })}</section>`;
 }

package/dist/storage.d.ts

@@ -2,6 +2,12 @@ import type { Store } from "./store.js";
 import { type CheckoutCleanup } from "./contracts/storage.js";
 /** Settings → Storage: when a finished task's clean checkout is removed. One row, or none (the default). */
 export declare const CHECKOUT_CLEANUP_SCHEMA = "\nCREATE TABLE IF NOT EXISTS checkout_cleanup_setting (\n  id         INTEGER PRIMARY KEY CHECK (id = 1),\n  cleanup    TEXT NOT NULL CHECK (cleanup IN ('finished', '2d', '7d', 'never')),\n  updated_by TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n";
+/**
+ * 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 declare const LANDED_CLEANUP_SCHEMA = "\nCREATE TABLE IF NOT EXISTS landed_cleanup (\n  id          INTEGER PRIMARY KEY,\n  repo        TEXT NOT NULL,\n  task_id     TEXT,\n  run_id      INTEGER,\n  receipt     TEXT,\n  head        TEXT NOT NULL,\n  how         TEXT NOT NULL CHECK (how IN ('merged', 'in-main', 'content-in-main')),\n  reason      TEXT NOT NULL,\n  completed   INTEGER NOT NULL DEFAULT 0 CHECK (completed IN (0, 1)),\n  actor       TEXT NOT NULL,\n  created_at  TEXT NOT NULL,\n  finished_at TEXT\n);\nCREATE UNIQUE INDEX IF NOT EXISTS landed_cleanup_result ON landed_cleanup(run_id) WHERE run_id IS NOT NULL;\nCREATE TABLE IF NOT EXISTS landed_cleanup_item (\n  id      INTEGER PRIMARY KEY,\n  cleanup INTEGER NOT NULL REFERENCES landed_cleanup(id) ON DELETE CASCADE,\n  kind    TEXT NOT NULL CHECK (kind IN ('checkout', 'branch')),\n  repo    TEXT NOT NULL,\n  target  TEXT NOT NULL,\n  expect  TEXT NOT NULL,\n  state   TEXT NOT NULL DEFAULT 'pending' CHECK (state IN ('pending', 'done', 'kept')),\n  why     TEXT,\n  done_at TEXT\n);\nCREATE UNIQUE INDEX IF NOT EXISTS landed_cleanup_pending ON landed_cleanup_item(kind, repo, target) WHERE state = 'pending';\nCREATE INDEX IF NOT EXISTS landed_cleanup_item_of ON landed_cleanup_item(cleanup, state);\n";
 /** What each storage sweep or clean-up by hand did (storage-sweep.ts): the latest few. */
 export declare const STORAGE_SWEEP_SCHEMA = "\nCREATE TABLE IF NOT EXISTS storage_sweep (\n  id     INTEGER PRIMARY KEY,\n  at     TEXT NOT NULL,\n  source TEXT NOT NULL CHECK (source IN ('automatic', 'manual')),\n  actor  TEXT NOT NULL,\n  result TEXT NOT NULL\n);\n";
 export type { CheckoutCleanup } from "./contracts/storage.js";

package/dist/storage.js

@@ -21,6 +21,41 @@ 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,
+  repo        TEXT NOT NULL,
+  task_id     TEXT,
+  run_id      INTEGER,
+  receipt     TEXT,
+  head        TEXT NOT NULL,
+  how         TEXT NOT NULL CHECK (how IN ('merged', 'in-main', 'content-in-main')),
+  reason      TEXT NOT NULL,
+  completed   INTEGER NOT NULL DEFAULT 0 CHECK (completed IN (0, 1)),
+  actor       TEXT NOT NULL,
+  created_at  TEXT NOT NULL,
+  finished_at TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS landed_cleanup_result ON landed_cleanup(run_id) WHERE run_id IS NOT NULL;
+CREATE TABLE IF NOT EXISTS landed_cleanup_item (
+  id      INTEGER PRIMARY KEY,
+  cleanup INTEGER NOT NULL REFERENCES landed_cleanup(id) ON DELETE CASCADE,
+  kind    TEXT NOT NULL CHECK (kind IN ('checkout', 'branch')),
+  repo    TEXT NOT NULL,
+  target  TEXT NOT NULL,
+  expect  TEXT NOT NULL,
+  state   TEXT NOT NULL DEFAULT 'pending' CHECK (state IN ('pending', 'done', 'kept')),
+  why     TEXT,
+  done_at TEXT
+);
+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 (