gsd-pi 2.33.0-dev.bafba33 → 2.33.1-dev.235d83a

package/src/resources/extensions/gsd/index.ts

@@ -23,30 +23,24 @@ import type {
   ExtensionCommandContext,
   ExtensionContext,
 } from "@gsd/pi-coding-agent";
-import { createBashTool, createWriteTool, createReadTool, createEditTool, isToolCallEventType } from "@gsd/pi-coding-agent";
+import {
+  createBashTool,
+  createEditTool,
+  createReadTool,
+  createWriteTool,
+  importExtensionModule,
+  isToolCallEventType,
+} from "@gsd/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 
 import { debugLog, debugTime } from "./debug-logger.js";
-import { registerGSDCommand } from "./commands.js";
+import { registerLazyGSDCommand } from "./commands-bootstrap.js";
 import { loadToolApiKeys } from "./commands-config.js";
 import { registerExitCommand } from "./exit-command.js";
-import { registerWorktreeCommand, getWorktreeOriginalCwd, getActiveWorktreeName } from "./worktree-command.js";
-import { getActiveAutoWorktreeContext } from "./auto-worktree.js";
+import { registerLazyWorktreeCommands } from "./worktree-command-bootstrap.js";
 import { saveFile, formatContinue, loadFile, parseContinue, parseSummary, loadActiveOverrides, formatOverridesSection } from "./files.js";
 import { loadPrompt } from "./prompt-loader.js";
-import { deriveState } from "./state.js";
-import { isAutoActive, isAutoPaused, handleAgentEnd, pauseAuto, getAutoDashboardData, getAutoModeStartModel, markToolStart, markToolEnd } from "./auto.js";
 import { saveActivityLog } from "./activity-log.js";
-import { checkAutoStartAfterDiscuss, getDiscussionMilestoneId, findMilestoneIds, nextMilestoneId } from "./guided-flow.js";
-import { GSDDashboardOverlay } from "./dashboard-overlay.js";
-import {
-  loadEffectiveGSDPreferences,
-  renderPreferencesForSystemPrompt,
-  resolveAllSkillReferences,
-  resolveModelWithFallbacksForUnit,
-  getNextFallbackModel,
-  isTransientNetworkError,
-} from "./preferences.js";
 import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "./skill-discovery.js";
 import {
   resolveSlicePath, resolveSliceFile, resolveTaskFile, resolveTaskFiles, resolveTasksDir,
@@ -60,19 +54,37 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { shortcutDesc } from "../shared/mod.js";
 import { Text } from "@gsd/pi-tui";
-import { pauseAutoForProviderError, classifyProviderError } from "./provider-error-pause.js";
 import { toPosixPath } from "../shared/mod.js";
-import { isParallelActive, shutdownParallel } from "./parallel-orchestrator.js";
 import { DEFAULT_BASH_TIMEOUT_SECS } from "./constants.js";
 import { getErrorMessage } from "./error-utils.js";
 
+function memoizeImport<T>(loader: () => Promise<T>): () => Promise<T> {
+  let promise: Promise<T> | null = null;
+  return () => {
+    if (!promise) {
+      promise = loader();
+    }
+    return promise;
+  };
+}
+
+const loadAutoModule = memoizeImport(() => importExtensionModule<typeof import("./auto.js")>(import.meta.url, "./auto.js"));
+const loadStateModule = memoizeImport(() => importExtensionModule<typeof import("./state.js")>(import.meta.url, "./state.js"));
+const loadGuidedFlowModule = memoizeImport(() => importExtensionModule<typeof import("./guided-flow.js")>(import.meta.url, "./guided-flow.js"));
+const loadPreferencesModule = memoizeImport(() => importExtensionModule<typeof import("./preferences.js")>(import.meta.url, "./preferences.js"));
+const loadDashboardOverlayModule = memoizeImport(() => importExtensionModule<typeof import("./dashboard-overlay.js")>(import.meta.url, "./dashboard-overlay.js"));
+const loadWorktreeCommandModule = memoizeImport(() => importExtensionModule<typeof import("./worktree-command.js")>(import.meta.url, "./worktree-command.js"));
+const loadAutoWorktreeModule = memoizeImport(() => importExtensionModule<typeof import("./auto-worktree.js")>(import.meta.url, "./auto-worktree.js"));
+const loadProviderErrorPauseModule = memoizeImport(() => importExtensionModule<typeof import("./provider-error-pause.js")>(import.meta.url, "./provider-error-pause.js"));
+const loadParallelOrchestratorModule = memoizeImport(() => importExtensionModule<typeof import("./parallel-orchestrator.js")>(import.meta.url, "./parallel-orchestrator.js"));
+
 /**
  * Ensure the GSD database is available, auto-initializing if needed.
  * Returns true if the DB is ready, false if initialization failed.
  */
 async function ensureDbAvailable(): Promise<boolean> {
   try {
-    const db = await import("./gsd-db.js");
+    const db = await importExtensionModule<typeof import("./gsd-db.js")>(import.meta.url, "./gsd-db.js");
     if (db.isDbAvailable()) return true;
 
     // Auto-initialize: open (and create if needed) the DB at the standard path
@@ -212,8 +224,8 @@ const GSD_LOGO_LINES = [
 ];
 
 export default function (pi: ExtensionAPI) {
-  registerGSDCommand(pi);
-  registerWorktreeCommand(pi);
+  registerLazyGSDCommand(pi);
+  registerLazyWorktreeCommands(pi);
   registerExitCommand(pi);
 
   // ── EPIPE guard — prevent crash when stdout/stderr pipe closes unexpectedly ──
@@ -223,11 +235,22 @@ export default function (pi: ExtensionAPI) {
   // chance to persist state and pause instead of crashing (see issue #739).
   if (!process.listeners("uncaughtException").some(l => l.name === "_gsdEpipeGuard")) {
     const _gsdEpipeGuard = (err: Error): void => {
-      if ((err as NodeJS.ErrnoException).code === "EPIPE") {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === "EPIPE") {
         // Pipe closed — nothing we can write; just exit cleanly
         process.exit(0);
       }
-      // Re-throw anything that isn't EPIPE so real crashes still surface
+      // ECOMPROMISED: proper-lockfile's update timer detected mtime drift (system
+      // sleep, heavy event loop stall, or filesystem precision mismatch on Node.js
+      // v25+). The onCompromised callback already set _lockCompromised = true, but
+      // due to a subtle interaction between the synchronous fs adapter and the
+      // setTimeout boundary, the error can still propagate here as an uncaught
+      // exception. Exit cleanly so the process.once("exit") handler removes the
+      // lock directory — allowing the next session to acquire cleanly (#1322).
+      if (code === "ECOMPROMISED") {
+        process.exit(1);
+      }
+      // Re-throw anything that isn't EPIPE or ECOMPROMISED so real crashes still surface
       throw err;
     };
     process.on("uncaughtException", _gsdEpipeGuard);
@@ -358,7 +381,7 @@ export default function (pi: ExtensionAPI) {
       }
 
       try {
-        const { saveDecisionToDb } = await import("./db-writer.js");
+        const { saveDecisionToDb } = await importExtensionModule<typeof import("./db-writer.js")>(import.meta.url, "./db-writer.js");
         const { id } = await saveDecisionToDb(
           {
             scope: params.scope,
@@ -420,7 +443,7 @@ export default function (pi: ExtensionAPI) {
 
       try {
         // Verify requirement exists
-        const db = await import("./gsd-db.js");
+        const db = await importExtensionModule<typeof import("./gsd-db.js")>(import.meta.url, "./gsd-db.js");
         const existing = db.getRequirementById(params.id);
         if (!existing) {
           return {
@@ -430,7 +453,7 @@ export default function (pi: ExtensionAPI) {
           };
         }
 
-        const { updateRequirementInDb } = await import("./db-writer.js");
+        const { updateRequirementInDb } = await importExtensionModule<typeof import("./db-writer.js")>(import.meta.url, "./db-writer.js");
         const updates: Record<string, string | undefined> = {};
         if (params.status !== undefined) updates.status = params.status;
         if (params.validation !== undefined) updates.validation = params.validation;
@@ -508,7 +531,7 @@ export default function (pi: ExtensionAPI) {
           relativePath = `milestones/${params.milestone_id}/${params.milestone_id}-${params.artifact_type}.md`;
         }
 
-        const { saveArtifactToDb } = await import("./db-writer.js");
+        const { saveArtifactToDb } = await importExtensionModule<typeof import("./db-writer.js")>(import.meta.url, "./db-writer.js");
         await saveArtifactToDb(
           {
             path: relativePath,
@@ -563,6 +586,10 @@ export default function (pi: ExtensionAPI) {
     parameters: Type.Object({}),
     async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
       try {
+        const [{ findMilestoneIds, nextMilestoneId }, { loadEffectiveGSDPreferences }] = await Promise.all([
+          loadGuidedFlowModule(),
+          loadPreferencesModule(),
+        ]);
         const basePath = process.cwd();
         const existingIds = findMilestoneIds(basePath);
         const uniqueEnabled = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
@@ -610,15 +637,15 @@ export default function (pi: ExtensionAPI) {
 
     // Always-on health widget — ambient system health signal below the editor
     try {
-      const { initHealthWidget } = await import("./health-widget.js");
+      const { initHealthWidget } = await importExtensionModule<typeof import("./health-widget.js")>(import.meta.url, "./health-widget.js");
       initHealthWidget(ctx);
     } catch { /* non-fatal — widget is best-effort */ }
 
     // Notify remote questions status if configured
     try {
       const [{ getRemoteConfigStatus }, { getLatestPromptSummary }] = await Promise.all([
-        import("../remote-questions/config.js"),
-        import("../remote-questions/status.js"),
+        importExtensionModule<typeof import("../remote-questions/config.js")>(import.meta.url, "../remote-questions/config.js"),
+        importExtensionModule<typeof import("../remote-questions/status.js")>(import.meta.url, "../remote-questions/status.js"),
       ]);
       const status = getRemoteConfigStatus();
       const latest = getLatestPromptSummary();
@@ -641,6 +668,7 @@ export default function (pi: ExtensionAPI) {
         return;
       }
 
+      const { GSDDashboardOverlay } = await loadDashboardOverlayModule();
       const result = await ctx.ui.custom<void>(
         (tui, theme, _kb, done) => {
           return new GSDDashboardOverlay(tui, theme, () => done());
@@ -658,7 +686,7 @@ export default function (pi: ExtensionAPI) {
 
       // Fallback for RPC mode where ctx.ui.custom() returns undefined.
       if (result === undefined) {
-        const { fireStatusViaCommand } = await import("./commands.js");
+        const { fireStatusViaCommand } = await importExtensionModule<typeof import("./commands.js")>(import.meta.url, "./commands.js");
         await fireStatusViaCommand(ctx);
       }
     },
@@ -670,6 +698,8 @@ export default function (pi: ExtensionAPI) {
 
     const stopContextTimer = debugTime("context-inject");
     const systemContent = loadPrompt("system");
+    const { loadEffectiveGSDPreferences, resolveAllSkillReferences, renderPreferencesForSystemPrompt } =
+      await loadPreferencesModule();
     const loadedPreferences = loadEffectiveGSDPreferences();
     let preferenceBlock = "";
     if (loadedPreferences) {
@@ -703,7 +733,7 @@ export default function (pi: ExtensionAPI) {
     // Inject auto-learned project memories
     let memoryBlock = "";
     try {
-      const { getActiveMemoriesRanked, formatMemoriesForPrompt } = await import("./memory-store.js");
+      const { getActiveMemoriesRanked, formatMemoriesForPrompt } = await importExtensionModule<typeof import("./memory-store.js")>(import.meta.url, "./memory-store.js");
       const memories = getActiveMemoriesRanked(30);
       if (memories.length > 0) {
         const formatted = formatMemoriesForPrompt(memories, 2000);
@@ -733,6 +763,10 @@ export default function (pi: ExtensionAPI) {
 
     // Worktree context — override the static CWD in the system prompt
     let worktreeBlock = "";
+    const [{ getActiveWorktreeName, getWorktreeOriginalCwd }, { getActiveAutoWorktreeContext }] = await Promise.all([
+      loadWorktreeCommandModule(),
+      loadAutoWorktreeModule(),
+    ]);
     const worktreeName = getActiveWorktreeName();
     const worktreeMainCwd = getWorktreeOriginalCwd();
     const autoWorktree = getActiveAutoWorktreeContext();
@@ -796,9 +830,31 @@ export default function (pi: ExtensionAPI) {
 
   // ── agent_end: auto-mode advancement or auto-start after discuss ───────────
   pi.on("agent_end", async (event, ctx: ExtensionContext) => {
+    const [
+      {
+        isAutoActive,
+        pauseAuto,
+        getAutoDashboardData,
+        getAutoModeStartModel,
+        handleAgentEnd,
+      },
+      { checkAutoStartAfterDiscuss },
+      {
+        isTransientNetworkError,
+        resolveModelWithFallbacksForUnit,
+        getNextFallbackModel,
+      },
+      { classifyProviderError, pauseAutoForProviderError },
+    ] = await Promise.all([
+      loadAutoModule(),
+      loadGuidedFlowModule(),
+      loadPreferencesModule(),
+      loadProviderErrorPauseModule(),
+    ]);
+
     // Clean up quick-task branch if one just completed (#1269)
     try {
-      const { cleanupQuickBranch } = await import("./quick.js");
+      const { cleanupQuickBranch } = await importExtensionModule<typeof import("./quick.js")>(import.meta.url, "./quick.js");
       cleanupQuickBranch();
     } catch { /* non-fatal */ }
 
@@ -1009,6 +1065,11 @@ export default function (pi: ExtensionAPI) {
 
   // ── session_before_compact ────────────────────────────────────────────────
   pi.on("session_before_compact", async (_event, _ctx: ExtensionContext) => {
+    const [{ isAutoActive, isAutoPaused }, { deriveState }] = await Promise.all([
+      loadAutoModule(),
+      loadStateModule(),
+    ]);
+
     // Block compaction during auto-mode — each unit is a fresh session
     // Also block during paused state — context is valuable for the user
     if (isAutoActive() || isAutoPaused()) {
@@ -1055,6 +1116,12 @@ export default function (pi: ExtensionAPI) {
 
   // ── session_shutdown: save activity log on Ctrl+C / SIGTERM ─────────────
   pi.on("session_shutdown", async (_event, ctx: ExtensionContext) => {
+    const [{ isParallelActive, shutdownParallel }, { isAutoActive, isAutoPaused, getAutoDashboardData }] =
+      await Promise.all([
+        loadParallelOrchestratorModule(),
+        loadAutoModule(),
+      ]);
+
     if (isParallelActive()) {
       try {
         await shutdownParallel(process.cwd());
@@ -1066,7 +1133,7 @@ export default function (pi: ExtensionAPI) {
     const cliWorktree = process.env.GSD_CLI_WORKTREE;
     if (cliWorktree) {
       try {
-        const { autoCommitCurrentBranch } = await import("./worktree.js");
+        const { autoCommitCurrentBranch } = await importExtensionModule<typeof import("./worktree.js")>(import.meta.url, "./worktree.js");
         const msg = autoCommitCurrentBranch(process.cwd(), "session-end", cliWorktree);
         if (msg) {
           ctx.ui.notify(`Auto-committed worktree ${cliWorktree} before exit.`, "info");
@@ -1091,6 +1158,7 @@ export default function (pi: ExtensionAPI) {
   // CONTEXT.md can be written.
   pi.on("tool_call", async (event) => {
     if (!isToolCallEventType("write", event)) return;
+    const { getDiscussionMilestoneId } = await loadGuidedFlowModule();
     const result = shouldBlockContextWrite(
       event.toolName,
       event.input.path,
@@ -1108,6 +1176,7 @@ export default function (pi: ExtensionAPI) {
   pi.on("tool_result", async (event) => {
     if (event.toolName !== "ask_user_questions") return;
 
+    const { getDiscussionMilestoneId } = await loadGuidedFlowModule();
     const milestoneId = getDiscussionMilestoneId();
     // Queue flows don't set pendingAutoStart, so milestoneId may be null.
     // Depth gate detection still applies — it sets per-milestone flags.
@@ -1183,11 +1252,13 @@ export default function (pi: ExtensionAPI) {
 
   // ── tool_execution_start/end: track in-flight tools for idle detection ──
   pi.on("tool_execution_start", async (event) => {
+    const { isAutoActive, markToolStart } = await loadAutoModule();
     if (!isAutoActive()) return;
     markToolStart(event.toolCallId);
   });
 
   pi.on("tool_execution_end", async (event) => {
+    const { markToolEnd } = await loadAutoModule();
     markToolEnd(event.toolCallId);
   });
 }
@@ -1202,6 +1273,7 @@ async function buildGuidedExecuteContextInjection(prompt: string, basePath: stri
   const resumeMatch = prompt.match(/Resume interrupted work\.[\s\S]*?slice\s+(S\d+)\s+of milestone\s+(M\d+(?:-[a-z0-9]{6})?)/i);
   if (resumeMatch) {
     const [, sliceId, milestoneId] = resumeMatch;
+    const { deriveState } = await loadStateModule();
     const state = await deriveState(basePath);
     if (
       state.activeMilestone?.id === milestoneId &&

package/src/resources/extensions/gsd/quick.ts

@@ -10,7 +10,7 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
-import { existsSync, mkdirSync, readdirSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
@@ -168,6 +168,8 @@ export async function handleQuick(
       slug,
       description,
     };
+    // Persist to disk so recovery works across session crashes (#1293).
+    persistPendingReturn(_pendingQuickBranchReturn, basePath);
   }
 }
 
@@ -181,15 +183,58 @@ let _pendingQuickBranchReturn: {
   description: string;
 } | null = null;
 
+// ─── Disk Persistence ─────────────────────────────────────────────────────
+
+/** Path to the pending quick-task return file. */
+function pendingReturnPath(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime", "quick-return.json");
+}
+
+/** Write pending return state to disk. */
+function persistPendingReturn(state: NonNullable<typeof _pendingQuickBranchReturn>, basePath: string): void {
+  const filePath = pendingReturnPath(basePath);
+  mkdirSync(join(gsdRoot(basePath), "runtime"), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+
+/** Remove pending return file from disk. */
+function clearPendingReturn(basePath: string): void {
+  try { unlinkSync(pendingReturnPath(basePath)); } catch { /* already gone */ }
+}
+
+/** Load pending return from disk (cross-session recovery). */
+function loadPendingReturn(basePath: string): NonNullable<typeof _pendingQuickBranchReturn> | null {
+  const filePath = pendingReturnPath(basePath);
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Merge the quick-task branch back to the original branch and switch.
  * Called from the agent_end handler after a quick task completes.
+ *
+ * Checks both in-memory state (same session) and disk state (cross-session
+ * recovery for crashed/interrupted sessions).
+ *
  * Returns true if a branch return was performed.
  */
 export function cleanupQuickBranch(): boolean {
-  if (!_pendingQuickBranchReturn) return false;
-  const { basePath, originalBranch, quickBranch, taskNum, slug, description } = _pendingQuickBranchReturn;
+  // Prefer in-memory state; fall back to disk for cross-session recovery
+  let state = _pendingQuickBranchReturn;
+  if (!state) {
+    // Try loading from disk — handles the case where the session that
+    // started the quick task crashed before agent_end could run (#1293).
+    const basePath = process.cwd();
+    state = loadPendingReturn(basePath);
+  }
+  if (!state) return false;
+
   _pendingQuickBranchReturn = null;
+  const { basePath, originalBranch, quickBranch, taskNum, slug, description } = state;
 
   try {
     // Auto-commit any remaining work
@@ -205,8 +250,12 @@ export function cleanupQuickBranch(): boolean {
 
     // Clean up quick branch
     try { runGit(basePath, ["branch", "-D", quickBranch]); } catch {}
+
+    // Clean up disk state
+    clearPendingReturn(basePath);
     return true;
   } catch {
+    // Cleanup failed — leave disk state for next attempt
     return false;
   }
 }

package/src/resources/extensions/gsd/repo-identity.ts

@@ -8,9 +8,9 @@
 
 import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, symlinkSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, symlinkSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve, sep } from "node:path";
+import { join, resolve } from "node:path";
 
 // ─── Repo Identity ──────────────────────────────────────────────────────────
 
@@ -35,35 +35,56 @@ function getRemoteUrl(basePath: string): string {
  * Resolve the git toplevel (real root) for the given path.
  * For worktrees this returns the main repo root, not the worktree path.
  */
-function resolveGitRoot(basePath: string): string {
+function canonicalizeExistingPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+function resolveGitCommonDir(basePath: string): string {
   try {
-    // In a worktree, --show-toplevel returns the worktree path, not the main
-    // repo root. Use --git-common-dir to find the shared .git directory,
-    // then derive the main repo root from it (#1288).
-    const commonDir = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+    return execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
+      cwd: basePath,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5_000,
+    }).trim();
+  } catch {
+    const raw = execFileSync("git", ["rev-parse", "--git-common-dir"], {
       cwd: basePath,
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 5_000,
     }).trim();
+    return resolve(basePath, raw);
+  }
+}
+
+function resolveGitRoot(basePath: string): string {
+  try {
+    const commonDir = resolveGitCommonDir(basePath);
+    const normalizedCommonDir = commonDir.replaceAll("\\", "/");
+
+    // Normal repo or worktree with shared common dir pointing at <repo>/.git.
+    if (normalizedCommonDir.endsWith("/.git")) {
+      return canonicalizeExistingPath(resolve(commonDir, ".."));
+    }
 
-    // If commonDir ends with .git/worktrees/<name>, the main repo is two
-    // levels up from the worktrees dir. If it's just .git, resolve normally.
-    if (commonDir.includes(`${sep}worktrees${sep}`) || commonDir.includes("/worktrees/")) {
-      // e.g., /path/to/project/.gsd/worktrees/M001/.git → /path/to/project
-      // or /path/to/project/.git/worktrees/M001 → /path/to/project
-      const gitDir = commonDir.replace(/[/\\]worktrees[/\\][^/\\]+$/, "");
-      const mainRoot = resolve(gitDir, "..");
-      return mainRoot;
+    // Some git setups may still expose <repo>/.git/worktrees/<name>.
+    const worktreeMarker = "/.git/worktrees/";
+    if (normalizedCommonDir.includes(worktreeMarker)) {
+      return canonicalizeExistingPath(resolve(commonDir, "..", ".."));
     }
 
-    // Not in a worktree — use --show-toplevel as usual
-    return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+    // Fallback for unusual layouts.
+    return canonicalizeExistingPath(execFileSync("git", ["rev-parse", "--show-toplevel"], {
       cwd: basePath,
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 5_000,
-    }).trim();
+    }).trim());
   } catch {
     return resolve(basePath);
   }
@@ -111,10 +132,17 @@ export function externalGsdRoot(basePath: string): string {
 export function ensureGsdSymlink(projectPath: string): string {
   const externalPath = externalGsdRoot(projectPath);
   const localGsd = join(projectPath, ".gsd");
+  const inWorktree = isInsideWorktree(projectPath);
 
   // Ensure external directory exists
   mkdirSync(externalPath, { recursive: true });
 
+  const replaceWithSymlink = (): string => {
+    rmSync(localGsd, { recursive: true, force: true });
+    symlinkSync(externalPath, localGsd, "junction");
+    return externalPath;
+  };
+
   if (!existsSync(localGsd)) {
     // Nothing exists yet — create symlink
     symlinkSync(externalPath, localGsd, "junction");
@@ -130,14 +158,20 @@ export function ensureGsdSymlink(projectPath: string): string {
       if (target === externalPath) {
         return externalPath; // correct symlink, no-op
       }
-      // Symlink exists but points elsewhere — leave it for now
-      // (could be a custom override or stale symlink)
+      // In a worktree, mismatched symlinks are always stale. Heal them so
+      // the worktree points at the same external state dir as the main repo.
+      if (inWorktree) {
+        return replaceWithSymlink();
+      }
+      // Outside worktrees, preserve custom overrides or legacy symlinks.
       return target;
     }
 
     if (stat.isDirectory()) {
-      // Real directory — migration will handle this later.
-      // Return the local path so existing code still works.
+      // Real directory in the main repo — migration will handle this later.
+      // In worktrees, keep the directory in place and let syncGsdStateToWorktree
+      // refresh its contents. Replacing a git-tracked .gsd directory with a
+      // symlink makes git think tracked planning files were deleted.
       return localGsd;
     }
   } catch {