@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.84c56d87

package/src/resources/extensions/gsd/db-workspace.ts

@@ -0,0 +1,170 @@
+// Project/App: gsd-pi
+// File Purpose: Workspace-facing Interface for opening and maintaining the workflow database.
+
+import { existsSync } from "node:fs";
+import { dirname } from "node:path";
+
+import type { GsdWorkspace, MilestoneScope } from "./workspace.js";
+import {
+  backupDatabaseSnapshot,
+  checkpointDatabase,
+  closeAllDatabases,
+  closeDatabase,
+  closeDatabaseByWorkspace,
+  getDbPath,
+  getDbStatus,
+  getDbProvider,
+  isDbAvailable,
+  openDatabase,
+  openDatabaseByScope,
+  openDatabaseByWorkspace,
+  refreshOpenDatabaseFromDisk,
+  vacuumDatabase,
+  wasDbOpenAttempted,
+} from "./gsd-db.js";
+import { resolveGsdPathContract } from "./paths.js";
+import { setLogBasePath } from "./workflow-logger.js";
+
+export interface WorkflowDatabaseLocation {
+  projectRoot: string;
+  projectGsd: string;
+  projectDb: string;
+}
+
+export type WorkflowDatabaseOpenReason =
+  | "opened-existing"
+  | "created-empty"
+  | "missing-database"
+  | "missing-gsd-dir"
+  | "open-failed";
+
+export type WorkflowDatabaseOpenResult =
+  | {
+      ok: true;
+      reason: "opened-existing" | "created-empty";
+      location: WorkflowDatabaseLocation;
+    }
+  | {
+      ok: false;
+      reason: "missing-database" | "missing-gsd-dir" | "open-failed";
+      location: WorkflowDatabaseLocation;
+      error?: Error;
+    };
+
+export type WorkflowDatabaseStatus = ReturnType<typeof getDbStatus>;
+export type WorkflowDatabaseProvider = ReturnType<typeof getDbProvider>;
+
+export function resolveWorkflowDatabaseLocation(basePath: string): WorkflowDatabaseLocation {
+  const contract = resolveGsdPathContract(basePath);
+  return {
+    projectRoot: dirname(dirname(contract.projectDb)),
+    projectGsd: contract.projectGsd,
+    projectDb: contract.projectDb,
+  };
+}
+
+/**
+ * Resolve the correct DB path for the current working directory.
+ * If `basePath` is inside a `.gsd/worktrees/<MID>/` directory, returns
+ * the project root's `.gsd/gsd.db` (shared WAL — R012). Otherwise returns
+ * `<basePath>/.gsd/gsd.db`.
+ */
+export function resolveProjectRootDbPath(basePath: string): string {
+  return resolveWorkflowDatabaseLocation(basePath).projectDb;
+}
+
+export function openWorkflowDatabase(basePath: string): WorkflowDatabaseOpenResult {
+  const location = resolveWorkflowDatabaseLocation(basePath);
+  if (!existsSync(location.projectGsd)) {
+    return { ok: false, reason: "missing-gsd-dir", location };
+  }
+
+  const existed = existsSync(location.projectDb);
+  try {
+    const opened = openDatabase(location.projectDb);
+    if (!opened) {
+      return { ok: false, reason: "open-failed", location };
+    }
+    setLogBasePath(location.projectRoot);
+    return {
+      ok: true,
+      reason: existed ? "opened-existing" : "created-empty",
+      location,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      reason: "open-failed",
+      location,
+      error: err instanceof Error ? err : new Error(String(err)),
+    };
+  }
+}
+
+export function openExistingWorkflowDatabase(basePath: string): WorkflowDatabaseOpenResult {
+  const location = resolveWorkflowDatabaseLocation(basePath);
+  if (!existsSync(location.projectDb)) {
+    return { ok: false, reason: "missing-database", location };
+  }
+  return openWorkflowDatabase(basePath);
+}
+
+export function openWorkflowDatabasePath(path: string): boolean {
+  return openDatabase(path);
+}
+
+export function openWorkflowDatabaseByWorkspace(workspace: GsdWorkspace): boolean {
+  return openDatabaseByWorkspace(workspace);
+}
+
+export function openWorkflowDatabaseByScope(scope: MilestoneScope): boolean {
+  return openDatabaseByScope(scope);
+}
+
+export function closeWorkflowDatabase(): void {
+  closeDatabase();
+}
+
+export function closeWorkflowDatabaseByWorkspace(workspace: GsdWorkspace): void {
+  closeDatabaseByWorkspace(workspace);
+}
+
+export function closeAllWorkflowDatabases(): void {
+  closeAllDatabases();
+}
+
+export function isWorkflowDatabaseOpen(): boolean {
+  return isDbAvailable();
+}
+
+export function wasWorkflowDatabaseOpenAttempted(): boolean {
+  return wasDbOpenAttempted();
+}
+
+export function getWorkflowDatabaseStatus(): WorkflowDatabaseStatus {
+  return getDbStatus();
+}
+
+export function getWorkflowDatabaseProvider(): WorkflowDatabaseProvider {
+  return getDbProvider();
+}
+
+export function getWorkflowDatabasePath(): string | null {
+  return getDbPath();
+}
+
+export function refreshWorkflowDatabaseFromDisk(): boolean {
+  return refreshOpenDatabaseFromDisk();
+}
+
+export function checkpointWorkflowDatabase(): void {
+  checkpointDatabase();
+}
+
+export function vacuumWorkflowDatabase(): void {
+  vacuumDatabase();
+}
+
+export function backupWorkflowDatabaseSnapshot(label: string): string | null {
+  return backupDatabaseSnapshot(label);
+}

package/src/resources/extensions/gsd/delegation-policy.ts

@@ -35,6 +35,8 @@
 // existing entry is the place to lift any of these out of default-deny
 // when the analysis has been done.
 
+import { canonicalWorkflowSurfaceToolName } from "./workflow-tool-surface.js";
+
 export type BackgroundabilityVerdict = "good" | "risky" | "no";
 
 export interface DelegationPolicyEntry {
@@ -123,18 +125,8 @@ const POLICY: Record<string, DelegationPolicyEntry> = {
   },
 };
 
-// Alias map keyed on the secondary name; resolves to the canonical entry above.
-// Sourced from packages/mcp-server/src/workflow-tools.ts alias registrations
-// (gsd_milestone_validate, gsd_roadmap_reassess, gsd_slice_replan, gsd_task_plan).
-const ALIASES: Record<string, string> = {
-  gsd_milestone_validate: "gsd_validate_milestone",
-  gsd_roadmap_reassess: "gsd_reassess_roadmap",
-  gsd_slice_replan: "gsd_replan_slice",
-  gsd_task_plan: "gsd_plan_task",
-};
-
 function resolveCanonical(name: string): string {
-  return ALIASES[name] ?? name;
+  return canonicalWorkflowSurfaceToolName(name);
 }
 
 export function getDelegationVerdict(toolName: string): DelegationPolicyEntry | null {

package/src/resources/extensions/gsd/discussion-handoff.ts

@@ -0,0 +1,276 @@
+// Project/App: gsd-pi
+// File Purpose: Owns the guided-discuss to auto-mode handoff.
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { startAutoDetached } from "./auto.js";
+import { extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
+import { getMilestone, insertMilestone, isDbAvailable } from "./gsd-db.js";
+import {
+  assessMilestoneHandoffReadiness,
+  formatAcceptedDiscussHandoffMessage,
+} from "./milestone-readiness.js";
+import { gsdRoot, resolveGsdRootFile, resolveMilestoneFile } from "./paths.js";
+import { _getPendingAutoStart, deletePendingAutoStart, type PendingAutoStartEntry } from "./pending-auto-start.js";
+import { logWarning } from "./workflow-logger.js";
+import { readManifest } from "./workflow-manifest.js";
+
+type AutoStartOptions = Parameters<typeof startAutoDetached>[4];
+type AutoStartLauncher = typeof startAutoDetached;
+
+// Cap failed in-flight DB row repair attempts before escalating to the user.
+const MAX_DB_ROW_RECOVERIES = 3;
+const PROJECT_DEPTH_GATE_IDS = new Set([
+  "depth_verification_project_confirm",
+  "depth_verification_requirements_confirm",
+  "depth_verification_research_decision_confirm",
+]);
+
+export function scheduleAutoStartAfterIdle(
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+  basePath: string,
+  verboseMode: boolean,
+  options?: AutoStartOptions,
+  launch: AutoStartLauncher = startAutoDetached,
+): void {
+  const waitForIdle =
+    typeof (ctx as { waitForIdle?: unknown }).waitForIdle === "function"
+      ? ctx.waitForIdle.bind(ctx)
+      : async () => {};
+  void waitForIdle()
+    .then(() => {
+      setTimeout(() => launch(ctx, pi, basePath, verboseMode, options), 0);
+    })
+    .catch((err) => {
+      const message = err instanceof Error ? err.message : String(err);
+      ctx.ui.notify(`Auto-start failed while waiting for the prior turn to settle: ${message}`, "error");
+      logWarning("guided", `auto-start idle wait failed: ${message}`);
+    });
+}
+
+function manifestContainsMilestone(basePath: string, milestoneId: string): boolean {
+  try {
+    const manifest = readManifest(basePath);
+    return (
+      Array.isArray(manifest?.milestones) &&
+      manifest.milestones.some(m => m.id === milestoneId)
+    );
+  } catch (e) {
+    logWarning("guided", `R3b: failed to read state manifest: ${(e as Error).message}`);
+    return false;
+  }
+}
+
+function notifyDbRowRecoveryFailed(entry: PendingAutoStartEntry): void {
+  entry.ctx.ui.notify(
+    `Milestone ${entry.milestoneId}: DB row recovery failed ${entry.r3bRecoveryCount} times. ` +
+    `Re-run /gsd to reset the recovery counter, or run /gsd-debug to diagnose without resetting.`,
+    "error",
+  );
+}
+
+function noteDbRowRecoveryMiss(entry: PendingAutoStartEntry): void {
+  entry.r3bRecoveryCount += 1;
+  if (entry.r3bRecoveryCount >= MAX_DB_ROW_RECOVERIES) {
+    notifyDbRowRecoveryFailed(entry);
+  }
+}
+
+function ensureMilestoneRowForAcceptedHandoff(
+  entry: PendingAutoStartEntry,
+  contextFile: string | null,
+): boolean {
+  if (!isDbAvailable()) return true;
+
+  const { basePath, milestoneId } = entry;
+  const milestoneRow = getMilestone(milestoneId);
+  if (milestoneRow) return true;
+
+  if (manifestContainsMilestone(basePath, milestoneId)) {
+    logWarning(
+      "guided",
+      `R3b: getMilestone(${milestoneId}) returned null but manifest has the row — treating as stale read`,
+    );
+    return true;
+  }
+
+  if (!contextFile) {
+    entry.ctx.ui.notify(
+      `Milestone ${milestoneId}: discuss artifacts on disk but no DB row exists. ` +
+      `PROJECT.md may have failed to register milestones. ` +
+      `Re-save PROJECT.md with canonical "- [ ] M001: Title — One-liner" lines, ` +
+      `then re-run /gsd to recover.`,
+      "error",
+    );
+    return false;
+  }
+
+  if (entry.r3bRecoveryCount >= MAX_DB_ROW_RECOVERIES) {
+    logWarning(
+      "guided",
+      `R3b: milestone ${milestoneId} DB-row recovery limit reached ` +
+      `(${entry.r3bRecoveryCount}/${MAX_DB_ROW_RECOVERIES}); user already notified`,
+    );
+    return false;
+  }
+
+  logWarning(
+    "guided",
+    `R3b: ${milestoneId} has CONTEXT.md but no DB row — inserting placeholder "queued" row ` +
+    `(attempt ${entry.r3bRecoveryCount + 1}/${MAX_DB_ROW_RECOVERIES})`,
+  );
+
+  try {
+    insertMilestone({ id: milestoneId, title: milestoneId, status: "queued" });
+  } catch (e) {
+    logWarning("guided", `R3b: insertMilestone failed: ${(e as Error).message}`);
+  }
+
+  if (getMilestone(milestoneId)) return true;
+
+  noteDbRowRecoveryMiss(entry);
+  return false;
+}
+
+/**
+ * Extract milestone IDs from PROJECT.md milestone sequence table.
+ * Looks for rows like "| M001 | Name | Status |" and extracts the ID column.
+ */
+function parseMilestoneSequenceFromProject(content: string): string[] {
+  const ids: string[] = [];
+  const lines = content.split(/\r?\n/);
+  for (const line of lines) {
+    const match = line.match(/^\|\s*(M\d{3}[A-Z0-9-]*)\s*\|/);
+    if (match) ids.push(match[1]);
+  }
+  return ids;
+}
+
+function hasBlockingDepthGate(entry: PendingAutoStartEntry): boolean {
+  const basePathForGate = entry.scope.workspace.projectRoot;
+  const pendingGateId = getPendingGate(basePathForGate);
+  if (!pendingGateId) return false;
+
+  const pendingMilestoneId = extractDepthVerificationMilestoneId(pendingGateId);
+  return pendingMilestoneId === entry.milestoneId || PROJECT_DEPTH_GATE_IDS.has(pendingGateId);
+}
+
+function discussionManifestPath(entry: PendingAutoStartEntry): string {
+  return join(entry.scope.workspace.contract.projectGsd, "DISCUSSION-MANIFEST.json");
+}
+
+function warnForMissingProjectMilestones(entry: PendingAutoStartEntry): string[] {
+  const { ctx, basePath } = entry;
+  const projectFile = resolveGsdRootFile(basePath, "PROJECT");
+  if (!projectFile) return [];
+
+  try {
+    const projectContent = readFileSync(projectFile, "utf-8");
+    const projectIds = parseMilestoneSequenceFromProject(projectContent);
+    if (projectIds.length <= 1) return projectIds;
+
+    const missing = projectIds.filter(id => {
+      const hasContext = !!resolveMilestoneFile(basePath, id, "CONTEXT");
+      const hasDraft = !!resolveMilestoneFile(basePath, id, "CONTEXT-DRAFT");
+      const hasDir = existsSync(join(gsdRoot(basePath), "milestones", id));
+      return !hasContext && !hasDraft && !hasDir;
+    });
+    if (missing.length > 0) {
+      ctx.ui.notify(
+        `Multi-milestone validation: ${missing.join(", ")} not found in filesystem. ` +
+        `Discussion may not have completed all readiness gates.`,
+        "warning",
+      );
+    }
+    return projectIds;
+  } catch (e) {
+    logWarning("guided", `PROJECT.md parsing failed: ${(e as Error).message}`);
+    return [];
+  }
+}
+
+function discussionManifestIsComplete(entry: PendingAutoStartEntry, projectIds: string[]): boolean {
+  const manifestPath = discussionManifestPath(entry);
+  if (!existsSync(manifestPath)) return true;
+
+  try {
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    const total = typeof manifest.total === "number" ? manifest.total : 0;
+    const completed = typeof manifest.gates_completed === "number" ? manifest.gates_completed : 0;
+
+    if (total > 1 && completed < total) {
+      return false;
+    }
+
+    if (projectIds.length > 0) {
+      const manifestIds = Object.keys(manifest.milestones ?? {});
+      const untracked = projectIds.filter(id => !manifestIds.includes(id));
+      if (untracked.length > 0) {
+        entry.ctx.ui.notify(
+          `Discussion manifest missing gates for: ${untracked.join(", ")}`,
+          "warning",
+        );
+      }
+    }
+  } catch (e) {
+    logWarning("guided", `discussion manifest verification failed: ${(e as Error).message}`);
+  }
+  return true;
+}
+
+function cleanupAcceptedHandoffArtifacts(entry: PendingAutoStartEntry): void {
+  const { basePath, milestoneId } = entry;
+  try {
+    const draftFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT-DRAFT");
+    if (draftFile) unlinkSync(draftFile);
+  } catch (e) {
+    logWarning("guided", `CONTEXT-DRAFT.md unlink failed: ${(e as Error).message}`);
+  }
+
+  const manifestPath = discussionManifestPath(entry);
+  if (existsSync(manifestPath)) {
+    try {
+      unlinkSync(manifestPath);
+    } catch (e) {
+      logWarning("guided", `manifest unlink failed: ${(e as Error).message}`);
+    }
+  }
+}
+
+/** Called from agent_end to check if auto-mode should start after discuss. */
+export function checkAutoStartAfterDiscuss(lookupBasePath?: string): boolean {
+  const entry = _getPendingAutoStart(lookupBasePath);
+  if (!entry) return false;
+
+  const { ctx, pi, basePath, milestoneId, step } = entry;
+  const contextFilePath = entry.scope.contextFile();
+  const roadmapFilePath = entry.scope.roadmapFile();
+  const contextFile = existsSync(contextFilePath) ? contextFilePath : null;
+  const roadmapFile = existsSync(roadmapFilePath) ? roadmapFilePath : null;
+  if (!contextFile && !roadmapFile) return false;
+
+  if (hasBlockingDepthGate(entry)) return false;
+  if (!ensureMilestoneRowForAcceptedHandoff(entry, contextFile)) return false;
+
+  const projectIds = warnForMissingProjectMilestones(entry);
+  if (!discussionManifestIsComplete(entry, projectIds)) return false;
+
+  cleanupAcceptedHandoffArtifacts(entry);
+  deletePendingAutoStart(basePath);
+
+  const readiness = assessMilestoneHandoffReadiness({
+    milestoneId,
+    contextFile,
+    roadmapFile,
+  });
+  ctx.ui.notify(
+    formatAcceptedDiscussHandoffMessage(milestoneId, readiness),
+    "success",
+  );
+  if (entry.startAuto !== false) {
+    scheduleAutoStartAfterIdle(ctx, pi, basePath, false, { step: step ?? true });
+  }
+  return true;
+}

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -73,6 +73,15 @@ These are **separate concerns**:
 
 Setting `prefer_skills: []` does **not** disable skill discovery — it just means you have no preference overrides. Use `skill_discovery: off` to disable discovery entirely.
 
+### Parse & Validation Diagnostics
+
+Preference loading never throws. When a file is malformed or contains invalid settings, GSD falls back to safe defaults but attaches structured diagnostics (see `collectPreferenceDiagnostics()` in `preferences-diagnostics.ts`) so the problem is reported instead of silently ignored:
+
+- **Parse failures** (missing closing `---` delimiter, YAML syntax error, or an unrecognized file format) cause the whole file to be ignored. Loading continues to the next candidate — a valid global or legacy preferences file is still used, and a malformed project file never becomes the effective wrapper or blocks fallback.
+- **Validation problems** (unknown keys, type mismatches) are sanitized or dropped per-field; the remaining valid settings in the file still apply.
+
+Diagnostics record the file path, scope (global/project), severity (error/warning), kind (parse/validation), and — for YAML parse errors — the line and column. They surface through session-start notifications, `/gsd doctor`, and auto-mode preflight, with each surface deduping repeated diagnostics.
+
 ---
 
 ## Field Guide

package/src/resources/extensions/gsd/doctor-environment.ts

@@ -15,6 +15,7 @@ import { join } from "node:path";
 
 import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
 import { detectPythonExecutable } from "./python-resolver.js";
+import { projectRootFromWorktreePath } from "./worktree-root.js";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -38,27 +39,18 @@ const CMD_TIMEOUT = 5_000;
 
 // ── Helpers ────────────────────────────────────────────────────────────────
 
-/** Worktree sentinel — path segment that marks an auto-worktree directory. */
-const WORKTREE_PATH_SEGMENT = `${join(".gsd", "worktrees")}/`;
-
 /**
- * Resolve the project root when running inside a `.gsd/worktrees/<name>/`
- * auto-worktree. Returns `null` if not in a worktree.
+ * Resolve the project root when running inside a GSD auto-worktree.
+ * Returns `null` if not in a worktree.
  *
  * Detection order:
  *   1. `GSD_WORKTREE` env var (set by the worktree launcher)
- *   2. `.gsd/worktrees/` segment in basePath
+ *   2. worktree segment in basePath (via worktree-root's layout matching)
  */
 function resolveWorktreeProjectRoot(basePath: string): string | null {
   const envRoot = process.env.GSD_WORKTREE;
   if (envRoot) return envRoot;
-
-  const normalised = basePath.replace(/\\/g, "/");
-  const idx = normalised.indexOf(WORKTREE_PATH_SEGMENT.replace(/\\/g, "/"));
-  if (idx === -1) return null;
-
-  // Everything before `.gsd/worktrees/` is the project root
-  return basePath.slice(0, idx);
+  return projectRootFromWorktreePath(basePath);
 }
 
 function tryExec(cmd: string, cwd: string): string | null {

package/src/resources/extensions/gsd/doctor-format.ts

@@ -1,4 +1,9 @@
-import type { DoctorIssue, DoctorIssueCode, DoctorReport, DoctorSummary } from "./doctor-types.js";
+import type { DoctorIssue, DoctorIssueCode, DoctorReport, DoctorSummary, DoctorSeverity } from "./doctor-types.js";
+import { doctorFixHint } from "./guidance.js";
+
+function severityTag(severity: DoctorSeverity): string {
+  return severity === "error" ? "ERROR" : severity === "warning" ? "WARN" : "INFO";
+}
 
 function matchesScope(unitId: string, scope?: string): boolean {
   if (!scope) return true;
@@ -53,8 +58,9 @@ export function formatDoctorReport(
   if (scopedIssues.length > 0) {
     lines.push("Priority issues:");
     for (const issue of scopedIssues.slice(0, maxIssues)) {
-      const prefix = issue.severity === "error" ? "ERROR" : issue.severity === "warning" ? "WARN" : "INFO";
-      lines.push(`- [${prefix}] ${issue.unitId}: ${issue.message}${issue.file ? ` (${issue.file})` : ""}`);
+      lines.push(`- [${severityTag(issue.severity)}] ${issue.unitId}: ${issue.message}${issue.file ? ` (${issue.file})` : ""}`);
+      const hint = doctorFixHint(issue.code);
+      if (hint && issue.severity !== "info") lines.push(`  Fix: ${hint}`);
     }
     if (scopedIssues.length > maxIssues) {
       lines.push(`- ...and ${scopedIssues.length - maxIssues} more in scope`);
@@ -72,10 +78,9 @@ export function formatDoctorReport(
 
 export function formatDoctorIssuesForPrompt(issues: DoctorIssue[]): string {
   if (issues.length === 0) return "- No remaining issues in scope.";
-  return issues.map(issue => {
-    const prefix = issue.severity === "error" ? "ERROR" : issue.severity === "warning" ? "WARN" : "INFO";
-    return `- [${prefix}] ${issue.unitId} | ${issue.code} | ${issue.message}${issue.file ? ` | file: ${issue.file}` : ""} | fixable: ${issue.fixable ? "yes" : "no"}`;
-  }).join("\n");
+  return issues.map(issue =>
+    `- [${severityTag(issue.severity)}] ${issue.unitId} | ${issue.code} | ${issue.message}${issue.file ? ` | file: ${issue.file}` : ""} | fixable: ${issue.fixable ? "yes" : "no"}`
+  ).join("\n");
 }
 
 /**

package/src/resources/extensions/gsd/doctor-git-checks.ts

@@ -9,7 +9,7 @@ import { parseRoadmap as parseLegacyRoadmap } from "./parsers-legacy.js";
 import { isDbAvailable, getMilestone } from "./gsd-db.js";
 import { resolveMilestoneFile } from "./paths.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
-import { createWorktree, listWorktrees, resolveGitDir, worktreesDir } from "./worktree-manager.js";
+import { allWorktreesDirs, createWorktree, listWorktrees, resolveGitDir } from "./worktree-manager.js";
 import { abortAndReset } from "./git-self-heal.js";
 import { RUNTIME_EXCLUSION_PATHS, resolveMilestoneIntegrationBranch, writeIntegrationBranch } from "./git-service.js";
 import { nativeIsRepo, nativeWorktreeList, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddTracked, nativeCommit } from "./native-git-bridge.js";
@@ -496,8 +496,8 @@ export async function checkGitHealth(
   // that is no longer registered with git. These orphaned dirs cause
   // "already exists" errors when re-creating the same worktree name.
   try {
-    const wtDir = worktreesDir(basePath);
-    if (existsSync(wtDir)) {
+    for (const wtDir of allWorktreesDirs(basePath)) {
+      if (!existsSync(wtDir)) continue;
       // Resolve symlinks and normalize separators so that symlinked .gsd
       // paths (e.g. ~/.gsd/projects/<hash>/worktrees/…) match the paths
       // returned by `git worktree list`.

package/src/resources/extensions/gsd/doctor-runtime-checks.ts

@@ -414,26 +414,31 @@ export async function checkRuntimeHealth(
         ".gsd/event-log.jsonl",
       ];
 
-      // If blanket .gsd/ or .gsd is present, all patterns are covered
+      // If blanket .gsd/ or .gsd is present, all .gsd/* patterns are covered —
+      // but NOT the .gsd-worktrees/ sibling, which always needs its own entry.
       const hasBlanketIgnore = existingLines.has(".gsd/") || existingLines.has(".gsd");
-
+      const missing: string[] = [];
+      if (!existingLines.has(".gsd-worktrees/") && !existingLines.has(".gsd-worktrees")) {
+        missing.push(".gsd-worktrees/");
+      }
       if (!hasBlanketIgnore) {
-        const missing = criticalPatterns.filter(p => !existingLines.has(p));
-        if (missing.length > 0) {
-          issues.push({
-            severity: "warning",
-            code: "gitignore_missing_patterns",
-            scope: "project",
-            unitId: "project",
-            message: `${missing.length} critical GSD runtime pattern(s) missing from .gitignore: ${missing.join(", ")}`,
-            file: ".gitignore",
-            fixable: true,
-          });
+        missing.push(...criticalPatterns.filter(p => !existingLines.has(p)));
+      }
 
-          if (shouldFix("gitignore_missing_patterns")) {
-            ensureGitignore(basePath, { manageGitignore });
-            fixesApplied.push("added missing GSD runtime patterns to .gitignore");
-          }
+      if (missing.length > 0) {
+        issues.push({
+          severity: "warning",
+          code: "gitignore_missing_patterns",
+          scope: "project",
+          unitId: "project",
+          message: `${missing.length} critical GSD runtime pattern(s) missing from .gitignore: ${missing.join(", ")}`,
+          file: ".gitignore",
+          fixable: true,
+        });
+
+        if (shouldFix("gitignore_missing_patterns")) {
+          ensureGitignore(basePath, { manageGitignore });
+          fixesApplied.push("added missing GSD runtime patterns to .gitignore");
         }
       }
     }