toolroll 0.9.59 → 0.9.61

package/dist/steer-status.js

@@ -0,0 +1,44 @@
+/** `liveBuild`: the task has a build whose agent is running and reads its steering folder (Store.steeringLiveBuild). */
+export function steerStandingOf(note, liveBuild) {
+    if (note.authorshipState !== "verified")
+        return "unverified";
+    if (note.supersededAt !== null)
+        return "ended";
+    if (note.deliveredAt !== null)
+        return "read";
+    if (!liveBuild)
+        return "next-attempt";
+    // Sent to the running build every time it was owed, and never moved to handled/ (steer-live.ts).
+    return note.liveMissedAt !== null ? "not-picked-up" : "waiting";
+}
+/** The words, and the moment the agent read it when it has: each surface renders that time its own way. */
+export function steerStandingParts(note, liveBuild) {
+    switch (steerStandingOf(note, liveBuild)) {
+        case "read": return { words: "Read by the agent at", readAt: note.ackedAt ?? note.deliveredAt };
+        case "waiting": return { words: "Waiting for the agent to read it", readAt: null };
+        case "not-picked-up": return { words: "Not picked up", readAt: null };
+        case "next-attempt": return { words: "Will reach the next attempt", readAt: null };
+        case "ended": return { words: "The task ended before the agent read it", readAt: null };
+        case "unverified": return { words: "Saved before notes required a sign-in; never sent", readAt: null };
+    }
+}
+export function steerStandingWords(note, liveBuild, time) {
+    const { words, readAt } = steerStandingParts(note, liveBuild);
+    return readAt === null ? words : `${words} ${time(readAt)}`;
+}
+/** Where a note filed now goes, said before or right after filing it. */
+export function steerDestinationWords(liveBuild, liveInput = false) {
+    // A Claude build with live input takes it in seconds (steer-live.ts); any other running build reads its folder.
+    return liveBuild && liveInput
+        ? "The running agent gets it now."
+        : liveBuild
+            ? "The running agent reads it when it next checks for notes."
+            : "The next attempt reads it before starting.";
+}
+/** A paused live build's one sentence: until when it can wait before it ends, and how long that is (live-input.ts
+ * idleLimit), or only that it is paused when it has no idle limit. `time` renders the moment its surface's way. */
+export function pausedWords(pause, time) {
+    if (pause.until === null || pause.limitMs === null)
+        return "Paused.";
+    return `Paused. It can wait until ${time(pause.until)} (${Math.max(1, Math.round(pause.limitMs / 60_000))} min) before it ends.`;
+}

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,41 @@
+/** 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;
+/** 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,187 @@
+/** The storage child's bounded IPC protocol. No paths or process arguments are written to logs. */
+import { fork } from "node:child_process";
+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;
+/** 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 child = fork(fileURLToPath(new URL(source ? "./storage-sweep-child.ts" : "./storage-sweep-child.js", import.meta.url)), [], {
+        execArgv: source ? ["--import", "tsx"] : [], stdio: ["ignore", "ignore", "ignore", "ipc"], detached: true,
+    });
+    // A one-shot CLI may exit after reconcile; the child's parent-loss guard then ends 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 workers arbitrate the daily 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.d.ts

@@ -1,7 +1,8 @@
 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 Store } from "./store.js";
+import { type WorktreePool } from "./worktree.js";
+import { type SweepSupervisor, type SweepExecutor } from "./storage-sweep-process.js";
 export declare const SWEEP_EVERY_MS = 86400000;
 /** A sweep that failed somewhere, or left work for later, runs again this soon. */
 export declare const RETRY_MS: number;
@@ -26,17 +27,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>;
+/** Claim and launch only. A hung child never holds reconciliation or the caller's store open. */
+export declare function dailyStorageSweep(store: Store, deps: SweepDeps, now: () => Date, supervisor?: SweepSupervisor): SweepRecord | null;
+/**
+ * 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. */