gsd-pi 2.12.0 → 2.13.0

package/dist/resources/extensions/gsd/auto.ts

@@ -86,6 +86,19 @@ import {
 import { GitServiceImpl, runGit } from "./git-service.js";
 import { nativeCommitCountBetween } from "./native-git-bridge.js";
 import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
+import { formatGitError } from "./git-self-heal.js";
+import {
+  createAutoWorktree,
+  enterAutoWorktree,
+  teardownAutoWorktree,
+  isInAutoWorktree,
+  getAutoWorktreePath,
+  getAutoWorktreeOriginalBase,
+  mergeSliceToMilestone,
+  mergeMilestoneToMain,
+  shouldUseWorktreeIsolation,
+  getMergeToMainMode,
+} from "./auto-worktree.js";
 import type { GitPreferences } from "./git-service.js";
 import { truncateToWidth, visibleWidth } from "@gsd/pi-tui";
 import { makeUI, GLYPH, INDENT } from "../shared/ui.js";
@@ -144,6 +157,7 @@ let stepMode = false;
 let verbose = false;
 let cmdCtx: ExtensionCommandContext | null = null;
 let basePath = "";
+let originalBasePath = "";
 let gitService: GitServiceImpl | null = null;
 
 /** Track total dispatches per unit to detect stuck loops (catches A→B→A→B patterns) */
@@ -151,6 +165,12 @@ const unitDispatchCount = new Map<string, number>();
 const MAX_UNIT_DISPATCHES = 3;
 /** Retry index at which a stub summary placeholder is written when the summary is still absent. */
 const STUB_RECOVERY_THRESHOLD = 2;
+/** Hard cap on total dispatches per unit across ALL reconciliation cycles.
+ *  unitDispatchCount can be reset by loop-recovery/self-repair paths, but this
+ *  counter is never reset — it catches infinite reconciliation loops where
+ *  artifacts exist but deriveState keeps returning the same unit. */
+const unitLifetimeDispatches = new Map<string, number>();
+const MAX_LIFETIME_DISPATCHES = 6;
 
 /** Tracks recovery attempt count per unit for backoff and diagnostics. */
 const unitRecoveryCount = new Map<string, number>();
@@ -343,6 +363,27 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI): Promi
 
   // Remove SIGTERM handler registered at auto-mode start
   deregisterSigtermHandler();
+
+  // ── Auto-worktree: exit worktree and reset basePath on stop ──
+  if (currentMilestoneId && isInAutoWorktree(basePath)) {
+    try {
+      teardownAutoWorktree(originalBasePath, currentMilestoneId);
+      basePath = originalBasePath;
+      gitService = new GitServiceImpl(basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+      ctx?.ui.notify("Exited auto-worktree.", "info");
+    } catch (err) {
+      ctx?.ui.notify(
+        `Auto-worktree teardown failed: ${err instanceof Error ? err.message : String(err)}`,
+        "warning",
+      );
+      // Force basePath back to original even if teardown failed
+      if (originalBasePath) {
+        basePath = originalBasePath;
+        try { process.chdir(basePath); } catch { /* best-effort */ }
+      }
+    }
+  }
+
   const ledger = getLedger();
   if (ledger && ledger.units.length > 0) {
     const totals = getProjectTotals(ledger.units);
@@ -367,8 +408,10 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI): Promi
   stepMode = false;
   unitDispatchCount.clear();
   unitRecoveryCount.clear();
+  unitLifetimeDispatches.clear();
   currentUnit = null;
   currentMilestoneId = null;
+  originalBasePath = "";
   cachedSliceProgress = null;
   pendingCrashRecovery = null;
   _handlingAgentEnd = false;
@@ -518,10 +561,17 @@ async function mergeOrphanedSliceBranches(
       "info",
     );
     try {
-      switchToMain(base);
-      const mergeResult = mergeSliceToMain(
-        base, milestoneId, sliceId, sliceEntry.title || sliceId,
-      );
+      let mergeResult;
+      if (isInAutoWorktree(base) && getMergeToMainMode() !== "slice") {
+        mergeResult = mergeSliceToMilestone(
+          base, milestoneId, sliceId, sliceEntry.title || sliceId,
+        );
+      } else {
+        switchToMain(base);
+        mergeResult = mergeSliceToMain(
+          base, milestoneId, sliceId, sliceEntry.title || sliceId,
+        );
+      }
       ctx.ui.notify(
         `Merged orphaned branch ${mergeResult.branch} → ${mainBranch}.`,
         "info",
@@ -568,13 +618,38 @@ export async function startAuto(
     cmdCtx = ctx;
     basePath = base;
     unitDispatchCount.clear();
+    unitLifetimeDispatches.clear();
     // Re-initialize metrics in case ledger was lost during pause
     if (!getLedger()) initMetrics(base);
     // Ensure milestone ID is set on git service for integration branch resolution
     if (currentMilestoneId) setActiveMilestoneId(base, currentMilestoneId);
 
+    // ── Auto-worktree: re-enter worktree on resume if not already inside ──
+    if (currentMilestoneId && originalBasePath && !isInAutoWorktree(basePath) && shouldUseWorktreeIsolation(originalBasePath)) {
+      try {
+        const existingWtPath = getAutoWorktreePath(originalBasePath, currentMilestoneId);
+        if (existingWtPath) {
+          const wtPath = enterAutoWorktree(originalBasePath, currentMilestoneId);
+          basePath = wtPath;
+          gitService = new GitServiceImpl(basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+          ctx.ui.notify(`Re-entered auto-worktree at ${wtPath}`, "info");
+        } else {
+          // Worktree was deleted while paused — recreate it.
+          const wtPath = createAutoWorktree(originalBasePath, currentMilestoneId);
+          basePath = wtPath;
+          gitService = new GitServiceImpl(basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+          ctx.ui.notify(`Recreated auto-worktree at ${wtPath}`, "info");
+        }
+      } catch (err) {
+        ctx.ui.notify(
+          `Auto-worktree re-entry failed: ${err instanceof Error ? err.message : String(err)}. Continuing at current path.`,
+          "warning",
+        );
+      }
+    }
+
     // Re-register SIGTERM handler for the resumed session
-    registerSigtermHandler(base);
+    registerSigtermHandler(basePath);
 
     ctx.ui.setStatus("gsd-auto", stepMode ? "next" : "auto");
     ctx.ui.setFooter(hideFooter);
@@ -687,6 +762,7 @@ export async function startAuto(
   basePath = base;
   unitDispatchCount.clear();
   unitRecoveryCount.clear();
+  unitLifetimeDispatches.clear();
   completedKeySet.clear();
   loadPersistedKeys(base, completedKeySet);
   resetHookState();
@@ -710,6 +786,36 @@ export async function startAuto(
     setActiveMilestoneId(base, currentMilestoneId);
   }
 
+  // ── Auto-worktree: create or enter worktree for the active milestone ──
+  // Store the original project root before any chdir so we can restore on stop.
+  originalBasePath = base;
+  if (currentMilestoneId && shouldUseWorktreeIsolation(base)) {
+    try {
+      const existingWtPath = getAutoWorktreePath(base, currentMilestoneId);
+      if (existingWtPath) {
+        // Worktree already exists (e.g., previous session created it) — enter it.
+        const wtPath = enterAutoWorktree(base, currentMilestoneId);
+        basePath = wtPath;
+        gitService = new GitServiceImpl(basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+        ctx.ui.notify(`Entered auto-worktree at ${wtPath}`, "info");
+      } else {
+        // Fresh start — create worktree and enter it.
+        const wtPath = createAutoWorktree(base, currentMilestoneId);
+        basePath = wtPath;
+        gitService = new GitServiceImpl(basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+        ctx.ui.notify(`Created auto-worktree at ${wtPath}`, "info");
+      }
+      // Re-register SIGTERM handler with the new basePath
+      registerSigtermHandler(basePath);
+    } catch (err) {
+      // Worktree creation is non-fatal — continue in the project root.
+      ctx.ui.notify(
+        `Auto-worktree setup failed: ${err instanceof Error ? err.message : String(err)}. Continuing in project root.`,
+        "warning",
+      );
+    }
+  }
+
   // Initialize metrics — loads existing ledger from disk
   initMetrics(base);
 
@@ -827,6 +933,24 @@ export async function handleAgentEnd(
     } catch {
       // Non-fatal
     }
+
+    // ── Path A fix: verify artifact and persist completion before re-entering dispatch ──
+    // After doctor + rebuildState, check whether the just-completed unit actually
+    // produced its expected artifact. If so, persist the completion key now so the
+    // idempotency check at the top of dispatchNextUnit() skips it — even if
+    // deriveState() still returns this unit as active (e.g. branch mismatch).
+    try {
+      if (verifyExpectedArtifact(currentUnit.type, currentUnit.id, basePath)) {
+        const completionKey = `${currentUnit.type}/${currentUnit.id}`;
+        if (!completedKeySet.has(completionKey)) {
+          persistCompletedKey(basePath, completionKey);
+          completedKeySet.add(completionKey);
+        }
+        invalidateStateCache();
+      }
+    } catch {
+      // Non-fatal — worst case we fall through to normal dispatch which has its own checks
+    }
   }
 
   // ── Post-unit hooks: check if a configured hook should run before normal dispatch ──
@@ -1382,6 +1506,9 @@ async function dispatchNextUnit(
 
   // Clear stale directory listing cache so deriveState sees fresh disk state (#431)
   clearPathCache();
+  // Clear parsed roadmap/plan cache — doctor may have re-populated it with
+  // stale data between handleAgentEnd and this dispatch call (Path B fix).
+  clearParseCache();
 
   let state = await deriveState(basePath);
   let mid = state.activeMilestone?.id;
@@ -1396,8 +1523,9 @@ async function dispatchNextUnit(
     // Reset stuck detection for new milestone
     unitDispatchCount.clear();
     unitRecoveryCount.clear();
+    unitLifetimeDispatches.clear();
     // Capture integration branch for the new milestone and update git service
-    captureIntegrationBranch(basePath, mid);
+    captureIntegrationBranch(originalBasePath || basePath, mid);
   }
   if (mid) {
     currentMilestoneId = mid;
@@ -1502,10 +1630,17 @@ async function dispatchNextUnit(
         if (sliceEntry?.done) {
           try {
             const sliceTitleForMerge = sliceEntry.title || branchSid;
-            switchToMain(basePath);
-            const mergeResult = mergeSliceToMain(
-              basePath, branchMid, branchSid, sliceTitleForMerge,
-            );
+            let mergeResult;
+            if (isInAutoWorktree(basePath) && getMergeToMainMode() !== "slice") {
+              mergeResult = mergeSliceToMilestone(
+                basePath, branchMid, branchSid, sliceTitleForMerge,
+              );
+            } else {
+              switchToMain(basePath);
+              mergeResult = mergeSliceToMain(
+                basePath, branchMid, branchSid, sliceTitleForMerge,
+              );
+            }
             const targetBranch = getMainBranch(basePath);
             ctx.ui.notify(
               `Merged ${mergeResult.branch} → ${targetBranch}.`,
@@ -1569,7 +1704,7 @@ async function dispatchNextUnit(
             }
 
             // Non-conflict errors: reset and stop
-            const message = error instanceof Error ? error.message : String(error);
+            const message = formatGitError(error instanceof Error ? error : String(error));
             try {
               const status = runGit(basePath, ["status", "--porcelain"], { allowFailure: true });
               if (status && (status.includes("UU ") || status.includes("AA ") || status.includes("UD "))) {
@@ -1626,6 +1761,27 @@ async function dispatchNextUnit(
       if (existsSync(file)) writeFileSync(file, JSON.stringify([]), "utf-8");
       completedKeySet.clear();
     } catch { /* non-fatal */ }
+
+    // ── Milestone merge: squash-merge milestone branch to main before stopping ──
+    if (currentMilestoneId && isInAutoWorktree(basePath) && originalBasePath && getMergeToMainMode() === "milestone") {
+      try {
+        const roadmapPath = resolveMilestoneFile(originalBasePath, currentMilestoneId, "ROADMAP");
+        const roadmapContent = readFileSync(roadmapPath, "utf-8");
+        const mergeResult = mergeMilestoneToMain(originalBasePath, currentMilestoneId, roadmapContent);
+        basePath = originalBasePath;
+        gitService = new GitServiceImpl(basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+        ctx.ui.notify(
+          `Milestone ${currentMilestoneId} merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`,
+          "info",
+        );
+      } catch (err) {
+        ctx.ui.notify(
+          `Milestone merge failed: ${err instanceof Error ? err.message : String(err)}`,
+          "warning",
+        );
+      }
+    }
+
     await stopAuto(ctx, pi);
     return;
   }
@@ -1888,6 +2044,26 @@ async function dispatchNextUnit(
   // Pattern A→B→A→B would reset retryCount every time; this map catches it.
   const dispatchKey = `${unitType}/${unitId}`;
   const prevCount = unitDispatchCount.get(dispatchKey) ?? 0;
+
+  // Hard lifetime cap — survives counter resets from loop-recovery/self-repair.
+  // Catches the case where reconciliation "succeeds" (artifacts exist) but
+  // deriveState keeps returning the same unit, creating an infinite cycle.
+  const lifetimeCount = (unitLifetimeDispatches.get(dispatchKey) ?? 0) + 1;
+  unitLifetimeDispatches.set(dispatchKey, lifetimeCount);
+  if (lifetimeCount > MAX_LIFETIME_DISPATCHES) {
+    if (currentUnit) {
+      const modelId = ctx.model?.id ?? "unknown";
+      snapshotUnitMetrics(ctx, currentUnit.type, currentUnit.id, currentUnit.startedAt, modelId);
+    }
+    saveActivityLog(ctx, basePath, unitType, unitId);
+    const expected = diagnoseExpectedArtifact(unitType, unitId, basePath);
+    await stopAuto(ctx, pi);
+    ctx.ui.notify(
+      `Hard loop detected: ${unitType} ${unitId} dispatched ${lifetimeCount} times total (across reconciliation cycles). Stopping.${expected ? `\n   Expected artifact: ${expected}` : ""}\n   This may indicate deriveState() keeps returning the same unit despite artifacts existing.\n   Check .gsd/completed-units.json and the slice plan checkbox state.`,
+      "error",
+    );
+    return;
+  }
   if (prevCount >= MAX_UNIT_DISPATCHES) {
     if (currentUnit) {
       const modelId = ctx.model?.id ?? "unknown";
@@ -1912,7 +2088,13 @@ async function dispatchNextUnit(
               `Loop recovery: ${unitId} reconciled after ${prevCount + 1} dispatches — blocker artifacts written, pipeline advancing.\n   Review ${status.summaryPath} and replace the placeholder with real work.`,
               "warning",
             );
+            // Persist completion so idempotency check prevents re-dispatch
+            // if deriveState keeps returning this unit (#462).
+            const reconciledKey = `${unitType}/${unitId}`;
+            persistCompletedKey(basePath, reconciledKey);
+            completedKeySet.add(reconciledKey);
             unitDispatchCount.delete(dispatchKey);
+            invalidateStateCache();
             await new Promise(r => setImmediate(r));
             await dispatchNextUnit(ctx, pi);
             return;
@@ -1921,6 +2103,30 @@ async function dispatchNextUnit(
       }
     }
 
+    // General reconciliation: if the last attempt DID produce the expected
+    // artifact on disk, clear the counter and advance instead of stopping.
+    // The execute-task path above handles its special case (writing placeholder
+    // summaries). This catch-all covers complete-slice, plan-slice,
+    // research-slice, and all other unit types where the Nth attempt at the
+    // dispatch limit succeeded but the counter check fires before anyone
+    // verifies disk state. Without this, a successful final attempt is
+    // indistinguishable from a failed one.
+    if (verifyExpectedArtifact(unitType, unitId, basePath)) {
+      ctx.ui.notify(
+        `Loop recovery: ${unitType} ${unitId} — artifact verified after ${prevCount + 1} dispatches. Advancing.`,
+        "info",
+      );
+      // Persist completion so the idempotency check prevents re-dispatch
+      // if deriveState keeps returning this unit (see #462).
+      persistCompletedKey(basePath, dispatchKey);
+      completedKeySet.add(dispatchKey);
+      unitDispatchCount.delete(dispatchKey);
+      invalidateStateCache();
+      await new Promise(r => setImmediate(r));
+      await dispatchNextUnit(ctx, pi);
+      return;
+    }
+
     const expected = diagnoseExpectedArtifact(unitType, unitId, basePath);
     const remediation = buildLoopRemediationSteps(unitType, unitId, basePath);
     await stopAuto(ctx, pi);
@@ -1947,7 +2153,12 @@ async function dispatchNextUnit(
               `Self-repaired ${unitId}: summary existed but checkbox was unmarked. Marked [x] and advancing.`,
               "warning",
             );
+            // Persist completion so idempotency check prevents re-dispatch (#462).
+            const repairedKey = `${unitType}/${unitId}`;
+            persistCompletedKey(basePath, repairedKey);
+            completedKeySet.add(repairedKey);
             unitDispatchCount.delete(dispatchKey);
+            invalidateStateCache();
             await new Promise(r => setImmediate(r));
             await dispatchNextUnit(ctx, pi);
             return;

package/dist/resources/extensions/gsd/doctor.ts

@@ -1,3 +1,4 @@
+import { execSync } from "node:child_process";
 import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 
@@ -5,6 +6,9 @@ import { loadFile, parsePlan, parseRoadmap, parseSummary, saveFile, parseTaskPla
 import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTaskFiles, resolveTasksDir, milestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile } from "./paths.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
 import { loadEffectiveGSDPreferences, type GSDPreferences } from "./preferences.js";
+import { listWorktrees } from "./worktree-manager.js";
+import { abortAndReset } from "./git-self-heal.js";
+import { RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
 
 export type DoctorSeverity = "info" | "warning" | "error";
 export type DoctorIssueCode =
@@ -23,7 +27,11 @@ export type DoctorIssueCode =
   | "active_requirement_missing_owner"
   | "blocked_requirement_missing_reason"
   | "blocker_discovered_no_replan"
-  | "delimiter_in_title";
+  | "delimiter_in_title"
+  | "orphaned_auto_worktree"
+  | "stale_milestone_branch"
+  | "corrupt_merge_state"
+  | "tracked_runtime_files";
 
 export interface DoctorIssue {
   severity: DoctorSeverity;
@@ -451,6 +459,189 @@ export function formatDoctorIssuesForPrompt(issues: DoctorIssue[]): string {
   }).join("\n");
 }
 
+async function checkGitHealth(
+  basePath: string,
+  issues: DoctorIssue[],
+  fixesApplied: string[],
+  shouldFix: (code: DoctorIssueCode) => boolean,
+): Promise<void> {
+  // Degrade gracefully if not a git repo
+  try {
+    execSync("git rev-parse --git-dir", { cwd: basePath, stdio: "pipe" });
+  } catch {
+    return; // Not a git repo — skip all git health checks
+  }
+
+  const gitDir = join(basePath, ".git");
+
+  // ── Orphaned auto-worktrees ──────────────────────────────────────────
+  try {
+    const worktrees = listWorktrees(basePath);
+    const milestoneWorktrees = worktrees.filter(wt => wt.branch.startsWith("milestone/"));
+
+    // Load roadmap state once for cross-referencing
+    const state = await deriveState(basePath);
+
+    for (const wt of milestoneWorktrees) {
+      // Extract milestone ID from branch name "milestone/M001" → "M001"
+      const milestoneId = wt.branch.replace(/^milestone\//, "");
+      const milestoneEntry = state.registry.find(m => m.id === milestoneId);
+
+      // Check if milestone is complete via roadmap
+      let isComplete = false;
+      if (milestoneEntry) {
+        const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+        const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
+        if (roadmapContent) {
+          const roadmap = parseRoadmap(roadmapContent);
+          isComplete = isMilestoneComplete(roadmap);
+        }
+      }
+
+      if (isComplete) {
+        issues.push({
+          severity: "warning",
+          code: "orphaned_auto_worktree",
+          scope: "milestone",
+          unitId: milestoneId,
+          message: `Worktree for completed milestone ${milestoneId} still exists at ${wt.path}`,
+          fixable: true,
+        });
+
+        if (shouldFix("orphaned_auto_worktree")) {
+          // Never remove a worktree matching current working directory
+          const cwd = process.cwd();
+          if (wt.path === cwd || cwd.startsWith(wt.path + "/")) {
+            fixesApplied.push(`skipped removing worktree at ${wt.path} (is cwd)`);
+          } else {
+            try {
+              execSync(`git worktree remove --force "${wt.path}"`, { cwd: basePath, stdio: "pipe" });
+              fixesApplied.push(`removed orphaned worktree ${wt.path}`);
+            } catch {
+              fixesApplied.push(`failed to remove worktree ${wt.path}`);
+            }
+          }
+        }
+      }
+    }
+
+    // ── Stale milestone branches ─────────────────────────────────────────
+    try {
+      const branchOutput = execSync("git branch --list 'milestone/*'", { cwd: basePath, stdio: "pipe" }).toString().trim();
+      if (branchOutput) {
+        const branches = branchOutput.split("\n").map(b => b.trim().replace(/^\*\s*/, "")).filter(Boolean);
+        const worktreeBranches = new Set(milestoneWorktrees.map(wt => wt.branch));
+
+        for (const branch of branches) {
+          // Skip branches that have a worktree (handled above)
+          if (worktreeBranches.has(branch)) continue;
+
+          const milestoneId = branch.replace(/^milestone\//, "");
+          const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+          const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
+          if (!roadmapContent) continue;
+
+          const roadmap = parseRoadmap(roadmapContent);
+          if (isMilestoneComplete(roadmap)) {
+            issues.push({
+              severity: "info",
+              code: "stale_milestone_branch",
+              scope: "milestone",
+              unitId: milestoneId,
+              message: `Branch ${branch} exists for completed milestone ${milestoneId}`,
+              fixable: true,
+            });
+
+            if (shouldFix("stale_milestone_branch")) {
+              try {
+                execSync(`git branch -D "${branch}"`, { cwd: basePath, stdio: "pipe" });
+                fixesApplied.push(`deleted stale branch ${branch}`);
+              } catch {
+                fixesApplied.push(`failed to delete branch ${branch}`);
+              }
+            }
+          }
+        }
+      }
+    } catch {
+      // git branch list failed — skip stale branch check
+    }
+  } catch {
+    // listWorktrees or deriveState failed — skip worktree/branch checks
+  }
+
+  // ── Corrupt merge state ────────────────────────────────────────────────
+  try {
+    const mergeStateFiles = ["MERGE_HEAD", "SQUASH_MSG"];
+    const mergeStateDirs = ["rebase-apply", "rebase-merge"];
+    const found: string[] = [];
+
+    for (const f of mergeStateFiles) {
+      if (existsSync(join(gitDir, f))) found.push(f);
+    }
+    for (const d of mergeStateDirs) {
+      if (existsSync(join(gitDir, d))) found.push(d);
+    }
+
+    if (found.length > 0) {
+      issues.push({
+        severity: "error",
+        code: "corrupt_merge_state",
+        scope: "project",
+        unitId: "project",
+        message: `Corrupt merge/rebase state detected: ${found.join(", ")}`,
+        fixable: true,
+      });
+
+      if (shouldFix("corrupt_merge_state")) {
+        const result = abortAndReset(basePath);
+        fixesApplied.push(`cleaned merge state: ${result.cleaned.join(", ")}`);
+      }
+    }
+  } catch {
+    // Can't check .git dir — skip
+  }
+
+  // ── Tracked runtime files ──────────────────────────────────────────────
+  try {
+    const trackedPaths: string[] = [];
+    for (const exclusion of RUNTIME_EXCLUSION_PATHS) {
+      try {
+        const output = execSync(`git ls-files "${exclusion}"`, { cwd: basePath, stdio: "pipe" }).toString().trim();
+        if (output) {
+          trackedPaths.push(...output.split("\n").filter(Boolean));
+        }
+      } catch {
+        // Individual ls-files can fail — continue
+      }
+    }
+
+    if (trackedPaths.length > 0) {
+      issues.push({
+        severity: "warning",
+        code: "tracked_runtime_files",
+        scope: "project",
+        unitId: "project",
+        message: `${trackedPaths.length} runtime file(s) are tracked by git: ${trackedPaths.slice(0, 5).join(", ")}${trackedPaths.length > 5 ? "..." : ""}`,
+        fixable: true,
+      });
+
+      if (shouldFix("tracked_runtime_files")) {
+        try {
+          for (const exclusion of RUNTIME_EXCLUSION_PATHS) {
+            execSync(`git rm --cached -r --ignore-unmatch "${exclusion}"`, { cwd: basePath, stdio: "pipe" });
+          }
+          fixesApplied.push(`untracked ${trackedPaths.length} runtime file(s)`);
+        } catch {
+          fixesApplied.push("failed to untrack runtime files");
+        }
+      }
+    }
+  } catch {
+    // git ls-files failed — skip
+  }
+}
+
 export async function runGSDDoctor(basePath: string, options?: { fix?: boolean; scope?: string; fixLevel?: "task" | "all" }): Promise<DoctorReport> {
   const issues: DoctorIssue[] = [];
   const fixesApplied: string[] = [];
@@ -491,6 +682,9 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
     }
   }
 
+  // Git health checks (orphaned worktrees, stale branches, corrupt merge state, tracked runtime files)
+  await checkGitHealth(basePath, issues, fixesApplied, shouldFix);
+
   const milestonesPath = milestonesDir(basePath);
   if (!existsSync(milestonesPath)) {
     return { ok: issues.every(issue => issue.severity !== "error"), basePath, issues, fixesApplied };