toolroll 0.9.60 → 0.9.61

package/dist/storage-sweep.js

@@ -5,6 +5,13 @@
  * 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.
  *
@@ -13,14 +20,19 @@
  * 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).
  */
-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 { openStoreNoMigrate } from "./store.js";
 import { removeStaleTestTemp } from "./test-temp.js";
+import { worktreeProcessOccupancy } from "./worktree.js";
+import { runSweepChild, storageSweepSupervisor } from "./storage-sweep-process.js";
 const 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. */
@@ -37,34 +49,208 @@ export function storageSweepOff(env = process.env) {
 export function storageSweepDue(store, now) {
     return now.getTime() - store.serviceCursor(CURSOR) >= SWEEP_EVERY_MS;
 }
-/** 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())
+/** Claim and launch only. A hung child never holds reconciliation or the caller's store open. */
+export function dailyStorageSweep(store, deps, now, supervisor = storageSweepSupervisor(deps.databaseFile)) {
+    if (storageSweepOff() || supervisor.running || !storageSweepDue(store, now()))
         return null;
+    // This handle belongs to the flight, not to the command that has already returned by the time it finishes.
+    const connection = openStoreNoMigrate(deps.databaseFile);
+    if (!connection.ok)
+        throw new Error("Sweep result store unavailable");
+    const results = connection.store;
     const at = now();
-    const mine = store.transact(() => {
-        if (!storageSweepDue(store, at))
-            return false;
-        store.setServiceCursor(CURSOR, at.getTime(), at);
-        return true;
-    });
-    if (!mine)
+    let completed = null;
+    let owned = false;
+    try {
+        const mine = store.transact(() => {
+            if (!storageSweepDue(store, at))
+                return false;
+            store.setServiceCursor(CURSOR, at.getTime(), at);
+            return true;
+        });
+        if (!mine)
+            return null;
+        const request = { version: 1, databaseFile: deps.databaseFile, poolRoot: deps.pool?.root ?? null, tempRoots: [...deps.tempRoots], actor: deps.actor ?? "worker", at: at.toISOString() };
+        owned = supervisor.start(request, result => {
+            const record = result.ok ? result.record : sweepFailure(request.at, request.actor, deps.pool !== null, result.reason);
+            try {
+                results.transact(() => {
+                    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(CURSOR) === at.getTime()) {
+                        results.setServiceCursor(CURSOR, Math.max(0, now().getTime() - SWEEP_EVERY_MS + RETRY_MS), now());
+                    }
+                });
+                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 {
+                results.close();
+            }
+        }, deps.owner);
+        if (!owned) {
+            store.transact(() => {
+                if (store.serviceCursor(CURSOR) === at.getTime())
+                    store.setServiceCursor(CURSOR, Math.max(0, at.getTime() - SWEEP_EVERY_MS + RETRY_MS), now());
+            });
+        }
+        return completed;
+    }
+    finally {
+        if (!owned)
+            results.close();
+    }
+}
+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 })) };
+}
+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 +265,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 +281,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 +301,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) {

package/dist/storage-ui.d.ts

@@ -1,6 +1,7 @@
 import { type Html } from "./html.js";
 import { type CheckoutPlan } from "./checkout-cleanup.js";
 import { type SweepRecord } from "./storage-sweep.js";
+import type { LandedSummary } from "./landed-cleanup.js";
 export declare const STORAGE_CSS: string;
 export type StorageView = {
     plan: CheckoutPlan;
@@ -9,6 +10,7 @@ export type StorageView = {
         last: SweepRecord | null;
         off: boolean;
     };
+    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), 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";
@@ -29,8 +29,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();
@@ -51,6 +55,14 @@ function sweepHtml(sweep) {
     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>`;
 }
+/** 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"
         ? html `<details class="discard"><summary>Discard</summary>${postForm("/settings/storage/discard", html `<p class="meta">Throws away this checkout and its uncommitted changes. Its branch stays.</p><label>Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label><button type="submit" class="danger">Discard changes</button>`, { hidden: { path: one.path } })}</details>`
@@ -70,5 +82,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 (