toolroll 0.9.60 → 0.9.62

package/dist/storage-sweep-child.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/storage-sweep-child.js

@@ -0,0 +1,76 @@
+/** Launched only by storage-sweep-process. All potentially expensive sweep work stays in this process. */
+import { Worker } from "node:worker_threads";
+import { openStoreNoMigrate } from "./store.js";
+import { WorktreePool } from "./worktree.js";
+import { executeSweep } from "./storage-sweep.js";
+import { sweepRequest } from "./storage-sweep-process.js";
+const parent = process.ppid;
+let store;
+let finished = false;
+const closeStore = () => { const opened = store; store = undefined; opened?.close(); };
+const abandon = () => {
+    if (finished)
+        return;
+    finished = true;
+    try {
+        closeStore();
+    }
+    finally {
+        // This detached child owns the group, including any blocked rm/du descendants.
+        try {
+            if (process.platform !== "win32")
+                process.kill(-process.pid, "SIGKILL");
+        }
+        catch { /* no group */ }
+        process.exit(1);
+    }
+};
+process.once("disconnect", abandon);
+process.once("SIGTERM", abandon);
+// A separate thread also detects parent loss while synchronous filesystem work blocks the child's event loop.
+const watchdog = new Worker(`
+  const { workerData } = require('node:worker_threads');
+  setInterval(() => {
+    let lost = process.ppid !== workerData.parent || workerData.parent <= 1;
+    try { process.kill(workerData.parent, 0); } catch (error) { if (error.code === 'ESRCH') lost = true; }
+    if (!lost) return;
+    try { if (process.platform !== 'win32') process.kill(-process.pid, 'SIGKILL'); } catch {}
+    process.kill(process.pid, 'SIGKILL');
+  }, 1000);
+`, { eval: true, workerData: { parent } });
+watchdog.unref();
+watchdog.once("error", abandon);
+const finish = (code) => {
+    if (finished)
+        return;
+    finished = true;
+    closeStore();
+    void watchdog.terminate();
+    process.exitCode = code;
+    if (process.connected)
+        process.disconnect?.();
+};
+if (parent <= 1 || !process.connected)
+    abandon();
+process.once("message", async (request) => {
+    if (!sweepRequest(request)) {
+        finish(1);
+        return;
+    }
+    try {
+        const opened = openStoreNoMigrate(request.databaseFile);
+        if (!opened.ok)
+            throw new Error("Sweep database unavailable");
+        store = opened.store;
+        const started = Date.now();
+        const now = () => new Date(Date.parse(request.at) + Date.now() - started);
+        const pool = request.poolRoot === null ? null : new WorktreePool(store, { root: request.poolRoot });
+        const record = await executeSweep(store, { databaseFile: request.databaseFile, pool, tempRoots: request.tempRoots, actor: request.actor }, now);
+        closeStore();
+        if (!finished)
+            process.send?.({ version: 1, record }, error => finish(error === null ? 0 : 1));
+    }
+    catch {
+        finish(1);
+    }
+});

package/dist/storage-sweep-process.d.ts

@@ -0,0 +1,48 @@
+/** The storage child's bounded IPC protocol. No paths or process arguments are written to logs. */
+import { type ChildProcess } from "node:child_process";
+import type { SweepRecord } from "./storage-sweep.js";
+export type SweepRequest = {
+    version: 1;
+    databaseFile: string;
+    poolRoot: string | null;
+    tempRoots: string[];
+    actor: string;
+    at: string;
+};
+export type SweepExecutor = (request: SweepRequest) => Promise<SweepRecord>;
+export declare function sweepRequest(value: unknown): value is SweepRequest;
+export declare function sweepResponse(value: unknown, request: SweepRequest): value is {
+    version: 1;
+    record: SweepRecord;
+};
+export type SweepCompletion = {
+    ok: true;
+    record: SweepRecord;
+} | {
+    ok: false;
+    reason: "failed" | "timeout" | "stopped";
+};
+export type SweepSupervisor = {
+    readonly running: boolean;
+    start: (request: SweepRequest, complete: (result: SweepCompletion) => void, owner?: object) => boolean;
+    stop: (owner?: object) => void;
+};
+export declare const SWEEP_TIMEOUT_MS: number;
+export declare const SWEEP_KILL_GRACE_MS = 5000;
+/** The sweep runs behind everything else: a positive nice and, on macOS, the background CPU and I/O policy. */
+export declare const SWEEP_NICE = 10;
+/** How the child starts: taskpolicy execs Node in place, so the pid, its group and the IPC channel stay the same. */
+export declare function sweepLaunch(platform?: NodeJS.Platform, exists?: (path: string) => boolean): {
+    execPath: string;
+    prefix: string[];
+};
+/** Owns one child without lending its lifetime to a reconcile pass or its database connection. */
+export declare function createSweepSupervisor(options?: {
+    timeoutMs?: number;
+    killGraceMs?: number;
+    launch?: () => ChildProcess;
+    signal?: (child: ChildProcess, signal: NodeJS.Signals) => void;
+}): SweepSupervisor;
+export declare function storageSweepSupervisor(databaseFile: string): SweepSupervisor;
+/** Awaitable only for explicit callers/tests; automatic maintenance always uses start(). */
+export declare const runSweepChild: SweepExecutor;

package/dist/storage-sweep-process.js

@@ -0,0 +1,204 @@
+/** The storage child's bounded IPC protocol. No paths or process arguments are written to logs. */
+import { fork } from "node:child_process";
+import { existsSync } from "node:fs";
+import { setPriority } from "node:os";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const object = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const date = (value) => typeof value === "string" && Number.isFinite(Date.parse(value));
+const strings = (value) => Array.isArray(value) && value.every(one => typeof one === "string");
+export function sweepRequest(value) {
+    return object(value) && value.version === 1 && typeof value.databaseFile === "string" && value.databaseFile !== ":memory:" &&
+        (value.poolRoot === null || typeof value.poolRoot === "string") && strings(value.tempRoots) && typeof value.actor === "string" && date(value.at);
+}
+export function sweepResponse(value, request) {
+    if (!object(value) || value.version !== 1 || !object(value.record))
+        return false;
+    const record = value.record;
+    const kinds = ["test temp", "orphans", ...(request.poolRoot === null ? [] : ["checkouts"]), "runtimes", "dependencies"];
+    if (!date(record.at) || record.source !== "automatic" || record.actor !== request.actor || !Array.isArray(record.parts) || record.parts.length !== kinds.length)
+        return false;
+    return record.parts.every((part, index) => object(part) && part.kind === kinds[index] &&
+        [part.count, part.bytes, part.failed].every(n => typeof n === "number" && Number.isSafeInteger(n) && n >= 0) &&
+        strings(part.items) && part.items.length <= 20 && part.items.every(item => item.length <= 16_384) &&
+        (part.more === undefined || typeof part.more === "boolean") && (part.problem === undefined || (typeof part.problem === "string" && part.problem.length <= 65_536)));
+}
+export const SWEEP_TIMEOUT_MS = 20 * 60_000;
+export const SWEEP_KILL_GRACE_MS = 5_000;
+/** The sweep runs behind everything else: a positive nice and, on macOS, the background CPU and I/O policy. */
+export const SWEEP_NICE = 10;
+const TASKPOLICY = "/usr/sbin/taskpolicy";
+/** How the child starts: taskpolicy execs Node in place, so the pid, its group and the IPC channel stay the same. */
+export function sweepLaunch(platform = process.platform, exists = existsSync) {
+    return platform === "darwin" && exists(TASKPOLICY) ? { execPath: TASKPOLICY, prefix: ["-b", process.execPath] } : { execPath: process.execPath, prefix: [] };
+}
+/** Only source checkouts need tsx; installed builds use the sibling child and the same Node. */
+function forkSweep() {
+    const source = import.meta.url.endsWith(".ts");
+    const launch = sweepLaunch();
+    const child = fork(fileURLToPath(new URL(source ? "./storage-sweep-child.ts" : "./storage-sweep-child.js", import.meta.url)), [], {
+        execPath: launch.execPath, execArgv: [...launch.prefix, ...(source ? ["--import", "tsx"] : [])], stdio: ["ignore", "ignore", "ignore", "ipc"], detached: true,
+    });
+    // Before the request is sent, so every rm/du the child starts inherits it.
+    if (child.pid !== undefined) {
+        try {
+            setPriority(child.pid, SWEEP_NICE);
+        }
+        catch { /* the default priority still works */ }
+    }
+    // The service never waits on the child to exit; stop() and the child's parent-loss guard end it.
+    child.unref();
+    child.channel?.unref();
+    return child;
+}
+/** The fork is a group leader: rm/du and any other descendants must receive the same signal. */
+function signalGroup(child, signal) {
+    if (child.pid === undefined)
+        return;
+    if (process.platform !== "win32") {
+        try {
+            process.kill(-child.pid, signal);
+            return;
+        }
+        catch (error) {
+            if (error.code === "ESRCH")
+                return;
+        }
+    }
+    try {
+        child.kill(signal);
+    }
+    catch { /* already gone */ }
+}
+/** Owns one child without lending its lifetime to a reconcile pass or its database connection. */
+export function createSweepSupervisor(options = {}) {
+    const timeoutMs = options.timeoutMs ?? SWEEP_TIMEOUT_MS;
+    const killGraceMs = options.killGraceMs ?? SWEEP_KILL_GRACE_MS;
+    for (const value of [timeoutMs, killGraceMs]) {
+        if (!Number.isSafeInteger(value) || value < 1 || value > 2_147_483_647)
+            throw new Error("Invalid sweep process time limit");
+    }
+    const signal = options.signal ?? signalGroup;
+    let active = null;
+    const stoppedOwners = new WeakSet();
+    return {
+        get running() { return active !== null; },
+        stop(owner) {
+            if (owner !== undefined)
+                stoppedOwners.add(owner);
+            if (owner === undefined || active?.owner === owner)
+                active?.stop();
+        },
+        start(request, complete, owner) {
+            if (active !== null || (owner !== undefined && stoppedOwners.has(owner)))
+                return false;
+            let child;
+            let settled = false, closed = false, killing = false, killed = false;
+            let record = null;
+            let deadline;
+            let grace;
+            const settle = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(deadline);
+                complete(result);
+            };
+            const release = () => {
+                if (!closed || grace !== undefined)
+                    return;
+                clearTimeout(deadline);
+                child.removeListener("message", message);
+                child.removeListener("error", error);
+                child.removeListener("close", close);
+                // A late IPC write error must not become an unhandled EventEmitter error.
+                child.on("error", () => { });
+                active = null;
+            };
+            const kill = () => {
+                if (killed)
+                    return;
+                killed = true;
+                killing = true;
+                clearTimeout(grace);
+                grace = undefined;
+                signal(child, "SIGKILL");
+                release();
+            };
+            const terminate = (reason) => {
+                if (settled)
+                    return;
+                killing = true;
+                signal(child, "SIGTERM");
+                // Even if the leader exits on TERM, descendants may ignore it. Keep the group owned through KILL.
+                grace = setTimeout(kill, killGraceMs);
+                grace.unref?.();
+                settle({ ok: false, reason });
+            };
+            const message = (value) => {
+                if (settled)
+                    return;
+                if (record !== null || !sweepResponse(value, request)) {
+                    terminate("failed");
+                    return;
+                }
+                record = value.record;
+            };
+            const error = () => terminate("failed");
+            const close = (code) => {
+                closed = true;
+                if (!settled) {
+                    if (code === 0 && record !== null)
+                        settle({ ok: true, record });
+                    else {
+                        signal(child, "SIGKILL");
+                        settle({ ok: false, reason: "failed" });
+                    }
+                }
+                if (!killing || grace === undefined)
+                    release();
+            };
+            try {
+                child = (options.launch ?? forkSweep)();
+            }
+            catch {
+                complete({ ok: false, reason: "failed" });
+                return true;
+            }
+            active = { owner, stop: () => { kill(); settle({ ok: false, reason: "stopped" }); } };
+            child.on("message", message);
+            child.on("error", error);
+            child.once("close", close);
+            deadline = setTimeout(() => terminate("timeout"), timeoutMs);
+            deadline.unref?.();
+            try {
+                child.send(request, error => { if (error !== null)
+                    terminate("failed"); });
+            }
+            catch {
+                terminate("failed");
+            }
+            return true;
+        },
+    };
+}
+// All watch loops in this process share a flight. Other services arbitrate the claim in SQLite.
+const supervisors = new Map();
+export function storageSweepSupervisor(databaseFile) {
+    const key = resolve(databaseFile);
+    let supervisor = supervisors.get(key);
+    if (supervisor === undefined) {
+        supervisor = createSweepSupervisor();
+        supervisors.set(key, supervisor);
+    }
+    return supervisor;
+}
+/** Awaitable only for explicit callers/tests; automatic maintenance always uses start(). */
+export const runSweepChild = request => new Promise((resolve, reject) => {
+    createSweepSupervisor().start(request, result => {
+        if (result.ok)
+            resolve(result.record);
+        else
+            reject(new Error("Sweep child failed"));
+    });
+});

package/dist/storage-sweep-schedule.d.ts

@@ -0,0 +1,30 @@
+import { type SweepDeps, type SweepRecord } from "./storage-sweep.js";
+import { type SweepSupervisor } from "./storage-sweep-process.js";
+import { type Store } from "./store.js";
+/** How often the service looks again at a due sweep. */
+export declare const SWEEP_CHECK_MS: number;
+/** After this long without an automatic sweep, it runs even while work is running or waiting. */
+export declare const SWEEP_FORCE_MS: number;
+export type SweepBusy = "run" | "claim" | "ready";
+/** What keeps a due sweep waiting now, or null when nothing is running or waiting. */
+export declare function sweepBusy(store: Store, now: Date): SweepBusy | null;
+/** Whether a long-lived Toolroll service holds a current lease. Rows from earlier services don't count. */
+export declare function sweepServiceRunning(store: Store, now: Date): boolean;
+export type SweepState = "off" | "sweeping" | "no-service" | "recent" | "retry" | "busy" | "forced" | "due";
+export type SweepSchedule = {
+    state: SweepState;
+    /** The latest automatic sweep's recorded time, or null when there has been none. */
+    lastAt: string | null;
+    /** When the next sweep is due, or null when it is off or due now. */
+    nextAt: string | null;
+    busy: SweepBusy | null;
+};
+/** The sweep's schedule from what is recorded now; reads only. */
+export declare function sweepSchedule(store: Store, now: Date, env?: NodeJS.ProcessEnv): SweepSchedule;
+/** Why the sweep is waiting or when it is next due, after "Automatic sweep: ". `when` formats a time for the reader. */
+export declare function sweepScheduleWords(schedule: SweepSchedule, when: (at: string) => string): string;
+/**
+ * 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 declare function idleStorageSweep(store: Store, deps: SweepDeps, now: () => Date, supervisor?: SweepSupervisor): SweepRecord | null;

package/dist/storage-sweep-schedule.js

@@ -0,0 +1,164 @@
+/**
+ * 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 };
+    }
+    const due = dueAt(store);
+    const nextAt = cursor === 0 || due <= now.getTime() ? null : new Date(due).toISOString();
+    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 };
+    }
+    const from = forcedFrom(store, last);
+    if (from !== null && now.getTime() - from >= SWEEP_FORCE_MS)
+        return { state: "forced", lastAt, nextAt: null, busy: null };
+    const busy = sweepBusy(store, now);
+    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.";
+        case "sweeping": return "sweeping now.";
+        case "no-service": return "waiting: no Toolroll service running.";
+        case "recent": return `swept recently, next due ${when(schedule.nextAt)}.`;
+        case "retry": return `retry due ${when(schedule.nextAt)}.`;
+        case "busy": return `due, waiting: ${BUSY_WORDS[schedule.busy]}.`;
+        case "forced": return "over 48 hours since the last sweep; it runs at the next check even if work is running.";
+        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))
+        return null;
+    const seen = looked.get(supervisor);
+    if (seen !== undefined && at.getTime() - seen < SWEEP_CHECK_MS && at.getTime() >= seen)
+        return null;
+    looked.set(supervisor, at.getTime());
+    const ready = () => {
+        if (at.getTime() < dueAt(store))
+            return false;
+        const from = forcedFrom(store, lastSweep(store, "automatic"));
+        return (from !== null && at.getTime() - from >= SWEEP_FORCE_MS) || sweepBusy(store, at) === null;
+    };
+    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");
+    const results = connection.store;
+    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;
+            store.setServiceCursor(SWEEP_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(SWEEP_CURSOR) === at.getTime()) {
+                        results.setServiceCursor(SWEEP_CURSOR, Math.max(1, 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(SWEEP_CURSOR) === at.getTime())
+                    store.setServiceCursor(SWEEP_CURSOR, Math.max(1, at.getTime() - SWEEP_EVERY_MS + RETRY_MS), now());
+            });
+        }
+        return completed;
+    }
+    finally {
+        if (!owned)
+            results.close();
+    }
+}

package/dist/storage-sweep.d.ts

@@ -1,7 +1,9 @@
 import { type Located } from "./orphan-sweep.js";
 import { type ProcessRow } from "./run-closeout.js";
 import type { Store } from "./store.js";
-import type { WorktreePool } from "./worktree.js";
+import { type WorktreePool } from "./worktree.js";
+import { type SweepCompletion, type SweepExecutor } from "./storage-sweep-process.js";
+export declare const SWEEP_CURSOR = "storage-sweep";
 export declare const SWEEP_EVERY_MS = 86400000;
 /** A sweep that failed somewhere, or left work for later, runs again this soon. */
 export declare const RETRY_MS: number;
@@ -26,17 +28,40 @@ export type SweepDeps = {
     pool: WorktreePool | null;
     tempRoots: readonly string[];
     actor?: string;
+    /** Parent lifecycle only; never sent to the child. */
+    owner?: object;
     census?: () => ProcessRow[];
     locate?: (pids: readonly number[]) => Map<number, Located>;
     inUse?: () => string[];
+    scripts?: (pids: readonly number[]) => string[];
     graceMs?: number;
 };
 export declare function storageSweepOff(env?: NodeJS.ProcessEnv): boolean;
-export declare function storageSweepDue(store: Store, now: Date): boolean;
-/** The daily sweep, when it's due and on: one worker takes it. Null when it wasn't this pass's to run. */
-export declare function dailyStorageSweep(store: Store, deps: SweepDeps, now: () => Date): Promise<SweepRecord | null>;
-/** One sweep, now, every part; saved and in the ledger. Each part's failure is its own: the others still run. */
-export declare function sweepStorage(store: Store, deps: SweepDeps, now: () => Date): Promise<SweepRecord>;
+export declare function sweepFailure(at: string, actor: string, withPool: boolean, reason: Exclude<SweepCompletion, {
+    ok: true;
+}>["reason"]): SweepRecord;
+/**
+ * What live work uses now. Live work: an open run, a current (unexpired, unreleased) lease, or a checkout leased, held
+ * by a process or whose task has either. It uses its checkouts, the shared install each links, and every folder its
+ * open runs' processes (with their groups and what they started) run from. `where` says where the given processes run
+ * from, or null when that can't be read: then `blind`, and everything stays. With nothing live, nothing is read from the OS.
+ */
+export type LiveWork = {
+    live: boolean;
+    paths: string[];
+    blind: boolean;
+};
+export declare function liveWork(store: Store, depsRoot: string, now: Date, where: (pids: readonly number[]) => string[] | null): LiveWork;
+/**
+ * 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 declare function liveUse(store: Store, deps: SweepDeps, now: () => Date): (path: string) => boolean;
+/** Parent side: no filesystem/process scans here. The executor seam is for deterministic unit tests only. */
+export declare function sweepStorage(store: Store, deps: SweepDeps, now: () => Date, execute?: SweepExecutor): Promise<SweepRecord>;
+export declare function sweepKinds(withPool: boolean): SweepKind[];
+/** Child side (also a focused unit-test seam): every scan and removal, without saving the parent's result. */
+export declare function executeSweep(store: Store, deps: SweepDeps, now: () => Date): Promise<SweepRecord>;
 /** Save what a sweep or a clean-up by hand did (the latest few are kept), with one ledger entry saying it. */
 export declare function saveSweep(store: Store, record: SweepRecord): SweepRecord;
 /** The latest sweep (of `source`, or either), or null when there has been none. */