@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

package/dist/resources/extensions/gsd/worktree-command.js

@@ -454,11 +454,11 @@ async function handleMerge(basePath, name, ctx, pi, targetBranch) {
             return;
         }
         // Gather merge context — full repo diff, not just .gsd/
-        const diffSummary = diffWorktreeAll(basePath, name);
-        const numstat = diffWorktreeNumstat(basePath, name);
-        const gsdDiff = getWorktreeGSDDiff(basePath, name);
-        const codeDiff = getWorktreeCodeDiff(basePath, name);
-        const commitLog = getWorktreeLog(basePath, name);
+        const diffSummary = diffWorktreeAll(basePath, name, undefined, mainBranch);
+        const numstat = diffWorktreeNumstat(basePath, name, undefined, mainBranch);
+        const gsdDiff = getWorktreeGSDDiff(basePath, name, mainBranch);
+        const codeDiff = getWorktreeCodeDiff(basePath, name, mainBranch);
+        const commitLog = getWorktreeLog(basePath, name, mainBranch);
         const totalChanges = diffSummary.added.length + diffSummary.modified.length + diffSummary.removed.length;
         if (totalChanges === 0 && !commitLog.trim()) {
             ctx.ui.notify(`Worktree ${CLR.name(name)} has no changes to merge.`, "info");
@@ -541,7 +541,7 @@ async function handleMerge(basePath, name, ctx, pi, targetBranch) {
             catch { /* non-fatal */ }
         }
         try {
-            mergeWorktreeToMain(basePath, name, commitMessage);
+            mergeWorktreeToMain(basePath, name, commitMessage, undefined, mainBranch);
             ctx.ui.notify([
                 `${CLR.ok("✓")} Merged ${CLR.name(name)} → ${CLR.branch(mainBranch)} ${CLR.muted("(deterministic squash)")}`,
                 "",

package/dist/resources/extensions/gsd/worktree-health.js

@@ -19,9 +19,9 @@ const DEFAULT_STALE_DAYS = 14;
  * @param basePath — the main project root (not the worktree path)
  * @param wt — worktree info from listWorktrees()
  * @param staleDays — days without commits to consider stale (default: 14)
+ * @param mainBranch — pre-detected main branch for batched health checks
  */
-export function getWorktreeHealth(basePath, wt, staleDays = DEFAULT_STALE_DAYS) {
-    const mainBranch = nativeDetectMainBranch(basePath);
+export function getWorktreeHealth(basePath, wt, staleDays = DEFAULT_STALE_DAYS, mainBranch = nativeDetectMainBranch(basePath)) {
     // Merge status: is the worktree branch fully contained in main?
     let mergedIntoMain = false;
     try {
@@ -84,7 +84,10 @@ export function getWorktreeHealth(basePath, wt, staleDays = DEFAULT_STALE_DAYS)
  */
 export function getAllWorktreeHealth(basePath, staleDays = DEFAULT_STALE_DAYS) {
     const worktrees = listWorktrees(basePath);
-    return worktrees.map(wt => getWorktreeHealth(basePath, wt, staleDays));
+    if (worktrees.length === 0)
+        return [];
+    const mainBranch = nativeDetectMainBranch(basePath);
+    return worktrees.map(wt => getWorktreeHealth(basePath, wt, staleDays, mainBranch));
 }
 /**
  * Format a human-readable status line for a worktree health entry.

package/dist/resources/extensions/gsd/worktree-lifecycle.js

@@ -102,6 +102,51 @@ class UserNotifiedError extends Error {
 function isSamePathPhysical(a, b) {
     return normalizeWorktreePathForCompare(a) === normalizeWorktreePathForCompare(b);
 }
+function preflightBlockedMergeReason(blockedReason) {
+    if (blockedReason?.startsWith("unmerged-conflicts")) {
+        return "preflight-unmerged-conflicts";
+    }
+    return "preflight-dirty-overlap";
+}
+/**
+ * Run a milestone merge behind the Worktree Lifecycle seam with the root-clean
+ * stash guard that protects user changes around merge.
+ *
+ * The helper owns the invariant ordering (preflight -> merge callback ->
+ * postflight on every attempted merge path) and returns the same typed result
+ * shape as `exitMilestone`. Auto closeout remains responsible for translating
+ * that result into loop policy (pause vs. stop, visible transcript
+ * preservation, projection rebuild).
+ */
+function runGuardedMilestoneMerge(request) {
+    const { merge, guard, milestoneId, notify } = request;
+    const preflight = guard.preflightCleanRoot(guard.projectRoot, milestoneId, notify);
+    if (preflight.blocked) {
+        return {
+            ok: false,
+            reason: preflightBlockedMergeReason(preflight.blockedReason),
+        };
+    }
+    let mergeError = null;
+    const exitResult = merge();
+    if (!exitResult.ok) {
+        mergeError = exitResult.cause ?? new Error(`exit ${exitResult.reason}`);
+    }
+    let postflight;
+    if (preflight.stashPushed) {
+        postflight = guard.postflightPopStash(guard.projectRoot, milestoneId, preflight.stashMarker, notify);
+    }
+    if (mergeError instanceof MergeConflictError) {
+        return { ok: false, reason: "merge-conflict", cause: mergeError, postflight };
+    }
+    if (mergeError) {
+        return { ok: false, reason: "merge-failed", cause: mergeError, postflight };
+    }
+    if (postflight?.needsManualRecovery) {
+        return { ok: false, reason: "postflight-stash-restore-failed", postflight };
+    }
+    return exitResult;
+}
 // ─── Validation ──────────────────────────────────────────────────────────
 function isValidMilestoneId(milestoneId) {
     return !/[\/\\]|\.\./.test(milestoneId);
@@ -645,7 +690,7 @@ function _mergeWorktreeModeImpl(deps, mctx) {
                 pushed: false,
             };
         }
-        const mergeResult = deps.mergeMilestoneToMain(originalBasePath, milestoneId, roadmapResolution.content);
+        const mergeResult = deps.mergeMilestone(originalBasePath, milestoneId, roadmapResolution.content);
         // #2945 Bug 3: mergeMilestoneToMain performs best-effort worktree
         // cleanup internally (step 12), but it can silently fail on Windows
         // or when the worktree directory is locked. Perform a secondary
@@ -780,7 +825,7 @@ function _mergeBranchModeImpl(deps, mctx) {
                 pushed: false,
             };
         }
-        const mergeResult = deps.mergeMilestoneToMain(worktreeBasePath, milestoneId, roadmapResolution.content);
+        const mergeResult = deps.mergeMilestone(worktreeBasePath, milestoneId, roadmapResolution.content);
         if (mergeResult.codeFilesChanged) {
             notify(`Milestone ${milestoneId} merged (branch mode).${mergeResult.pushed ? " Pushed to remote." : ""}`, "info");
         }
@@ -983,14 +1028,31 @@ export class WorktreeLifecycle {
      * With `opts.merge === false`, runs auto-commit and teardown without
      * merging to main.
      *
+     * When `opts.guardedMerge` is present with `opts.merge === true`, the
+     * lifecycle verb also owns the root-clean guard around the merge: preflight
+     * runs before the inner merge, postflight stash restore runs after every
+     * attempted merge path, and guard failures are returned as typed
+     * `ExitResult` reasons.
+     *
      * Returns a typed `ExitResult`. `MergeConflictError` is surfaced as
      * `{ ok: false, reason: "merge-conflict", cause }` instead of thrown,
-     * giving callers a typed branch for the expected failure path.
-     * Unexpected failures (filesystem, git permissions, etc.) are wrapped
-     * as `{ ok: false, reason: "teardown-failed", cause }` so callers always
+     * giving callers a typed branch for the expected failure path. Guarded merge
+     * failures surface as `preflight-dirty-overlap`,
+     * `preflight-unmerged-conflicts`, `merge-failed`, or
+     * `postflight-stash-restore-failed`. Unexpected failures (filesystem, git
+     * permissions, etc.) are wrapped as
+     * `{ ok: false, reason: "teardown-failed", cause }` so callers always
      * receive a discriminated union — no exceptions for any expected outcome.
      */
     exitMilestone(milestoneId, opts, ctx) {
+        if (opts.merge && opts.guardedMerge) {
+            return runGuardedMilestoneMerge({
+                merge: () => this.exitMilestone(milestoneId, { merge: true }, ctx),
+                guard: opts.guardedMerge,
+                milestoneId,
+                notify: ctx.notify,
+            });
+        }
         if (opts.merge) {
             try {
                 const merged = this._mergeAndExit(milestoneId, ctx);

package/dist/resources/extensions/gsd/worktree-manager.js

@@ -17,12 +17,12 @@
  *   3. merge()   — LLM-guided reconciliation of .gsd/ artifacts back to main
  *   4. remove()  — git worktree remove + branch cleanup
  */
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { join, resolve, sep } from "node:path";
 import { GSDError, GSD_PARSE_ERROR, GSD_STALE_STATE, GSD_LOCK_HELD, GSD_GIT_ERROR, GSD_MERGE_CONFLICT } from "./errors.js";
 import { logWarning } from "./workflow-logger.js";
-import { nativeBranchList, nativeBranchDelete, nativeBranchExists, nativeBranchForceReset, nativeCommit, nativeDetectMainBranch, nativeDiffContent, nativeDiffNameStatus, nativeDiffNumstat, nativeGetCurrentBranch, nativeIsAncestor, nativeLogOneline, nativeMergeSquash, nativeWorktreeAdd, nativeWorktreeList, nativeWorktreePrune, nativeWorktreeRemove, } from "./native-git-bridge.js";
+import { nativeBranchList, nativeBranchDelete, nativeBranchExists, nativeBranchForceReset, nativeCommit, nativeDetectMainBranch, nativeDiffContent, nativeDiffNameStatus, nativeDiffNumstat, nativeGetCurrentBranch, nativeIsAncestor, nativeLogOneline, nativeMergeAbort, nativeMergeSquash, nativeWorktreeAdd, nativeWorktreeList, nativeWorktreePrune, nativeWorktreeRemove, } from "./native-git-bridge.js";
 import { emitCanonicalRootRedirect } from "./worktree-telemetry.js";
 import { isGsdWorktreePath, normalizeWorktreePathForCompare, resolveWorktreeProjectRoot, } from "./worktree-root.js";
 import { MILESTONE_ID_RE } from "./milestone-ids.js";
@@ -37,6 +37,36 @@ function deleteBranchIfPresent(basePath, branch, warningPrefix) {
         logWarning("worktree", `${warningPrefix}: ${e.message}`);
     }
 }
+function cleanupFailedSquashMergeState(basePath) {
+    try {
+        nativeMergeAbort(basePath);
+    }
+    catch (e) {
+        // Squash conflicts may not create MERGE_HEAD; this is expected.
+        logWarning("worktree", `merge abort skipped: ${e.message}`);
+    }
+    try {
+        execFileSync("git", ["reset", "--merge"], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+    }
+    catch (e) {
+        logWarning("worktree", `failed squash merge reset failed: ${e.message}`);
+    }
+    const gitDir = resolveGitDir(basePath);
+    for (const marker of ["SQUASH_MSG", "MERGE_MSG", "MERGE_MODE", "MERGE_HEAD", "AUTO_MERGE"]) {
+        try {
+            const markerPath = join(gitDir, marker);
+            if (existsSync(markerPath))
+                unlinkSync(markerPath);
+        }
+        catch (e) {
+            logWarning("worktree", `failed squash merge marker cleanup failed (${marker}): ${e.message}`);
+        }
+    }
+}
 // ─── Path Helpers ──────────────────────────────────────────────────────────
 function normalizePathForComparison(path) {
     const normalized = path
@@ -133,6 +163,76 @@ function isRegisteredGitWorktreeAtPath(basePath, wtPath) {
         return false;
     }
 }
+function inspectUncommittedWorktreeState(wtPath) {
+    try {
+        const status = execFileSync("git", ["status", "--porcelain=v1", "--untracked-files=all"], { cwd: wtPath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trimEnd();
+        return { dirty: status.length > 0, status };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logWarning("worktree", `dirty worktree inspection failed for ${wtPath}: ${message}`);
+        // Fail closed: unknown state must quarantine rather than force-remove.
+        return { dirty: true, status: `git status failed: ${message}` };
+    }
+}
+function timestampForPath() {
+    return new Date().toISOString().replace(/[:.]/g, "-");
+}
+function uniqueQuarantinePath(basePath, name) {
+    const root = join(basePath, ".gsd", "quarantine", "worktrees");
+    const baseName = `${name}-${timestampForPath()}`;
+    let candidate = join(root, baseName);
+    let suffix = 2;
+    while (existsSync(candidate)) {
+        candidate = join(root, `${baseName}-${suffix}`);
+        suffix++;
+    }
+    return candidate;
+}
+function quarantineDirtyWorktree(basePath, name, branch, wtPath, status) {
+    const quarantinePath = uniqueQuarantinePath(basePath, name);
+    mkdirSync(join(basePath, ".gsd", "quarantine", "worktrees"), { recursive: true });
+    let moved = false;
+    try {
+        renameSync(wtPath, quarantinePath);
+        moved = true;
+    }
+    catch (renameErr) {
+        logWarning("worktree", `dirty worktree rename quarantine failed for ${name}: ${renameErr instanceof Error ? renameErr.message : String(renameErr)}; trying copy snapshot`);
+        try {
+            cpSync(wtPath, quarantinePath, { recursive: true, force: false, errorOnExist: true });
+        }
+        catch (copyErr) {
+            logWarning("reconcile", `Dirty worktree quarantine failed; preserving original worktree ${wtPath}: ${copyErr instanceof Error ? copyErr.message : String(copyErr)}`, { worktree: name, path: wtPath });
+            return null;
+        }
+    }
+    try {
+        const gitFile = join(quarantinePath, ".git");
+        if (existsSync(gitFile) && lstatSync(gitFile).isFile()) {
+            unlinkSync(gitFile);
+        }
+    }
+    catch (err) {
+        logWarning("worktree", `failed to remove quarantined worktree git pointer: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+        writeFileSync(join(quarantinePath, ".gsd-quarantine.json"), JSON.stringify({
+            kind: "dirty-worktree",
+            worktree: name,
+            branch,
+            originalPath: wtPath,
+            moved,
+            quarantinedAt: new Date().toISOString(),
+            status,
+        }, null, 2) + "\n", "utf-8");
+    }
+    catch (err) {
+        logWarning("worktree", `failed to write worktree quarantine metadata: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    logWarning("reconcile", `Quarantined dirty worktree ${name} at ${quarantinePath} before removal. Branch ${branch} was preserved.`, { worktree: name, path: quarantinePath, branch });
+    return quarantinePath;
+}
 /** True when `wtPath` has a git worktree checkout marker (`.git` file with gitdir pointer). */
 export function isLiveGitWorktreeCheckout(wtPath) {
     const gitPath = join(wtPath, ".git");
@@ -225,7 +325,7 @@ export function pruneEphemeralGhostWorktreeDirectories(basePath) {
     }
     return removed;
 }
-function removeStaleWorktreeDirectory(wtPath, name) {
+export function removeStaleWorktreeDirectory(wtPath, name) {
     logWarning("reconcile", `Removing stale worktree directory (not registered with git): ${wtPath}`, { worktree: name });
     try {
         rmSync(wtPath, { recursive: true, force: true });
@@ -580,6 +680,7 @@ export function removeWorktree(basePath, name, opts = {}) {
     let wtPath = worktreePath(basePath, name);
     const branch = opts.branch ?? worktreeBranchName(name);
     const { deleteBranch = true, force = true } = opts;
+    let deleteBranchAfterRemoval = deleteBranch;
     // Resolve the ACTUAL worktree path from git's worktree list.
     // The computed path may differ when .gsd/ is (or was) a symlink to an
     // external state directory — git resolves symlinks at worktree creation
@@ -634,10 +735,10 @@ export function removeWorktree(basePath, name, opts = {}) {
     }
     if (!existsSync(wtPath)) {
         nativeWorktreePrune(basePath);
-        if (deleteBranch) {
+        if (deleteBranchAfterRemoval) {
             deleteBranchIfPresent(basePath, branch, "nativeBranchDelete failed");
         }
-        return;
+        return true;
     }
     // Submodule safety (#2337): detect submodules with uncommitted changes
     // before force-removing the worktree. Force removal destroys all uncommitted
@@ -691,6 +792,27 @@ export function removeWorktree(basePath, name, opts = {}) {
             }
         }
     }
+    // Dirty-worktree quarantine (#2365): once submodule (#2337) and nested-.git
+    // (#2616) rescue have run — they commit/clean the tree first — quarantine any
+    // uncommitted state that remains instead of force-deleting it. Gate on a live
+    // git checkout so a stale local directory left behind by state-sync (which
+    // has no `.git` file and is not a registered worktree) is removed normally
+    // rather than quarantined; otherwise its branch would never be deleted and
+    // the worktree would never be unregistered (#1852).
+    if (force && resolvedPathSafe && isLiveGitWorktreeCheckout(resolvedWtPath)) {
+        const dirtyState = inspectUncommittedWorktreeState(resolvedWtPath);
+        if (dirtyState.dirty) {
+            const quarantinePath = quarantineDirtyWorktree(basePath, name, branch, resolvedWtPath, dirtyState.status);
+            if (!quarantinePath) {
+                return false;
+            }
+            deleteBranchAfterRemoval = false;
+            if (!existsSync(resolvedWtPath)) {
+                nativeWorktreePrune(basePath);
+                return true;
+            }
+        }
+    }
     // Remove worktree — only use force/rmSync when the path is safely contained
     if (resolvedPathSafe) {
         // Remove worktree: try non-force first when submodules have changes,
@@ -748,9 +870,10 @@ export function removeWorktree(basePath, name, opts = {}) {
     }
     // Prune stale entries so git knows the worktree is gone
     nativeWorktreePrune(basePath);
-    if (deleteBranch) {
+    if (deleteBranchAfterRemoval) {
         deleteBranchIfPresent(basePath, branch, "final branch delete failed");
     }
+    return true;
 }
 /**
  * Paths to skip in all worktree diffs (internal/runtime artifacts).
@@ -821,10 +944,10 @@ function parseDiffNameStatus(entries) {
  * Diff the .gsd/ directory between the worktree branch and main branch.
  * Returns a summary of added, modified, and removed GSD artifacts.
  */
-export function diffWorktreeGSD(basePath, name) {
+export function diffWorktreeGSD(basePath, name, mainBranchOverride) {
     basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = worktreeBranchName(name);
-    const mainBranch = nativeDetectMainBranch(basePath);
+    const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
     const entries = nativeDiffNameStatus(basePath, mainBranch, branch, ".gsd/", true);
     return parseDiffNameStatus(entries);
 }
@@ -834,10 +957,10 @@ export function diffWorktreeGSD(basePath, name) {
  * on main when the merge is applied. If both branches have identical
  * content, this correctly returns an empty diff.
  */
-export function diffWorktreeAll(basePath, name, branchOverride) {
+export function diffWorktreeAll(basePath, name, branchOverride, mainBranchOverride) {
     basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = branchOverride ?? worktreeBranchName(name);
-    const mainBranch = nativeDetectMainBranch(basePath);
+    const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
     const entries = nativeDiffNameStatus(basePath, mainBranch, branch);
     return parseDiffNameStatus(entries);
 }
@@ -845,10 +968,10 @@ export function diffWorktreeAll(basePath, name, branchOverride) {
  * Get per-file line addition/deletion stats for what will change on main.
  * Uses direct diff (not merge-base) so the preview matches the actual merge outcome.
  */
-export function diffWorktreeNumstat(basePath, name, branchOverride) {
+export function diffWorktreeNumstat(basePath, name, branchOverride, mainBranchOverride) {
     basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = branchOverride ?? worktreeBranchName(name);
-    const mainBranch = nativeDetectMainBranch(basePath);
+    const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
     const rawStats = nativeDiffNumstat(basePath, mainBranch, branch);
     const stats = [];
     for (const entry of rawStats) {
@@ -862,29 +985,29 @@ export function diffWorktreeNumstat(basePath, name, branchOverride) {
  * Get the full diff content for .gsd/ between the worktree branch and main.
  * Returns the raw unified diff for LLM consumption.
  */
-export function getWorktreeGSDDiff(basePath, name) {
+export function getWorktreeGSDDiff(basePath, name, mainBranchOverride) {
     basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = worktreeBranchName(name);
-    const mainBranch = nativeDetectMainBranch(basePath);
+    const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
     return nativeDiffContent(basePath, mainBranch, branch, ".gsd/", undefined, true);
 }
 /**
  * Get the full diff content for non-.gsd/ files between the worktree branch and main.
  * Returns the raw unified diff for LLM consumption.
  */
-export function getWorktreeCodeDiff(basePath, name) {
+export function getWorktreeCodeDiff(basePath, name, mainBranchOverride) {
     basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = worktreeBranchName(name);
-    const mainBranch = nativeDetectMainBranch(basePath);
+    const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
     return nativeDiffContent(basePath, mainBranch, branch, undefined, ".gsd/", true);
 }
 /**
  * Get commit log for the worktree branch since it diverged from main.
  */
-export function getWorktreeLog(basePath, name) {
+export function getWorktreeLog(basePath, name, mainBranchOverride) {
     basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = worktreeBranchName(name);
-    const mainBranch = nativeDetectMainBranch(basePath);
+    const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
     const entries = nativeLogOneline(basePath, mainBranch, branch);
     return entries.map(e => `${e.sha} ${e.message}`).join("\n");
 }
@@ -893,16 +1016,28 @@ export function getWorktreeLog(basePath, name) {
  * Must be called from the main working tree (not the worktree itself).
  * Returns the merge commit message.
  */
-export function mergeWorktreeToMain(basePath, name, commitMessage, branchOverride) {
+export function mergeWorktreeToMain(basePath, name, commitMessage, branchOverride, mainBranchOverride) {
     basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = branchOverride ?? worktreeBranchName(name);
-    const mainBranch = nativeDetectMainBranch(basePath);
+    const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
     const current = nativeGetCurrentBranch(basePath);
     if (current !== mainBranch) {
         throw new GSDError(GSD_GIT_ERROR, `Must be on ${mainBranch} to merge. Currently on ${current}.`);
     }
     const result = nativeMergeSquash(basePath, branch);
     if (!result.success) {
+        const dirtyWorkingTree = result.conflicts.includes("__dirty_working_tree__");
+        if (!dirtyWorkingTree) {
+            cleanupFailedSquashMergeState(basePath);
+        }
+        if (!dirtyWorkingTree && branch.startsWith("milestone/")) {
+            try {
+                removeWorktree(basePath, name, { branch, deleteBranch: true, force: true });
+            }
+            catch (e) {
+                logWarning("worktree", `failed milestone branch cleanup after squash merge failure: ${e.message}`);
+            }
+        }
         throw new GSDError(GSD_MERGE_CONFLICT, `Merge conflicts detected in: ${result.conflicts.join(", ")}`);
     }
     nativeCommit(basePath, commitMessage);

package/dist/resources/extensions/gsd/worktree-safety.js

@@ -5,7 +5,7 @@ import { execFileSync } from "node:child_process";
 import { join, resolve } from "node:path";
 import { normalizeWorktreePathForCompare } from "./worktree-root.js";
 import { worktreesDirs } from "./worktree-placement.js";
-import { listWorktrees } from "./worktree-manager.js";
+import { listWorktrees, removeStaleWorktreeDirectory } from "./worktree-manager.js";
 import { getCurrentBranch } from "./worktree.js";
 const fsOnlyDeps = {
     existsSync,
@@ -25,6 +25,7 @@ const defaultDeps = {
             stdio: "pipe",
         });
     },
+    removeStaleWorktreeDirectory,
     getCurrentBranch,
 };
 function isValidMilestoneId(milestoneId) {
@@ -40,7 +41,6 @@ function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
 export function createWorktreeSafetyModule(deps = defaultDeps) {
-    const unregisteredRecoveryFailed = new Set();
     return {
         validateUnitRoot(input) {
             if (input.writeScope === "planning-only") {
@@ -98,30 +98,39 @@ export function createWorktreeSafetyModule(deps = defaultDeps) {
                     return failure("worktree-git-probe-failed", `Unable to list registered worktrees for project root ${projectRoot}.`, "Recover or recreate the milestone worktree before dispatching the source-writing Unit.", { projectRoot, error: errorMessage(error) });
                 }
                 if (registered && !registered.some((worktree) => samePath(worktree.path, unitRoot))) {
-                    const wasPreviouslyTracked = unregisteredRecoveryFailed.has(unitRoot);
                     let attemptedPrune = false;
-                    if (!wasPreviouslyTracked && deps.pruneRegisteredWorktrees) {
+                    if (deps.pruneRegisteredWorktrees) {
                         attemptedPrune = true;
                         try {
                             deps.pruneRegisteredWorktrees(projectRoot);
                             const rechecked = deps.listRegisteredWorktrees?.(projectRoot);
                             if (rechecked?.some((worktree) => samePath(worktree.path, unitRoot))) {
-                                unregisteredRecoveryFailed.delete(unitRoot);
                                 registered = rechecked;
                             }
-                            else {
-                                unregisteredRecoveryFailed.add(unitRoot);
-                            }
                         }
                         catch (error) {
-                            unregisteredRecoveryFailed.add(unitRoot);
                             return failure("worktree-git-probe-failed", `Unable to recover unregistered worktree root ${unitRoot}.`, "Run 'git worktree prune', then recreate or re-register the milestone worktree before dispatching the source-writing Unit.", { projectRoot, unitRoot, error: errorMessage(error) });
                         }
                     }
                     if (!registered?.some((worktree) => samePath(worktree.path, unitRoot))) {
-                        return failure("worktree-unregistered", `Worktree root ${unitRoot} is not registered with git worktree list.`, attemptedPrune || wasPreviouslyTracked
+                        // The directory exists on disk with a .git marker but git no longer
+                        // tracks it as a worktree (e.g. a prior removeWorktree crash left the
+                        // directory while `git worktree prune` cleaned the registry). Remove
+                        // the orphaned directory — the same cleanup createWorktree performs —
+                        // so the next dispatch recreates the milestone worktree from scratch
+                        // instead of looping forever on worktree-unregistered (#803, #590).
+                        if (deps.removeStaleWorktreeDirectory) {
+                            try {
+                                deps.removeStaleWorktreeDirectory(unitRoot, milestoneId);
+                                return failure("worktree-missing", `Worktree root ${unitRoot} was not registered with git; removed the orphaned directory so it can be recreated.`, "Recreate the milestone worktree before dispatching the source-writing Unit. Auto-mode recreates it automatically on the next dispatch.", { unitRoot, attemptedPrune, removedStaleDirectory: true });
+                            }
+                            catch (error) {
+                                return failure("worktree-unregistered", `Worktree root ${unitRoot} is not registered with git worktree list and the orphaned directory could not be removed.`, "Remove the orphaned worktree directory manually (it may be locked by another process), then recreate or re-register the milestone worktree before dispatching the source-writing Unit.", { unitRoot, attemptedPrune, removedStaleDirectory: false, error: errorMessage(error) });
+                            }
+                        }
+                        return failure("worktree-unregistered", `Worktree root ${unitRoot} is not registered with git worktree list.`, attemptedPrune
                             ? "Worktree recovery was attempted but the root is still unregistered. Recreate or re-register the milestone worktree before dispatching the source-writing Unit."
-                            : "Run 'git worktree prune'. If still unregistered, recreate or re-register the milestone worktree before dispatching the source-writing Unit.", { unitRoot, attemptedPrune, trackedAsFailed: unregisteredRecoveryFailed.has(unitRoot) });
+                            : "Run 'git worktree prune'. If still unregistered, recreate or re-register the milestone worktree before dispatching the source-writing Unit.", { unitRoot, attemptedPrune });
                     }
                 }
             }

package/dist/resources/extensions/mcp-client/manager.js

@@ -355,14 +355,14 @@ function normalizeRawServerConfig(name, config, source) {
         cwd: typeof config.cwd === "string" ? config.cwd : undefined,
         headers,
         oauth: config.oauth && typeof config.oauth === "object" ? config.oauth : undefined,
-        envWarnings: collectEnvWarnings([
+        envWarnings: collectMcpEnvWarnings([
             ["url", url],
             ...Object.entries(env ?? {}).map(([key, value]) => [`env.${key}`, value]),
             ...Object.entries(headers ?? {}).map(([key, value]) => [`headers.${key}`, value]),
         ]),
     };
 }
-function detectTransport(config) {
+export function detectTransport(config) {
     const type = typeof config.type === "string" ? config.type.toLowerCase() : undefined;
     if (type && type !== "stdio" && type !== "http")
         return "unsupported";
@@ -397,7 +397,7 @@ function serializeServerInput(input) {
         _gsdImportedFrom: input.importedFrom,
     });
 }
-function collectEnvWarnings(values) {
+export function collectMcpEnvWarnings(values) {
     const warnings = [];
     for (const [label, value] of values) {
         if (!value)