@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

package/src/resources/extensions/gsd/worktree-git-recovery.ts

@@ -0,0 +1,314 @@
+// Project/App: gsd-pi
+// File Purpose: Git checkout/stash/merge-state recovery primitives for worktree operations.
+
+/**
+ * Worktree Git Recovery — the recurring-bug hot spot, in one place.
+ *
+ * Owns the verbs that recover a repository from interrupted or conflicting
+ * git operations during worktree transitions:
+ *
+ *   - `checkoutBranchWithStashGuard` — branch switch with stash protection,
+ *     including the stash-pop EEXIST collision recovery for untracked files
+ *     (force-checkout + targeted stash drop; #645 broadened it beyond `.gsd/`,
+ *     guarded by "no non-.gsd unmerged entries remain").
+ *   - `removeMergeStateFiles` — clears SQUASH_MSG / MERGE_HEAD / etc. left by
+ *     a failed merge so subsequent merges don't fail on stale state.
+ *   - `cleanupConflictState` — merge-abort + index reset + state-file cleanup
+ *     after a conflicted (including squash) merge.
+ *   - stash helpers (`popStashByRef`, `stashRefFromError`,
+ *     `stashAlreadyExistsFilesFromError`, `gsdJsonlFilesWithConflictMarkers`)
+ *     used by the merge pipeline in auto-worktree.ts.
+ *
+ * Extracted from auto-worktree.ts so recovery fixes land here instead of as
+ * embedded special cases in a 2,600-line orchestration module, and so the
+ * rules can be tested against scripted git states.
+ *
+ * The State Reconciliation drift repair (`state-reconciliation/drift/
+ * merge-state.ts`) keeps its own merge-state primitive by design — drift
+ * repairs own their raw primitives (see CONTEXT.md, Drift repair).
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+
+import { debugLog } from "./debug-logger.js";
+import { logError, logWarning } from "./workflow-logger.js";
+import {
+  nativeAddPaths,
+  nativeCheckoutBranch,
+  nativeConflictFiles,
+  nativeLsFiles,
+  nativeMergeAbort,
+  nativeWorkingTreeStatus,
+} from "./native-git-bridge.js";
+import { resolveGitDir } from "./worktree-manager.js";
+
+/**
+ * Pop the stash entry created with `stashMarker` in its subject, resolving it
+ * to a concrete `stash@{n}` ref first so a concurrent stash push cannot make
+ * `git stash pop` grab the wrong entry.
+ *
+ * If `stashMarker` is null or no longer present in the stash list (e.g. a
+ * concurrent process popped/dropped it), leaves the stash list untouched and
+ * returns null.
+ *
+ * Throws on pop failure so callers can handle conflict cases the same way
+ * they would with the prior `git stash pop` form. When throwing after a
+ * targeted pop attempt, the error is annotated with the targeted stash ref.
+ *
+ * (Issue #4980 HIGH-6)
+ */
+export function popStashByRef(basePath: string, stashMarker: string | null): string | null {
+  let popArg: string | null = null;
+  if (stashMarker) {
+    try {
+      const list = execFileSync("git", ["stash", "list", "--format=%gd%x00%s"], {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+      }).trim().split("\n").filter(Boolean);
+      for (const entry of list) {
+        const [ref, subject] = entry.split("\0");
+        if (ref && subject?.includes(stashMarker)) {
+          popArg = ref;
+          break;
+        }
+      }
+    } catch (err) {
+      logWarning("worktree", `stash list lookup failed; leaving stash untouched: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  if (!popArg) {
+    logWarning("worktree", "recorded stash entry could not be resolved; skipping automatic pop");
+    return null;
+  }
+  try {
+    execFileSync("git", ["stash", "pop", popArg], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+  } catch (err) {
+    if (err && typeof err === "object") {
+      (err as { stashRef?: string }).stashRef = popArg;
+    }
+    throw err;
+  }
+  return popArg;
+}
+
+/**
+ * Extract a stash ref annotation injected by popStashByRef() when git stash
+ * pop fails and we need to conditionally drop the exact stash entry later.
+ */
+export function stashRefFromError(err: unknown): string | null {
+  if (!err || typeof err !== "object") return null;
+  const stashRef = (err as { stashRef?: unknown }).stashRef;
+  return typeof stashRef === "string" && stashRef.length > 0 ? stashRef : null;
+}
+
+export function stashAlreadyExistsFilesFromError(err: unknown): string[] {
+  if (!err || typeof err !== "object") return [];
+  const stderr = (err as { stderr?: unknown }).stderr;
+  const stderrText = typeof stderr === "string"
+    ? stderr
+    : stderr instanceof Uint8Array
+      ? Buffer.from(stderr).toString("utf-8")
+      : "";
+  const message = err instanceof Error ? err.message : String(err);
+  const text = `${stderrText}\n${message}`;
+  const files = new Set<string>();
+  for (const line of text.split("\n")) {
+    const m = line.match(/^(.*?)\s+already exists, no checkout\s*$/i);
+    if (!m) continue;
+    const filePath = m[1]?.trim();
+    if (filePath) files.add(filePath);
+  }
+  return [...files];
+}
+
+/**
+ * Detect whether an on-disk file still contains unresolved merge conflict
+ * markers from a failed stash-pop or merge attempt.
+ *
+ * Returns false when the file cannot be read.
+ */
+export function hasConflictMarkers(filePath: string): boolean {
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    return content.includes("<<<<<<<") && content.includes("=======") && content.includes(">>>>>>>");
+  } catch {
+    return false;
+  }
+}
+
+export function gsdJsonlFilesWithConflictMarkers(basePath: string): string[] {
+  return nativeLsFiles(basePath, ".gsd/*.jsonl").filter((f) =>
+    hasConflictMarkers(join(basePath, f)),
+  );
+}
+
+export function removeMergeStateFiles(basePath: string, contextLabel: string): void {
+  try {
+    for (const f of ["SQUASH_MSG", "MERGE_MSG", "MERGE_MODE", "MERGE_HEAD", "AUTO_MERGE"]) {
+      const rawPath = execFileSync("git", ["rev-parse", "--git-path", f], {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+      }).trim();
+      const p = rawPath.length > 0
+        ? (isAbsolute(rawPath) ? rawPath : resolve(basePath, rawPath))
+        : join(resolveGitDir(basePath), f);
+      if (existsSync(p)) unlinkSync(p);
+    }
+  } catch (err) {
+    logError("worktree", `${contextLabel} merge state cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+export function cleanupConflictState(basePath: string): void {
+  // Merge conflicts can leave unmerged index entries; merge-abort alone is not
+  // enough for squash merges (MERGE_HEAD is never written). Reset the merge
+  // index, then remove merge message files that native/libgit2 paths may have
+  // created.
+  try {
+    nativeMergeAbort(basePath);
+  } catch (err) {
+    // MERGE_HEAD absent (squash merge path) — abort is a no-op, which is fine.
+    debugLog("conflict-cleanup:merge-abort-skipped", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+  try {
+    execFileSync("git", ["reset", "--merge"], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+  } catch (err) {
+    logError("worktree", `git reset --merge failed after merge conflict: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  removeMergeStateFiles(basePath, "conflict");
+}
+
+export function checkoutBranchWithStashGuard(
+  basePath: string,
+  branch: string,
+  reason: string,
+): void {
+  let stashMarker: string | null = null;
+  let stashed = false;
+
+  const status = nativeWorkingTreeStatus(basePath).trim();
+  if (status.length > 0) {
+    stashMarker = `gsd-checkout-stash:${reason}:${process.pid}:${Date.now()}:${process.hrtime.bigint().toString(36)}`;
+    const stashListBefore = execFileSync("git", ["stash", "list"], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+    execFileSync(
+      "git",
+      ["stash", "push", "--include-untracked", "-m", `gsd: checkout stash [${stashMarker}]`],
+      {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+      },
+    );
+    const stashListAfter = execFileSync("git", ["stash", "list"], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+    stashed = stashListAfter !== stashListBefore;
+  }
+
+  // Checkout and stash-restore are split so we can distinguish two failure
+  // modes: (a) checkout failed → HEAD did not move, restore stash and rethrow;
+  // (b) checkout succeeded but stash pop failed → HEAD moved to `branch` but
+  // the working-tree changes remain in the stash list. We surface a distinct
+  // error in case (b) so callers don't assume the branch switch was rolled back.
+  try {
+    nativeCheckoutBranch(basePath, branch);
+  } catch (checkoutErr) {
+    if (stashed) {
+      try {
+        popStashByRef(basePath, stashMarker);
+      } catch (restoreErr) {
+        logWarning("worktree", `git stash pop failed during checkout restore: ${restoreErr instanceof Error ? restoreErr.message : String(restoreErr)}`);
+      }
+    }
+    throw checkoutErr;
+  }
+
+  if (stashed) {
+    try {
+      popStashByRef(basePath, stashMarker);
+    } catch (popErr) {
+      const msg = popErr instanceof Error ? popErr.message : String(popErr);
+      const stderr = popErr && typeof popErr === "object"
+        ? (popErr as { stderr?: unknown }).stderr
+        : undefined;
+      const stderrText = typeof stderr === "string"
+        ? stderr
+        : stderr instanceof Uint8Array
+          ? Buffer.from(stderr).toString("utf-8")
+          : "";
+      const stashPopMessage = `${stderrText}\n${msg}`.trim();
+      const alreadyExists = stashAlreadyExistsFilesFromError(popErr);
+      const isUntrackedRestoreFailure = stashPopMessage.includes("could not restore untracked files from stash");
+      const stashRefForDrop = stashRefFromError(popErr);
+      const allConflictFiles = nativeConflictFiles(basePath);
+      const nonGsdUnmerged = allConflictFiles.filter((f) => !f.startsWith(".gsd/"));
+      const gsdUnmerged = allConflictFiles.filter((f) => f.startsWith(".gsd/"));
+      const gsdContentConflicts = isUntrackedRestoreFailure
+        ? gsdJsonlFilesWithConflictMarkers(basePath)
+        : [];
+      // Resolve ALL untracked-collision files by accepting HEAD — files in
+      // alreadyExists were untracked on the source branch by definition of the
+      // "already exists, no checkout" failure, so target HEAD is authoritative.
+      // gsdUnmerged: .gsd/ index conflicts left by the partial stash pop are
+      // also resolved via HEAD — .gsd/ runtime state is always authoritative
+      // on the target branch, so accepting HEAD is safe here too.
+      const resolvable = [...new Set([...alreadyExists, ...gsdContentConflicts, ...gsdUnmerged])];
+
+      if (
+        isUntrackedRestoreFailure &&
+        resolvable.length > 0 &&
+        nonGsdUnmerged.length === 0
+      ) {
+        for (const f of resolvable) {
+          execFileSync("git", ["checkout", "HEAD", "--", f], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+          });
+          nativeAddPaths(basePath, [f]);
+        }
+
+        if (stashRefForDrop) {
+          try {
+            execFileSync("git", ["stash", "drop", stashRefForDrop], {
+              cwd: basePath,
+              stdio: ["ignore", "pipe", "pipe"],
+              encoding: "utf-8",
+            });
+          } catch (err) { /* stash may already be consumed */
+            logWarning("worktree", `git stash drop failed: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        } else {
+          logWarning("worktree", "recorded stash entry could not be resolved; skipping automatic drop");
+        }
+        return;
+      }
+
+      const wrapped = new Error(
+        `checkout to '${branch}' succeeded but stash restore failed; working tree changes remain in the stash list. Original error: ${msg}`,
+      );
+      if (stashRefForDrop) (wrapped as { stashRef?: string }).stashRef = stashRefForDrop;
+      throw wrapped;
+    }
+  }
+}

package/src/resources/extensions/gsd/worktree-lifecycle.ts

@@ -47,6 +47,7 @@ import {
 // callers — production wiring previously injected them via deps; the seam
 // added type churn without enabling test variation.
 import { loadEffectiveGSDPreferences, getIsolationMode } from "./preferences.js";
+import { isolationDegradedFallbackGuidance, worktreeCreationFailedGuidance } from "./guidance.js";
 import { invalidateAllCaches } from "./cache.js";
 import { resolveMilestoneFile } from "./paths.js";
 import { getMilestone, insertMilestone, isDbAvailable, updateMilestoneStatus } from "./gsd-db.js";
@@ -79,6 +80,7 @@ import {
   teardownAutoWorktree,
 } from "./auto-worktree.js";
 import { resolveRoadmapForMilestoneMerge } from "./milestone-merge-roadmap.js";
+import type { MilestoneMergeTransactionRunner } from "./milestone-merge-transaction.js";
 
 const recentWorktreeMergeFailures = new Map<string, number>();
 const MERGE_FAILURE_DEDUPE_MS = 60_000;
@@ -147,25 +149,15 @@ export interface WorktreeLifecycleDeps {
    */
   worktreeProjection: WorktreeStateProjection;
 
-  // ── Merge primitive ──────────────────────────────────────────────────
+  // ── Merge transaction ────────────────────────────────────────────────
   /**
-   * Inner squash-merge primitive (`auto-worktree.ts:mergeMilestoneToMain`).
+   * Milestone Merge Transaction Module runner.
    *
-   * **Module-internal seam — do not construct your own.** Only the wiring
-   * factory `auto.ts:buildWorktreeLifecycleDeps()` is permitted to populate
-   * this field. The primitive is `@internal`; production callers reach the
-   * merge body through `WorktreeLifecycle.exitMilestone({ merge: true })`,
-   * never by calling this dep directly.
+   * The field name is preserved for existing test fixtures, but production
+   * wiring now supplies the named transaction wrapper rather than the raw
+   * squash-merge primitive directly.
    */
-  mergeMilestoneToMain: (
-    basePath: string,
-    milestoneId: string,
-    roadmapContent: string,
-  ) => {
-    pushed: boolean;
-    codeFilesChanged: boolean;
-    commitMessage?: string;
-  };
+  mergeMilestoneToMain: MilestoneMergeTransactionRunner;
 
   // ADR-016 phase 2 / C1 + C2 + C3 + C4 inlined the following fields as
   // direct imports — leaf primitives that did not vary across callers:
@@ -684,7 +676,16 @@ export function _enterMilestoneCore(
   // Handles the case where originalBasePath is falsy and basePath is itself
   // a worktree path — prevents double-nested worktree paths (#3729).
   const basePath = resolveWorktreeProjectRoot(s.basePath, s.originalBasePath);
-  const mode = opts.modeOverride ?? getIsolationMode(basePath);
+  // A stranded-recovery session that adopted the milestone branch in the
+  // project root must keep re-entering in that mode: the root checkout holds
+  // the branch, so creating the canonical worktree would fail with "already
+  // in use by another worktree". The override clears when the recovered
+  // milestone merges (_mergeAndExit), restoring configured isolation for
+  // subsequent milestones.
+  const mode =
+    opts.modeOverride ??
+    s.strandedRecoveryIsolationMode ??
+    getIsolationMode(basePath);
 
   if (s.isolationDegraded) {
     if (mode === "worktree") {
@@ -693,10 +694,7 @@ export function _enterMilestoneCore(
         s.basePath = basePath;
         rebuildGitService(s, deps);
         invalidateAllCaches();
-        ctx.notify(
-          `Worktree isolation is degraded. Fell back to branch milestone/${milestoneId}.`,
-          "warning",
-        );
+        ctx.notify(isolationDegradedFallbackGuidance(milestoneId), "warning");
         return { ok: true, mode: "branch", path: basePath };
       } catch (err) {
         debugLog("WorktreeLifecycle", {
@@ -883,10 +881,7 @@ export function _enterMilestoneCore(
       eventType: "worktree-create-failed",
       data: { milestoneId, error: msg, fallback: "project-root" },
     });
-    ctx.notify(
-      `Auto-worktree creation for ${milestoneId} failed: ${msg}. Continuing in project root.`,
-      "warning",
-    );
+    ctx.notify(worktreeCreationFailedGuidance(milestoneId, msg), "warning");
     // Degrade isolation for the rest of this session so mergeAndExit
     // doesn't try to merge a nonexistent worktree branch (#2483)
     s.isolationDegraded = true;

package/src/resources/extensions/gsd/worktree-manager.ts

@@ -4,7 +4,8 @@
 /**
  * GSD Worktree Manager
  *
- * Creates and manages git worktrees under .gsd/worktrees/<name>/.
+ * Creates and manages git worktrees under .gsd-worktrees/<name>/ (canonical;
+ * legacy .gsd/worktrees/<name>/ stays recognized — see worktree-placement.ts).
  * Each worktree gets its own branch (worktree/<name>) and a full
  * working copy of the project, enabling parallel work streams.
  *
@@ -12,7 +13,7 @@
  * the main branch, then dispatches an LLM-guided merge flow.
  *
  * Flow:
- *   1. create()  — git worktree add .gsd/worktrees/<name> -b worktree/<name>
+ *   1. create()  — git worktree add .gsd-worktrees/<name> -b worktree/<name>
  *   2. user works in the worktree (new plans, milestones, etc.)
  *   3. merge()   — LLM-guided reconciliation of .gsd/ artifacts back to main
  *   4. remove()  — git worktree remove + branch cleanup
@@ -48,6 +49,7 @@ import {
   normalizeWorktreePathForCompare,
   resolveWorktreeProjectRoot,
 } from "./worktree-root.js";
+import { canonicalWorktreesDir, worktreePathFor, worktreesDirs } from "./worktree-placement.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -138,12 +140,20 @@ export function resolveGitDir(basePath: string): string {
   return gitPath;
 }
 
+/** Canonical container for new worktrees. For scans that must also see legacy
+ *  worktrees, use allWorktreesDirs(). */
 export function worktreesDir(basePath: string): string {
-  return join(resolveWorktreeProjectRoot(basePath), ".gsd", "worktrees");
+  return canonicalWorktreesDir(resolveWorktreeProjectRoot(basePath));
 }
 
+/** Every container a GSD worktree may live in (canonical + legacy), canonical first. */
+export function allWorktreesDirs(basePath: string): string[] {
+  return worktreesDirs(resolveWorktreeProjectRoot(basePath));
+}
+
+/** Path for worktree `name` — an existing legacy worktree keeps its location. */
 export function worktreePath(basePath: string, name: string): string {
-  return join(worktreesDir(basePath), name);
+  return worktreePathFor(resolveWorktreeProjectRoot(basePath), name);
 }
 
 export function worktreeBranchName(name: string): string {
@@ -151,20 +161,22 @@ export function worktreeBranchName(name: string): string {
 }
 
 /**
- * Validate that a path is inside the .gsd/worktrees/ directory.
- * Resolves symlinks and normalizes ".." traversals before comparison
- * so that a symlink-resolved or crafted path cannot escape containment.
+ * Validate that a path is inside a GSD worktrees container (canonical
+ * .gsd-worktrees/ or legacy .gsd/worktrees/). Resolves symlinks and
+ * normalizes ".." traversals before comparison so that a symlink-resolved
+ * or crafted path cannot escape containment.
  *
  * Used as a safety gate before any destructive operation (rmSync,
  * nativeWorktreeRemove --force) to prevent #2365-style data loss.
  */
 export function isInsideWorktreesDir(basePath: string, targetPath: string): boolean {
-  const wtDirPath = worktreesDir(basePath);
-  const wtDir = existsSync(wtDirPath) ? realpathSync(wtDirPath) : resolve(wtDirPath);
   const resolved = existsSync(targetPath) ? realpathSync(targetPath) : resolve(targetPath);
-  // The resolved path must start with the worktrees dir followed by a separator,
-  // not merely be a prefix match (e.g. ".gsd/worktrees-extra" must not match).
-  return resolved === wtDir || resolved.startsWith(wtDir + sep);
+  return allWorktreesDirs(basePath).some((wtDirPath) => {
+    const wtDir = existsSync(wtDirPath) ? realpathSync(wtDirPath) : resolve(wtDirPath);
+    // The resolved path must start with the worktrees dir followed by a separator,
+    // not merely be a prefix match (e.g. ".gsd/worktrees-extra" must not match).
+    return resolved === wtDir || resolved.startsWith(wtDir + sep);
+  });
 }
 
 function isRegisteredGitWorktreeAtPath(basePath: string, wtPath: string): boolean {
@@ -277,12 +289,12 @@ export function buildManualValidationGuidance(
 ): string | null {
   if (!milestoneId) return null;
   const validationRoot = resolveCanonicalMilestoneRoot(basePath, milestoneId);
-  const inWorktree = validationRoot.includes(`${sep}.gsd${sep}worktrees${sep}`);
+  const inWorktree = isGsdWorktreePath(validationRoot);
   const lines: string[] = [`Validate the work here: ${validationRoot}`];
   if (inWorktree) {
     lines.push(
-      "This milestone runs in a git worktree, so the code lives under the hidden " +
-        `\`.gsd/worktrees/\` path. Open it with: cd "${validationRoot}"`,
+      "This milestone runs in a git worktree, so the code lives under the " +
+        `GSD worktrees directory. Open it with: cd "${validationRoot}"`,
     );
   }
   if (opts.uatPath) {
@@ -307,24 +319,33 @@ export function createWorktree(basePath: string, name: string, opts: { branch?:
     throw new GSDError(GSD_PARSE_ERROR, `Invalid worktree name "${name}". Use only letters, numbers, hyphens, and underscores.`);
   }
 
-  const wtPath = worktreePath(basePath, name);
+  const existingPath = worktreePath(basePath, name);
   const branch = opts.branch ?? worktreeBranchName(name);
 
-  if (existsSync(wtPath)) {
+  if (existsSync(existingPath)) {
     // A valid git worktree is registered in `git worktree list` and has a .git
     // *file* with a gitdir: pointer. Leftover directories (no .git, a standalone
     // .git directory from accidental `git init`, or an orphan pointer) block
     // creation unless removed.
-    if (isRegisteredGitWorktreeAtPath(basePath, wtPath)) {
-      throw new GSDError(GSD_STALE_STATE, `Worktree "${name}" already exists at ${wtPath}`);
+    if (isRegisteredGitWorktreeAtPath(basePath, existingPath)) {
+      throw new GSDError(GSD_STALE_STATE, `Worktree "${name}" already exists at ${existingPath}`);
     }
-    removeStaleWorktreeDirectory(wtPath, name);
+    removeStaleWorktreeDirectory(existingPath, name);
   }
 
-  // Ensure the .gsd/worktrees/ directory exists
+  // New worktrees always land in the canonical container, even when a stale
+  // legacy directory was just cleaned up.
   const wtDir = worktreesDir(basePath);
+  const wtPath = join(wtDir, name);
   mkdirSync(wtDir, { recursive: true });
 
+  // When existingPath resolved to a legacy location, the canonical target may
+  // still hold a stale directory from a prior aborted creation (no .git marker).
+  // Remove it so git worktree add does not fail with "path already exists".
+  if (existingPath !== wtPath && existsSync(wtPath) && !isRegisteredGitWorktreeAtPath(basePath, wtPath)) {
+    removeStaleWorktreeDirectory(wtPath, name);
+  }
+
   // Prune any stale worktree entries from a previous removal
   nativeWorktreePrune(basePath);
 
@@ -405,7 +426,8 @@ export function createWorktree(basePath: string, name: string, opts: { branch?:
 
 /**
  * List all GSD-managed worktrees.
- * Uses native worktree list and filters to those under .gsd/worktrees/.
+ * Uses native worktree list and filters to those under a GSD worktrees
+ * container (canonical .gsd-worktrees/ or legacy .gsd/worktrees/).
  */
 export function listWorktrees(basePath: string): WorktreeInfo[] {
   basePath = normalizeBasePathForWorktreeOps(basePath);
@@ -416,12 +438,8 @@ export function listWorktrees(basePath: string): WorktreeInfo[] {
   }
   const seenRoots = new Set<string>();
   const worktreeRoots = baseVariants
-    .map(baseVariant => {
-      const path = join(baseVariant, ".gsd", "worktrees");
-      return {
-        normalized: normalizePathForComparison(path),
-      };
-    })
+    .flatMap(baseVariant => worktreesDirs(baseVariant))
+    .map(path => ({ normalized: normalizePathForComparison(path) }))
     .filter(root => {
       if (seenRoots.has(root.normalized)) return false;
       seenRoots.add(root.normalized);
@@ -638,7 +656,12 @@ export function removeWorktree(
   const resolvedPathSafe = isInsideWorktreesDir(basePath, resolvedWtPath);
 
   // If we're inside the worktree, move out first — git can't remove an in-use directory
-  const cwd = process.cwd();
+  let cwd: string;
+  try {
+    cwd = process.cwd();
+  } catch {
+    cwd = basePath;
+  }
   const resolvedCwd = existsSync(cwd) ? realpathSync(cwd) : cwd;
   if (resolvedCwd === resolvedWtPath || resolvedCwd.startsWith(resolvedWtPath + sep)) {
     process.chdir(basePath);
@@ -794,6 +817,7 @@ export function removeWorktree(
  * This module uses a split representation (paths/exact/prefixes) for efficient matching.
  */
 const SKIP_PATHS = [
+  ".gsd-worktrees/",
   ".gsd/worktrees/",
   ".gsd/runtime/",
   ".gsd/activity/",

package/src/resources/extensions/gsd/worktree-placement.ts

@@ -0,0 +1,63 @@
+/**
+ * Worktree Placement module — owns WHERE GSD worktrees physically live.
+ *
+ * Canonical placement: `<projectRoot>/.gsd-worktrees/<name>` — a real
+ * directory that never crosses the `.gsd` symlink managed by repo-identity.
+ * Under the external-state layout (`.gsd → ~/.gsd/projects/<hash>/`), the
+ * legacy `.gsd/worktrees/` location materialised worktrees inside the user's
+ * home directory behind an opaque hash path; the canonical sibling keeps the
+ * working copy at the project root regardless of where `.gsd` state lives.
+ *
+ * Legacy placement (`<projectRoot>/.gsd/worktrees/<name>`, possibly resolving
+ * through the symlink to `~/.gsd/projects/<hash>/worktrees/<name>`) stays
+ * recognized so in-flight milestones keep working across upgrades:
+ *   - creation always uses the canonical location;
+ *   - resolution prefers an existing legacy worktree for the same name;
+ *   - containment checks accept membership in either location.
+ *
+ * Path → project identification lives in worktree-root.ts; this module owns
+ * only the forward direction (project + name → physical path).
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/** Directory name of the canonical worktrees container at the project root. */
+export const CANONICAL_WORKTREES_DIRNAME = ".gsd-worktrees";
+
+/** Canonical container for newly created worktrees. Never crosses the `.gsd` symlink. */
+export function canonicalWorktreesDir(projectRoot: string): string {
+  return join(projectRoot, CANONICAL_WORKTREES_DIRNAME);
+}
+
+/** Legacy container (`.gsd/worktrees/`) — may resolve through the external-state symlink. */
+export function legacyWorktreesDir(projectRoot: string): string {
+  return join(projectRoot, ".gsd", "worktrees");
+}
+
+/**
+ * All containers a GSD worktree may live in, canonical first.
+ * Use for listing, scanning, and containment checks.
+ */
+export function worktreesDirs(projectRoot: string): string[] {
+  return [canonicalWorktreesDir(projectRoot), legacyWorktreesDir(projectRoot)];
+}
+
+/**
+ * Physical path for the worktree `name` under `projectRoot`.
+ *
+ * Canonical wins only when it has a `.git` marker (i.e. is a live worktree).
+ * A bare directory with no `.git` — a stale leftover from an aborted create
+ * or a partial cleanup — does not shadow an existing legacy worktree, so the
+ * legacy path is tried next. The legacy check remains a plain existsSync;
+ * callers that need a *registered* worktree validate the `.git` marker
+ * themselves (resolveCanonicalMilestoneRoot, getAutoWorktreePath).
+ * Falls back to canonical for new-worktree creation when neither path exists.
+ */
+export function worktreePathFor(projectRoot: string, name: string): string {
+  const canonical = join(canonicalWorktreesDir(projectRoot), name);
+  if (existsSync(canonical) && existsSync(join(canonical, ".git"))) return canonical;
+  const legacy = join(legacyWorktreesDir(projectRoot), name);
+  if (existsSync(legacy)) return legacy;
+  return canonical;
+}