@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

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

@@ -12,12 +12,14 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
+import { access, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { AuthStorage } from "@gsd/pi-coding-agent";
 import { getEnvApiKey } from "@gsd/pi-ai";
+import { isCursorAgentReadyUncached } from "../cursor-cli/readiness.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getAuthPath, PROVIDER_REGISTRY, supportsBrowserOAuth, type ProviderCategory } from "./key-manager.js";
-import { homedir } from "node:os";
 
 // ── Types ──────────────────────────────────────────────────────────────────────
 
@@ -48,6 +50,7 @@ const CLI_AUTH_PROVIDERS = new Set([
   "claude-code",
   "google-gemini-cli",
   "google-antigravity",
+  "cursor-agent",
 ]);
 
 /**
@@ -56,9 +59,9 @@ const CLI_AUTH_PROVIDERS = new Set([
  * e.g. GitHub Copilot subscriptions can access Claude and GPT models.
  */
 const PROVIDER_ROUTES: Record<string, string[]> = {
-  anthropic: ["github-copilot", "claude-code"],
-  openai: ["github-copilot", "openai-codex"],
-  google: ["google-antigravity", "google-gemini-cli"],
+  anthropic: ["github-copilot", "claude-code", "cursor-agent"],
+  openai: ["github-copilot", "openai-codex", "cursor-agent"],
+  google: ["google-antigravity", "google-gemini-cli", "cursor-agent"],
 };
 
 // ── Model → Provider ID mapping ───────────────────────────────────────────────
@@ -85,6 +88,7 @@ function modelToProviderId(model: string): string | null {
       anthropic: "anthropic",
       openai: "openai",
       "github-copilot": "github-copilot",
+      "cursor-agent": "cursor-agent",
     };
     if (prefixMap[prefix]) return prefixMap[prefix];
     return rawPrefix;
@@ -94,6 +98,7 @@ function modelToProviderId(model: string): string | null {
   if (lower.startsWith("claude"))        return "anthropic";
   if (lower.startsWith("gpt-") || lower.startsWith("o1") || lower.startsWith("o3")) return "openai";
   if (lower.startsWith("gemini"))        return "google";
+  if (lower.startsWith("composer"))      return "cursor-agent";
   if (lower.startsWith("llama") || lower.startsWith("mixtral")) return "groq";
   if (lower.startsWith("grok"))          return "xai";
   if (lower.startsWith("mistral") || lower.startsWith("codestral")) return "mistral";
@@ -159,22 +164,20 @@ const CLI_BINARY_MAP: Record<string, string[]> = {
   "claude-code": ["claude", "claude-code"],
   "google-gemini-cli": ["gemini"],
   "google-antigravity": ["agy"],
+  "cursor-agent": ["cursor-agent"],
 };
 
 const CLI_AUTH_PATH_CHECK_PROVIDERS = new Set([
   "google-gemini-cli",
   "google-antigravity",
+  "cursor-agent",
 ]);
 
-/**
- * Check if a CLI provider's binary exists anywhere in PATH.
- * Fast filesystem scan — no subprocess, no network, sub-1ms.
- */
-function isCliBinaryInPath(providerId: string): boolean {
-  const binaries = CLI_BINARY_MAP[providerId];
-  if (!binaries) return false;
+let asyncCliBinaryPathCache: Map<string, boolean> | null = null;
 
-  const pathDirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+function cliExecutableNames(providerId: string): string[] {
+  const binaries = CLI_BINARY_MAP[providerId];
+  if (!binaries) return [];
 
   // On Windows, command shims are commonly installed as .cmd/.exe/.bat/.com.
   // Scan PATHEXT candidates in addition to the bare binary name.
@@ -196,9 +199,63 @@ function isCliBinaryInPath(providerId: string): boolean {
     }
   }
 
+  return executableNames;
+}
+
+/**
+ * Check if a CLI provider's binary exists anywhere in PATH.
+ * Fast filesystem scan — no subprocess, no network, sub-1ms.
+ */
+function isCliBinaryInPath(providerId: string): boolean {
+  const cached = asyncCliBinaryPathCache?.get(providerId);
+  if (cached !== undefined) return cached;
+
+  const executableNames = cliExecutableNames(providerId);
+  if (executableNames.length === 0) return false;
+
+  const pathDirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+
   return pathDirs.some(dir => executableNames.some(name => existsSync(join(dir, name))));
 }
 
+function isExternalCliProviderReady(providerId: string): boolean {
+  if (providerId === "cursor-agent") return isCursorAgentReadyUncached();
+  return isCliBinaryInPath(providerId);
+}
+
+function cursorAgentFailureDetail(): string {
+  if (!isCliBinaryInPath("cursor-agent")) {
+    return "Install Cursor Agent and ensure `cursor-agent` is on PATH";
+  }
+  return "Run `cursor-agent login` or set CURSOR_API_KEY";
+}
+
+async function isCliBinaryInPathAsync(providerId: string): Promise<boolean> {
+  const executableNames = cliExecutableNames(providerId);
+  if (executableNames.length === 0) return false;
+
+  const pathDirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+  const candidates = pathDirs.flatMap(dir => executableNames.map(name => join(dir, name)));
+  if (candidates.length === 0) return false;
+
+  try {
+    await Promise.any(candidates.map(candidate => access(candidate)));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function loadCliBinaryPathCache(): Promise<Map<string, boolean>> {
+  const entries = await Promise.all(
+    Object.keys(CLI_BINARY_MAP).map(async providerId => [
+      providerId,
+      await isCliBinaryInPathAsync(providerId),
+    ] as const),
+  );
+  return new Map(entries);
+}
+
 function modelsJsonPaths(): string[] {
   const home = homedir();
   return [
@@ -208,7 +265,13 @@ function modelsJsonPaths(): string[] {
   ];
 }
 
+let asyncModelsJsonApiKeyCache: Set<string> | null = null;
+
 function hasModelsJsonApiKey(providerId: string): boolean {
+  if (asyncModelsJsonApiKeyCache) {
+    return asyncModelsJsonApiKeyCache.has(providerId);
+  }
+
   for (const path of modelsJsonPaths()) {
     if (!existsSync(path)) continue;
     try {
@@ -226,7 +289,27 @@ function hasModelsJsonApiKey(providerId: string): boolean {
   return false;
 }
 
-function resolveKey(providerId: string): KeyLookup {
+async function loadModelsJsonApiKeyCache(): Promise<Set<string>> {
+  const providersWithKeys = new Set<string>();
+  for (const path of modelsJsonPaths()) {
+    try {
+      const parsed = JSON.parse(await readFile(path, "utf-8")) as {
+        providers?: Record<string, { apiKey?: unknown }>;
+      };
+      for (const [providerId, provider] of Object.entries(parsed.providers ?? {})) {
+        const apiKey = provider.apiKey;
+        if (typeof apiKey === "string" && apiKey.trim().length > 0) {
+          providersWithKeys.add(providerId);
+        }
+      }
+    } catch {
+      // Missing or malformed models.json should not break dashboard health checks.
+    }
+  }
+  return providersWithKeys;
+}
+
+function resolveKeyFromAuthOrEnv(providerId: string): KeyLookup | null {
   const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
 
   if (providerId === "anthropic-vertex" && process.env.ANTHROPIC_VERTEX_PROJECT_ID) {
@@ -276,13 +359,26 @@ function resolveKey(providerId: string): KeyLookup {
     return { found: true, source: "env", backedOff: false };
   }
 
+  return null;
+}
+
+function resolveKey(providerId: string): KeyLookup {
+  if (providerId === "cursor-agent") {
+    return isExternalCliProviderReady(providerId)
+      ? { found: true, source: "env", backedOff: false }
+      : { found: false, source: "none", backedOff: false };
+  }
+
+  const direct = resolveKeyFromAuthOrEnv(providerId);
+  if (direct) return direct;
+
   if (hasModelsJsonApiKey(providerId)) {
     return { found: true, source: "models.json", backedOff: false };
   }
 
   // Cross-provider routes can use a local CLI when it is installed. Explicit
   // external CLI provider selections are handled in checkLlmProviders() below.
-  if (CLI_AUTH_PROVIDERS.has(providerId) && isCliBinaryInPath(providerId)) {
+  if (CLI_AUTH_PROVIDERS.has(providerId) && isExternalCliProviderReady(providerId)) {
     return { found: true, source: "env", backedOff: false };
   }
 
@@ -301,17 +397,22 @@ function checkLlmProviders(): ProviderCheckResult[] {
     if (CLI_AUTH_PROVIDERS.has(providerId)) {
       const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
       const label = info?.label ?? providerId;
-      if (CLI_AUTH_PATH_CHECK_PROVIDERS.has(providerId) && !isCliBinaryInPath(providerId)) {
+      if (CLI_AUTH_PATH_CHECK_PROVIDERS.has(providerId) && !isExternalCliProviderReady(providerId)) {
         const binaries = CLI_BINARY_MAP[providerId]?.map(binary => `\`${binary}\``).join(" or ");
+        const detail = providerId === "cursor-agent"
+          ? cursorAgentFailureDetail()
+          : binaries
+          ? `Install ${label} and ensure ${binaries} is on PATH`
+          : `Install ${label} and ensure its CLI is on PATH`;
         results.push({
           name: providerId,
           label,
           category: "llm",
           status: "error",
-          message: `${label} — CLI not found`,
-          detail: binaries
-            ? `Install ${label} and ensure ${binaries} is on PATH`
-            : `Install ${label} and ensure its CLI is on PATH`,
+          message: providerId === "cursor-agent" && isCliBinaryInPath(providerId)
+            ? `${label} — CLI not authenticated`
+            : `${label} — CLI not found`,
+          detail,
           required: true,
         });
         continue;
@@ -495,6 +596,28 @@ export function runProviderChecks(): ProviderCheckResult[] {
   return results;
 }
 
+/**
+ * Non-blocking equivalent of `runProviderChecks` for the health-widget
+ * background refresh. PATH checks and custom models.json discovery use async
+ * filesystem APIs so periodic widget refreshes do not stall the input loop.
+ */
+export async function runProviderChecksAsync(): Promise<ProviderCheckResult[]> {
+  const [cliCache, modelsJsonCache] = await Promise.all([
+    loadCliBinaryPathCache(),
+    loadModelsJsonApiKeyCache(),
+  ]);
+  const previousCliCache = asyncCliBinaryPathCache;
+  const previousModelsJsonCache = asyncModelsJsonApiKeyCache;
+  asyncCliBinaryPathCache = cliCache;
+  asyncModelsJsonApiKeyCache = modelsJsonCache;
+  try {
+    return runProviderChecks();
+  } finally {
+    asyncCliBinaryPathCache = previousCliCache;
+    asyncModelsJsonApiKeyCache = previousModelsJsonCache;
+  }
+}
+
 /**
  * Format provider check results as a human-readable report string.
  */

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

@@ -12,7 +12,7 @@ import { getActiveAutoWorkers } from "./db/auto-workers.js";
 import { normalizeRealPath } from "./paths.js";
 import { ensureGitignore, isGsdGitignored } from "./gitignore.js";
 import { readAllSessionStatuses, isSessionStale, removeSessionStatus } from "./session-status-io.js";
-import { recoverFailedMigration } from "./migrate-external.js";
+import { isCurrentGsdStateIntactForMigratingCleanup, recoverFailedMigration } from "./migrate-external.js";
 import { splitCompletedKey } from "./forensics.js";
 import { findMilestoneIds } from "./milestone-ids.js";
 import { getAllMilestones, isDbAvailable } from "./gsd-db.js";
@@ -20,19 +20,6 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 
 const MAX_UAT_ATTEMPTS = 3;
 
-function isCurrentGsdStateIntactForMigratingCleanup(basePath: string): boolean {
-  try {
-    const stateFile = resolveGsdRootFile(basePath, "STATE");
-    const milestonesPath = milestonesDir(basePath);
-    const dbPath = join(gsdRoot(basePath), "gsd.db");
-    const hasDbFile = existsSync(dbPath);
-    const hasNonEmptyDb = hasDbFile && statSync(dbPath).size > 0;
-    return existsSync(stateFile) && existsSync(milestonesPath) && hasNonEmptyDb;
-  } catch {
-    return false;
-  }
-}
-
 function hasAssessmentVerdict(basePath: string, mid: string, sid: string): boolean {
   const assessmentPath = join(gsdRoot(basePath), "milestones", mid, "slices", sid, `${sid}-ASSESSMENT.md`);
   if (!existsSync(assessmentPath)) return false;
@@ -421,6 +408,9 @@ export async function checkRuntimeHealth(
       if (!existingLines.has(".gsd-worktrees/") && !existingLines.has(".gsd-worktrees")) {
         missing.push(".gsd-worktrees/");
       }
+      if (!existingLines.has(".gsd-backups/") && !existingLines.has(".gsd-backups")) {
+        missing.push(".gsd-backups/");
+      }
       if (!hasBlanketIgnore) {
         missing.push(...criticalPatterns.filter(p => !existingLines.has(p)));
       }
@@ -467,7 +457,7 @@ export async function checkRuntimeHealth(
 
         if (shouldFix("failed_migration")) {
           if (recoverFailedMigration(basePath)) {
-            fixesApplied.push("recovered failed migration (.gsd.migrating → .gsd)");
+            fixesApplied.push("recovered failed external state migration");
           } else if (isCurrentGsdStateIntactForMigratingCleanup(basePath)) {
             try {
               rmSync(migratingPath, { recursive: true, force: true });

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

@@ -2,6 +2,7 @@
 export type DoctorSeverity = "info" | "warning" | "error";
 export type DoctorIssueCode =
   | "invalid_preferences"
+  | "missing_roadmap"
   | "missing_tasks_dir"
   | "missing_slice_plan"
   | "all_slices_done_missing_milestone_validation"
@@ -83,14 +84,21 @@ export type DoctorIssueCode =
   | "db_orphaned_task"
   | "db_orphaned_slice"
   | "db_done_task_no_summary"
+  | "artifact_file_missing"
+  | "artifact_user_content_missing"
   | "artifact_db_status_divergence"
+  | "checkbox_db_status_divergence"
   | "completed_milestone_reopened"
   | "db_duplicate_id"
   | "db_unavailable"
+  | "memories_fts_rebuild_missing"
   | "projection_drift"
   // Milestone filesystem/DB drift (#4996)
   | "orphan_milestone_dir"
-  | "orphan_milestone_db";
+  | "orphan_milestone_db"
+  // Parent-workspace declared repository checks (#818)
+  | "workspace_repo_path_missing"
+  | "workspace_repo_not_a_repo";
 
 /**
  * Issue codes that represent global or completion-critical state.

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

@@ -1,11 +1,13 @@
-import { existsSync, mkdirSync, lstatSync, readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
 
 import { loadFile, parseSummary, saveFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.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 { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, milestonesDir, legacyMilestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile, relMilestonePath, resolveGsdPathContract } from "./paths.js";
+import { findMilestoneIds } from "./milestone-ids.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { loadEffectiveGSDPreferences, type GSDPreferences } from "./preferences.js";
@@ -15,6 +17,8 @@ import { isClosedStatus } from "./status-guards.js";
 import type { DoctorIssue, DoctorIssueCode, DoctorReport } from "./doctor-types.js";
 import { GLOBAL_STATE_CODES } from "./doctor-types.js";
 import type { RoadmapSliceEntry } from "./types.js";
+import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
+import { createRepositoryRegistryFromPreferences } from "./repository-registry.js";
 import { checkGitHealth, checkRuntimeHealth, checkGlobalHealth, checkEngineHealth } from "./doctor-checks.js";
 import { checkEnvironmentHealth } from "./doctor-environment.js";
 import { runProviderChecks } from "./doctor-providers.js";
@@ -194,7 +198,8 @@ export async function selectDoctorScope(basePath: string, requestedScope?: strin
   }
 
   const milestonesPath = milestonesDir(basePath);
-  if (!existsSync(milestonesPath)) return undefined;
+  const legacyMilestonesPath = legacyMilestonesDir(basePath);
+  if (!existsSync(milestonesPath) && !existsSync(legacyMilestonesPath)) return undefined;
 
   for (const milestone of state.registry) {
     const roadmapPath = resolveMilestoneFile(basePath, milestone.id, "ROADMAP");
@@ -306,6 +311,94 @@ export async function readDoctorHistory(basePath: string, lastN = 50): Promise<D
   } catch { return []; }
 }
 
+/**
+ * Resolve the git working-tree root for a path, or null if it is not a repo.
+ * Used by the workspace-repository probe to check that a declared child path is
+ * itself a git repository (not merely nested inside the parent's repo).
+ */
+function resolveGitToplevel(cwd: string): string | null {
+  try {
+    const out = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+      env: GIT_NO_PROMPT_ENV,
+    }).trim();
+    return out ? resolve(out) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** realpath that falls back to the resolved path if the link cannot be read. */
+function realpathSafe(p: string): string {
+  try {
+    return realpathSync(p);
+  } catch {
+    return resolve(p);
+  }
+}
+
+/**
+ * Parent-workspace probe (#818): validate that every declared child repository
+ * exists on disk and is a git repository at its own root. The registry only
+ * checks paths stay inside the project root; it never checks existence or
+ * git-ness, so a typo'd path (e.g. `frontned`) would otherwise build cleanly
+ * and silently produce "no problems found." No-op for single-repo projects.
+ */
+function checkWorkspaceRepositoryHealth(
+  basePath: string,
+  prefs: GSDPreferences | undefined,
+  issues: DoctorIssue[],
+): void {
+  if (prefs?.workspace?.mode !== "parent") return;
+  let registry;
+  try {
+    registry = createRepositoryRegistryFromPreferences(basePath, prefs);
+  } catch (err) {
+    issues.push({
+      severity: "error",
+      code: "invalid_preferences",
+      scope: "project",
+      unitId: "workspace",
+      message: `workspace registry failed to build: ${err instanceof Error ? err.message : String(err)}`,
+      fixable: false,
+    });
+    return;
+  }
+  for (const repo of registry.repositories) {
+    if (repo.id === "project") continue;
+    if (!existsSync(repo.root)) {
+      issues.push({
+        severity: "error",
+        code: "workspace_repo_path_missing",
+        scope: "project",
+        unitId: `workspace.repositories.${repo.id}`,
+        message: `declared repository "${repo.id}" path does not exist on disk: ${repo.root}`,
+        fixable: false,
+      });
+      continue;
+    }
+    // Must be a repo at its OWN root — a plain dir nested in the parent repo
+    // would otherwise pass a bare `nativeIsRepo` check via the enclosing
+    // parent's .git. Compare on realpath so symlinked temp roots (macOS
+    // /var vs /private/var) don't cause a false mismatch.
+    const toplevel = resolveGitToplevel(repo.root);
+    const declaredReal = realpathSafe(repo.root);
+    const toplevelReal = toplevel ? realpathSafe(toplevel) : null;
+    if (toplevelReal !== declaredReal) {
+      issues.push({
+        severity: "warning",
+        code: "workspace_repo_not_a_repo",
+        scope: "project",
+        unitId: `workspace.repositories.${repo.id}`,
+        message: `declared repository "${repo.id}" path is not a git repository at its own root: ${repo.root}`,
+        fixable: false,
+      });
+    }
+  }
+}
+
 export async function runGSDDoctor(basePath: string, options?: { fix?: boolean; dryRun?: boolean; scope?: string; fixLevel?: "task" | "all"; isolationMode?: "none" | "worktree" | "branch"; includeBuild?: boolean; includeTests?: boolean }): Promise<DoctorReport> {
   const issues: DoctorIssue[] = [];
   const fixesApplied: string[] = [];
@@ -363,7 +456,8 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   const isolationMode: "none" | "worktree" | "branch" = options?.isolationMode ??
     (prefs?.preferences?.git?.isolation === "worktree" ? "worktree" :
     prefs?.preferences?.git?.isolation === "branch" ? "branch" : "none");
-  await checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode);
+  await checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode, dryRun);
+  checkWorkspaceRepositoryHealth(basePath, prefs?.preferences, issues);
   const gitMs = Date.now() - t0git;
 
   // Runtime health checks — timed
@@ -384,10 +478,11 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   const envMs = Date.now() - t0env;
 
   // Engine health checks — DB constraints and projection drift
-  await checkEngineHealth(basePath, issues, fixesApplied);
+  await checkEngineHealth(basePath, issues, fixesApplied, { repair: fix && !dryRun });
 
   const milestonesPath = milestonesDir(basePath);
-  if (!existsSync(milestonesPath)) {
+  const legacyMilestonesPath2 = legacyMilestonesDir(basePath);
+  if (!existsSync(milestonesPath) && !existsSync(legacyMilestonesPath2)) {
     const report: DoctorReport = { ok: issues.every(i => i.severity !== "error"), basePath, issues, fixesApplied, timing: { git: gitMs, runtime: runtimeMs, environment: envMs, gsdState: 0 } };
     await appendDoctorHistory(basePath, report);
     return report;
@@ -432,7 +527,15 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
     }
   }
 
-  for (const milestone of state.registry) {
+  // When DB is unavailable, state.registry is empty. Fall back to a direct
+  // filesystem scan so the doctor can still report issues (e.g. missing ROADMAP)
+  // for milestone dirs that exist on disk.
+  const milestoneEntries: Array<{ id: string; title: string }> =
+    state.registry.length > 0
+      ? state.registry
+      : findMilestoneIds(basePath).map(id => ({ id, title: id }));
+
+  for (const milestone of milestoneEntries) {
     const milestoneId = milestone.id;
     const milestonePath = resolveMilestonePath(basePath, milestoneId);
     if (!milestonePath) continue;
@@ -471,7 +574,17 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
 
     const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
     const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
-    if (!roadmapContent) continue;
+    if (!roadmapContent) {
+      issues.push({
+        severity: "error",
+        code: "missing_roadmap",
+        scope: "milestone",
+        unitId: milestoneId,
+        message: `Milestone ${milestoneId} is missing its ROADMAP.md file.`,
+        fixable: false,
+      });
+      continue;
+    }
 
     // Normalize slices: prefer DB, fall back to parser
     type NormSlice = RoadmapSliceEntry & { pending?: boolean; skipped?: boolean };
@@ -612,6 +725,8 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
         // Pending slices haven't been planned yet — tasks/ is created on demand.
         // Skipped slices may legitimately never create tasks/.
         if (slice.pending || slice.skipped) continue;
+        // Flat-phase: tasks are embedded in plan files; no tasks/ subdir expected.
+        if (!existsSync(legacyMilestonesDir(basePath))) continue;
         issues.push({
           severity: slice.done ? "warning" : "error",
           code: "missing_tasks_dir",
@@ -781,7 +896,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
         code: "all_slices_done_missing_milestone_validation",
         scope: "milestone",
         unitId: milestoneId,
-        message: `All slices are done but ${milestoneId}-VALIDATION.md is missing \u2014 milestone is in validating-milestone phase`,
+        message: `All slices are done but the milestone VALIDATION.md is missing \u2014 milestone is in validating-milestone phase`,
         file: relMilestoneFile(basePath, milestoneId, "VALIDATION"),
         fixable: false,
       });

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

@@ -10,7 +10,7 @@
  * @see https://github.com/open-gsd/gsd-pi/issues/2577
  */
 
-import { TOOL_SURFACE_NOT_READY } from "./tool-surface-readiness.js";
+import { TOOL_SURFACE_NOT_READY, isTerminalToolSurfaceError } from "./tool-surface-readiness.js";
 
 // ── ErrorClass discriminated union ──────────────────────────────────────────
 
@@ -114,7 +114,20 @@ export function classifyError(errorMsg: string, retryAfterMs?: number): ErrorCla
     return { kind: "tool-schema", retryAfterMs: 0 };
   }
 
+  // Terminal tool-surface failure: the workflow MCP server is in a
+  // non-self-healing status (failed / needs-auth / disabled). This is NOT
+  // transient — retrying the same model cannot repair a dead server, so it
+  // must escalate / pause rather than retrying every ~3s into the per-unit
+  // cost cap. Checked ahead of the transient readiness branch below, which
+  // shares the TOOL_SURFACE_NOT_READY prefix and would otherwise collapse the
+  // terminal case into a transient `network` retry. See #783.
+  if (isTerminalToolSurfaceError(errorMsg)) {
+    return { kind: "permanent" };
+  }
+
   // Tool-surface readiness abort — transient; retry the same model shortly.
+  // This covers the not-yet-connected variants (absent, pending, connected but
+  // not registered); terminal statuses were handled by the branch above.
   if (TOOL_SURFACE_NOT_READY_RE.test(errorMsg)) {
     return { kind: "network", retryAfterMs: retryAfterMs ?? 3_000 };
   }

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

@@ -10,7 +10,7 @@ import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import type { EscalationArtifact, EscalationOption } from "./types.js";
-import { resolveSlicePath } from "./paths.js";
+import { legacyMilestonesDir, resolveSlicePath, resolveTasksDir } from "./paths.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import {
   getTask,
@@ -35,9 +35,14 @@ import { logWarning } from "./workflow-logger.js";
 export function escalationArtifactPath(
   basePath: string, milestoneId: string, sliceId: string, taskId: string,
 ): string | null {
-  const sDir = resolveSlicePath(basePath, milestoneId, sliceId);
-  if (!sDir) return null;
-  return join(sDir, "tasks", `${taskId}-ESCALATION.json`);
+  const tDir = resolveTasksDir(basePath, milestoneId, sliceId);
+  if (tDir) return join(tDir, `${taskId}-ESCALATION.json`);
+  // Flat-phase: tasks live in plan files; escalation artifacts sit in the phase dir.
+  // Legacy without tasks/: return null so writeEscalationArtifact throws (run doctor).
+  if (existsSync(legacyMilestonesDir(basePath))) return null;
+  const phaseDir = resolveSlicePath(basePath, milestoneId, sliceId);
+  if (!phaseDir) return null;
+  return join(phaseDir, `${taskId}-ESCALATION.json`);
 }
 
 // ─── Artifact I/O ─────────────────────────────────────────────────────────