toolroll 0.9.103 → 0.9.105

package/dist/steer-mailbox.js

@@ -1,44 +1,10 @@
-/**
- * The running build's steering mailbox (v120). A note an operator files
- * while a build runs used to wait for the next attempt; now the builder's
- * pulse writes it into one nonce-named folder in the worktree, as a numbered
- * file the agent reads and acknowledges by moving it into `handled/` — the
- * same small contract a person's own inbox keeps:
- *
- * - The durable record is the delivery. A note is mailed (written into the
- *   folder) and read (moved by the agent); nothing else counts. A hook
- *   reminding the agent, or a file the pulse wrote, proves nothing.
- * - Numbers are never reused: the next one is past every name in the folder
- *   and in `handled/`, and past every one this pulse has used.
- * - Whatever is still unread when the attempt ends keeps today's road: the
- *   note stays pending, the next attempt's brief quotes it, and a task that
- *   ends first supersedes it.
- *
- * Every step is bookkeeping, and bookkeeping never fails a build: a folder
- * the agent removed is made again, one it replaced with anything but a real
- * directory is never written through, and an error waits for the next beat.
- *
- * Two boundaries, because the folder lives where the agent and anything it
- * runs can write:
- * - Every genuine note carries this attempt's key, which only the brief and
- *   the notes themselves name. A file in the folder without it was not
- *   written by the operator, and the brief tells the agent to act on none.
- *   (The brief rides the agent's argv, so a process that reads argv could
- *   learn it: this keeps ordinary repository code from posing as the
- *   operator, not a determined local process.)
- * - The pulse writes only while the folder still resolves to this worktree's
- *   own folder, before and after each write, so swapping it for a link can
- *   never make the plane write a note somewhere else.
- */
 import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { fence } from "./brief-fence.js";
 import { ANSWER_FILE_BYTES, findingAnswerSchema, findingLine, findingSourceWords, FINDING_ROUND_LIMIT, markFindingDelivered, markFindingRead, saveFindingAnswer, undeliveredFindings } from "./findings.js";
 import { FAILING_FIRST_FILE, failingFirstReportSchema, saveFailingFirstReport } from "./failing-first.js";
 export const STEER_HANDLED = "handled";
-/** Findings have their own folder: a finding is not operator steering, and must never read as it (findings.ts). */
 export const STEER_FINDINGS = "findings";
-/** What the agent writes back: one file per finding it answers. */
 export const STEER_ANSWERS = "answers";
 export const findingNoteName = (id) => `finding-${id}.json`;
 const NOTE_NAME = /^(\d+)\.json$/;
@@ -51,7 +17,6 @@ const isRealDirectory = (path) => {
         return false;
     }
 };
-/** Make the folder and its handled/ inside the worktree; null when it cannot be made. */
 export function openSteerMailbox(worktree, folder, runId, taskRef, key) {
     let realDir;
     try {
@@ -63,7 +28,6 @@ export function openSteerMailbox(worktree, folder, runId, taskRef, key) {
     const box = { runId, taskRef, folder, dir: join(worktree, folder), realDir, key, last: 0, waiting: new Map(), findingsWaiting: new Set() };
     return ensureFolder(box) ? box : null;
 }
-/** The folder is still this worktree's own, not a link to somewhere else. */
 const stillInside = (box) => {
     try {
         return realpathSync(box.dir) === box.realDir;
@@ -74,7 +38,6 @@ const stillInside = (box) => {
 };
 function ensureFolder(box) {
     for (const path of [box.dir, join(box.dir, STEER_HANDLED), join(box.dir, STEER_FINDINGS), join(box.dir, STEER_ANSWERS)]) {
-        // A folder swapped for a link gets nothing made inside it.
         if (path !== box.dir && !stillInside(box))
             return false;
         try {
@@ -84,7 +47,6 @@ function ensureFolder(box) {
             if (error.code !== "EEXIST")
                 return false;
         }
-        // Something the agent put in the folder's place is never written through.
         if (!isRealDirectory(path))
             return false;
     }
@@ -108,7 +70,6 @@ function highestNumber(box) {
     }
     return highest;
 }
-/** Every waiting note the agent moved into handled/ is read, by this run. */
 function collectAcknowledgements(store, box, now) {
     if (box.waiting.size === 0)
         return;
@@ -129,16 +90,14 @@ function collectAcknowledgements(store, box, now) {
         store.ackSteerNote(noteId, box.runId, now);
     }
 }
-/** Remove a name this pulse wrote, only while the folder is still this worktree's own; a link goes, never its target. */
 function removeOwn(box, name) {
     if (!stillInside(box))
         return;
     try {
         unlinkSync(join(box.dir, name));
     }
-    catch { /* never written, or the agent already took it */ }
+    catch { }
 }
-/** Write each note this run has not seen yet: a temp name, then the number. */
 function mailNotes(store, box, now) {
     const notes = store.mailableSteerNotes(box.taskRef, box.runId);
     if (notes.length === 0 || !ensureFolder(box))
@@ -158,8 +117,6 @@ function mailNotes(store, box, now) {
             removeOwn(box, temp);
             return;
         }
-        // Checked again after the write: a folder swapped for a link mid-write
-        // leaves the note unrecorded, deletes nothing, and mails nothing more this beat.
         if (!stillInside(box))
             return;
         box.last = number;
@@ -174,14 +131,10 @@ function mailNotes(store, box, now) {
             box.waiting.set(number, note.id);
         }
         else {
-            // The task ended or the note settled between the read and the write, or
-            // the mailing could not be recorded: an unrecorded file would only be
-            // mailed twice, so it goes, and the next beat tries again.
             removeOwn(box, name);
         }
     }
 }
-/** A file the agent wrote, read without following a link and never past `limit`; null for anything else. */
 function readOwn(path, limit) {
     let fd;
     try {
@@ -205,8 +158,6 @@ function readOwn(path, limit) {
         closeSync(fd);
     }
 }
-/** Write each open finding this run has not been given. The file carries the attempt's key and quoted data only; what
- * to do with it is the brief's rule, never the file's. */
 function mailFindings(store, box, now) {
     const findings = undeliveredFindings(store, box.taskRef, box.runId);
     if (findings.length === 0 || !ensureFolder(box))
@@ -241,7 +192,6 @@ function mailFindings(store, box, now) {
             removeOwn(box, join(STEER_FINDINGS, name));
     }
 }
-/** A finding moved to handled/ is read, and only read: it stays open until an answer counts. */
 function collectFindingReads(store, box, now) {
     if (box.findingsWaiting.size === 0)
         return;
@@ -262,7 +212,6 @@ function collectFindingReads(store, box, now) {
         markFindingRead(store, id, box.runId, now);
     }
 }
-/** Save each answer in answers/ that carries this attempt's key. It counts, or doesn't, when the attempt settles. */
 function collectAnswers(store, box, now) {
     const dir = join(box.dir, STEER_ANSWERS);
     if (!stillInside(box) || !isRealDirectory(dir))
@@ -293,7 +242,6 @@ function collectAnswers(store, box, now) {
         saveFindingAnswer(store, box.runId, read.data, now);
     }
 }
-/** The agent's failing-test-first report, when its task asked for one. Its own words, saved as that (evidence-pair.ts). */
 function collectFailingFirst(store, box, now) {
     if (!stillInside(box))
         return;
@@ -311,7 +259,6 @@ function collectFailingFirst(store, box, now) {
     if (read.success && read.data.key === box.key)
         saveFailingFirstReport(store, box.taskRef, box.runId, read.data, now);
 }
-/** One beat: record what the agent read and answered, then mail what is new while the agent runs. */
 export function pulseSteerMailbox(store, box, now, agentRunning) {
     collectAcknowledgements(store, box, now);
     collectFindingReads(store, box, now);
@@ -321,30 +268,23 @@ export function pulseSteerMailbox(store, box, now, agentRunning) {
         mailFindings(store, box, now);
     }
 }
-/** The attempt is over: one last read, then the folder goes. Unread notes stay pending for the next attempt. */
 export function closeSteerMailbox(store, box, now) {
     try {
         collectAcknowledgements(store, box, now);
     }
-    catch { /* the notes stay pending */ }
+    catch { }
     try {
         collectFindingReads(store, box, now);
         collectAnswers(store, box, now);
         collectFailingFirst(store, box, now);
     }
-    catch { /* the findings stay open */ }
+    catch { }
     try {
         rmSync(box.dir, { recursive: true, force: true });
     }
-    catch { /* the next attempt's sweep removes it */ }
+    catch { }
 }
 const shellQuote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
-/**
- * Claude's doorbell: a synchronous PostToolUse hook that lists the folder and,
- * while a note is unread, hands the agent one line of context between tool
- * calls. It only says notes are waiting — it never quotes one, and its firing
- * is never an acknowledgement. Rendered into the run's own --settings.
- */
 export function claudeSteerHooks(dir, folder) {
     const context = {
         hookSpecificOutput: {
@@ -353,7 +293,6 @@ export function claudeSteerHooks(dir, folder) {
         },
     };
     const command = `set -- ${shellQuote(dir)}/[0-9]*.json; [ -e "$1" ] || exit 0; printf ${shellQuote(`${JSON.stringify(context)}\n`)} "$#"`;
-    // Findings ring their own bell, in their own words: never "operator", because their text is not the operator's.
     const findings = {
         hookSpecificOutput: {
             hookEventName: "PostToolUse",

package/dist/steer-status.js

@@ -1,4 +1,3 @@
-/** `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";
@@ -8,10 +7,8 @@ export function steerStandingOf(note, liveBuild) {
         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: "Picked up at", readAt: note.ackedAt ?? note.deliveredAt };
@@ -26,17 +23,13 @@ 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.";

package/dist/stop-proof.js

@@ -1,25 +1,3 @@
-/**
- * Toolroll's own proof that a finished build stopped. Nobody is ever asked to "confirm it stopped": a person can't see
- * whether a process exited, and asking defeats unattended builds and releases.
- *
- * When a finished run's process record is missing or incomplete (a spawn whose process ID was never written, a lost
- * process-tree snapshot, an agent start with no witness, a workspace note that can't be read), Toolroll looks at this
- * computer itself, a grace period after the run finished:
- *
- *   - no process the run is known to have started is still that process (pid and birth time, never a pid alone);
- *   - no process works in the run's folder (its working directory) or names it in its command line;
- *   - this process still tracks no live child for the run.
- *
- * A leftover it finds is stopped (SIGTERM, then SIGKILL) only when it is proven the run's: in the run's folder, born
- * while the run ran, not this service or its ancestors, and orphaned or descended from the run's
- * own processes — or it descends from such a leftover. A pid now held by a process born after the run ended is never
- * the run's. Anything else in the folder (a person's shell or editor) is left alone and holds the proof, in plain
- * words. When this computer can't look (the process table or the folder listing can't be read, or the run's
- * processes belong to another computer), the stop stays unproven and the reason is shown; there is still nothing to
- * vouch for.
- *
- * Command lines are read only to match the folder's path in memory; they are never stored or shown.
- */
 import { execFileSync } from "node:child_process";
 import { existsSync, readdirSync, readlinkSync, realpathSync } from "node:fs";
 import { hostname } from "node:os";
@@ -28,12 +6,8 @@ import { ownedProcessCount, runOwnerTag } from "./exec.js";
 import { closeoutTargets, processCensus, protectedProcesses, stopProcesses, stoppedWords } from "./run-closeout.js";
 import { localWitnessSql, recordStopProofBlocked, settleRunStopByObservation } from "./store.js";
 import { worktreeProcessOccupancy } from "./worktree.js";
-/** How long after a run finished its processes have to go on their own before Toolroll looks. */
 export const STOP_PROOF_GRACE_MS = 60_000;
-/** `ps` gives ages in whole seconds: a process born this close to the run's start or end still counts as during it. */
 const BIRTH_SLACK_MS = 2_000;
-/** One pass's shared look at this computer: the process table, folders and command lines are read once for every
- * run the pass checks, and again after anything was stopped. */
 export function sharedLook(options = {}) {
     let census = null, folders = null, lines = null;
     return {
@@ -44,14 +18,12 @@ export function sharedLook(options = {}) {
         refresh: () => { census = null; folders = null; lines = null; options.refresh?.(); },
     };
 }
-/** Which processes work inside each path, from the OS: /proc on Linux, lsof on macOS. Unlike a best-effort listing,
- * it throws when the listing can't be read: no answer is never "nobody". */
 export function processesInStrict(paths, listing = processFolders()) {
     const found = new Map();
     const roots = paths.map(path => { let real = path; try {
         real = realpathSync(path);
     }
-    catch { /* gone */ } return { path, real }; });
+    catch { } return { path, real }; });
     for (const { pid, cwd } of listing) {
         for (const one of roots)
             if ([one.path, one.real].some(root => cwd === root || cwd.startsWith(root + sep)))
@@ -59,7 +31,6 @@ export function processesInStrict(paths, listing = processFolders()) {
     }
     return found;
 }
-/** Every process's working directory, from the OS; throws when the listing can't be read. */
 export function processFolders() {
     const found = [];
     const note = (pid, cwd) => { found.push({ pid, cwd }); };
@@ -67,11 +38,10 @@ export function processFolders() {
         for (const name of readdirSync("/proc")) {
             if (!/^\d+$/.test(name))
                 continue;
-            // Gone, or another user's (never a process this user's run started).
             try {
                 note(Number(name), readlinkSync(`/proc/${name}/cwd`));
             }
-            catch { /* not readable */ }
+            catch { }
         }
         if (found.length === 0)
             throw new Error("no process folder could be read");
@@ -84,8 +54,6 @@ export function processFolders() {
         text = execFileSync("lsof", ["-nP", "-d", "cwd", "-Fpn"], { encoding: "utf8", timeout: 20_000, maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] });
     }
     catch (error) {
-        // lsof exits 1 when some process can't be inspected (another user's) yet still lists every one it can.
-        // A timeout, a signal or an overflow leaves a partial listing, which is no answer at all.
         const failure = error;
         if (failure.status !== 1 || failure.signal != null || typeof failure.code === "string")
             throw new Error("the process folder listing could not be read");
@@ -102,7 +70,6 @@ export function processFolders() {
     }
     return found;
 }
-/** Every process's command line, by pid. Read to match a folder's path in memory only; never stored or shown. */
 export function processCommandLines() {
     if (process.platform === "win32")
         throw new Error("command lines can't be read here");
@@ -117,7 +84,6 @@ export function processCommandLines() {
         throw new Error("the process list was empty");
     return lines;
 }
-/** Whether a command line names `path` or something inside it (a whole path, never a longer folder's prefix). */
 export function namesPath(line, path) {
     for (let at = line.indexOf(path); at >= 0; at = line.indexOf(path, at + 1)) {
         const before = at === 0 ? " " : line[at - 1], after = line[at + path.length];
@@ -126,10 +92,6 @@ export function namesPath(line, path) {
     }
     return false;
 }
-/**
- * One look at this computer for one finished run: which processes are its leftovers (`targets`) and which are in its
- * folder without being proven its (`blockers`). Throws when something can't be read.
- */
 function look(store, runId, options) {
     const run = store.getRun(runId);
     const census = (options.census ?? (() => processCensus()))();
@@ -137,13 +99,11 @@ function look(store, runId, options) {
         throw new Error("the process table was empty");
     const guard = protectedProcesses(census, options.self);
     const byPid = new Map(census.map(row => [row.pid, row]));
-    // Its recorded processes still open: still the same process (pid and birth), or a member of its open group.
     const open = store.handle.prepare(`SELECT pid, process_group, observed_at FROM run_process
     WHERE run = ? AND exited_at IS NULL AND pid IS NOT NULL AND containment IS NULL AND container IS NULL`).all(runId)
         .map(row => ({ pid: Number(row["pid"]), group: Number(row["process_group"]) === 1, observedAt: Date.parse(String(row["observed_at"])) }))
         .filter(one => Number.isFinite(one.observedAt));
     const recorded = new Set(closeoutTargets(census, open, guard).map(row => row.pid));
-    // Its folder: working directory inside it, or named on the command line.
     const folder = new Set();
     if (run.worktree !== null) {
         const paths = [run.worktree];
@@ -152,7 +112,7 @@ function look(store, runId, options) {
             if (real !== run.worktree)
                 paths.push(real);
         }
-        catch { /* gone: only its name can match */ }
+        catch { }
         for (const pids of (options.cwds ?? processesInStrict)(paths).values())
             for (const pid of pids)
                 folder.add(pid);
@@ -163,16 +123,12 @@ function look(store, runId, options) {
     const started = Date.parse(run.startedAt) - BIRTH_SLACK_MS, ended = Date.parse(run.finishedAt) + BIRTH_SLACK_MS;
     const during = (row) => row.bornAt >= started && row.bornAt <= ended;
     const unguarded = (row) => !guard.pids.has(row.pid) && !guard.groups.has(row.pgid);
-    // A leftover in the folder: born while the run ran and orphaned (its starter gone). A terminal proves nothing either
-    // way here: a worker started from a terminal hands its controlling terminal to everything its runs start.
     const orphans = new Set();
     for (const pid of folder) {
         const row = byPid.get(pid);
         if (row !== undefined && during(row) && unguarded(row) && row.ppid === 1)
             orphans.add(pid);
     }
-    // And whatever descends from a leftover, wherever it works: from the run's own recorded processes (proven by pid
-    // and birth) or from an orphan found in its folder.
     const descendsFrom = (roots, row) => {
         for (let at = row, hops = 0; at !== undefined && at.pid > 1 && hops < 64; at = byPid.get(at.ppid), hops++)
             if (roots.has(at.pid))
@@ -181,13 +137,7 @@ function look(store, runId, options) {
     };
     const targets = census.filter(row => unguarded(row) && (descendsFrom(recorded, row) || descendsFrom(orphans, row)));
     const chosen = new Set(targets.map(row => row.pid));
-    // In the folder while the run ran but not proven its (a person's shell or editor: a live parent Toolroll didn't start):
-    // left alone, and the proof waits for it. Born before the run or after it ended (and not a leftover's child) can't
-    // be the run's, so it neither blocks nor is touched.
     const blockers = [...folder].map(pid => byPid.get(pid)).filter((row) => row !== undefined && !chosen.has(row.pid) && during(row) && !guard.pids.has(row.pid));
-    // A run with no folder (a reviewer's): nothing names its processes but their groups. An orphan born while it ran
-    // in one of its recorded process groups may be its own, or a newer group that took the number: never signalled,
-    // it holds the proof.
     if (run.worktree === null) {
         const groups = new Set(store.handle.prepare("SELECT pid FROM run_process WHERE run = ? AND pid IS NOT NULL AND process_group = 1").all(runId).map(row => Number(row["pid"])));
         for (const row of census)
@@ -196,17 +146,12 @@ function look(store, runId, options) {
     }
     return { census, targets, blockers, inFolder: folder.size };
 }
-/**
- * Prove one finished run stopped, on this computer, without asking anyone (see the file's comment). Walks the run's
- * owned runs one unproven stop at a time. Never signals a process that isn't proven the run's.
- */
 export async function proveRunStopped(store, runId, clock, options = {}) {
     let stopped = 0;
     for (let pass = 0; pass < 8; pass++) {
         const fact = store.stopQuiescenceFact(runId);
         if (fact === null)
             return { run: runId, outcome: pass === 0 ? "skipped" : "settled", words: "stopped", ...(stopped > 0 ? { stopped } : {}) };
-        // Already proven by the record (an unrecorded spawn whose run's every process is proven gone): settle it now.
         if (fact.kind === "settling" && store.settleUnspawnedWitnesses(clock(), fact.run) > 0) {
             store.settleQuiescentStops(clock());
             continue;
@@ -233,7 +178,7 @@ export async function proveRunStopped(store, runId, clock, options = {}) {
                 if (held.held)
                     return { run: subject, outcome: "waiting", words: `its folder is still held by process ${held.by}` };
             }
-            catch { /* an unreadable note: the look below decides */ }
+            catch { }
         }
         let seen;
         try {
@@ -273,8 +218,6 @@ function block(store, runId, words, detail, now) {
     recordStopProofBlocked(store, runId, words, detail, now);
     return { run: runId, outcome: "blocked", words };
 }
-/** The worker's pass (operate.ts reconcile): every finished run of this computer whose stop is unproven where
- * Toolroll's own look can prove it. A batch a pass, oldest first; a blocked run never holds newer ones back. */
 export async function proveFinishedRunsStopped(store, clock, options = {}) {
     const grace = options.afterFinishMs ?? STOP_PROOF_GRACE_MS;
     const before = new Date(clock().getTime() - grace).toISOString();
@@ -289,7 +232,7 @@ export async function proveFinishedRunsStopped(store, clock, options = {}) {
         try {
             out.push(await proveRunStopped(store, runId, clock, shared));
         }
-        catch { /* one run's failure never stops the pass; the next pass looks again */ }
+        catch { }
     }
     return out;
 }

package/dist/storage-sweep-child.js

@@ -1,4 +1,3 @@
-/** 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";
@@ -16,18 +15,16 @@ const abandon = () => {
         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 */ }
+        catch { }
         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(() => {
@@ -57,7 +54,6 @@ process.once("message", async (request) => {
         finish(1);
         return;
     }
-    // Node and the sweep's code are loaded: from here on, on macOS, the work and everything it starts runs in the background.
     enterSweepBackground();
     try {
         const opened = openStoreNoMigrate(request.databaseFile);

package/dist/storage-sweep-process.js

@@ -1,4 +1,3 @@
-/** The storage child's bounded IPC protocol. No paths or process arguments are written to logs. */
 import { execFileSync, fork } from "node:child_process";
 import { existsSync } from "node:fs";
 import { setPriority } from "node:os";
@@ -25,19 +24,11 @@ export function sweepResponse(value, request) {
 }
 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 enters the background policy on macOS, or null elsewhere (or without taskpolicy): the child runs it on
- * its own pid once Node has started and loaded the sweep, before any sweep work. Everything it starts after that (rm,
- * du, git) inherits the policy. Starting Node itself under it let a busy machine hold the child's start for as long
- * as anything else wanted the CPU, before it had done any of the work the policy is for.
- */
 export function sweepBackground(pid, platform = process.platform, exists = existsSync) {
     return platform === "darwin" && exists(TASKPOLICY) ? { file: TASKPOLICY, args: ["-b", "-p", String(pid)] } : null;
 }
-/** In the child: the background policy from now on. Without it the sweep still runs, at the nice its parent set. */
 export function enterSweepBackground(run = (file, args) => { execFileSync(file, args, { stdio: "ignore", timeout: 5_000 }); }) {
     const command = sweepBackground(process.pid);
     if (command === null)
@@ -50,25 +41,21 @@ export function enterSweepBackground(run = (file, args) => { execFileSync(file,
         return false;
     }
 }
-/** 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,
     });
-    // 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 */ }
+        catch { }
     }
-    // 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;
@@ -85,9 +72,8 @@ function signalGroup(child, signal) {
     try {
         child.kill(signal);
     }
-    catch { /* already gone */ }
+    catch { }
 }
-/** 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;
@@ -128,7 +114,6 @@ export function createSweepSupervisor(options = {}) {
                 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;
             };
@@ -147,7 +132,6 @@ export function createSweepSupervisor(options = {}) {
                     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 });
@@ -199,7 +183,6 @@ export function createSweepSupervisor(options = {}) {
         },
     };
 }
-// 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);
@@ -210,7 +193,6 @@ export function storageSweepSupervisor(databaseFile) {
     }
     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)