@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.955e4da0

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 { findWorktreeSegment } from "./worktree-root.js";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -38,27 +39,23 @@ 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;
+  const segment = findWorktreeSegment(basePath.replace(/\\/g, "/"));
+  if (!segment) return null;
 
-  // Everything before `.gsd/worktrees/` is the project root
-  return basePath.slice(0, idx);
+  // Everything before the worktree segment is the project root
+  return basePath.slice(0, segment.gsdIdx);
 }
 
 function tryExec(cmd: string, cwd: string): string | null {

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,11 +414,18 @@ 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));
+        missing.push(...criticalPatterns.filter(p => !existingLines.has(p)));
+      }
+
+      {
         if (missing.length > 0) {
           issues.push({
             severity: "warning",

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

@@ -3,11 +3,13 @@ import { join } from "node:path";
 
 import { loadFile, parseSummary, saveFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js";
-import { isDbAvailable, openDatabase, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
+import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
+import { openExistingWorkflowDatabase } from "./db-workspace.js";
 import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, milestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile, relMilestonePath, resolveGsdPathContract } from "./paths.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { loadEffectiveGSDPreferences, type GSDPreferences } from "./preferences.js";
+import { collectPreferenceDiagnostics, formatPreferenceDiagnosticDetail } from "./preferences-diagnostics.js";
 import { isClosedStatus } from "./status-guards.js";
 
 import type { DoctorIssue, DoctorIssueCode, DoctorReport } from "./doctor-types.js";
@@ -314,10 +316,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   // CLI doctor can run before any tool handler has opened the DB. Runtime
   // health checks need the existing project DB to surface DB-backed crash
   // locks, paused sessions, and coordination rows.
-  const dbPath = resolveGsdPathContract(basePath).projectDb;
-  if (existsSync(dbPath)) {
-    try { openDatabase(dbPath); } catch { /* surfaced later as db_unavailable */ }
-  }
+  openExistingWorkflowDatabase(basePath);
 
   // Issue codes that represent completion state transitions — creating summary
   // stubs, marking slices/milestones done in the roadmap. These belong to the
@@ -333,6 +332,17 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   };
 
   const prefs = loadEffectiveGSDPreferences(basePath);
+  for (const diagnostic of collectPreferenceDiagnostics(basePath)) {
+    issues.push({
+      severity: diagnostic.severity,
+      code: "invalid_preferences",
+      scope: "project",
+      unitId: "project",
+      message: `GSD preferences ${diagnostic.kind}: ${formatPreferenceDiagnosticDetail(diagnostic)}`,
+      file: diagnostic.path,
+      fixable: false,
+    });
+  }
   if (prefs) {
     const prefIssues = validatePreferenceShape(prefs.preferences);
     for (const issue of prefIssues) {

package/src/resources/extensions/gsd/error-classifier.ts

@@ -58,7 +58,7 @@ const AFFORDABILITY_RE = /requires more credits|can only afford|insufficient cre
 // are emitted by SDK/harness transports for mid-stream disconnects.
 // These indicate transient network-level interruptions.
 // See: https://github.com/open-gsd/gsd-pi/issues/4558
-const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|web ?socket|fetch failed|connection.*reset|dns|unexpected eof|stream idle timeout|partial response received/i;
+const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|web ?socket|fetch failed|connection.*reset|dns|unexpected eof|stream idle timeout|partial response received|stream ended without finish_reason/i;
 // Context overflow errors (context window/length exceeded) should be treated as server-class
 // transient errors so auto-mode can retry with reduced budget or fall back to a larger-context model.
 // See: https://github.com/open-gsd/gsd-pi/issues/4528

package/src/resources/extensions/gsd/git-conflict-state.ts

@@ -64,7 +64,23 @@ export function gitDiffCheckFailures(basePath: string): string[] | null {
       .filter(Boolean)
       .join("\n")
       .trim();
-    failures.push(output || `git diff --check ${args.join(" ")} failed`);
+
+    // git diff --check exits non-zero for both whitespace errors and leftover
+    // conflict markers. Only conflict markers block the gate — whitespace errors
+    // in staged files (common in auto-generated code) must not be misread as an
+    // unresolved merge conflict. Filter to lines git explicitly labels as
+    // "leftover conflict marker".
+    if (!output) {
+      failures.push(`git diff --check ${args.join(" ")} failed`);
+      continue;
+    }
+    const conflictMarkerLines = output
+      .split("\n")
+      .filter((line) => /leftover conflict marker/i.test(line))
+      .join("\n");
+    if (conflictMarkerLines) {
+      failures.push(conflictMarkerLines);
+    }
   }
 
   return failures;

package/src/resources/extensions/gsd/git-service.ts

@@ -359,6 +359,7 @@ export interface PreMergeCheckResult {
  * This array must stay synchronized with it.
  */
 export const RUNTIME_EXCLUSION_PATHS: readonly string[] = [
+  ".gsd-worktrees/",
   ".gsd/activity/",
   ".gsd/audit/",
   ".gsd/forensics/",