@ai-dossier/worktree-pool 0.5.2 → 0.6.0

package/dist/pool-actions.js

@@ -33,8 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReturnFailure = void 0;
 exports.readPoolFileConfig = readPoolFileConfig;
 exports.resolvePoolDir = resolvePoolDir;
+exports.findBrokenEntries = findBrokenEntries;
 exports.replenish = replenish;
 exports.claim = claim;
 exports.returnWorktree = returnWorktree;
@@ -346,6 +348,53 @@ function lockfilePathForWorktree(worktreeAbsPath, cfg) {
     const projectDir = (0, project_env_1.resolveProjectDir)(worktreeAbsPath, cfg.project_subdir);
     return (0, project_env_1.lockfilePathFor)((0, project_env_1.detectProjectEnv)(projectDir), cfg.project_subdir);
 }
+/**
+ * Did the project lockfile change between `baseCommit` and the configured base
+ * ref? An unreadable diff counts as "changed" — re-warming is cheap, a stale
+ * `node_modules` is not.
+ */
+function lockfileChangedSince(gitRoot, baseCommit, worktreeAbsPath, cfg) {
+    try {
+        const diff = git(['diff', '--name-only', `${baseCommit}..${cfg.base_ref}`], { cwd: gitRoot });
+        return (0, project_env_1.lockfileChangedInDiff)(diff, lockfilePathForWorktree(worktreeAbsPath, cfg));
+    }
+    catch {
+        return true;
+    }
+}
+/** Message of a thrown value, whatever it is. */
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Make git's error text safe to persist and re-print. `.pool-state.json` is a
+ * plain file that `status` echoes back, and git quotes remote URLs verbatim in
+ * its errors — including any `https://user:token@host` credentials — so an
+ * unfiltered message would write a secret to disk and replay terminal escape
+ * sequences from a remote on every later `status`.
+ */
+function sanitizeReason(text) {
+    return (text
+        .replace(/([a-z][a-z0-9+.-]*:\/\/)[^/\s@]+@/gi, '$1<redacted>@')
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping terminal escapes is the point
+        .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '')
+        .slice(0, 2000));
+}
+/**
+ * The value to record as an entry's `path`. State paths are contractually bare
+ * directory names directly inside the pool directory (`classifyPath` matches on
+ * `basename`), so anything that escapes — from a hand-edited or corrupted state
+ * file — keeps the previously recorded name rather than being written back.
+ */
+function relativePoolPath(poolDir, onDiskPath, fallback) {
+    const rel = path.relative(poolDir, onDiskPath);
+    const isBareSegment = rel.length > 0 &&
+        !path.isAbsolute(rel) &&
+        !rel.startsWith('..') &&
+        !rel.includes(path.sep) &&
+        rel !== '.';
+    return isBareSegment ? rel : fallback;
+}
 // --- Ownership / provenance ---
 //
 // The pool directory is routinely shared with worktrees a developer made by
@@ -361,6 +410,52 @@ function realpathOrSelf(p) {
         return path.resolve(p);
     }
 }
+/**
+ * Absolute path of the git admin dir a linked worktree points at, or `null`
+ * when the directory carries no readable `.git` link. A directory holding a
+ * real `.git` directory (a whole repo, not a linked worktree) reports itself.
+ */
+function resolveWorktreeAdminDir(absPath) {
+    const dotGit = path.join(absPath, '.git');
+    let stat;
+    try {
+        stat = fs.statSync(dotGit);
+    }
+    catch {
+        return null;
+    }
+    if (stat.isDirectory())
+        return dotGit;
+    let raw;
+    try {
+        raw = fs.readFileSync(dotGit, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    const match = /^gitdir:\s*(.+)$/m.exec(raw);
+    if (!match)
+        return null;
+    const target = match[1].trim();
+    if (target.length === 0)
+        return null;
+    return path.isAbsolute(target) ? target : path.resolve(absPath, target);
+}
+/**
+ * True when a directory that is on disk has lost the git admin dir behind it.
+ *
+ * This is the #443 corruption: a rename repaired without its new path leaves a
+ * dangling `gitdir` forward link, and the next `git worktree prune` deletes
+ * `.git/worktrees/<id>`. The directory survives with a `.git` file pointing at
+ * nothing, so every git command inside it fails with
+ * `fatal: not a git repository`.
+ */
+function isWorktreeAdminDirMissing(absPath) {
+    if (!fs.existsSync(absPath))
+        return false;
+    const adminDir = resolveWorktreeAdminDir(absPath);
+    return adminDir === null || !fs.existsSync(adminDir);
+}
 /**
  * Absolute worktree path -> checked-out branch, from `git worktree list`.
  * A registered worktree with a detached HEAD maps to `null`.
@@ -410,6 +505,7 @@ function classifyPath(ctx, absPath) {
             branch: ctx.branches.get(resolved) ?? null,
             provenance: 'foreign',
             owned: false,
+            broken: false,
             reason: `outside the pool directory (${poolDirReal})`,
         };
     }
@@ -420,6 +516,7 @@ function classifyPath(ctx, absPath) {
         registered,
         existsOnDisk: fs.existsSync(resolved),
         stateEntry: ctx.state.worktrees.find((w) => w.path === name) ?? null,
+        adminDirMissing: registered ? false : isWorktreeAdminDirMissing(resolved),
     });
     return {
         name,
@@ -441,10 +538,31 @@ function scanPoolDir(ctx) {
     }
     return reports;
 }
-/** Foreign worktrees found in the pool directory, for reporting. */
-function foreignInPoolDir(gitRoot, poolDir, state) {
-    const ctx = buildOwnershipContext(gitRoot, poolDir, state);
-    return scanPoolDir(ctx).filter((e) => !e.owned);
+/**
+ * Split the pool directory into the two things worth reporting: worktrees the
+ * pool did not create, and entries corrupted on disk (#443).
+ *
+ * A corrupted entry is listed only under `broken` — reporting it as foreign as
+ * well would read as two separate problems with one directory.
+ */
+function reportPoolDirEntries(gitRoot, poolDir, state) {
+    const entries = scanPoolDir(buildOwnershipContext(gitRoot, poolDir, state));
+    const broken = entries.filter((e) => e.broken);
+    const brokenPaths = new Set(broken.map((e) => e.path));
+    return {
+        foreign: entries.filter((e) => !e.owned && !brokenPaths.has(e.path)),
+        broken,
+    };
+}
+/**
+ * Corrupted pool directories: still on disk, but git has no admin dir for them
+ * (#443). Reported so a broken pool is visible rather than surfacing as a raw
+ * `fatal: not a git repository` from whichever command touched it first.
+ */
+function findBrokenEntries() {
+    const gitRoot = findGitRoot();
+    const poolDir = resolvePoolDirSync(gitRoot);
+    return reportPoolDirEntries(gitRoot, poolDir).broken;
 }
 // --- Destroy helper ---
 /**
@@ -567,8 +685,19 @@ function claim(issue, branch) {
     const gitRoot = findGitRoot();
     const cfg = readPoolFileConfig(gitRoot);
     const poolDir = resolvePoolDirSync(gitRoot);
+    // A warm entry whose directory lost its git admin dir would fail every git
+    // command with a raw `fatal: not a git repository`. Skip it and take the
+    // next warm spare instead, reporting what was passed over.
+    const brokenSkipped = [];
     const result = withLock(poolDir, (state) => {
-        const claimed = (0, pool_state_1.claimWorktree)(state, issue, branch);
+        const ctx = buildOwnershipContext(gitRoot, poolDir, state);
+        const claimed = (0, pool_state_1.claimWorktree)(state, issue, branch, (candidate) => {
+            const report = classifyPath(ctx, toAbs(poolDir, candidate.path));
+            if (!report.broken)
+                return true;
+            brokenSkipped.push(report);
+            return false;
+        });
         if (!claimed)
             return { state, result: null };
         return { state: claimed.state, result: claimed.worktree };
@@ -583,17 +712,7 @@ function claim(issue, branch) {
         // Check freshness
         const currentBase = git(['rev-parse', cfg.base_ref], { cwd: gitRoot });
         if (worktree.base_commit !== currentBase) {
-            const lockfilePath = lockfilePathForWorktree(absPath, cfg);
-            let lockChanged = false;
-            try {
-                const diff = git(['diff', '--name-only', `${worktree.base_commit}..${cfg.base_ref}`], {
-                    cwd: gitRoot,
-                });
-                lockChanged = (0, project_env_1.lockfileChangedInDiff)(diff, lockfilePath);
-            }
-            catch {
-                lockChanged = true;
-            }
+            const lockChanged = lockfileChangedSince(gitRoot, worktree.base_commit, absPath, cfg);
             git(['fetch', (0, pool_state_1.remoteForBaseRef)(cfg.base_ref)], { cwd: absPath });
             git(['reset', '--hard', cfg.base_ref], { cwd: absPath });
             if (lockChanged) {
@@ -602,10 +721,15 @@ function claim(issue, branch) {
         }
         // Create issue branch
         git(['checkout', '-b', branch], { cwd: absPath });
-        // Rename directory
+        // Rename directory.
+        // `git worktree repair` must be given the *new* path: a pathless repair
+        // only fixes the worktree->repo back-link, leaving the repo-side
+        // `.git/worktrees/<id>/gitdir` forward link pointing at the old location.
+        // The next `git worktree prune` then sees a dangling gitdir, deletes the
+        // admin dir, and the renamed worktree is corrupted (#443).
         if (absPath !== newAbsPath && !fs.existsSync(newAbsPath)) {
             fs.renameSync(absPath, newAbsPath);
-            git(['worktree', 'repair'], { cwd: gitRoot });
+            git(['worktree', 'repair', newAbsPath], { cwd: gitRoot });
         }
         // Delete temp branch
         try {
@@ -623,7 +747,7 @@ function claim(issue, branch) {
             }),
             result: undefined,
         }));
-        return { path: newAbsPath };
+        return { path: newAbsPath, broken: brokenSkipped };
     }
     catch (err) {
         // Revert claim on failure
@@ -638,6 +762,139 @@ function claim(issue, branch) {
         throw err;
     }
 }
+/**
+ * A `return` that failed, tagged with the step that failed (#453 AC1). The
+ * pool entry has been left in `status: 'broken'` — not `assigned`, not `warm`
+ * — and the worktree directory is deliberately NOT destroyed, so the failure
+ * is inspectable and `gc` can clear it deliberately.
+ *
+ * `markError` is the one case where that promise could not be kept: the
+ * broken-marking write itself failed. Callers must report it rather than
+ * assume the entry is marked, or they reproduce the very bug #453 is about.
+ */
+class ReturnFailure extends Error {
+    step;
+    entryId;
+    worktreePath;
+    /** Why the entry could NOT be marked broken, or `null` when it was marked. */
+    markError;
+    constructor(step, worktreePath, entryId, cause, markError = null) {
+        super(`return failed at step '${step}': ${messageOf(cause)}`, { cause });
+        this.name = 'ReturnFailure';
+        this.step = step;
+        this.entryId = entryId;
+        this.worktreePath = worktreePath;
+        this.markError = markError;
+    }
+}
+exports.ReturnFailure = ReturnFailure;
+/** Run `fn`, tagging any throw with the step it happened in. */
+function step(name, fn) {
+    try {
+        return fn();
+    }
+    catch (err) {
+        // Kept so that if a step is ever nested inside another, the innermost
+        // attribution wins rather than being overwritten by its caller.
+        if (err instanceof StepError)
+            throw err;
+        throw new StepError(name, err);
+    }
+}
+/** Internal carrier so `step` can attribute a failure without unwinding twice. */
+class StepError extends Error {
+    step;
+    constructor(stepName, cause) {
+        super(messageOf(cause), { cause });
+        this.name = 'StepError';
+        this.step = stepName;
+    }
+}
+/** Branch checked out at `absPath`, or `null` when it cannot be determined. */
+function currentBranchOf(absPath) {
+    try {
+        const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: absPath });
+        return branch === 'HEAD' ? null : branch;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Tracked-file cleanliness of `absPath`. A git failure is reported as an error
+ * rather than as "dirty" — telling an operator to look for uncommitted changes
+ * that do not exist is the wrong place to send them.
+ */
+function inspectWorktreeCleanliness(absPath) {
+    let output;
+    try {
+        output = git(['status', '--porcelain', '--untracked-files=no'], { cwd: absPath });
+    }
+    catch (err) {
+        return { clean: false, entries: [`git status failed: ${messageOf(err)}`] };
+    }
+    const entries = output.length === 0 ? [] : output.split('\n');
+    return { clean: entries.length === 0, entries };
+}
+/**
+ * Verify a finished recycle against reality (#453 AC2). Separate from
+ * `returnWorktree` so the rules are readable and testable on their own.
+ */
+function verifyRecycled(poolDir, newId, newAbsPath, newTempBranch) {
+    const committed = readState(poolDir).worktrees.find((w) => w.id === newId);
+    const cleanliness = inspectWorktreeCleanliness(newAbsPath);
+    const result = {
+        entry_status: committed?.status ?? 'missing',
+        directory_clean: cleanliness.clean,
+        dirty_entries: cleanliness.entries,
+        checked_out_branch: currentBranchOf(newAbsPath),
+        expected_branch: newTempBranch,
+    };
+    const problems = [];
+    if (result.entry_status !== 'warm') {
+        problems.push(`entry status is '${result.entry_status}', expected 'warm'`);
+    }
+    if (!result.directory_clean) {
+        problems.push(`directory ${newAbsPath} is not clean: ${result.dirty_entries.slice(0, 5).join(', ')}`);
+    }
+    if (result.checked_out_branch !== newTempBranch) {
+        problems.push(`checked-out branch is '${result.checked_out_branch ?? 'detached HEAD'}', ` +
+            `expected '${newTempBranch}'`);
+    }
+    if (problems.length > 0) {
+        throw new Error(`post-return self-check failed: ${problems.join('; ')}`);
+    }
+    return result;
+}
+/**
+ * Mark a pool entry `broken` after a failed recycle. Returns `null` on
+ * success, or the reason the mark itself failed — never throws, because the
+ * caller is already reporting a failure and must not lose it, but never
+ * silently either: an unmarked entry is the #453 bug.
+ */
+function markEntryBroken(poolDir, entryId, updates) {
+    try {
+        withLock(poolDir, (state) => ({
+            state: (0, pool_state_1.updateWorktree)(state, entryId, updates),
+            result: undefined,
+        }));
+        return null;
+    }
+    catch (err) {
+        return messageOf(err);
+    }
+}
+/**
+ * Recycle an assigned worktree back to `warm`.
+ *
+ * Transactional in outcome (#453): it either finishes and returns a verified
+ * `warm` entry, or it leaves the entry `broken` and throws a `ReturnFailure`
+ * naming the step. It never leaves the entry `assigned`, never reports success
+ * over an unverified pool, and — unlike the pre-#453 behaviour — never
+ * destroys the worktree on failure. A broken entry keeps its provenance
+ * (recorded id, actual on-disk path, a pool-owned temp branch) so `status`
+ * shows it and `gc` can remove it.
+ */
 function returnWorktree(worktreePath) {
     const gitRoot = findGitRoot();
     const cfg = readPoolFileConfig(gitRoot);
@@ -646,53 +903,73 @@ function returnWorktree(worktreePath) {
     const newId = (0, types_1.generateId)();
     const newTempBranch = `pool/spare-${newId}`;
     const newAbsPath = toAbs(poolDir, newId);
-    // Look up entry and mark as recycling atomically under lock
-    const entry = withLock(poolDir, (state) => {
-        const found = state.worktrees.find((w) => toAbs(poolDir, w.path) === absPath);
-        if (!found) {
-            throw new Error(`Worktree not found in pool state: ${worktreePath}`);
-        }
-        return {
-            state: (0, pool_state_1.updateWorktree)(state, found.id, { status: 'recycling' }),
-            result: { ...found },
-        };
-    });
+    // Look up the entry and mark it `recycling`, atomically. This is the one
+    // failure with no entry to mark broken — there is no entry — but it still
+    // speaks the ReturnFailure contract so the CLI and library callers get the
+    // step name rather than a bare internal error.
+    let entry;
     try {
-        git(['fetch', (0, pool_state_1.remoteForBaseRef)(cfg.base_ref)], { cwd: absPath });
-        git(['checkout', '-b', newTempBranch, cfg.base_ref], { cwd: absPath });
-        git(['clean', '-fd'], { cwd: absPath });
-        if (entry.assigned_branch) {
-            try {
-                git(['branch', '-D', entry.assigned_branch], { cwd: absPath });
+        entry = withLock(poolDir, (state) => {
+            const found = state.worktrees.find((w) => toAbs(poolDir, w.path) === absPath);
+            if (!found) {
+                throw new Error(`Worktree not found in pool state: ${worktreePath} (resolved to ${absPath}); ` +
+                    `pool dir ${poolDir} tracks ${state.worktrees.length} entries`);
             }
-            catch {
-                // may not exist
+            return {
+                state: (0, pool_state_1.updateWorktree)(state, found.id, { status: 'recycling' }),
+                result: { ...found },
+            };
+        });
+    }
+    catch (err) {
+        throw new ReturnFailure('lookup', absPath, null, err);
+    }
+    // Where the directory, its branch and its state row actually are right now.
+    // Updated as the steps progress so a failure after a partial rename — or
+    // after `commit-state` has already renamed the entry id — records the truth
+    // rather than the values we started from.
+    let livePath = absPath;
+    let liveTempBranch = entry.temp_branch;
+    let liveId = entry.id;
+    try {
+        step('fetch', () => git(['fetch', (0, pool_state_1.remoteForBaseRef)(cfg.base_ref)], { cwd: livePath }));
+        step('checkout-temp-branch', () => git(['checkout', '-b', newTempBranch, cfg.base_ref], { cwd: livePath }));
+        liveTempBranch = newTempBranch;
+        step('clean', () => git(['clean', '-fd'], { cwd: livePath }));
+        const assignedBranch = entry.assigned_branch;
+        if (assignedBranch) {
+            // Best-effort: the branch may already be gone. Anything else is worth
+            // saying out loud — a surviving branch collides on the next claim.
+            try {
+                git(['branch', '-D', assignedBranch], { cwd: livePath });
             }
-        }
-        if (absPath !== newAbsPath) {
-            if (fs.existsSync(newAbsPath)) {
-                throw new Error(`Recycle target already exists: ${newAbsPath}`);
+            catch (err) {
+                const msg = messageOf(err);
+                if (!/not found|no branch named/i.test(msg)) {
+                    console.error(`Warning: could not delete assigned branch '${assignedBranch}': ${msg}`);
+                }
             }
-            fs.renameSync(absPath, newAbsPath);
-            git(['worktree', 'repair'], { cwd: gitRoot });
         }
-        const currentBase = git(['rev-parse', cfg.base_ref], { cwd: gitRoot });
-        const lockfilePath = lockfilePathForWorktree(newAbsPath, cfg);
-        let lockChanged = false;
-        try {
-            const diff = git(['diff', '--name-only', `${entry.base_commit}..${cfg.base_ref}`], {
-                cwd: gitRoot,
+        if (livePath !== newAbsPath) {
+            step('rename', () => {
+                if (fs.existsSync(newAbsPath)) {
+                    throw new Error(`Recycle target already exists: ${newAbsPath}`);
+                }
+                fs.renameSync(livePath, newAbsPath);
             });
-            lockChanged = (0, project_env_1.lockfileChangedInDiff)(diff, lockfilePath);
-        }
-        catch {
-            lockChanged = true;
+            livePath = newAbsPath;
+            // Repair the moved worktree by its new path — see the note in `claim`;
+            // a pathless repair leaves a dangling gitdir for `prune` to delete (#443).
+            step('repair', () => git(['worktree', 'repair', newAbsPath], { cwd: gitRoot }));
         }
-        if (lockChanged) {
-            runWarmCommands(newAbsPath, cfg);
-        }
-        withLock(poolDir, (state) => ({
-            state: (0, pool_state_1.updateWorktree)(state, entry.id, {
+        const currentBase = step('read-base-commit', () => git(['rev-parse', cfg.base_ref], { cwd: gitRoot }));
+        step('warm-commands', () => {
+            if (lockfileChangedSince(gitRoot, entry.base_commit, newAbsPath, cfg)) {
+                runWarmCommands(newAbsPath, cfg);
+            }
+        });
+        step('commit-state', () => withLock(poolDir, (state) => ({
+            state: (0, pool_state_1.updateWorktree)(state, liveId, {
                 id: newId,
                 path: newId,
                 status: 'warm',
@@ -701,35 +978,45 @@ function returnWorktree(worktreePath) {
                 warmed_at: new Date().toISOString(),
                 assigned_to_issue: null,
                 assigned_branch: null,
+                broken_step: undefined,
+                broken_reason: undefined,
+                broken_branch: undefined,
             }),
             result: undefined,
-        }));
+        })));
+        // `commit-state` renamed the row. Anything that fails from here on must
+        // mark THIS id, or the entry silently stays `warm` and claimable (#453).
+        liveId = newId;
+        // AC2: verify against reality before claiming success. A pool that only
+        // *says* it is warm is what #453 is about.
+        return {
+            id: newId,
+            path: newAbsPath,
+            verification: step('verify', () => verifyRecycled(poolDir, newId, newAbsPath, newTempBranch)),
+        };
     }
     catch (err) {
-        // Cleanup is best-effort but never indiscriminate: `destroyWorktree`
-        // refuses any path it cannot prove the pool created, and those refusals
-        // are surfaced instead of being retried with `rm -rf`.
-        const skipped = [];
-        const ctx = buildOwnershipContext(gitRoot, poolDir);
-        for (const [branch, target] of [
-            [entry.temp_branch, absPath],
-            [newTempBranch, newAbsPath],
-        ]) {
-            if (!fs.existsSync(target))
-                continue;
-            try {
-                destroyWorktree(ctx, branch, target);
-            }
-            catch (cleanupErr) {
-                skipped.push(cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr));
-            }
-        }
-        withLock(poolDir, (state) => ({
-            state: (0, pool_state_1.removeWorktree)(state, entry.id),
-            result: undefined,
-        }));
-        const suffix = skipped.length > 0 ? ` Left on disk: ${skipped.join('; ')}` : '';
-        throw new Error(`Recycle failed (destroyed worktree): ${err instanceof Error ? err.message : String(err)}.${suffix}`);
+        const failedStep = err instanceof StepError ? err.step : 'unknown';
+        const cause = err instanceof StepError ? (err.cause ?? err) : err;
+        const reason = sanitizeReason(messageOf(cause));
+        // Mark broken instead of destroying (#453). The directory stays on disk so
+        // the failure can be inspected; the entry points at where the directory
+        // actually is so `classifyPoolDirEntry` still calls it ours and `gc` can
+        // clear it.
+        const onDiskPath = fs.existsSync(livePath) ? livePath : absPath;
+        const observedBranch = currentBranchOf(onDiskPath);
+        const markError = markEntryBroken(poolDir, liveId, {
+            status: 'broken',
+            path: relativePoolPath(poolDir, onDiskPath, entry.path),
+            // NEVER widen provenance from what happens to be checked out: recording
+            // a developer's branch here would make `classifyPoolDirEntry`'s ownership
+            // test tautological and hand `gc` a directory it must refuse (#438).
+            temp_branch: (0, pool_state_1.isPoolTempBranch)(observedBranch) ? observedBranch : liveTempBranch,
+            broken_step: failedStep,
+            broken_reason: reason,
+            broken_branch: observedBranch,
+        });
+        throw new ReturnFailure(failedStep, onDiskPath, liveId, cause, markError);
     }
 }
 function refresh() {
@@ -798,6 +1085,7 @@ async function gc(opts = {}) {
     const errors = [];
     const staleIds = [];
     const orphanIds = [];
+    const brokenIds = [];
     let removed = 0;
     const state = readState(poolDir);
     const ctx = buildOwnershipContext(gitRoot, poolDir, state);
@@ -806,8 +1094,32 @@ async function gc(opts = {}) {
     const ownedNames = new Set(onDisk.filter((e) => e.owned).map((e) => e.name));
     const candidates = [];
     const claimed = new Set();
+    // Entries a `return` left broken (#453). Collected immediately rather than
+    // after `stale_after_hours`: they are unusable from the moment they are
+    // marked, they occupy `max_pool_size` capacity until removed, and the CLI
+    // tells the operator to clear them with `gc`. Still routed through
+    // `classifyPath`, the removal plan, and the --yes/TTY confirmation.
+    for (const wt of state.worktrees) {
+        if (wt.status !== 'broken')
+            continue;
+        claimed.add(wt.id);
+        const classification = classifyPath(ctx, toAbs(poolDir, wt.path));
+        const why = `return failed at '${wt.broken_step ?? 'unknown'}': ` +
+            `${(wt.broken_reason ?? 'unknown').split('\n')[0]}`;
+        candidates.push({
+            kind: classification.owned ? 'broken' : 'orphan-state',
+            id: wt.id,
+            path: classification.owned ? toAbs(poolDir, wt.path) : null,
+            tempBranch: wt.temp_branch,
+            reason: classification.owned
+                ? `${why}; ${classification.reason}`
+                : `${why}; directory is ${classification.reason} — directory left on disk`,
+        });
+    }
     // Stale pool worktrees.
     for (const wt of (0, pool_state_1.findStaleWorktrees)(state)) {
+        if (claimed.has(wt.id))
+            continue;
         claimed.add(wt.id);
         const classification = classifyPath(ctx, toAbs(poolDir, wt.path));
         if (classification.owned) {
@@ -861,7 +1173,7 @@ async function gc(opts = {}) {
         });
     }
     describeGcPlan(candidates, foreign);
-    const base = { staleIds, orphanIds, foreign, candidates, errors };
+    const base = { staleIds, orphanIds, brokenIds, foreign, candidates, errors };
     if (opts.dryRun) {
         console.error('\nDry run — nothing was removed.');
         return { ...base, removed: 0, dryRun: true, aborted: false };
@@ -894,6 +1206,8 @@ async function gc(opts = {}) {
             }
             if (c.kind === 'stale')
                 staleIds.push(c.id);
+            else if (c.kind === 'broken')
+                brokenIds.push(c.id);
             else
                 orphanIds.push(c.id);
             removed++;
@@ -909,10 +1223,12 @@ function status() {
     const gitRoot = findGitRoot();
     const poolDir = resolvePoolDirSync(gitRoot);
     const state = readState(poolDir);
+    const { foreign, broken } = reportPoolDirEntries(gitRoot, poolDir, state);
     return {
         ...(0, pool_state_1.getPoolStatus)(state),
         pool_dir: poolDir,
-        foreign: foreignInPoolDir(gitRoot, poolDir, state),
+        foreign,
+        broken,
     };
 }
 /**