toolroll 0.9.103 → 0.9.105

package/dist/worktree.js

@@ -1,27 +1,3 @@
-/**
- * The pool of working copies, and the leases over them.
- *
- * Semantics copied from treehouse rather than reinvented, including the two
- * rules that are easy to get wrong and expensive to get wrong quietly:
- *
- * **Untracked files count as dirty.** A repository whose `.gitignore` hides
- * build output is still a repository with somebody's work in it, and a pool
- * that recycles a directory because `git status` looked clean under the
- * operator's config will delete something they wanted. So the check is run
- * with ignored files excluded but untracked files included, which is the
- * conservative reading of "is anyone using this".
- *
- * **Reconstructed state is leased-until-verified.** A worktree found on disk
- * after a crash describes what a dead process was doing, not what is true now.
- * It comes back into the pool marked unverified, and something has to look at
- * it before it is handed to anybody.
- *
- * Where the pool lives is a decision, not a detail. Worktrees are created
- * outside the repository — never inside it, where they would appear as
- * untracked directories in the operator's own `git status`, and never inside a
- * synced folder like OneDrive or Dropbox, where a sync client racing an agent
- * over `.git` internals corrupts both.
- */
 import { INCIDENT_QUIET_MS, recentGitIncident } from "./git-incident.js";
 import { createHash, randomBytes } from "node:crypto";
 import { existsSync, lstatSync, readFileSync, writeFileSync, rmSync, realpathSync, mkdirSync, readdirSync, renameSync } from "node:fs";
@@ -36,24 +12,10 @@ import { diskBytes } from "./storage.js";
 import { markNeverIndex } from "./never-index.js";
 import { endedInterrupted } from "./run-ending.js";
 import { checkoutGit, gitIncidentRecord, teardownGit } from "./teardown-git.js";
-/**
- * The note a lease leaves in the checkout, naming the process holding it.
- *
- * Deliberately inside the worktree rather than beside it: it travels with the
- * directory, and `git status` will show it as untracked, which is honest —
- * something is in there.
- */
 export const MARKER = ".standing-orders-lease";
-/**
- * The reflog message of a branch Toolroll created, naming it: its creation entry is the proof, later, that the branch
- * is Toolroll's and how old it is. A branch copied or renamed from it names the old branch, so it proves nothing.
- */
 export const branchCreatedMessage = (branch) => `Toolroll created branch ${branch}`;
-/** Scouts' disposable branches: never landed work. */
 export const SCOUT_PREFIX = "toolroll-scout/";
-/** Checkouts this process is leasing or removing right now: a lease and storage retention never overlap on one. */
 const busy = new Map();
-// Outside the checkout so removal cannot erase the reservation before git and the row update finish.
 const reservationPath = (path) => `${path}.occupancy`;
 function reservation(path) {
     try {
@@ -66,7 +28,6 @@ function reservation(path) {
         if (error.code === "ENOENT")
             return null;
     }
-    // An unreadable reservation is occupied, never a reason to delete someone's checkout.
     return { pid: 0, host: "unknown", bootId: null, token: "unknown" };
 }
 function reservationAlive(note) {
@@ -82,8 +43,6 @@ function reservationAlive(note) {
         return error.code !== "ESRCH";
     }
 }
-/** A short store transaction arbitrates marker creation/recovery, never git, a scan or deletion.
- * Atomic rename publishes a complete owner; a crash cannot leave a half-written reservation. */
 function reserveCheckout(store, path) {
     const note = { pid: process.pid, host: hostname(), bootId: currentBootId(), token: randomBytes(12).toString("hex"), machineId: currentMachineId() };
     const file = reservationPath(path), temp = `${file}.${note.token}`;
@@ -109,37 +68,21 @@ function reserveCheckout(store, path) {
     return () => store.transact(() => { if (reservation(path)?.token === note.token)
         rmSync(file, { force: true }); });
 }
-/** What a kept checkout drops once its run ends (only where .gitignore hides it): dependencies and build output. */
 export const SLIM_NAMES = ["node_modules", "dist", "build", "out", ".next", ".nuxt", ".svelte-kit", ".turbo", ".parcel-cache", "coverage", "target"];
-/** Creating a worktree copies a tree; it is local work but not instant. */
 export const WORKTREE_TIMEOUT_MS = 60_000;
 const GIT = "git";
 const READ_ONLY = ["--no-optional-locks"];
-/**
- * A path for this repository and branch that is stable across runs.
- *
- * Stable so that a second attempt at the same task reuses the checkout it
- * already paid for, and flattened so a branch called `feat/a/b` cannot escape
- * the pool root through its own slashes.
- */
 export function worktreePath(root, repo, branch) {
-    // The readable part is for a person reading `ls`; the digest is what makes
-    // it correct. Flattening alone collides in two ways that both end with one
-    // task's work landing in another's checkout: `feat/a` and `feat-a` reduce to
-    // the same name, and `/x/api` and `/y/api` share a basename. The digest is
-    // taken over the full repository path and the exact branch, so neither can.
     const digest = createHash("sha256")
         .update(`${normalisePath(repo)}\u0000${branch}`, "utf8")
         .digest("hex")
         .slice(0, 8);
     return join(root, safeSegment(basenameOf(repo)), `${safeSegment(branch)}-${digest}`);
 }
-/** The pool root a checkout at `path` of `repo` was made under (worktreePath's layout), or null for one it didn't make. */
 export function poolRootOf(path, repo) {
     const project = dirname(path);
     return basename(project) === safeSegment(basenameOf(repo)) && /-[0-9a-f]{8}$/.test(basename(path)) ? dirname(project) : null;
 }
-/** Inspect names, not their destinations, before the plane writes into a pool. */
 function safePoolPath(root, target) {
     const base = resolve(root);
     const rel = relative(base, resolve(target));
@@ -159,7 +102,6 @@ function safePoolPath(root, target) {
     }
     return true;
 }
-/** The checkout itself, strictly inside the pool as real paths, reached by real folders only: never a link out of it. */
 function insidePool(root, path) {
     if (!safePoolPath(root, path))
         return false;
@@ -178,25 +120,19 @@ function basenameOf(repo) {
     const parts = repo.replace(/\\/g, "/").replace(/\/+$/, "").split("/");
     return parts[parts.length - 1] ?? "repo";
 }
-/** Anything that is not a plain name becomes one; no separators survive. */
 function safeSegment(text) {
     const cleaned = text.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^[.-]+/, "");
     return cleaned === "" ? "x" : cleaned;
 }
-/** Record a potentially writing subprocess against the original checkout lease. */
 export function recordWorktreeProcess(store, path, runner, pid, leaseEpoch) {
     const leased = store.getWorktree(path);
     if (!Number.isInteger(pid) || pid <= 0 || leased === null || leased.releasedAt !== null || leased.runner !== runner ||
         (leaseEpoch !== undefined && leased.leaseEpoch !== leaseEpoch)) {
         throw new Error(`${path}: subprocess custody no longer matches its worktree lease`);
     }
-    // The boot the holder was born under rides the note (v53): after a
-    // verified boot change nothing of it survives, and the checkout is free
-    // without a PID probe that a reused pid could answer wrongly.
     const bootId = currentBootId();
     writeFileSync(join(path, MARKER), `${pid} ${runner} group ${bootId ?? "unknown"} ${hostname()} ${currentMachineId() ?? "unknown"}\n`, "utf8");
 }
-/** Read-only occupancy witness shared with stop settlement. */
 export function worktreeProcessOccupancy(path) {
     const reserved = reservation(path);
     if (reserved !== null && (reserved.pid !== process.pid || !isThisMachine(reserved)) && reservationAlive(reserved))
@@ -209,20 +145,14 @@ export function worktreeProcessOccupancy(path) {
     if (!Number.isInteger(pid) || pid <= 0)
         return { held: false };
     const noteHost = parts[4];
-    // The sixth word (v150) is the writer's machine id; "unknown", or a note from before it, is matched by name.
     const noteMachine = parts[5] === undefined || parts[5] === "unknown" ? null : parts[5];
     if (noteHost !== undefined && !isThisMachine({ host: noteHost, machineId: noteMachine }))
         return { held: true, by: pid };
     if (pid === process.pid && parts[2] !== "group")
         return { held: false };
-    // A note from a previous, VERIFIED boot of this host names a process
-    // that cannot exist any more; a note without a boot id (legacy) or a
-    // boot this host cannot verify keeps the probe below.
     const noteBoot = parts[3];
     if (noteBoot !== undefined && noteHost !== undefined && provenDeadByBootChange({ host: noteHost, bootId: noteBoot }, { host: noteHost, bootId: currentBootId() }))
         return { held: false };
-    // A shell/provider can exit before its descendants. A recorded POSIX
-    // process group remains an owner until that whole group has gone.
     if (parts[2] === "group" && process.platform !== "win32") {
         try {
             process.kill(-pid, 0);
@@ -238,21 +168,10 @@ export function worktreeProcessOccupancy(path) {
         return { held: true, by: pid };
     }
     catch (error) {
-        // Two different answers hide behind one throw. ESRCH means the process
-        // is gone and the note is what it left behind. EPERM means it is very
-        // much alive and simply not ours to signal — running as another user, or
-        // elevated — and reading that as "gone" would hand somebody's live
-        // checkout to another runner. Only ESRCH frees it.
         const code = error.code;
         return code === "ESRCH" ? { held: false } : { held: true, by: pid };
     }
 }
-/**
- * A checkout's uncommitted work as one patch — tracked changes against HEAD,
- * then each untracked file against nothing (the lease note aside) — written
- * to `file`. Nothing in the checkout is touched. Every road that is about to
- * reset or clean a tree saves this first.
- */
 export async function saveWorkPatch(runner, path, file, header) {
     const git = teardownGit(runner);
     const status = await git(path, [...READ_ONLY, "status", "--porcelain", "--untracked-files=all", "--ignore-submodules=all"]);
@@ -267,7 +186,6 @@ export async function saveWorkPatch(runner, path, file, header) {
         return { ok: false, message: `${path}: git diff failed while saving its work (${firstLine(tracked.stderr)})` };
     const parts = [tracked.stdout];
     for (const one of untracked) {
-        // --no-index exits 1 when the sides differ; that is the expected answer.
         const diff = await git(path, [...READ_ONLY, "diff", "--binary", "--no-index", "--ignore-submodules=all", "--", "/dev/null", one]);
         if (diff.code > 1)
             return { ok: false, message: `${path}: ${one} could not be captured (${firstLine(diff.stderr)})` };
@@ -286,50 +204,17 @@ export class WorktreePool {
     store;
     options;
     runner;
-    /** The pool's own git in a project's repository and its checkouts (making, moving and reading them): hardened against
-     * a frozen view of the repository's config and info (teardown-git.ts checkoutGit), which agents can write. An injected
-     * runner (tests' stubbed git) is used as given. */
     hardened;
-    /** Carried to the independent storage sweep process. */
     get root() { return this.options.root; }
     constructor(store, options) {
         this.store = store;
         this.options = options;
         this.runner = options.runner ?? run;
-        // Bound to the project's repository from the pool's own request or record (teardown-git.ts GitBinding).
         this.hardened = repo => this.runner === run ? checkoutGit(run, "build", { repo }) : this.runner;
     }
-    /**
-     * Take a working copy for this branch.
-     *
-     * Refused when somebody else holds it — losing is ordinary, and a caller
-     * that is told who holds it can go and do something else rather than poll.
-     */
-    /**
-     * Whether a live process is working in there, independently of what the
-     * database believes.
-     *
-     * treehouse's rule, and it exists because the database is the thing most
-     * likely to be wrong: a row saying "released" written by a process that then
-     * kept running, or a stale row from a crash, are both cases where the
-     * checkout is genuinely occupied and only the machine can say so. So each
-     * lease drops a note naming the process holding it, and `process.kill(pid, 0)`
-     * — which signals nothing and only asks whether the pid exists — is what
-     * answers the question afterwards.
-     *
-     * A pid can be recycled by the operating system, so this can say "in use"
-     * about a stranger. That is the safe direction: refusing a checkout somebody
-     * may be in costs a retry, and taking one they are in costs their work.
-     */
     inUse(path) {
         return worktreeProcessOccupancy(path);
     }
-    /**
-     * Once a provider exists it, not the supervising console, is the process
-     * whose liveness protects this checkout. Rewriting the occupancy marker at
-     * spawn means a replacement control plane waits for an orphaned provider
-     * to finish instead of starting a second writer in the same worktree.
-     */
     markProviderOccupancy(path, runner, providerPid, leaseEpoch) {
         if (!Number.isInteger(providerPid) || providerPid <= 0)
             return false;
@@ -346,8 +231,6 @@ export class WorktreePool {
             return false;
         }
     }
-    /** Spawn callbacks must fail if custody cannot be recorded. The transport
-     * kills and reaps its child before returning that callback failure. */
     recordProviderOccupancy(path, runner, providerPid, leaseEpoch) {
         if (!this.markProviderOccupancy(path, runner, providerPid, leaseEpoch)) {
             throw new Error(`${path}: the provider's worktree custody could not be recorded`);
@@ -372,10 +255,6 @@ export class WorktreePool {
         }
     }
     async leaseNow(request) {
-        // A worktree leased to a runner nobody registered cannot be heartbeated
-        // and cannot be recovered — it would be a checkout that never comes back.
-        // The database enforces this too; catching it here is what turns a foreign
-        // key error into a sentence somebody can act on.
         if (this.store.getRunner(request.runner) === null) {
             return {
                 ok: false,
@@ -388,10 +267,6 @@ export class WorktreePool {
         if (!safePoolPath(this.options.root, path))
             return unsafe();
         const existing = this.store.getWorktree(path);
-        // The machine outranks the database here. A row can say "released" while a
-        // process that never got to write its own ending is still working in the
-        // directory, and that is exactly when taking it away costs somebody a
-        // night's work.
         const occupied = this.inUse(path);
         if (occupied.held) {
             return {
@@ -407,10 +282,6 @@ export class WorktreePool {
                 message: `${path} is leased to ${existing.runner ?? "someone"}`,
             };
         }
-        // Re-inspect every released checkout at the lease boundary. `verified`
-        // says it was clean when released, not that no orphan/provider/person
-        // wrote to it afterwards; trusting that old bit is how a restored safety
-        // patch can be handed out without recovery lineage or silently reset.
         let reclaimed;
         let resumedFromRun;
         let recoveryKind;
@@ -420,9 +291,6 @@ export class WorktreePool {
                 return { ok: false, reason: "git", message: `${path} could not be inspected` };
             }
             if (dirty) {
-                // The task's own leftover, from an attempt that finished and said
-                // so: kept as evidence, then cleared, so the retry starts from the
-                // branch and not from a half-edit. Anything else stays for a person.
                 const own = request.reclaim !== undefined && request.taskRef !== undefined && existing.taskRef === request.taskRef;
                 if (!own) {
                     return {
@@ -439,12 +307,6 @@ export class WorktreePool {
                     return { ok: false, reason: "git", message: kept.message };
                 reclaimed = kept.file;
                 if (recovery !== null) {
-                    // The predecessor reached a structurally valid completed handoff
-                    // before its runner disappeared. Keep its draft in place under the
-                    // fresh lease so the successor reviews and verifies it. build()
-                    // quarantines the old nonce-bound handoff before the new provider
-                    // starts, so only the source draft crosses attempts — never the old
-                    // attempt's authority.
                     resumedFromRun = recovery.runId;
                     recoveryKind = recovery.kind;
                 }
@@ -457,13 +319,9 @@ export class WorktreePool {
         }
         const created = existing === null;
         if (created) {
-            // A branch that already exists (its checkout removed by storage retention) is checked out as it stands, just
-            // as its kept checkout would have been reused; `base` only starts a branch that doesn't exist yet.
             const branchExists = request.base !== undefined && request.reuseBranch === true &&
                 (await this.git(request.repo, ["rev-parse", "--verify", "--quiet", `refs/heads/${request.branch}`], READ_ONLY)).code === 0;
             const fromBase = request.base !== undefined && !branchExists;
-            // Spotlight leaves the checkouts alone: the marker sits in the pool and the project's folder, never inside a
-            // checkout, where a build's `git add -A` would commit it (never-index.ts).
             if (!safePoolPath(this.options.root, path))
                 return unsafe();
             try {
@@ -474,7 +332,6 @@ export class WorktreePool {
             }
             markNeverIndex(this.options.root);
             markNeverIndex(dirname(path));
-            // A new branch is created first, on its own, so its reflog's first entry says Toolroll made it and when.
             let made = null;
             if (fromBase) {
                 const base = await this.git(request.repo, ["rev-parse", "--verify", "--quiet", `${request.base}^{commit}`], READ_ONLY);
@@ -495,8 +352,6 @@ export class WorktreePool {
                 return { ok: false, reason: "git", message: firstLine(add.stderr) };
             }
         }
-        // Fresh base, inside the same reservation as everything above: nothing else leases, prunes or slims this
-        // checkout between the inspection and the move.
         let base;
         if (request.freshBase !== undefined && request.taskRef !== undefined) {
             const fresh = await this.freshen(request.repo, path, request.branch, request.taskRef, request.freshBase, request.now);
@@ -513,17 +368,9 @@ export class WorktreePool {
             createdAt: existing?.createdAt ?? request.now.toISOString(),
             leasedAt: request.now.toISOString(),
             releasedAt: null,
-            // Freshly created, or inspected just above — either way, checked.
             verified: true,
-            // The occupancy epoch (live-peek findings 16/28): fresh randomness,
-            // written by the SAME row write that grants the lease — it can never
-            // repeat and never lag the occupancy it names.
             leaseEpoch: randomBytes(12).toString("hex"),
         };
-        // The note goes down before the lease is granted. A checkout we cannot
-        // mark is one whose next holder cannot tell it is occupied — the in-use
-        // check would report it free while a process worked in it — so failing to
-        // write the note fails the lease rather than quietly leaving the gap.
         if (!this.mark(path, request.runner)) {
             return {
                 ok: false,
@@ -542,12 +389,6 @@ export class WorktreePool {
             ...(base === undefined ? {} : { base }),
         };
     }
-    /**
-     * Move an untouched checkout to current main, or say how far behind it is. Untouched means all three: on its own
-     * branch, HEAD still the recorded base (or, with none recorded, a commit main already has), and nothing changed or
-     * untracked. The move is `git reset --keep`, which refuses rather than overwrite anything; HEAD and the tree are read
-     * again right before and after it, and any surprise fails the lease with the checkout left for a person.
-     */
     async freshen(repo, path, branch, taskRef, fresh, now) {
         const read = async (args) => {
             const out = await this.hardened(repo)(GIT, [...READ_ONLY, ...args], { cwd: path, timeoutMs: WORKTREE_TIMEOUT_MS });
@@ -573,7 +414,6 @@ export class WorktreePool {
             return stay("has commits");
         if (await this.isDirty(path) !== false)
             return stay("has changes");
-        // Recorded before git moves it: a move that then fails leaves the next attempt's own base as the branch's origin.
         this.store.recordBranchBaseMove(taskRef, branch, head, main, now);
         const moved = await this.hardened(repo)(GIT, ["reset", "--keep", main], { cwd: path, timeoutMs: WORKTREE_TIMEOUT_MS });
         const after = await read(["rev-parse", "--verify", "--quiet", "HEAD^{commit}"]);
@@ -583,33 +423,16 @@ export class WorktreePool {
         }
         return { ok: true, standing: { head: main, main, behind: 0, moved: { from: head, behind }, kept: null } };
     }
-    /**
-     * A crash can strand either a finished handoff or a partial source draft.
-     * The expired lease can no longer authorize a commit, so this never ingests
-     * the old result. It classifies the recovery context for the next freshly
-     * fenced attempt, which must review and prove the inherited work itself.
-     */
     recoverableDraft(path, runId, latestRun) {
         const prior = this.store.getRun(runId);
         if (prior === null)
             return null;
-        // Once a fresh attempt has explicitly inherited a validated draft, keep
-        // that lineage through an infrastructure/provider failure too. A warm
-        // park resume also uses parentRun, but its parent is `parked`, never the
-        // failed/interrupted source required here.
         if (prior.parentRun !== null) {
             const source = this.store.getRun(prior.parentRun);
             if (source !== null && endedInterrupted(source)) {
                 return { runId: source.id, kind: "partial" };
             }
         }
-        // An attempt that stopped before its handoff (run 2085) left work it
-        // never got to hand off: kept in place for the next attempt, never reset
-        // — until a later attempt fails some other way. That failure may have
-        // broken the tree, and the work is already saved (its own patch, and the
-        // leftover patch the caller writes first), so the tree can be reset. A
-        // crash or a sign-in that stopped working says nothing about the tree.
-        // A resumed or repair turn is judged as part of the attempt it belongs to.
         const attemptOf = (one) => one !== null && one.role === "repair" && one.parentRun !== null ? this.store.getRun(one.parentRun) ?? one : one;
         const brokeTree = (one) => one !== null && one.outcome === "failed" && one.reason !== "no-handoff" && one.reason !== "interrupted" && one.reason !== "auth-expired";
         const attempt = attemptOf(prior);
@@ -640,19 +463,12 @@ export class WorktreePool {
             kind: parsed.ok && parsed.handoff.status === "completed" ? "completed" : "partial",
         };
     }
-    /**
-     * Preserve a dirty tree's work as one patch — tracked changes against
-     * HEAD, then each untracked file against nothing — under the evidence of
-     * the last run that lived in this checkout (or a leftover folder when no
-     * run is on record). Nothing is deleted here.
-     */
     async keepLeftover(path, evidenceRoot, now) {
         const lastRun = this.store.latestRunInWorktree(path);
         const dir = lastRun === null ? join(evidenceRoot, "leftover") : join(evidenceRoot, String(lastRun));
         const file = join(dir, lastRun === null ? `${now.toISOString().replace(/[:.]/g, "-")}.patch` : "leftover.patch");
         return saveWorkPatch(this.runner, path, file, `# leftover from ${path}\n# kept ${now.toISOString()} before the tree was reset for the next attempt\n`);
     }
-    /** Back to HEAD, untracked gone, our lease note kept; proven clean after. */
     async resetTree(path) {
         const checkout = await this.teardown(path, ["checkout", "--", "."]);
         if (checkout.code !== 0)
@@ -665,7 +481,6 @@ export class WorktreePool {
             return { ok: false, message: `${path} is still not clean after the reset — leaving it for a person` };
         return { ok: true };
     }
-    /** Leave a note naming the process holding this checkout. */
     mark(path, runner, pid = process.pid) {
         try {
             writeFileSync(join(path, MARKER), `${pid} ${runner} process ${currentBootId() ?? "unknown"} ${hostname()} ${currentMachineId() ?? "unknown"}\n`, "utf8");
@@ -675,38 +490,22 @@ export class WorktreePool {
             return false;
         }
     }
-    /**
-     * Hand a working copy back.
-     *
-     * The tree is inspected first, and dirt is reported rather than cleaned.
-     * `git reset --hard` leaves untracked files behind and destroys work that
-     * might have been repairable, which is why the failure taxonomy this project
-     * borrows says to preserve a failed commit rather than blanket-reset.
-     */
     async release(path, now) {
         const existing = this.store.getWorktree(path);
         if (existing === null) {
             return { ok: false, reason: "git", message: `${path} is not a worktree we made` };
         }
         const dirty = await this.isDirty(path);
-        // The note goes before the row is written: a crash between the two should
-        // leave a checkout that looks free rather than one held by a pid that has
-        // gone, which is the direction that needs no human to unstick it.
         try {
             rmSync(join(path, MARKER), { force: true });
         }
         catch {
-            // Nothing to do about it, and the pid check handles a note left behind.
         }
         const row = {
             ...existing,
             runner: null,
             releasedAt: now.toISOString(),
-            // Unknown counts as unverified. Saying "clean" about a tree we could not
-            // read would hand the next runner a surprise.
             verified: dirty === false,
-            // Occupancy ended: the epoch rotates HERE too, so a peek proved
-            // against the tenancy that just ended can only discard (finding 28).
             leaseEpoch: randomBytes(12).toString("hex"),
         };
         this.store.saveWorktree(row);
@@ -722,20 +521,6 @@ export class WorktreePool {
         }
         return { ok: true, worktree: row, created: false };
     }
-    /**
-     * Worktrees git knows about that this pool does not, and the reverse.
-     *
-     * The first is somebody else's business and is left alone. The second is
-     * ours: a row for a directory that is no longer there, which happens when a
-     * machine is reimaged or a pool root is deleted between runs.
-     */
-    /**
-     * Remove a released checkout and its branch (v4 review, finding 3): the
-     * read-only roles' workspaces are disposable, so the next attempt starts
-     * from the requested base instead of whatever the last one saw. Refused
-     * while a process holds the directory; a failure leaves the checkout
-     * where `worktrees` can see it rather than pretending it is gone.
-     */
     async discard(path, now) {
         const existing = this.store.getWorktree(path);
         if (existing === null)
@@ -748,7 +533,6 @@ export class WorktreePool {
         const removed = await this.teardown(existing.repo, ["worktree", "remove", "--force", path]);
         if (removed.code !== 0)
             return { ok: false, message: `git worktree remove: ${removed.stderr.trim() || `exit ${removed.code}`}` };
-        // The branch is disposable too; a failure here is bookkeeping, not custody.
         await this.teardown(existing.repo, ["branch", "-D", existing.branch]);
         this.store.forgetWorktree(path);
         void now;
@@ -756,9 +540,6 @@ export class WorktreePool {
     }
     async orphans(repo) {
         const listed = await this.teardown(repo, ["worktree", "list", "--porcelain"]);
-        // A listing that failed is not a listing that came back empty. Treating
-        // it as empty would report every stored row as missing — and anything
-        // acting on that answer would erase real bookkeeping over a git hiccup.
         if (listed.code !== 0) {
             return {
                 ok: false,
@@ -777,33 +558,10 @@ export class WorktreePool {
             missing: ours.filter(row => !onDisk.has(row.path)).map(row => row.path),
         };
     }
-    /**
-     * Take responsibility for worktrees that exist but nothing recorded.
-     *
-     * These turn up after a crash between `git worktree add` and the row that
-     * should have followed it, or when a database is replaced while checkouts
-     * survive on disk. Left alone they are invisible: git knows about them,
-     * every pool query does not, and the same branch gets checked out again
-     * beside them.
-     *
-     * Adopted **released and unverified**, never leased. Nobody watched them
-     * being made, so they are a claim about the past — the same rule that
-     * governs a dead runner's worktrees, for the same reason.
-     *
-     * Rows whose directory is gone are dropped: a lease over a path that does
-     * not exist can only refuse work that could otherwise have run.
-     */
     async adopt(repo, now) {
         const found = await this.orphans(repo);
-        // Fail closed, before anything is written or forgotten: an answer built
-        // on a failed listing would adopt nothing and erase everything.
         if (!found.ok)
             return found;
-        // Only what lives under this pool's root is ours to adopt. A worktree the
-        // operator made by hand, wherever they made it, is somebody's business —
-        // it is named by `orphans()` and left exactly where it is. Compared as
-        // real paths, because git reports where a directory actually is while the
-        // configured root may reach it through a symlink (macOS's /var, for one).
         const real = (path) => {
             try {
                 return realpathSync(path);
@@ -814,10 +572,6 @@ export class WorktreePool {
         };
         const root = normalisePath(real(this.options.root)) + "/";
         const adoptable = found.untracked.filter(path => normalisePath(real(path)).startsWith(root));
-        // Git's listing is a survey, not permission to overwrite custody. A
-        // builder may create and record a worktree while the listing is in
-        // flight. Recheck under the writer transaction, and never forget an
-        // owned checkout or a directory that appeared after the listing.
         return this.store.transact(() => {
             const adopted = [];
             const forgotten = [];
@@ -827,8 +581,6 @@ export class WorktreePool {
                 this.store.saveWorktree({
                     path,
                     repo,
-                    // The branch is not knowable from the listing alone, and inventing one
-                    // would be worse than admitting it: whoever verifies this will look.
                     branch: "unknown",
                     runner: null,
                     taskRef: null,
@@ -849,31 +601,17 @@ export class WorktreePool {
             return { ok: true, adopted, forgotten };
         });
     }
-    /**
-     * Whether a let-go checkout could go without losing anything: clean (build output that .gitignore hides is not
-     * work, and neither are the files Toolroll itself wrote in there), and everything its HEAD reaches on a branch, tag
-     * or remote. Reads only, through `git` when given (teardown's hardened git).
-     */
     async inspect(path, git = this.teardown) {
-        // A checkout that had a git incident lately is left alone (git-incident.ts): nothing re-runs git there each pass.
         if (quietAfterIncident(path))
             return "unreadable";
         const dirty = await this.isDirty(path, true, git);
         if (dirty !== false)
             return dirty === null ? "unreadable" : "has changes";
-        // Commits only this checkout's HEAD reaches (a detached HEAD moved on) exist nowhere else.
         const own = await git(path, [...READ_ONLY, "rev-list", "-1", "HEAD", "--not", "--branches", "--tags", "--remotes"]);
         if (own.code !== 0)
             return "unreadable";
         return own.stdout.trim() === "" ? "clean" : "has commits";
     }
-    /**
-     * Whether a checkout a task may still come back to can go, beyond `inspect`: a later lease of its branch must make the
-     * same checkout, and every commit its task recorded must outlive it (git's garbage collection counts a worktree's HEAD
-     * and reflog; once they go only a branch holds a commit). So: the folder is the pool's own, the checkout belongs to its
-     * project by the plane's record (`boundDirs`, not its `.git` file), its HEAD is its recorded branch, every recorded
-     * `heads` commit is on a branch, and no ref lives only in this worktree. Reads only; anything unreadable keeps it.
-     */
     async proveRecreatable(row, heads) {
         if (quietAfterIncident(row.path))
             return "unreadable";
@@ -902,15 +640,6 @@ export class WorktreePool {
             return "unreadable";
         return own.stdout.trim() === "" ? "clean" : "has commits";
     }
-    /**
-     * Keep storage in check: remove the working copies nobody needs any more. Of `rows`, a checkout goes when it is
-     * let go, nothing holds it, `wanted` says it may go (asked again right before it goes, so a task coming back or a
-     * lease since keeps it) and `inspect` finds it clean, then clean still right before it goes (git refuses an edit
-     * made after that). Only the working copy goes: its branch, and so every commit,
-     * stays, and a later lease of the same branch makes a new one. At most `max` go per pass. Every git command goes
-     * through `git` when given: landed cleanup passes its hardened teardown git (teardown-git.ts). `proof` is asked last,
-     * inside the reservation, for what `inspect` doesn't cover (idle cleanup: `proveRecreatable`).
-     */
     async prune(rows, wanted, max = Infinity, git = this.teardown, proof) {
         const removed = [];
         const kept = [];
@@ -937,11 +666,9 @@ export class WorktreePool {
                 continue;
             busy.set(row.path, "removing");
             try {
-                // A lease, or a task coming back, since the listing wins: look again right before removing.
                 const now = this.store.getWorktree(row.path);
                 if (!idle(now, row.releasedAt))
                     continue;
-                // Landed cleanup rechecks Git here; existing synchronous guards keep their synchronous path.
                 const allowed = wanted(now, true);
                 if (!(typeof allowed === "boolean" ? allowed : await allowed))
                     continue;
@@ -964,12 +691,6 @@ export class WorktreePool {
         }
         return { removed, kept };
     }
-    /**
-     * Drop a let-go, idle checkout's dependencies and build output: the folders .gitignore hides that are named like
-     * them (SLIM_NAMES). Its work, tracked or untracked, is untouched. The setup stamp goes first, so the next lease
-     * runs the project's setup again and restores them. `wanted` is asked again right before anything goes; `deps`
-     * false keeps node_modules (no setup would restore it).
-     */
     async slim(row, wanted, deps = true) {
         const idle = (now) => now !== null && now.runner === null && now.releasedAt !== null && now.releasedAt === row.releasedAt && !this.inUse(row.path).held;
         if (busy.has(row.path) || !existsSync(row.path) || !idle(this.store.getWorktree(row.path)))
@@ -991,7 +712,6 @@ export class WorktreePool {
             const now = this.store.getWorktree(row.path);
             if (!idle(now) || !wanted(now))
                 return { ok: false, message: `${row.path} is in use` };
-            // Held while it slims: another process's lease sees this process in it.
             try {
                 writeFileSync(note, `${process.pid} storage-retention slimming ${currentBootId() ?? "unknown"} ${hostname()} ${currentMachineId() ?? "unknown"}\n`, "utf8");
                 held = true;
@@ -1012,10 +732,6 @@ export class WorktreePool {
             busy.delete(row.path);
         }
     }
-    /**
-     * Throw away a let-go checkout kept for its changes, on purpose: the working copy and what is uncommitted in it
-     * go; its branch, and every commit on it, stays. Refused while anything holds it.
-     */
     async discardChanges(path) {
         const row = this.store.getWorktree(path);
         if (row === null)
@@ -1045,10 +761,7 @@ export class WorktreePool {
             busy.delete(path);
         }
     }
-    /** Throw away one idle checkout's working copy, changes and all (the caller holds it in `busy`), and forget its row.
-     * Only `discardChanges`, where losing them is what a person asked for. */
     async removeWorkingCopy(row) {
-        // Held while it goes: another process's lease sees this process in it (the busy map is this process's only).
         const note = join(row.path, MARKER);
         try {
             writeFileSync(note, `${process.pid} storage-retention removing ${currentBootId() ?? "unknown"} ${hostname()} ${currentMachineId() ?? "unknown"}\n`, "utf8");
@@ -1064,12 +777,6 @@ export class WorktreePool {
         this.forgetRemoved(row);
         return true;
     }
-    /**
-     * Remove one idle checkout's working copy only while it is still clean (the caller holds it in `busy`, and its
-     * reservation outside the checkout holds it for other processes): inspected once more right before it goes, then
-     * removed without --force, so git itself refuses an edit made since. Only Toolroll's own files go first, because
-     * git's check would count them.
-     */
     async removeCleanCopy(row, git) {
         const found = await this.inspect(row.path, git);
         if (found !== "clean")
@@ -1095,29 +802,15 @@ export class WorktreePool {
                 this.store.forgetWorktree(row.path);
         });
     }
-    /**
-     * Whether anybody's work is in there. null means we could not tell, which is
-     * neither clean nor dirty and must not be rounded to either.
-     *
-     * `--untracked-files=all` and no `--ignored`: build output that .gitignore
-     * hides is not work, but a file somebody dropped in and never staged is.
-     */
     async isDirty(path, ignoreOwnFiles = false, git = this.teardown) {
         const status = await git(path, [...READ_ONLY, "status", "--porcelain", "--untracked-files=all", "--ignore-submodules=all"]);
         if (status.code !== 0)
             return null;
-        // Our own lease note is not the operator's work. Without this the marker
-        // makes every checkout permanently dirty, which would jam the pool shut on
-        // the first lease — untracked files counting as dirty is the right rule,
-        // and this is the one file it must not apply to.
-        // Deciding whether a checkout can go, the files Toolroll wrote at its top (a progress note, a handoff, a
-        // proof list) are not a person's work either; any other untracked or changed file still is.
         return status.stdout
             .split("\n")
             .filter(line => line.trim() !== "")
             .some(line => !line.trimEnd().endsWith(MARKER) && !(ignoreOwnFiles && line.startsWith("?? ") && looksLikeProtocolFile(line.slice(3).trim())));
     }
-    /** All disposal and inspection paths share the hardened teardown boundary. */
     teardown = (cwd, args) => teardownGit(this.runner)(cwd, args);
     git(cwd, args, prefix = []) {
         return this.hardened(cwd)(GIT, [...prefix, ...args], { cwd, timeoutMs: WORKTREE_TIMEOUT_MS });
@@ -1127,7 +820,6 @@ function firstLine(text) {
     const [line = ""] = text.trim().split("\n");
     return line;
 }
-/** Whether a checkout had a git incident within INCIDENT_QUIET_MS (by its real path, as incidents record it). */
 function quietAfterIncident(path) {
     let real;
     try {