@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/pool.js

@@ -0,0 +1,988 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { join, resolve } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { metaPath, readTaskMeta } from "./task.js";
+import { classifyPathEntry, readRegularPathIfPresent } from "./fleet.js";
+import { pathsNameSameObject } from "./path-identity.js";
+/**
+ * Worktree pool over a project clone (kernel plan v1, M1-P3 step 3).
+ * BUILD from the contract (plan decision D-1, FM-026): a clean disposable
+ * worktree per task at <fleet>/worktrees/<task-id>, parallel-safe through
+ * unique paths, O_EXCL record creation, and git worktree add's own
+ * locking. That safety is claimed only at the width M1 actually uses:
+ * criterion 15's two concurrent creates, which are witnessed. This
+ * phase's own verification measured failures above roughly six-way
+ * concurrency on both the fetch and the worktree add, and hardening
+ * for that width is deferred to M5 (see the deferral list in
+ * delivery/work-history/m1-p3.md). Do not read this as a guarantee at
+ * arbitrary concurrency. Substrate-neutral: pure filesystem and git
+ * (DR-0007).
+ *
+ * Base resolution is the five binding steps of EXT-F-03: resolve the
+ * project's configured remote and its default branch, fetch that branch,
+ * record the fetched base SHA in the pool record (and the CLI emits it on
+ * stdout; M1-P4 spawn copies it into tasks/<id>/meta.json as baseSha),
+ * create the task branch and worktree directly from that exact SHA, and
+ * on fetch failure fail rather than silently use a stale local branch,
+ * unless --offline was explicitly passed, in which case the last fetched
+ * remote-tracking SHA is used and offline: true is recorded. The clone's
+ * local branches are never consulted: a stale local branch is never the
+ * base, whether behind or ahead of the remote.
+ *
+ * The pool record lives BESIDE the worktree (worktrees/<task-id>.pool.json,
+ * plain JSON per D-3), never inside it, so the record can never dirty the
+ * destroy-time cleanliness check (FM-059: no exemption list, ever).
+ *
+ * Destroy refuses a dirty worktree (uncommitted changes or untracked
+ * files) unless --discard, which is reserved for the teardown scout path
+ * (PR-010). A transient git index.lock during destroy is retried; the
+ * lock file is removed only under a fail-safe staleness proof (provably
+ * no holder via lsof plus mtime age beyond a threshold; any uncertainty
+ * means leave it and fail loudly), per FM-036 and FM-051.
+ */
+/** Task branch created by the pool at the fetched base SHA. */
+export function taskBranchName(taskId) {
+    return `task/${taskId}`;
+}
+/** Task ids are single safe path segments. */
+export const TASK_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * THE BOUND ON A NETWORK-REACHING GIT SUBPROCESS (M4-P19 fix round).
+ *
+ * `spawnSync` with no `timeout` waits for the child forever. For a local
+ * git command that is harmless: it either answers or fails. For one that
+ * opens a socket it is not, and the failure mode is not a slow command,
+ * it is a command that NEVER RETURNS. Measured by the clean-room
+ * reviewer against head abde402: a remote pointed at a TCP listener that
+ * accepts and never speaks made `tiphys pool list` and `tiphys doctor`
+ * run until killed (exit 124 under `timeout 25`), where the same fixture
+ * on the phase base exited 0 in about a second.
+ *
+ * This bound is applied to `ls-remote --symref <remote> HEAD` only, and
+ * the reason it is safe THERE and not elsewhere is a property of the
+ * command rather than a judgement about it: that invocation transfers a
+ * ref advertisement and nothing else, so a legitimate one is bounded by
+ * round-trip latency. `git fetch` (src/pool.ts, src/teardown.ts) and
+ * `git push` (src/teardown.ts) transfer objects, so their legitimate
+ * duration IS unbounded and a wall-clock cap on them would abort real
+ * work. They are left unbounded deliberately, and they are reached only
+ * from a command the operator invoked to do that work, never from a
+ * reporting path; keeping reporting paths off the network entirely is
+ * the other half of this fix (see `reconstructPoolRecord`).
+ *
+ * TIPHYS_GIT_NETWORK_TIMEOUT_MS is a TEST SEAM in the style of
+ * TIPHYS_WATCH_TEST_HOLD (src/watcher.ts) and TIPHYS_LOCK_TEST_HOLD
+ * (src/commands/lock.ts): a test cannot afford to wait out the shipped
+ * bound, and a shipped bound short enough for a test would abort a
+ * legitimate ls-remote over a slow link. A value that is not a positive
+ * integer is IGNORED rather than honoured, so a malformed environment
+ * cannot silently remove the bound.
+ */
+export const NETWORK_TIMEOUT_MS = 20_000;
+/**
+ * Exported as a PURE function so the validation has a witness that does
+ * not have to wait out a twenty-second bound to observe it. The
+ * end-to-end bound is witnessed separately, against a real remote that
+ * never answers; this is the arm that says a malformed environment
+ * cannot silently switch the bound off.
+ *
+ * `Number("")` is 0 and `Number("0x10")` is 16, so neither a blank value
+ * nor a hexadecimal one is passed through: the accepted set is exactly
+ * the positive integers, and everything else falls back.
+ */
+export function resolveNetworkTimeoutMs(raw) {
+    if (raw === undefined) {
+        return NETWORK_TIMEOUT_MS;
+    }
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        return NETWORK_TIMEOUT_MS;
+    }
+    return parsed;
+}
+function networkTimeoutMs() {
+    return resolveNetworkTimeoutMs(process.env["TIPHYS_GIT_NETWORK_TIMEOUT_MS"]);
+}
+function runGit(cwd, args, timeoutMs) {
+    const result = spawnSync("git", ["-C", cwd, ...args], {
+        encoding: "utf8",
+        // The transient-contention classification below reads git's English
+        // message text, so the locale is pinned rather than inherited
+        // (U-8). Without this a translated git silently stops retrying.
+        env: { ...process.env, LC_ALL: "C", LANG: "C" },
+        ...(timeoutMs === undefined ? {} : { timeout: timeoutMs }),
+    });
+    if (result.error !== undefined) {
+        // A killed-on-timeout child arrives here with an ETIMEDOUT error. It
+        // is named in terms rather than passed through as
+        // "Error: spawnSync git ETIMEDOUT", because the operator's remedy
+        // (an unreachable remote) is not readable from that string.
+        const timedOut = timeoutMs !== undefined &&
+            result.error.code === "ETIMEDOUT";
+        return {
+            status: null,
+            stdout: "",
+            stderr: timedOut
+                ? `git ${args.join(" ")} did not answer within ${String(timeoutMs)}ms and was killed`
+                : String(result.error),
+        };
+    }
+    return {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    };
+}
+/**
+ * The ONE signature of transient git contention, derived from real
+ * captured stderr rather than from a general rule about git. Every
+ * alternative below was observed in a real race on git 2.43 and proved
+ * transient by an immediate retry succeeding:
+ *
+ * 1. A held lock file, which names the lock path: "Unable to create
+ *    '<path>.lock': File exists." (index locks and ref locks alike).
+ * 2. A refused ref transaction under concurrent update, which names NO
+ *    lock file: "cannot lock ref '<ref>': is at <sha> but expected
+ *    <sha>". This is the dominant transient of concurrent fetches of
+ *    the same tracking ref.
+ * 3. Two concurrent worktree operations colliding on a half-written
+ *    admin file: "bad object worktrees/<id>/HEAD" on a fetch, and
+ *    "failed to read .git/worktrees/<id>/commondir: Success" on an add.
+ *
+ * One signature is used at every call site. An earlier revision split
+ * these by call site, reasoning about which path was allowed to retry
+ * which shape; that distinction existed only to protect a rollback that
+ * no longer exists, and the splitting itself produced defects. If the
+ * add's retry finds the branch already there, create refuses with its
+ * existing clear message, which is the correct outcome.
+ *
+ * The bare phrases "File exists" and "cannot lock ref" must NOT be used
+ * on their own: permanent failures emit them too. A directory/file ref
+ * conflict reports "cannot lock ref 'refs/x': 'refs/x/y' exists; cannot
+ * create 'refs/x'", which is permanent, and retrying it only wastes
+ * about a second before the same error surfaces.
+ *
+ * Known trade, stated rather than hidden (U-11): the worktrees admin
+ * shapes also match a permanent condition (an admin HEAD holding a
+ * nonexistent object), indistinguishable by message, so that
+ * out-of-contract case burns all attempts and fails in about 1.25s
+ * instead of about 0.29s.
+ *
+ * Maintenance rule, learned the hard way: this classification is
+ * message-text-only. Do not re-derive it from a plausible general
+ * property of git; a previous revision assumed "a genuine transient
+ * always names a lock file", which is false, and parallel pool create
+ * began failing hard. Capture real stderr from a real race first.
+ */
+const GIT_CONTENTION = /index\.lock|Unable to create '[^']*\.lock'|cannot lock ref '[^']*': (is at [0-9a-f]+ but expected|reference already exists|reference is missing but expected)|bad object worktrees\/|failed to read .*worktrees\/[^/]*\/commondir/;
+/** Exported for the contention-classification test. */
+export function isTransientGitLockError(stderr) {
+    return GIT_CONTENTION.test(stderr);
+}
+async function runGitRetrying(cwd, args, attempts = 5) {
+    let result = runGit(cwd, args);
+    for (let attempt = 1; attempt < attempts; attempt += 1) {
+        if (result.status === 0 || !GIT_CONTENTION.test(result.stderr)) {
+            return result;
+        }
+        await sleep(100 * attempt);
+        result = runGit(cwd, args);
+    }
+    return result;
+}
+export function recordPath(fleet, taskId) {
+    return join(fleet.worktreesDir, `${taskId}.pool.json`);
+}
+export function worktreePath(fleet, taskId) {
+    return join(fleet.worktreesDir, taskId);
+}
+/**
+ * THE RECORD'S ENTRY TYPE IS ESTABLISHED BEFORE IT IS OPENED. A bare read
+ * here hung `tiphys pool destroy` forever with zero output against a named
+ * pipe at `worktrees/<id>.pool.json`; measured before the fix, `pool list`
+ * (which reads only the NAME) returned in the same second while
+ * `pool destroy --task t-0001` was killed at ten seconds. The two commands
+ * differ by whether this function runs, which is what makes the mechanism
+ * the open and not the command.
+ *
+ * A non-regular record is a REFUSAL rather than `undefined`: `undefined`
+ * already means "there is no record", and a caller that cannot tell that
+ * apart from "the record could not be opened" would rebuild a worktree over
+ * a record it never read.
+ */
+export function readPoolRecord(fleet, taskId) {
+    const read = readRegularPathIfPresent(recordPath(fleet, taskId));
+    if (read.kind === "absent") {
+        return undefined;
+    }
+    if (read.kind === "refused") {
+        throw new Error(read.reason);
+    }
+    try {
+        return JSON.parse(read.body);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * EXT-F-03 step 1: resolve the project's configured remote. origin when
+ * present; otherwise the single configured remote; otherwise fail.
+ */
+function resolveRemote(project) {
+    const result = runGit(project, ["remote"]);
+    if (result.status !== 0) {
+        return { ok: false, reason: `${project} is not a git repository (git remote failed: ${result.stderr.trim()})` };
+    }
+    const remotes = result.stdout.split("\n").filter((line) => line !== "");
+    if (remotes.includes("origin")) {
+        return { ok: true, value: "origin" };
+    }
+    if (remotes.length === 1) {
+        return { ok: true, value: remotes[0] };
+    }
+    if (remotes.length === 0) {
+        return { ok: false, reason: `${project} has no configured remote` };
+    }
+    return {
+        ok: false,
+        reason: `${project} has ${String(remotes.length)} remotes and none is origin; cannot pick one`,
+    };
+}
+/**
+ * EXT-F-03 step 1: resolve the remote's default branch. origin/HEAD when
+ * set locally (no network); otherwise the remote's advertised default
+ * via ls-remote --symref. The clone's own HEAD is never consulted, so a
+ * detached HEAD in the clone is irrelevant.
+ *
+ * `network` IS A REQUIRED PARAMETER AND HAS NO DEFAULT (M4-P19 fix
+ * round). Every caller must state whether it is allowed to open a
+ * socket, because the two callers that exist have opposite answers and a
+ * default would hand the wrong one to whichever caller is added next
+ * without anybody having to decide. `false` stops at the local
+ * `origin/HEAD` lookup and refuses, naming the fact that the network was
+ * not consulted, so a caller reading the refusal can tell "this remote
+ * has no default branch" from "I was not permitted to ask".
+ */
+function resolveDefaultBranch(project, remote, network) {
+    const local = runGit(project, [
+        "symbolic-ref",
+        "--quiet",
+        `refs/remotes/${remote}/HEAD`,
+    ]);
+    if (local.status === 0) {
+        const ref = local.stdout.trim();
+        const prefix = `refs/remotes/${remote}/`;
+        if (ref.startsWith(prefix)) {
+            return { ok: true, value: ref.slice(prefix.length) };
+        }
+    }
+    if (!network) {
+        return {
+            ok: false,
+            reason: `cannot resolve the default branch of remote ${remote} without the ` +
+                `network: ${remote}/HEAD is unset locally, and this caller reports ` +
+                `rather than writes, so it does not contact ${remote} to ask`,
+        };
+    }
+    const advertised = runGit(project, ["ls-remote", "--symref", remote, "HEAD"], networkTimeoutMs());
+    if (advertised.status === 0) {
+        const match = /^ref:\s+refs\/heads\/(\S+)\s+HEAD$/m.exec(advertised.stdout);
+        if (match !== null) {
+            return { ok: true, value: match[1] };
+        }
+        return {
+            ok: false,
+            reason: `remote ${remote} did not advertise a default branch (no symref HEAD)`,
+        };
+    }
+    return {
+        ok: false,
+        reason: `cannot resolve the default branch of remote ${remote}: ` +
+            `${remote}/HEAD is unset locally and ls-remote failed: ${advertised.stderr.trim()}`,
+    };
+}
+/**
+ * Rebuild a pool record for taskId from tasks/<id>/meta.json and git.
+ * Reads only; writes nothing anywhere, ever.
+ */
+export function reconstructPoolRecord(fleet, taskId, options) {
+    if (!TASK_ID_PATTERN.test(taskId)) {
+        return { kind: "absent", reason: `task id "${taskId}" is not a safe path segment` };
+    }
+    const meta = readTaskMeta(fleet, taskId);
+    if (meta === undefined) {
+        return {
+            kind: "absent",
+            reason: `no readable task meta at ${metaPath(fleet, taskId)}, so there is ` +
+                `nothing to reconstruct a pool record from`,
+        };
+    }
+    const unresolved = [];
+    const details = [];
+    let remote;
+    let branch;
+    if (!existsSync(meta.project)) {
+        // Both fields live in the clone, so losing the clone loses both. They
+        // are reported together rather than one at a time, because a caller
+        // that repaired only the first would be told about the second on the
+        // next run and learn nothing it could not have been told now.
+        unresolved.push("remote", "branch");
+        details.push(`the project clone ${meta.project} recorded in meta.json is absent`);
+    }
+    else {
+        const resolvedRemote = resolveRemote(meta.project);
+        if (resolvedRemote.ok) {
+            remote = resolvedRemote.value;
+            const resolvedBranch = resolveDefaultBranch(meta.project, remote, options.network);
+            if (resolvedBranch.ok) {
+                branch = resolvedBranch.value;
+            }
+            else {
+                unresolved.push("branch");
+                details.push(resolvedBranch.reason);
+            }
+        }
+        else {
+            unresolved.push("remote", "branch");
+            details.push(resolvedRemote.reason);
+        }
+    }
+    if (remote === undefined || branch === undefined) {
+        return { kind: "incomplete", unresolved, detail: details.join("; ") };
+    }
+    return {
+        kind: "complete",
+        record: {
+            taskId,
+            project: meta.project,
+            remote,
+            branch,
+            baseSha: meta.baseSha,
+            branchName: meta.branch,
+            offline: meta.baseOffline,
+            createdAt: meta.createdAt,
+        },
+    };
+}
+/**
+ * pool create (EXT-F-03 five steps; see module doc). Returns the pool
+ * record on success.
+ *
+ * On failure NOTHING IS REMOVED. The pool record, the worktree
+ * directory and the task branch may each survive, depending on how far
+ * the attempt got, and the reason line names exactly which of them did
+ * and the command that clears them. The automatic rollback this
+ * docstring used to promise was deleted deliberately: it served a
+ * concurrent-create path M1 never enters (parallelism is off until M5)
+ * and produced four consecutive rounds of defects, including deleting
+ * state it had not validated. Failing loudly and leaving state is the
+ * chosen contract, not an oversight.
+ */
+export async function poolCreate(fleet, options) {
+    const { taskId, offline } = options;
+    if (!TASK_ID_PATTERN.test(taskId)) {
+        return { ok: false, reason: `task id "${taskId}" is not a safe path segment` };
+    }
+    const project = resolve(options.project);
+    const record = recordPath(fleet, taskId);
+    const worktree = worktreePath(fleet, taskId);
+    if (existsSync(record) || existsSync(worktree)) {
+        return { ok: false, reason: `task id already used: ${taskId}` };
+    }
+    // CR-201: a leftover task branch would otherwise surface as a raw git
+    // error from deep inside worktree add. Destroy now removes the branch
+    // it created, so this only fires when the branch came from elsewhere.
+    const branchName = taskBranchName(taskId);
+    const existing = runGit(project, [
+        "rev-parse",
+        "--verify",
+        "--quiet",
+        `refs/heads/${branchName}`,
+    ]);
+    if (existing.status === 0) {
+        return {
+            ok: false,
+            reason: `branch ${branchName} already exists in ${project}; the pool creates ` +
+                `it fresh, so delete or rename it before re-using task id ${taskId}`,
+        };
+    }
+    // U-12: the opposite collision direction. A ref UNDER
+    // refs/heads/task/<id>/ (for example task/foo/bar when creating
+    // task/foo) makes the branch equally uncreatable, and the exact-ref
+    // and strict-prefix checks both miss it, so it used to reach git
+    // worktree add and surface as the raw two-line git error the
+    // pre-check exists to eliminate.
+    const nested = runGit(project, [
+        "for-each-ref",
+        "--count=1",
+        "--format=%(refname)",
+        `refs/heads/${branchName}/`,
+    ]);
+    if (nested.status === 0 && nested.stdout.trim() !== "") {
+        return {
+            ok: false,
+            reason: `ref ${nested.stdout.trim()} already exists in ${project} and blocks ` +
+                `${branchName} (a ref cannot be both a branch and a directory); ` +
+                `delete or rename it before using task id ${taskId}`,
+        };
+    }
+    // U-7: the exact ref can be absent while the branch is still
+    // uncreatable, because any strict prefix of refs/heads/task/<id>
+    // existing as a ref is a directory/file conflict. Catch it here
+    // instead of after a full network fetch, inside git worktree add.
+    const segments = branchName.split("/");
+    for (let i = 1; i < segments.length; i += 1) {
+        const prefix = segments.slice(0, i).join("/");
+        const conflict = runGit(project, [
+            "rev-parse",
+            "--verify",
+            "--quiet",
+            `refs/heads/${prefix}`,
+        ]);
+        if (conflict.status === 0) {
+            return {
+                ok: false,
+                reason: `branch ${prefix} already exists in ${project} and blocks ` +
+                    `${branchName} (a ref cannot be both a branch and a directory); ` +
+                    `delete or rename it before using task id ${taskId}`,
+            };
+        }
+    }
+    const remote = resolveRemote(project);
+    if (!remote.ok) {
+        return remote;
+    }
+    // poolCreate is a write the operator invoked and it is about to fetch
+    // from this remote anyway, so it may ask the remote for its default.
+    const branch = resolveDefaultBranch(project, remote.value, true);
+    if (!branch.ok) {
+        return branch;
+    }
+    const trackingRef = `refs/remotes/${remote.value}/${branch.value}`;
+    // EXT-F-03 step 2: fetch the default branch, force-updating exactly
+    // the remote-tracking ref (so a rewound remote is still mirrored).
+    let usedOffline = false;
+    const fetch = await runGitRetrying(project, [
+        "fetch",
+        remote.value,
+        `+refs/heads/${branch.value}:${trackingRef}`,
+    ]);
+    if (fetch.status !== 0) {
+        if (!offline) {
+            return {
+                ok: false,
+                reason: `fetch of ${remote.value}/${branch.value} failed and --offline was ` +
+                    `not passed; refusing to base work on a stale ref: ${fetch.stderr.trim()}`,
+            };
+        }
+        usedOffline = true;
+    }
+    // EXT-F-03 step 3: the base SHA is the (just) fetched remote-tracking
+    // ref, never a local branch.
+    const base = runGit(project, ["rev-parse", "--verify", `${trackingRef}^{commit}`]);
+    if (base.status !== 0) {
+        return {
+            ok: false,
+            reason: usedOffline
+                ? `--offline was passed but ${trackingRef} has never been fetched; nothing to base on`
+                : `cannot resolve ${trackingRef} after fetch: ${base.stderr.trim()}`,
+        };
+    }
+    const baseSha = base.stdout.trim();
+    const poolRecord = {
+        taskId,
+        project,
+        remote: remote.value,
+        branch: branch.value,
+        baseSha,
+        branchName,
+        offline: usedOffline,
+        createdAt: new Date().toISOString(),
+    };
+    // O_EXCL record reservation: the atomic duplicate gate for concurrent
+    // creates with the same task id.
+    try {
+        writeFileSync(record, `${JSON.stringify(poolRecord, null, 2)}\n`, {
+            flag: "wx",
+        });
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            return { ok: false, reason: `task id already used: ${taskId}` };
+        }
+        throw error;
+    }
+    // EXT-F-03 step 4: task branch and worktree directly from the exact
+    // fetched SHA. Transient contention is retried by the one signature.
+    //
+    // There is deliberately NO automatic cleanup on failure. Parallelism
+    // is off until M5 (plan section 1.4), so nothing in M1 drives the
+    // concurrent-create path this machinery existed for, and four rounds
+    // of defects came out of it: a global prune that could kill another
+    // create, an unvalidated recursive delete of an admin directory, and
+    // a rollback that broke under the very contention it existed to
+    // handle. Failing loudly and leaving state is strictly better than
+    // cleanup code that deletes the wrong thing. The operator is told
+    // exactly what was left and exactly how to clear it.
+    const add = await runGitRetrying(project, [
+        "worktree",
+        "add",
+        "-b",
+        poolRecord.branchName,
+        worktree,
+        baseSha,
+    ]);
+    if (add.status !== 0) {
+        const leftovers = [`pool record ${record}`];
+        if (existsSync(worktree)) {
+            leftovers.push(`worktree directory ${worktree}`);
+        }
+        const branchProbe = runGit(project, [
+            "rev-parse",
+            "--verify",
+            "--quiet",
+            `refs/heads/${poolRecord.branchName}^{commit}`,
+        ]);
+        if (branchProbe.status === 0) {
+            leftovers.push(`branch ${poolRecord.branchName}`);
+        }
+        return {
+            ok: false,
+            reason: `git worktree add failed: ${add.stderr.trim()}; nothing was removed, ` +
+                `left behind: ${leftovers.join(", ")}; clear it with "tiphys pool ` +
+                `destroy --task ${taskId} --discard --delete-branch-force" run in the fleet home`,
+        };
+    }
+    return { ok: true, value: poolRecord };
+}
+/** The worktree's current HEAD SHA, or "missing" when there is no worktree. */
+function headShaOf(fleet, taskId) {
+    const worktree = worktreePath(fleet, taskId);
+    const head = existsSync(worktree)
+        ? runGit(worktree, ["rev-parse", "HEAD"])
+        : undefined;
+    return head !== undefined && head.status === 0 ? head.stdout.trim() : "missing";
+}
+/**
+ * One entry per pool record, with the worktree's current HEAD SHA, PLUS
+ * one per OPEN task that has no pool record beside it (M4-P19).
+ *
+ * The second group is what a reclaim leaves behind: tasks/ is tracked and
+ * survives, worktrees/ is gitignored and does not, so a task can be open
+ * with its record gone. Reporting only the first group makes those tasks
+ * invisible to `pool list` and to doctor, which is the state the plan
+ * calls a defect. Every such entry is marked, never silently blended in
+ * with the originals, and NOTHING here is written to disk.
+ *
+ * Closed tasks are excluded: a closed task is not in the pool, and
+ * listing every task this fleet ever finished as a missing worktree would
+ * make the report useless within a week.
+ *
+ * THIS FUNCTION OPENS NO SOCKET (M4-P19 fix round). It reads the
+ * filesystem and runs local git commands, and its reconstruction is
+ * asked for with `{ network: false }`. An entry whose default branch
+ * cannot be established from the clone alone is reported
+ * `unreconstructable (unresolved: branch)` rather than waited on. See
+ * `ReconstructOptions` for the measured hang that this closes.
+ */
+export function poolList(fleet) {
+    const entries = [];
+    const seen = new Set();
+    const names = readdirSync(fleet.worktreesDir)
+        .filter((name) => name.endsWith(".pool.json"))
+        .sort();
+    for (const name of names) {
+        const taskId = name.slice(0, -".pool.json".length);
+        seen.add(taskId);
+        entries.push({ taskId, headSha: headShaOf(fleet, taskId), origin: "record" });
+    }
+    /* AN UNLISTABLE tasks/ IS NOT AN ABSENCE OF TASKS (T-036's mechanism, and
+       src/commands/next.ts:40 states the standard: a category empty BY
+       CONSTRUCTION reported as empty BY OBSERVATION). This `catch` swallowed
+       it into `[]`, so `tiphys pool list` printed nothing and exited 0 and
+       doctor's CHECK worktrees printed the positive claim "no pool worktrees"
+       about a directory it had not read. It now reaches the caller through the
+       SAME channel the `readdirSync(fleet.worktreesDir)` above it already
+       uses, which src/commands/next.ts:334 already catches and reports into
+       its `unknown` list. */
+    const taskIds = readdirSync(fleet.tasksDir).sort();
+    for (const taskId of taskIds) {
+        if (seen.has(taskId) || !TASK_ID_PATTERN.test(taskId)) {
+            continue;
+        }
+        /* A task record that is PRESENT and did not READ is not a closed task.
+           `readTaskMeta` answers `undefined` for absent, unreadable and
+           unparseable alike, and dropping all three hid exactly the interrupted
+           spawn this listing exists to surface: with tasks/t-0001/meta.json
+           truncated mid-write, `pool list` printed NOTHING while doctor's CHECK
+           tasks reported the same task as open. The entry type is established
+           here rather than inferred from `readTaskMeta`'s one-word answer. */
+        const metaEntry = classifyPathEntry(metaPath(fleet, taskId));
+        const meta = readTaskMeta(fleet, taskId);
+        if (meta === undefined && metaEntry.kind !== "absent" && metaEntry.kind !== "dangling") {
+            entries.push({
+                taskId,
+                headSha: headShaOf(fleet, taskId),
+                origin: "unreconstructable",
+                unresolved: ["meta"],
+            });
+            continue;
+        }
+        if (meta === undefined || meta.status !== "open") {
+            continue;
+        }
+        // REPORTING, so NO NETWORK. `pool list` and doctor's CHECK worktrees
+        // both arrive here, and both must return. A task whose `branch`
+        // needs the network to resolve is reported `unreconstructable`,
+        // which is a true statement about what this path can establish.
+        const rebuilt = reconstructPoolRecord(fleet, taskId, { network: false });
+        if (rebuilt.kind === "absent") {
+            continue;
+        }
+        entries.push(rebuilt.kind === "complete"
+            ? { taskId, headSha: headShaOf(fleet, taskId), origin: "reconstructed" }
+            : {
+                taskId,
+                headSha: headShaOf(fleet, taskId),
+                origin: "unreconstructable",
+                unresolved: rebuilt.unresolved,
+            });
+    }
+    return entries;
+}
+function defaultLsof(path) {
+    const result = spawnSync("lsof", ["-t", "--", path], { encoding: "utf8" });
+    if (result.error !== undefined) {
+        return { available: false, exitCode: null, stdout: "" };
+    }
+    return {
+        available: true,
+        exitCode: result.status,
+        stdout: result.stdout ?? "",
+    };
+}
+/** Age a lock file must reach before a staleness proof is even considered. */
+export const STALE_LOCK_AGE_MS = 300_000;
+/**
+ * Fail-safe staleness proof for a git lock file (FM-036, FM-051): true
+ * only when the lock exists, its mtime age exceeds the threshold, and
+ * lsof is available and shows provably no holder (exit 1, empty stdout).
+ * Any uncertainty (lsof missing, erroring, or listing holders) is false:
+ * the lock is left in place and the operation fails loudly.
+ */
+export function provablyStaleLock(lockFile, opts = {}) {
+    const nowMs = opts.nowMs ?? Date.now();
+    const threshold = opts.ageThresholdMs ?? STALE_LOCK_AGE_MS;
+    const probe = opts.runLsof ?? defaultLsof;
+    let mtimeMs;
+    try {
+        mtimeMs = statSync(lockFile).mtimeMs;
+    }
+    catch {
+        return false;
+    }
+    if (nowMs - mtimeMs <= threshold) {
+        return false;
+    }
+    const lsof = probe(lockFile);
+    if (!lsof.available || lsof.exitCode !== 1 || lsof.stdout.trim() !== "") {
+        return false;
+    }
+    return true;
+}
+async function destroyGitStep(contextDir, args, worktree) {
+    let result = await runGitRetrying(contextDir, args);
+    if (result.status !== 0 && GIT_CONTENTION.test(result.stderr)) {
+        // Retries exhausted on a lock signature: attempt the fail-safe
+        // staleness proof on the worktree's index.lock, the one transient
+        // lock a destroy can legitimately hit (FM-036).
+        const gitDir = runGit(worktree, ["rev-parse", "--absolute-git-dir"]);
+        if (gitDir.status === 0) {
+            const indexLock = join(gitDir.stdout.trim(), "index.lock");
+            if (provablyStaleLock(indexLock)) {
+                try {
+                    unlinkSync(indexLock);
+                }
+                catch {
+                    // Already gone; retry either way.
+                }
+                result = await runGitRetrying(contextDir, args);
+            }
+        }
+    }
+    return result;
+}
+/** Stage 1: gather facts. Read only; mutates nothing. */
+async function resolveDestroy(fleet, taskId, reconstructed) {
+    const worktree = worktreePath(fleet, taskId);
+    const recordFile = recordPath(fleet, taskId);
+    const onDisk = readPoolRecord(fleet, taskId);
+    // The on-disk record always wins. The reconstruction is a FALLBACK, so
+    // a present-but-different record can never be overridden by one.
+    const record = onDisk ?? reconstructed;
+    // Deliberately the FILE, not the record: this is what authorizes the
+    // unlink in stage 3, and a reconstruction has no file to unlink.
+    const haveRecord = existsSync(recordFile);
+    const haveWorktree = existsSync(worktree);
+    if (!haveRecord && !haveWorktree) {
+        return { ok: false, reason: `no pool worktree for task id ${taskId}` };
+    }
+    // The git context must be resolved while the worktree still exists,
+    // because the worktree is one of only two ways to find it.
+    let contextDir;
+    if (record !== undefined && existsSync(record.project)) {
+        contextDir = record.project;
+    }
+    else if (haveWorktree) {
+        const common = runGit(worktree, [
+            "rev-parse",
+            "--path-format=absolute",
+            "--git-common-dir",
+        ]);
+        if (common.status === 0 && common.stdout.trim() !== "") {
+            contextDir = common.stdout.trim();
+        }
+    }
+    if (contextDir === undefined) {
+        return {
+            ok: false,
+            reason: `cannot resolve the project repository for task id ${taskId}: the ` +
+                `pool record ${recordFile} is missing or unreadable and there is no ` +
+                `usable worktree. Nothing was removed; repair or delete that record ` +
+                `file to release the id`,
+        };
+    }
+    let dirty;
+    let dirtyProbeError;
+    if (haveWorktree) {
+        const status = await destroyGitStep(worktree, ["status", "--porcelain"], worktree);
+        if (status.status !== 0) {
+            dirtyProbeError = status.stderr.trim();
+        }
+        else {
+            dirty = status.stdout.trim() !== "";
+        }
+    }
+    const branchName = record?.branchName ?? taskBranchName(taskId);
+    const tip = runGit(contextDir, [
+        "rev-parse",
+        "--verify",
+        "--quiet",
+        `refs/heads/${branchName}^{commit}`,
+    ]);
+    let branchTip;
+    if (tip.status === 0) {
+        branchTip = { kind: "present", sha: tip.stdout.trim() };
+    }
+    else if (tip.status === 1) {
+        branchTip = { kind: "absent" };
+    }
+    else {
+        branchTip = {
+            kind: "indeterminate",
+            detail: tip.stderr.trim() === "" ? `git exited ${String(tip.status)}` : tip.stderr.trim(),
+        };
+    }
+    let branchCheckedOutAt;
+    const listed = runGit(contextDir, ["worktree", "list", "--porcelain"]);
+    if (listed.status === 0) {
+        let currentPath;
+        for (const line of listed.stdout.split("\n")) {
+            if (line.startsWith("worktree ")) {
+                currentPath = line.slice("worktree ".length).trim();
+            }
+            else if (line.trim() === `branch refs/heads/${branchName}`) {
+                // IDENTITY, NOT STRING EQUALITY, and the difference is a shipped
+                // defect this comparison had until 2026-09-16 (macOS smoke job of
+                // pull request #155). `currentPath` is GIT'S spelling and `worktree`
+                // is THIS KERNEL'S: git canonicalizes every worktree path it records,
+                // so a fleet reached through a symlink makes the two sides different
+                // strings for one directory. `resolve` does not resolve symlinks, so
+                // the old comparison then reported the task's OWN worktree as a
+                // foreign worktree holding the branch, stage 2 refused the destroy
+                // that was never in danger, and spawn's rollback left the worktree,
+                // the pool record and the branch behind after a launch that never
+                // started. On macOS no unusual setup is needed to reach it: the
+                // platform puts `os.tmpdir()` behind `/var -> /private/var`.
+                if (currentPath !== undefined && !pathsNameSameObject(currentPath, worktree)) {
+                    branchCheckedOutAt = currentPath;
+                }
+            }
+        }
+    }
+    return {
+        ok: true,
+        value: {
+            taskId,
+            contextDir,
+            record,
+            recordFile,
+            haveRecord,
+            worktree,
+            haveWorktree,
+            dirty,
+            dirtyProbeError,
+            branchName,
+            branchTip,
+            branchCheckedOutAt,
+        },
+    };
+}
+/**
+ * Stage 2: decide. Pure over the facts, no IO, so no gate can destroy
+ * anything. Returns a refusal reason, or undefined to proceed.
+ */
+function evaluateDestroy(facts, options) {
+    if (facts.haveWorktree && !options.discard) {
+        if (facts.dirtyProbeError !== undefined) {
+            return `cannot verify worktree cleanliness: ${facts.dirtyProbeError}`;
+        }
+        if (facts.dirty === true) {
+            return (`worktree ${facts.worktree} has uncommitted changes or untracked ` +
+                `files; commit or land them first, or pass --discard to remove anyway`);
+        }
+    }
+    if (facts.branchTip.kind === "indeterminate") {
+        return (`cannot determine whether branch ${facts.branchName} exists in ` +
+            `${facts.contextDir} (${facts.branchTip.detail}); refusing to finish ` +
+            `destroy for task id ${facts.taskId}`);
+    }
+    if (facts.branchTip.kind === "present" &&
+        facts.branchCheckedOutAt !== undefined) {
+        // Policy, and therefore a stage-2 refusal: a true no-op. Deleting a
+        // branch another worktree has checked out would strand it on a
+        // dangling HEAD. git branch -D enforces this; update-ref, which
+        // stage 3 uses for its atomic compare-and-delete, does not, so the
+        // rule is enforced here rather than relied on downstream.
+        return (`cannot delete branch ${facts.branchName}: it is checked out at ` +
+            `${facts.branchCheckedOutAt}; remove that worktree first`);
+    }
+    if (facts.branchTip.kind === "present" && !options.deleteBranchForce) {
+        const baseSha = facts.record?.baseSha;
+        if (baseSha === undefined) {
+            return (`cannot verify branch ${facts.branchName} against its recorded base ` +
+                `(pool record missing or unreadable), tip ${facts.branchTip.sha}; land ` +
+                `it or pass --delete-branch-force to delete it anyway`);
+        }
+        if (facts.branchTip.sha !== baseSha) {
+            return (`branch ${facts.branchName} carries commits beyond its base ` +
+                `${baseSha} (tip ${facts.branchTip.sha}); land them or pass ` +
+                `--delete-branch-force to delete it anyway`);
+        }
+    }
+    return undefined;
+}
+/**
+ * Stage 3: perform. Reached only with every gate passed, so there is
+ * nothing left to refuse; failures here are operational, not policy.
+ */
+async function applyDestroy(facts, options) {
+    if (facts.haveWorktree) {
+        // F-1: --discard means "remove anyway" (plan step 3), and git's own
+        // documented way to say that for a LOCKED working tree is a second
+        // --force. An interrupted git worktree add leaves
+        // .git/worktrees/<id>/locked = "initializing", which a single
+        // --force refuses, so the remedy this kernel prints on a failed
+        // create used to exit 1 and clear nothing, wedging the task id. No
+        // concurrency is needed to reach that state: Ctrl-C, a crash, a
+        // full disk or an OOM kill during a large checkout produces it.
+        // The default path is deliberately unchanged: without --discard
+        // nothing here is forced at all.
+        const removeArgs = options.discard
+            ? ["worktree", "remove", "--force", "--force", facts.worktree]
+            : ["worktree", "remove", facts.worktree];
+        const removed = await destroyGitStep(facts.contextDir, removeArgs, facts.worktree);
+        if (removed.status !== 0) {
+            return {
+                ok: false,
+                reason: `git worktree remove failed: ${removed.stderr.trim()}`,
+            };
+        }
+    }
+    else {
+        const pruned = await runGitRetrying(facts.contextDir, ["worktree", "prune"]);
+        if (pruned.status !== 0) {
+            return {
+                ok: false,
+                reason: `git worktree prune failed: ${pruned.stderr.trim()}`,
+            };
+        }
+    }
+    const outcome = {};
+    if (facts.branchTip.kind === "present") {
+        // Stage 2 approved a SPECIFIC tip. Rather than re-read the tip and
+        // then delete (two steps with a window between them, which is what
+        // a check-then-act race is), hand the comparison to git: with an
+        // old-value argument, update-ref -d deletes the ref ONLY if it is
+        // still exactly that sha and fails atomically otherwise. The safety
+        // claim is therefore enforced by the ref transaction, not by a
+        // recheck that can be overtaken between checking and acting.
+        // Deliberately NOT runGitRetrying. git reports a failed old-value
+        // comparison as "cannot lock ref '<ref>': is at X but expected Y",
+        // which the contention signature treats as transient because on a
+        // FETCH it means another process already advanced the ref and a
+        // retry succeeds. Here the same text means the branch is no longer
+        // what stage 2 approved, which no amount of retrying will change:
+        // same shape, different call site, different meaning.
+        const deleted = runGit(facts.contextDir, [
+            "update-ref",
+            "-d",
+            `refs/heads/${facts.branchName}`,
+            facts.branchTip.sha,
+        ]);
+        if (deleted.status !== 0) {
+            // The worktree is already gone by this point and cannot be put
+            // back, so this is a PARTIAL FAILURE, not a refusal. Enumerate
+            // the real remaining state rather than implying nothing changed.
+            const detail = deleted.stderr.trim().split("\n")[0] ?? "";
+            const nowTip = runGit(facts.contextDir, [
+                "rev-parse",
+                "--verify",
+                "--quiet",
+                `refs/heads/${facts.branchName}^{commit}`,
+            ]);
+            const currentTip = nowTip.status === 0 ? nowTip.stdout.trim() : "absent";
+            const worktreeState = facts.haveWorktree
+                ? `worktree ${facts.worktree} HAS BEEN REMOVED (with any git-ignored files in it) and its registration pruned`
+                : `no worktree directory was present`;
+            return {
+                ok: false,
+                reason: `partial destroy of task id ${facts.taskId}: ${worktreeState}; branch ` +
+                    `${facts.branchName} was NOT deleted and is left at ${currentTip} ` +
+                    `(the delete was approved for ${facts.branchTip.sha} and git refused: ` +
+                    `${detail}); the pool record ${facts.recordFile} is left in place; ` +
+                    `re-run "tiphys pool destroy --task ${facts.taskId} ` +
+                    `--delete-branch-force" to finish once you have checked that branch`,
+            };
+        }
+        outcome.deletedBranch = facts.branchName;
+        // The recovery handle: without it a mistaken destroy leaves the sha
+        // discoverable only through git fsck --lost-found, until gc.
+        outcome.deletedSha = facts.branchTip.sha;
+    }
+    if (facts.haveRecord) {
+        unlinkSync(facts.recordFile);
+    }
+    return { ok: true, value: outcome };
+}
+export async function poolDestroy(fleet, options) {
+    const { taskId } = options;
+    if (!TASK_ID_PATTERN.test(taskId)) {
+        return { ok: false, reason: `task id "${taskId}" is not a safe path segment` };
+    }
+    // Stage 1: read only.
+    const resolved = await resolveDestroy(fleet, taskId, options.reconstructed);
+    if (!resolved.ok) {
+        return resolved;
+    }
+    // Stage 2: pure decision. Every refusal returns here, before stage 3
+    // has touched anything.
+    const refusal = evaluateDestroy(resolved.value, options);
+    if (refusal !== undefined) {
+        return { ok: false, reason: refusal };
+    }
+    // Stage 3: destructive, and no longer able to refuse.
+    return applyDestroy(resolved.value, options);
+}