@opengsd/gsd-pi 1.4.0 → 1.5.0-dev.4fb2d460

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

@@ -1,18 +1,28 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { isAbsolute, join, relative } from "node:path";
+import { isAbsolute, join, relative, sep } from "node:path";
 
 import type { DoctorIssue } from "./doctor-types.js";
 import {
+  deleteArtifactByPath,
   getAllMilestones,
   getMilestoneSlices,
   getSliceTasks,
   isDbAvailable,
   isMemoriesFtsAvailable,
+  repairTaskCompletionFromSummary,
   _getAdapter,
 } from "./gsd-db.js";
 import { MEMORIES_FTS_REBUILT_KEY } from "./db-memory-fts-schema.js";
 import { isAfter, latestExplicitReopenAt } from "./milestone-reopen-events.js";
-import { gsdProjectionRoot, gsdRoot, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "./paths.js";
+import {
+  buildTaskFileName,
+  gsdProjectionRoot,
+  gsdRoot,
+  resolveGsdPathContract,
+  resolveMilestoneFile,
+  resolveMilestonePath,
+  resolveSliceFile,
+} from "./paths.js";
 import { deriveState } from "./state.js";
 import { isClosedStatus } from "./status-guards.js";
 import { workflowEventLogPath } from "./workflow-event-ledger.js";
@@ -20,11 +30,48 @@ import { readEvents } from "./workflow-events.js";
 import { flushWorkflowProjections } from "./projection-flush.js";
 import { parseRoadmapSlices } from "./roadmap-slices.js";
 import { parsePlan } from "./parsers-legacy.js";
+import { parseSummary } from "./files.js";
+import { LAYOUT_SEGMENTS } from "./layout-policy.js";
+
+const USER_AUTHORED_ARTIFACT_TYPES = new Set(["CONTEXT", "RESEARCH"]);
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 
 function relativeFile(basePath: string, filePath: string): string {
   return relative(basePath, filePath).split("\\").join("/");
 }
 
+function normalizedArtifactType(artifactType: string): string {
+  return artifactType.trim().toUpperCase();
+}
+
+function isUserAuthoredArtifactType(artifactType: string): boolean {
+  return USER_AUTHORED_ARTIFACT_TYPES.has(normalizedArtifactType(artifactType));
+}
+
+function userContentRecoveryCommand(artifactType: string): string {
+  return normalizedArtifactType(artifactType) === "CONTEXT" ? "/gsd discuss" : "/gsd auto";
+}
+
+function userContentMissingMessage(path: string, artifactType: string): string {
+  const type = normalizedArtifactType(artifactType) || "UNKNOWN";
+  return `Artifact \`${path}\` is a user-authored ${type} file recorded in the database but missing from disk. Re-run \`${userContentRecoveryCommand(type)}\` in this milestone to regenerate it.`;
+}
+
+function artifactPathRelativeToGsd(artifactPath: string): string {
+  const parts = artifactPath.split(/[\\/]+/);
+  const gsdIndex = parts.lastIndexOf(".gsd");
+  if (gsdIndex < 0 || gsdIndex === parts.length - 1) return artifactPath;
+  return parts.slice(gsdIndex + 1).join("/");
+}
+
+function isPathInside(basePath: string, candidatePath: string): boolean {
+  const rel = relative(basePath, candidatePath);
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
 function reportCheckboxDbStatusDivergence(
   issues: DoctorIssue[],
   basePath: string,
@@ -122,12 +169,183 @@ function isClearedByMilestoneShellProjectionFlush(
   return issue.file === relativeFile(basePath, roadmapPath);
 }
 
-function artifactExistsOnDisk(basePath: string, artifactPath: string): boolean {
-  if (isAbsolute(artifactPath)) return existsSync(artifactPath);
-  return [
-    join(gsdProjectionRoot(basePath), artifactPath),
-    join(gsdRoot(basePath), artifactPath),
-  ].some((candidate) => existsSync(candidate));
+function artifactExistsOnDisk(basePath: string, artifactPath: string, row?: ArtifactRow): boolean {
+  return resolveArtifactDiskPath(basePath, artifactPath, row) !== null;
+}
+
+function resolveLiteralArtifactDiskPath(basePath: string, artifactPath: string): string | null {
+  const relativeArtifactPath = artifactPathRelativeToGsd(artifactPath);
+  if (isAbsolute(relativeArtifactPath)) {
+    return existsSync(relativeArtifactPath) ? relativeArtifactPath : null;
+  }
+  for (const root of [gsdProjectionRoot(basePath), gsdRoot(basePath)]) {
+    const candidate = join(root, relativeArtifactPath);
+    if (isPathInside(root, candidate) && existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function relativeToGsdRoot(basePath: string, diskPath: string): string | null {
+  for (const root of [gsdProjectionRoot(basePath), gsdRoot(basePath)]) {
+    if (!isPathInside(root, diskPath)) continue;
+    return relative(root, diskPath).split("\\").join("/");
+  }
+  return null;
+}
+
+function isFlatPhaseDiskPath(basePath: string, diskPath: string): boolean {
+  return relativeToGsdRoot(basePath, diskPath)?.startsWith(`${LAYOUT_SEGMENTS.level1}/`) ?? false;
+}
+
+function hasFlatPhaseLayout(basePath: string): boolean {
+  return existsSync(join(gsdProjectionRoot(basePath), LAYOUT_SEGMENTS.level1));
+}
+
+function resolveFlatPhaseArtifactDiskPath(basePath: string, row: ArtifactRow): string | null {
+  if (!hasFlatPhaseLayout(basePath)) return null;
+  if (!row.milestone_id) return null;
+  const artifactType = normalizedArtifactType(row.artifact_type);
+  if (!artifactType) return null;
+
+  if (row.slice_id && row.task_id) {
+    const phaseDir = resolveMilestonePath(basePath, row.milestone_id);
+    if (!phaseDir || !isFlatPhaseDiskPath(basePath, phaseDir)) return null;
+    const candidate = join(phaseDir, buildTaskFileName(row.task_id, artifactType));
+    return existsSync(candidate) ? candidate : null;
+  }
+
+  const candidate = row.slice_id
+    ? resolveSliceFile(basePath, row.milestone_id, row.slice_id, artifactType)
+    : resolveMilestoneFile(basePath, row.milestone_id, artifactType);
+
+  return candidate && isFlatPhaseDiskPath(basePath, candidate) ? candidate : null;
+}
+
+function resolveArtifactDiskPath(basePath: string, artifactPath: string, row?: ArtifactRow): string | null {
+  if (row && isMilestonesArtifactPath(row.path)) {
+    const flatPath = resolveFlatPhaseArtifactDiskPath(basePath, row);
+    if (flatPath) return flatPath;
+  }
+  return resolveLiteralArtifactDiskPath(basePath, artifactPath);
+}
+
+function taskExistsInPlan(basePath: string, milestoneId: string, sliceId: string, taskId: string): boolean {
+  const planPath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN");
+  if (!planPath || !existsSync(planPath)) return false;
+  try {
+    return parsePlan(readFileSync(planPath, "utf-8")).tasks.some((task) => task.id === taskId);
+  } catch {
+    return false;
+  }
+}
+
+function isPassingVerificationResult(value: string): boolean {
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) return false;
+  if (/\b(fail(?:ed|ing)?|error|blocked|mixed|untested)\b/.test(normalized)) return false;
+  if (
+    /\b(?:not|never|no|didn't|did\s+not|cannot|can't|won't|couldn't)\s+(?:\w+\s+){0,3}?(?:pass(?:ed|ing)?|success(?:ful)?|succeeded)\b/.test(
+      normalized,
+    )
+  ) {
+    return false;
+  }
+  return /\b(pass(?:ed|ing)?|success(?:ful)?|succeeded)\b/.test(normalized) || normalized === "all-pass";
+}
+
+function readTaskCompletionEvidenceFromSummary(
+  basePath: string,
+  row: {
+    path: string;
+    milestone_id: string;
+    slice_id: string | null;
+    task_id: string | null;
+    task_status: string | null;
+    task_count: number;
+  },
+): {
+  completedAt: string;
+  verificationResult: string;
+  title: string;
+  oneLiner: string;
+  narrative: string;
+  duration: string;
+  blockerDiscovered: boolean;
+  deviations: string;
+  knownIssues: string;
+  keyFiles: string[];
+  keyDecisions: string[];
+  fullSummaryMd: string;
+} | null {
+  if (!row.slice_id || !row.task_id) return null;
+  if (!row.task_status && Number(row.task_count) > 0 && !taskExistsInPlan(basePath, row.milestone_id, row.slice_id, row.task_id)) {
+    return null;
+  }
+  const diskPath = resolveArtifactDiskPath(basePath, row.path, { ...row, artifact_type: "SUMMARY" });
+  if (!diskPath) return null;
+  try {
+    const fullSummaryMd = readFileSync(diskPath, "utf-8");
+    const summary = parseSummary(fullSummaryMd);
+    const fm = summary.frontmatter;
+    if (fm.id !== row.task_id || fm.parent !== row.slice_id || fm.milestone !== row.milestone_id) return null;
+    if (fm.blocker_discovered) return null;
+    if (!isPassingVerificationResult(fm.verification_result)) return null;
+    const completedAt = fm.completed_at.trim();
+    if (!completedAt || !Number.isFinite(Date.parse(completedAt))) return null;
+    return {
+      completedAt,
+      verificationResult: fm.verification_result.trim(),
+      title: summary.title.replace(new RegExp(`^${escapeRegExp(row.task_id)}:\\s*`), "").trim(),
+      oneLiner: summary.oneLiner,
+      narrative: summary.whatHappened,
+      duration: fm.duration,
+      blockerDiscovered: fm.blocker_discovered,
+      deviations: summary.deviations,
+      knownIssues: summary.knownLimitations,
+      keyFiles: fm.key_files.filter((file) => file !== "(none)"),
+      keyDecisions: fm.key_decisions.filter((decision) => decision !== "(none)"),
+      fullSummaryMd,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function repairTaskArtifactDbStatusDivergence(
+  basePath: string,
+  row: {
+    path: string;
+    artifact_type?: string;
+    milestone_id: string;
+    slice_id: string | null;
+    task_id: string | null;
+    task_status: string | null;
+    task_count: number;
+  },
+): boolean {
+  const evidence = readTaskCompletionEvidenceFromSummary(basePath, row);
+  if (!evidence || !row.slice_id || !row.task_id) return false;
+  repairTaskCompletionFromSummary({
+    milestoneId: row.milestone_id,
+    sliceId: row.slice_id,
+    taskId: row.task_id,
+    ...evidence,
+  });
+  return true;
+}
+
+function artifactDbStatusDivergenceFixable(
+  basePath: string,
+  row: {
+    path: string;
+    milestone_id: string;
+    slice_id: string | null;
+    task_id: string | null;
+    task_status: string | null;
+    task_count: number;
+  },
+): boolean {
+  return readTaskCompletionEvidenceFromSummary(basePath, row) !== null;
 }
 
 function artifactUnitId(row: { milestone_id: string | null; slice_id: string | null; task_id: string | null }): string {
@@ -144,10 +362,99 @@ function artifactScope(row: { milestone_id: string | null; slice_id: string | nu
   return "project";
 }
 
+type ArtifactRow = {
+  path: string;
+  artifact_type: string;
+  milestone_id: string | null;
+  slice_id: string | null;
+  task_id: string | null;
+};
+
+function sameArtifactIdentity(left: ArtifactRow, right: ArtifactRow): boolean {
+  return left.artifact_type === right.artifact_type &&
+    left.milestone_id === right.milestone_id &&
+    left.slice_id === right.slice_id &&
+    left.task_id === right.task_id;
+}
+
+function isMilestonesArtifactPath(artifactPath: string): boolean {
+  return artifactPathRelativeToGsd(artifactPath).startsWith("milestones/");
+}
+
+function expectedMilestonesArtifactPath(row: ArtifactRow): string | null {
+  if (!row.milestone_id) return null;
+  const artifactType = normalizedArtifactType(row.artifact_type);
+  if (!artifactType) return null;
+  if (row.slice_id && row.task_id) {
+    return `milestones/${row.milestone_id}/slices/${row.slice_id}/tasks/${row.task_id}-${artifactType}.md`;
+  }
+  if (row.slice_id) {
+    return `milestones/${row.milestone_id}/slices/${row.slice_id}/${row.slice_id}-${artifactType}.md`;
+  }
+  return `milestones/${row.milestone_id}/${row.milestone_id}-${artifactType}.md`;
+}
+
+function hasPresentMilestonesReplacement(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
+  const expectedPath = expectedMilestonesArtifactPath(row);
+  if (expectedPath && artifactExistsOnDisk(basePath, expectedPath)) return true;
+
+  return artifactRows.some(
+    (other) =>
+      other.path !== row.path &&
+      isMilestonesArtifactPath(other.path) &&
+      sameArtifactIdentity(row, other) &&
+      artifactExistsOnDisk(basePath, other.path),
+  );
+}
+
+function hasPresentFlatPhaseReplacement(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
+  if (resolveFlatPhaseArtifactDiskPath(basePath, row)) return true;
+
+  return artifactRows.some(
+    (other) =>
+      other.path !== row.path &&
+      !isMilestonesArtifactPath(other.path) &&
+      sameArtifactIdentity(row, other) &&
+      artifactExistsOnDisk(basePath, other.path, other),
+  );
+}
+
+function hasNoFlatPhaseFileEquivalent(row: ArtifactRow): boolean {
+  const artifactType = normalizedArtifactType(row.artifact_type);
+  if (row.slice_id && row.task_id) {
+    return artifactType === "PLAN" || artifactType === "SUMMARY";
+  }
+  return Boolean(row.slice_id && !row.task_id && artifactType === "SUMMARY");
+}
+
+function staleMilestonesArtifactRowFixable(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
+  if (!isMilestonesArtifactPath(row.path)) return false;
+  if (!hasFlatPhaseLayout(basePath)) return false;
+  if (hasPresentFlatPhaseReplacement(basePath, row, artifactRows)) return true;
+  return hasNoFlatPhaseFileEquivalent(row) && !resolveLiteralArtifactDiskPath(basePath, row.path);
+}
+
+function stalePhasesArtifactRowFixable(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
+  const issuePath = artifactPathRelativeToGsd(row.path);
+  return issuePath.startsWith(`${LAYOUT_SEGMENTS.level1}/`) && hasPresentMilestonesReplacement(basePath, row, artifactRows);
+}
+
+function staleArtifactRowFixable(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
+  return staleMilestonesArtifactRowFixable(basePath, row, artifactRows) ||
+    stalePhasesArtifactRowFixable(basePath, row, artifactRows);
+}
+
+function staleArtifactPruneMessage(row: ArtifactRow): string {
+  return isMilestonesArtifactPath(row.path)
+    ? `pruned stale legacy artifact row ${row.path}`
+    : `pruned stale flat-phase artifact row ${row.path}`;
+}
+
 export async function checkEngineHealth(
   basePath: string,
   issues: DoctorIssue[],
   fixesApplied: string[],
+  options?: { repair?: boolean },
 ): Promise<void> {
   const dbPath = resolveGsdPathContract(basePath).projectDb;
 
@@ -357,6 +664,7 @@ export async function checkEngineHealth(
       }
 
       // f. Artifact rows reference files that no longer exist on disk.
+      const missingUserContentArtifacts: Array<{ path: string; artifactType: string }> = [];
       try {
         const artifactRows = adapter
           .prepare(
@@ -365,30 +673,55 @@ export async function checkEngineHealth(
              WHERE path != ''
              ORDER BY path`,
           )
-          .all() as Array<{
-            path: string;
-            artifact_type: string;
-            milestone_id: string | null;
-            slice_id: string | null;
-            task_id: string | null;
-          }>;
+          .all() as ArtifactRow[];
 
         for (const row of artifactRows) {
-          if (artifactExistsOnDisk(basePath, row.path)) continue;
           const unitId = artifactUnitId(row);
+          const issuePath = artifactPathRelativeToGsd(row.path);
+          if (artifactExistsOnDisk(basePath, row.path)) continue;
+          if (options?.repair && staleArtifactRowFixable(basePath, row, artifactRows)) {
+            // Route the write through the Single Writer owner (gsd-db.ts) instead
+            // of issuing raw DELETE SQL here — doctor is a read-only consumer and
+            // the single-writer invariant forbids write SQL outside the allowlist.
+            deleteArtifactByPath(row.path);
+            fixesApplied.push(staleArtifactPruneMessage(row));
+            continue;
+          }
+          if (artifactExistsOnDisk(basePath, row.path, row)) continue;
+          if (isUserAuthoredArtifactType(row.artifact_type)) {
+            const artifactType = normalizedArtifactType(row.artifact_type);
+            missingUserContentArtifacts.push({ path: issuePath, artifactType });
+            issues.push({
+              severity: "warning",
+              code: "artifact_user_content_missing",
+              scope: artifactScope(row),
+              unitId,
+              message: userContentMissingMessage(issuePath, artifactType),
+              file: issuePath,
+              fixable: false,
+            });
+            continue;
+          }
           issues.push({
             severity: "error",
             code: "artifact_file_missing",
             scope: artifactScope(row),
             unitId,
-            message: `Artifact ${row.path} is recorded in the database as ${row.artifact_type || "UNKNOWN"} but no matching file exists on disk`,
-            file: row.path,
-            fixable: false,
+            message: `Artifact ${issuePath} is recorded in the database as ${row.artifact_type || "UNKNOWN"} but no matching file exists on disk`,
+            file: issuePath,
+            fixable: staleArtifactRowFixable(basePath, row, artifactRows),
           });
         }
       } catch {
         // Non-fatal — artifact file existence check failed
       }
+      if (options?.repair) {
+        for (const artifact of missingUserContentArtifacts) {
+          fixesApplied.push(
+            `skipped user-authored ${artifact.artifactType} artifact ${artifact.path} (content cannot be regenerated from the database)`,
+          );
+        }
+      }
 
       // g. Completion artifacts disagree with open DB hierarchy rows.
       try {
@@ -408,6 +741,7 @@ export async function checkEngineHealth(
           )
           .all() as Array<{
             path: string;
+            artifact_type: string;
             milestone_id: string;
             slice_id: string | null;
             task_id: string | null;
@@ -419,7 +753,7 @@ export async function checkEngineHealth(
 
         const seen = new Set<string>();
         for (const row of rows) {
-          if (!artifactExistsOnDisk(basePath, row.path)) continue;
+          if (!artifactExistsOnDisk(basePath, row.path, row)) continue;
           const reopenAt = latestExplicitReopenAt(basePath, row.milestone_id);
           if (!isAfter(row.imported_at, reopenAt)) continue;
           const isSliceSummary = row.slice_id && !row.task_id && row.slice_status && !["complete", "done", "skipped", "closed"].includes(row.slice_status);
@@ -434,13 +768,29 @@ export async function checkEngineHealth(
               : row.milestone_id;
           if (seen.has(unitId)) continue;
           seen.add(unitId);
+          const fixable = artifactDbStatusDivergenceFixable(basePath, row);
+          let repairFailed = false;
+          if (options?.repair && fixable) {
+            try {
+              if (repairTaskArtifactDbStatusDivergence(basePath, row)) {
+                fixesApplied.push(`repaired task completion from SUMMARY artifact for ${unitId}`);
+                continue;
+              }
+            } catch {
+              repairFailed = true;
+            }
+          }
           issues.push({
             severity: "error",
             code: "artifact_db_status_divergence",
             scope: row.task_id ? "task" : row.slice_id ? "slice" : "milestone",
             unitId,
-            message: `Completion artifact ${row.path} exists while DB state for ${unitId} is still open or missing. Runtime will not import it silently; run explicit recovery/repair after review.`,
-            fixable: false,
+            message: repairFailed
+              ? `Completion artifact ${row.path} exists while DB state for ${unitId} is still open or missing. Doctor found valid SUMMARY completion evidence but could not repair the database state.`
+              : fixable
+              ? `Completion artifact ${row.path} exists while DB state for ${unitId} is still open or missing. Doctor can repair this from the SUMMARY completion evidence.`
+              : `Completion artifact ${row.path} exists while DB state for ${unitId} is still open or missing. Runtime will not import it silently; run explicit recovery/repair after review.`,
+            fixable,
           });
         }
       } catch {

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

@@ -13,12 +13,13 @@
 
 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 ──────────────────────────────────────────────────────────────────────
 
@@ -49,6 +50,7 @@ const CLI_AUTH_PROVIDERS = new Set([
   "claude-code",
   "google-gemini-cli",
   "google-antigravity",
+  "cursor-agent",
 ]);
 
 /**
@@ -57,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 ───────────────────────────────────────────────
@@ -86,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;
@@ -95,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";
@@ -160,11 +164,13 @@ 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",
 ]);
 
 let asyncCliBinaryPathCache: Map<string, boolean> | null = null;
@@ -212,6 +218,18 @@ function isCliBinaryInPath(providerId: string): 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;
@@ -345,6 +363,12 @@ function resolveKeyFromAuthOrEnv(providerId: string): KeyLookup | 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;
 
@@ -354,7 +378,7 @@ function resolveKey(providerId: string): KeyLookup {
 
   // 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 };
   }
 
@@ -373,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;

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

@@ -85,6 +85,7 @@ export type DoctorIssueCode =
   | "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"
@@ -94,7 +95,10 @@ export type DoctorIssueCode =
   | "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.