@ai-dossier/worktree-pool 0.4.0 → 0.5.1

package/dist/pool-actions.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPoolFileConfig = readPoolFileConfig;
 exports.resolvePoolDir = resolvePoolDir;
 exports.replenish = replenish;
 exports.claim = claim;
@@ -40,15 +41,18 @@ exports.returnWorktree = returnWorktree;
 exports.refresh = refresh;
 exports.gc = gc;
 exports.status = status;
+exports.detect = detect;
 exports.init = init;
 const node_child_process_1 = require("node:child_process");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const readline = __importStar(require("node:readline"));
 const pool_state_1 = require("./pool-state");
+const project_env_1 = require("./project-env");
 const types_1 = require("./types");
 const LOCK_TIMEOUT_MS = 10_000;
 const LOCK_RETRY_MS = 200;
+const WARM_COMMAND_TIMEOUT_MS = 300_000;
 const POOL_CONFIG_FILE = '.worktree-pool.json';
 // --- Git helpers ---
 function findGitRoot() {
@@ -67,25 +71,49 @@ function git(args, opts) {
 function getConfigPath(gitRoot) {
     return path.join(gitRoot, POOL_CONFIG_FILE);
 }
-function readPoolDirConfig(gitRoot) {
+/**
+ * Read `.worktree-pool.json` from the repo root. Missing or corrupt files fall
+ * back to defaults. `pool_dir`, when set, is resolved to an absolute path.
+ */
+function readPoolFileConfig(gitRoot) {
     const configPath = getConfigPath(gitRoot);
     if (!fs.existsSync(configPath))
-        return null;
+        return (0, pool_state_1.normalizePoolFileConfig)({});
+    let raw;
     try {
-        const raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-        if (raw.pool_dir && typeof raw.pool_dir === 'string') {
-            return { pool_dir: path.resolve(gitRoot, raw.pool_dir) };
-        }
+        raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
     }
     catch {
         // corrupt config — treat as absent
+        return (0, pool_state_1.normalizePoolFileConfig)({});
+    }
+    const cfg = (0, pool_state_1.normalizePoolFileConfig)(raw);
+    if (cfg.pool_dir) {
+        cfg.pool_dir = path.resolve(gitRoot, cfg.pool_dir);
     }
-    return null;
+    return cfg;
 }
+function readPoolDirConfig(gitRoot) {
+    const cfg = readPoolFileConfig(gitRoot);
+    return cfg.pool_dir ? { pool_dir: cfg.pool_dir } : null;
+}
+/** Persist `pool_dir` without clobbering other keys in the config file. */
 function writePoolDirConfig(gitRoot, poolDir) {
     const configPath = getConfigPath(gitRoot);
-    const relPoolDir = path.relative(gitRoot, poolDir);
-    fs.writeFileSync(configPath, `${JSON.stringify({ pool_dir: relPoolDir }, null, 2)}\n`);
+    let existing = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                existing = parsed;
+            }
+        }
+        catch {
+            // corrupt config — overwrite it
+        }
+    }
+    existing.pool_dir = path.relative(gitRoot, poolDir);
+    fs.writeFileSync(configPath, `${JSON.stringify(existing, null, 2)}\n`);
 }
 function discoverPoolDirFromWorktrees(gitRoot) {
     try {
@@ -289,28 +317,176 @@ function copyEnvFiles(gitRoot, targetDir) {
     }
     walk(gitRoot, 0, '');
 }
+// --- Warm-up commands ---
+/**
+ * Run the project's warm-up commands (install + build) inside a worktree.
+ *
+ * Commands come from `warm_commands` in `.worktree-pool.json` when set,
+ * otherwise from package-manager detection. They run in
+ * `<worktree>/<project_subdir>` so nested monorepo package roots work.
+ */
+function runWarmCommands(worktreeAbsPath, cfg) {
+    const projectDir = (0, project_env_1.resolveProjectDir)(worktreeAbsPath, cfg.project_subdir);
+    for (const cmd of (0, project_env_1.resolveWarmCommands)(projectDir, cfg)) {
+        const [bin, ...args] = cmd;
+        if (!bin)
+            continue;
+        (0, node_child_process_1.execFileSync)(bin, args, {
+            cwd: projectDir,
+            stdio: 'pipe',
+            timeout: WARM_COMMAND_TIMEOUT_MS,
+        });
+    }
+}
+/**
+ * Repo-root-relative lockfile path for a worktree, used to decide whether a
+ * range of upstream commits invalidates the installed dependencies.
+ */
+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);
+}
+// --- Ownership / provenance ---
+//
+// The pool directory is routinely shared with worktrees a developer made by
+// hand (imboard-ai/ai-dossier#438). Every path that deletes a directory or a
+// branch goes through this layer first; nothing is removed on the strength of
+// its location alone.
+/** Resolve symlinks so paths from git and from config compare equal. */
+function realpathOrSelf(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/**
+ * Absolute worktree path -> checked-out branch, from `git worktree list`.
+ * A registered worktree with a detached HEAD maps to `null`.
+ */
+function listWorktreeBranches(gitRoot) {
+    const map = new Map();
+    let output;
+    try {
+        output = git(['worktree', 'list', '--porcelain'], { cwd: gitRoot });
+    }
+    catch {
+        return map;
+    }
+    let current = null;
+    for (const raw of output.split('\n')) {
+        const line = raw.trimEnd();
+        if (line.startsWith('worktree ')) {
+            current = realpathOrSelf(line.slice('worktree '.length));
+            map.set(current, null);
+        }
+        else if (current !== null && line.startsWith('branch ')) {
+            map.set(current, line.slice('branch '.length).replace(/^refs\/heads\//, ''));
+        }
+        else if (line === '') {
+            current = null;
+        }
+    }
+    return map;
+}
+function buildOwnershipContext(gitRoot, poolDir, state) {
+    return {
+        gitRoot,
+        poolDir,
+        state: state ?? readState(poolDir),
+        branches: listWorktreeBranches(gitRoot),
+    };
+}
+/** Classify one absolute path against the pool's provenance rules. */
+function classifyPath(ctx, absPath) {
+    const resolved = realpathOrSelf(absPath);
+    const name = path.basename(resolved);
+    const poolDirReal = realpathOrSelf(ctx.poolDir);
+    if (path.dirname(resolved) !== poolDirReal) {
+        return {
+            name,
+            path: resolved,
+            branch: ctx.branches.get(resolved) ?? null,
+            provenance: 'foreign',
+            owned: false,
+            reason: `outside the pool directory (${poolDirReal})`,
+        };
+    }
+    const registered = ctx.branches.has(resolved);
+    const classification = (0, pool_state_1.classifyPoolDirEntry)({
+        name,
+        branch: ctx.branches.get(resolved) ?? null,
+        registered,
+        existsOnDisk: fs.existsSync(resolved),
+        stateEntry: ctx.state.worktrees.find((w) => w.path === name) ?? null,
+    });
+    return {
+        name,
+        path: resolved,
+        branch: ctx.branches.get(resolved) ?? null,
+        ...classification,
+    };
+}
+/** Every directory inside the pool directory, classified. */
+function scanPoolDir(ctx) {
+    if (!fs.existsSync(ctx.poolDir))
+        return [];
+    const reports = [];
+    for (const entry of fs.readdirSync(ctx.poolDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') {
+            continue;
+        }
+        reports.push(classifyPath(ctx, path.join(ctx.poolDir, entry.name)));
+    }
+    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);
+}
 // --- Destroy helper ---
-function destroyWorktree(gitRoot, tempBranch, absPath) {
+/**
+ * Remove a worktree the pool created. Refuses anything it cannot prove is the
+ * pool's own — the caller is expected to report the refusal, not swallow it.
+ */
+function destroyWorktree(ctx, tempBranch, absPath) {
+    const classification = classifyPath(ctx, absPath);
+    if (!classification.owned) {
+        throw new Error(`Refusing to remove ${absPath}: ${classification.reason}. ` +
+            'The worktree pool only removes worktrees it created.');
+    }
     try {
-        git(['worktree', 'remove', absPath, '--force'], { cwd: gitRoot });
+        git(['worktree', 'remove', absPath, '--force'], { cwd: ctx.gitRoot });
     }
     catch {
         fs.rmSync(absPath, { recursive: true, force: true });
     }
+    deletePoolTempBranch(ctx.gitRoot, tempBranch);
+    git(['worktree', 'prune'], { cwd: ctx.gitRoot });
+}
+/**
+ * Delete a `pool/spare-*` branch. Any other ref is left alone — a corrupt or
+ * hand-edited `.pool-state.json` must not be able to delete a real branch.
+ */
+function deletePoolTempBranch(gitRoot, branch) {
+    if (!(0, pool_state_1.isPoolTempBranch)(branch))
+        return;
     try {
-        git(['branch', '-D', tempBranch], { cwd: gitRoot });
+        git(['branch', '-D', branch], { cwd: gitRoot });
     }
     catch {
         // branch may not exist
     }
-    git(['worktree', 'prune'], { cwd: gitRoot });
 }
 // --- Public operations ---
 async function replenish(count, _parallel = false) {
     const gitRoot = findGitRoot();
+    const cfg = readPoolFileConfig(gitRoot);
     const poolDir = await resolvePoolDir(gitRoot, { interactive: true });
     fs.mkdirSync(poolDir, { recursive: true });
-    git(['fetch', 'origin'], { cwd: gitRoot });
+    git(['fetch', (0, pool_state_1.remoteForBaseRef)(cfg.base_ref)], { cwd: gitRoot });
     let toCreate;
     if (count !== undefined) {
         toCreate = count;
@@ -329,7 +505,7 @@ async function replenish(count, _parallel = false) {
         const absWorktreePath = toAbs(poolDir, id);
         const tempBranch = `pool/spare-${id}`;
         const baseCommit = withLock(poolDir, (state) => {
-            const sha = git(['rev-parse', 'origin/main'], { cwd: gitRoot });
+            const sha = git(['rev-parse', cfg.base_ref], { cwd: gitRoot });
             const wt = {
                 id,
                 path: id,
@@ -343,7 +519,7 @@ async function replenish(count, _parallel = false) {
             return { state: (0, pool_state_1.addWorktree)(state, wt), result: sha };
         });
         try {
-            git(['branch', tempBranch, 'origin/main'], { cwd: gitRoot });
+            git(['branch', tempBranch, cfg.base_ref], { cwd: gitRoot });
             git(['worktree', 'add', absWorktreePath, tempBranch], {
                 cwd: gitRoot,
             });
@@ -352,16 +528,7 @@ async function replenish(count, _parallel = false) {
                 result: undefined,
             }));
             copyEnvFiles(gitRoot, absWorktreePath);
-            (0, node_child_process_1.execFileSync)('npm', ['install'], {
-                cwd: absWorktreePath,
-                stdio: 'pipe',
-                timeout: 300_000,
-            });
-            (0, node_child_process_1.execFileSync)('make', ['build-core', 'build-mcp', 'build-cli'], {
-                cwd: absWorktreePath,
-                stdio: 'pipe',
-                timeout: 300_000,
-            });
+            runWarmCommands(absWorktreePath, cfg);
             withLock(poolDir, (state) => ({
                 state: (0, pool_state_1.updateWorktree)(state, id, {
                     status: 'warm',
@@ -376,10 +543,12 @@ async function replenish(count, _parallel = false) {
             const msg = err instanceof Error ? err.message : String(err);
             errors.push(`Failed to create ${id}: ${msg}`);
             try {
-                destroyWorktree(gitRoot, tempBranch, absWorktreePath);
+                destroyWorktree(buildOwnershipContext(gitRoot, poolDir), tempBranch, absWorktreePath);
             }
-            catch {
-                // best effort
+            catch (cleanupErr) {
+                // A refusal here means the path is not provably ours — say so rather
+                // than deleting it anyway.
+                errors.push(`Could not clean up ${id}: ${cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)}`);
             }
             withLock(poolDir, (state) => ({
                 state: (0, pool_state_1.removeWorktree)(state, id),
@@ -396,6 +565,7 @@ async function replenish(count, _parallel = false) {
 }
 function claim(issue, branch) {
     const gitRoot = findGitRoot();
+    const cfg = readPoolFileConfig(gitRoot);
     const poolDir = resolvePoolDirSync(gitRoot);
     const result = withLock(poolDir, (state) => {
         const claimed = (0, pool_state_1.claimWorktree)(state, issue, branch);
@@ -411,31 +581,23 @@ function claim(issue, branch) {
     const newAbsPath = toAbs(poolDir, branchDir);
     try {
         // Check freshness
-        const currentMain = git(['rev-parse', 'origin/main'], { cwd: gitRoot });
-        if (worktree.base_commit !== currentMain) {
+        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}..origin/main`], {
+                const diff = git(['diff', '--name-only', `${worktree.base_commit}..${cfg.base_ref}`], {
                     cwd: gitRoot,
                 });
-                lockChanged = diff.includes('package-lock.json');
+                lockChanged = (0, project_env_1.lockfileChangedInDiff)(diff, lockfilePath);
             }
             catch {
                 lockChanged = true;
             }
-            git(['fetch', 'origin'], { cwd: absPath });
-            git(['reset', '--hard', 'origin/main'], { cwd: absPath });
+            git(['fetch', (0, pool_state_1.remoteForBaseRef)(cfg.base_ref)], { cwd: absPath });
+            git(['reset', '--hard', cfg.base_ref], { cwd: absPath });
             if (lockChanged) {
-                (0, node_child_process_1.execFileSync)('npm', ['install'], {
-                    cwd: absPath,
-                    stdio: 'pipe',
-                    timeout: 300_000,
-                });
-                (0, node_child_process_1.execFileSync)('make', ['build-core', 'build-mcp', 'build-cli'], {
-                    cwd: absPath,
-                    stdio: 'pipe',
-                    timeout: 300_000,
-                });
+                runWarmCommands(absPath, cfg);
             }
         }
         // Create issue branch
@@ -478,6 +640,7 @@ function claim(issue, branch) {
 }
 function returnWorktree(worktreePath) {
     const gitRoot = findGitRoot();
+    const cfg = readPoolFileConfig(gitRoot);
     const poolDir = resolvePoolDirSync(gitRoot);
     const absPath = path.resolve(worktreePath);
     const newId = (0, types_1.generateId)();
@@ -495,8 +658,8 @@ function returnWorktree(worktreePath) {
         };
     });
     try {
-        git(['fetch', 'origin'], { cwd: absPath });
-        git(['checkout', '-b', newTempBranch, 'origin/main'], { cwd: absPath });
+        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 {
@@ -507,31 +670,26 @@ function returnWorktree(worktreePath) {
             }
         }
         if (absPath !== newAbsPath) {
+            if (fs.existsSync(newAbsPath)) {
+                throw new Error(`Recycle target already exists: ${newAbsPath}`);
+            }
             fs.renameSync(absPath, newAbsPath);
             git(['worktree', 'repair'], { cwd: gitRoot });
         }
-        const currentMain = git(['rev-parse', 'origin/main'], { 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}..origin/main`], {
+            const diff = git(['diff', '--name-only', `${entry.base_commit}..${cfg.base_ref}`], {
                 cwd: gitRoot,
             });
-            lockChanged = diff.includes('package-lock.json');
+            lockChanged = (0, project_env_1.lockfileChangedInDiff)(diff, lockfilePath);
         }
         catch {
             lockChanged = true;
         }
         if (lockChanged) {
-            (0, node_child_process_1.execFileSync)('npm', ['install'], {
-                cwd: newAbsPath,
-                stdio: 'pipe',
-                timeout: 300_000,
-            });
-            (0, node_child_process_1.execFileSync)('make', ['build-core', 'build-mcp', 'build-cli'], {
-                cwd: newAbsPath,
-                stdio: 'pipe',
-                timeout: 300_000,
-            });
+            runWarmCommands(newAbsPath, cfg);
         }
         withLock(poolDir, (state) => ({
             state: (0, pool_state_1.updateWorktree)(state, entry.id, {
@@ -539,7 +697,7 @@ function returnWorktree(worktreePath) {
                 path: newId,
                 status: 'warm',
                 temp_branch: newTempBranch,
-                base_commit: currentMain,
+                base_commit: currentBase,
                 warmed_at: new Date().toISOString(),
                 assigned_to_issue: null,
                 assigned_branch: null,
@@ -548,48 +706,56 @@ function returnWorktree(worktreePath) {
         }));
     }
     catch (err) {
-        try {
-            destroyWorktree(gitRoot, entry.temp_branch, absPath);
-        }
-        catch {
-            // best effort
-        }
-        try {
-            destroyWorktree(gitRoot, newTempBranch, newAbsPath);
-        }
-        catch {
-            // best effort
+        // 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,
         }));
-        throw new Error(`Recycle failed (destroyed worktree): ${err instanceof Error ? err.message : String(err)}`);
+        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}`);
     }
 }
 function refresh() {
     const gitRoot = findGitRoot();
+    const cfg = readPoolFileConfig(gitRoot);
     const poolDir = resolvePoolDirSync(gitRoot);
-    git(['fetch', 'origin'], { cwd: gitRoot });
+    git(['fetch', (0, pool_state_1.remoteForBaseRef)(cfg.base_ref)], { cwd: gitRoot });
     const state = readState(poolDir);
+    const ctx = buildOwnershipContext(gitRoot, poolDir, state);
     const warmWorktrees = state.worktrees.filter((w) => w.status === 'warm');
     let refreshed = 0;
+    const skipped = [];
     const errors = [];
     for (const wt of warmWorktrees) {
         const absPath = toAbs(poolDir, wt.path);
+        // `git reset --hard` destroys uncommitted work, so it is only ever pointed
+        // at a directory that still looks like the pool worktree state describes.
+        const classification = classifyPath(ctx, absPath);
+        if (!classification.owned) {
+            skipped.push(classification);
+            continue;
+        }
         try {
-            git(['fetch', 'origin'], { cwd: absPath });
-            git(['reset', '--hard', 'origin/main'], { cwd: absPath });
-            (0, node_child_process_1.execFileSync)('npm', ['install'], {
-                cwd: absPath,
-                stdio: 'pipe',
-                timeout: 300_000,
-            });
-            (0, node_child_process_1.execFileSync)('make', ['build-core', 'build-mcp', 'build-cli'], {
-                cwd: absPath,
-                stdio: 'pipe',
-                timeout: 300_000,
-            });
+            git(['fetch', (0, pool_state_1.remoteForBaseRef)(cfg.base_ref)], { cwd: absPath });
+            git(['reset', '--hard', cfg.base_ref], { cwd: absPath });
+            runWarmCommands(absPath, cfg);
             const newSha = git(['rev-parse', 'HEAD'], { cwd: absPath });
             withLock(poolDir, (state) => ({
                 state: (0, pool_state_1.updateWorktree)(state, wt.id, {
@@ -604,88 +770,168 @@ function refresh() {
             errors.push(`Failed to refresh ${wt.id}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    return { refreshed, errors };
+    return { refreshed, skipped, errors };
 }
-function gc() {
+function describeGcPlan(candidates, foreign) {
+    if (candidates.length === 0) {
+        console.error('Nothing to remove.');
+    }
+    else {
+        console.error(`Will remove ${candidates.length} item(s):`);
+        for (const c of candidates) {
+            const target = c.path ?? '(state entry only)';
+            console.error(`  [${c.kind}] ${target}`);
+            console.error(`      ${c.reason}`);
+        }
+    }
+    if (foreign.length > 0) {
+        console.error(`\nForeign, skipped (${foreign.length}) — not created by the pool:`);
+        for (const f of foreign) {
+            console.error(`  ${f.path}`);
+            console.error(`      ${f.reason}`);
+        }
+    }
+}
+async function gc(opts = {}) {
     const gitRoot = findGitRoot();
     const poolDir = resolvePoolDirSync(gitRoot);
     const errors = [];
     const staleIds = [];
     const orphanIds = [];
     let removed = 0;
-    // Get disk state — directory names inside poolDir
-    const existingNames = new Set();
-    if (fs.existsSync(poolDir)) {
-        for (const entry of fs.readdirSync(poolDir, { withFileTypes: true })) {
-            if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
-                existingNames.add(entry.name);
-            }
-        }
-    }
     const state = readState(poolDir);
-    // Remove stale worktrees
-    const stale = (0, pool_state_1.findStaleWorktrees)(state);
-    for (const wt of stale) {
-        try {
-            destroyWorktree(gitRoot, wt.temp_branch, toAbs(poolDir, wt.path));
-            withLock(poolDir, (s) => ({
-                state: (0, pool_state_1.removeWorktree)(s, wt.id),
-                result: undefined,
-            }));
-            staleIds.push(wt.id);
-            removed++;
+    const ctx = buildOwnershipContext(gitRoot, poolDir, state);
+    const onDisk = scanPoolDir(ctx);
+    const foreign = onDisk.filter((e) => !e.owned);
+    const ownedNames = new Set(onDisk.filter((e) => e.owned).map((e) => e.name));
+    const candidates = [];
+    const claimed = new Set();
+    // Stale pool worktrees.
+    for (const wt of (0, pool_state_1.findStaleWorktrees)(state)) {
+        claimed.add(wt.id);
+        const classification = classifyPath(ctx, toAbs(poolDir, wt.path));
+        if (classification.owned) {
+            candidates.push({
+                kind: 'stale',
+                id: wt.id,
+                path: toAbs(poolDir, wt.path),
+                tempBranch: wt.temp_branch,
+                reason: `stale past ${state.config.stale_after_hours}h (warmed ${wt.warmed_at}); ${classification.reason}`,
+            });
         }
-        catch (err) {
-            errors.push(`Failed to remove stale ${wt.id}: ${err instanceof Error ? err.message : String(err)}`);
+        else {
+            // The directory this row points at is no longer ours. Drop the row so the
+            // pool is not wedged, but leave the directory alone.
+            candidates.push({
+                kind: 'orphan-state',
+                id: wt.id,
+                path: null,
+                tempBranch: wt.temp_branch,
+                reason: `stale state entry for ${wt.path}, which is ${classification.reason} — directory left on disk`,
+            });
         }
     }
-    // Reconcile orphans — compare relative path names
+    // State rows whose directory is gone (or was never ours).
+    for (const wt of state.worktrees) {
+        if (claimed.has(wt.id))
+            continue;
+        if (ownedNames.has(wt.path))
+            continue;
+        claimed.add(wt.id);
+        const classification = classifyPath(ctx, toAbs(poolDir, wt.path));
+        candidates.push({
+            kind: 'orphan-state',
+            id: wt.id,
+            path: null,
+            tempBranch: wt.temp_branch,
+            reason: `state entry for ${wt.path}: ${classification.reason}`,
+        });
+    }
+    // Pool-created directories with no state row.
     const stateNames = new Set(state.worktrees.map((w) => w.path));
-    const inStateNotOnDisk = state.worktrees.filter((w) => !existingNames.has(w.path));
-    const onDiskNotInState = [...existingNames].filter((name) => !stateNames.has(name));
-    for (const wt of inStateNotOnDisk) {
-        try {
-            withLock(poolDir, (s) => ({
-                state: (0, pool_state_1.removeWorktree)(s, wt.id),
-                result: undefined,
-            }));
-            try {
-                git(['branch', '-D', wt.temp_branch], { cwd: gitRoot });
-            }
-            catch {
-                // branch may not exist
-            }
-            orphanIds.push(wt.id);
-            removed++;
+    for (const entry of onDisk) {
+        if (!entry.owned || stateNames.has(entry.name))
+            continue;
+        candidates.push({
+            kind: 'orphan-disk',
+            id: entry.name,
+            path: entry.path,
+            tempBranch: entry.branch,
+            reason: entry.reason,
+        });
+    }
+    describeGcPlan(candidates, foreign);
+    const base = { staleIds, orphanIds, foreign, candidates, errors };
+    if (opts.dryRun) {
+        console.error('\nDry run — nothing was removed.');
+        return { ...base, removed: 0, dryRun: true, aborted: false };
+    }
+    if (candidates.length > 0 && !opts.yes) {
+        const interactive = opts.interactive ?? Boolean(process.stdin.isTTY);
+        if (!interactive) {
+            console.error('\nRefusing to remove without confirmation. Re-run with --yes (or --dry-run).');
+            return { ...base, removed: 0, dryRun: false, aborted: true };
         }
-        catch (err) {
-            errors.push(`Failed to clean orphan state ${wt.id}: ${err instanceof Error ? err.message : String(err)}`);
+        const answer = await promptUser(`\nRemove ${candidates.length} item(s)? [y/N]: `);
+        if (!/^y(es)?$/i.test(answer)) {
+            console.error('Aborted — nothing was removed.');
+            return { ...base, removed: 0, dryRun: false, aborted: true };
         }
     }
-    for (const dirName of onDiskNotInState) {
+    for (const c of candidates) {
         try {
-            const absPath = toAbs(poolDir, dirName);
-            try {
-                git(['worktree', 'remove', absPath, '--force'], { cwd: gitRoot });
+            if (c.path !== null) {
+                destroyWorktree(ctx, c.tempBranch, c.path);
             }
-            catch {
-                fs.rmSync(absPath, { recursive: true, force: true });
+            else {
+                deletePoolTempBranch(gitRoot, c.tempBranch);
+            }
+            if (c.kind !== 'orphan-disk') {
+                withLock(poolDir, (s) => ({
+                    state: (0, pool_state_1.removeWorktree)(s, c.id),
+                    result: undefined,
+                }));
             }
-            orphanIds.push(dirName);
+            if (c.kind === 'stale')
+                staleIds.push(c.id);
+            else
+                orphanIds.push(c.id);
             removed++;
         }
         catch (err) {
-            errors.push(`Failed to clean orphan disk ${dirName}: ${err instanceof Error ? err.message : String(err)}`);
+            errors.push(`Failed to remove ${c.path ?? c.id}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
     git(['worktree', 'prune'], { cwd: gitRoot });
-    return { removed, staleIds, orphanIds, errors };
+    return { ...base, removed, dryRun: false, aborted: false };
 }
 function status() {
     const gitRoot = findGitRoot();
     const poolDir = resolvePoolDirSync(gitRoot);
     const state = readState(poolDir);
-    return { ...(0, pool_state_1.getPoolStatus)(state), pool_dir: poolDir };
+    return {
+        ...(0, pool_state_1.getPoolStatus)(state),
+        pool_dir: poolDir,
+        foreign: foreignInPoolDir(gitRoot, poolDir, state),
+    };
+}
+/**
+ * Detect the project environment for `dir`, or — when omitted — for this
+ * repo's package root (git root plus `project_subdir` from the pool config).
+ */
+function detect(dir) {
+    if (dir) {
+        return (0, project_env_1.detectProjectEnv)(path.resolve(dir));
+    }
+    let gitRoot;
+    try {
+        gitRoot = findGitRoot();
+    }
+    catch {
+        return (0, project_env_1.detectProjectEnv)(process.cwd());
+    }
+    const cfg = readPoolFileConfig(gitRoot);
+    return (0, project_env_1.detectProjectEnv)((0, project_env_1.resolveProjectDir)(gitRoot, cfg.project_subdir));
 }
 async function init() {
     const gitRoot = findGitRoot();