gsd-pi 2.78.0 → 2.78.1-dev.2d3fd6e71

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

@@ -0,0 +1,197 @@
+// Delegation policy — codifies which GSD MCP tools are safe to run as
+// background sub-agents while the foreground /gsd flow continues. Verdicts
+// are derived from the round-1 and round-2 evaluations recorded in this
+// branch's PR description; the rationale field on each entry preserves
+// the reason so future changes have to revisit the analysis explicitly.
+//
+// Default-deny: unknown tools are never backgroundable.
+//
+// ─── Tool-name vs unit-type namespaces ───────────────────────────────────
+// Entries are keyed by canonical MCP tool name (`gsd_*`). The optional
+// `unitType` field is a *secondary* index for the dispatcher's convenience
+// — it bridges this policy to `auto-dispatch.ts`' `DispatchAction.unitType`
+// values. The two namespaces are not 1:1:
+//
+//   - Some tools have no corresponding unit type (e.g. `gsd_doctor`,
+//     `gsd_plan_task`) and intentionally omit `unitType`.
+//   - Some unit types share a tool — e.g. `execute-task`, `execute-task-simple`,
+//     and `reactive-execute` all invoke `gsd_execute`. The current shape
+//     allows only one `unitType` per entry, so those units fall through to
+//     `getVerdictByUnitType() === null` (→ `backgroundable: false`) even
+//     though `gsd_execute` itself is GOOD. This is the intended default-deny
+//     posture until a future PR wires actual background dispatch and
+//     decides whether each unit-level orchestration is safe — the unit
+//     wraps a prompt, harness setup, and post-processing on top of the
+//     tool, and the tool's safety doesn't transfer automatically.
+//
+// Auto-dispatch produces 20 distinct unit types; only 5 are explicitly
+// classified here. The other 15 default-deny:
+//   complete-milestone, complete-slice, discuss-milestone, discuss-project,
+//   discuss-requirements, execute-task, execute-task-simple, gate-evaluate,
+//   reactive-execute, refine-slice, research-decision, research-milestone,
+//   research-project, research-slice, rewrite-docs, run-uat
+//
+// Adding a `unitType` mapping (or a future `unitTypes: string[]`) to an
+// existing entry is the place to lift any of these out of default-deny
+// when the analysis has been done.
+
+export type BackgroundabilityVerdict = "good" | "risky" | "no";
+
+export interface DelegationPolicyEntry {
+  /** Canonical MCP tool name (the verb_object form, e.g. `gsd_plan_slice`). */
+  toolName: string;
+  /** Workflow unit type from auto-dispatch.ts, when one exists. */
+  unitType?: string;
+  verdict: BackgroundabilityVerdict;
+  /** One-line justification grounded in the evaluation findings. */
+  rationale: string;
+  /**
+   * Constraints the caller MUST satisfy when dispatching this unit in the
+   * background. Only populated for `good` and conditional `risky` entries.
+   */
+  constraints?: string[];
+}
+
+const POLICY: Record<string, DelegationPolicyEntry> = {
+  gsd_plan_slice: {
+    toolName: "gsd_plan_slice",
+    unitType: "plan-slice",
+    verdict: "good",
+    rationale:
+      "Self-contained, no user prompts, atomic DB tx; existing slice-parallel-orchestrator pattern transfers cleanly.",
+    constraints: [
+      "Lock the slice from further user discussion once dispatched (context is frozen at dispatch time).",
+      "Foreground must not derive state for that slice while the transaction is in flight.",
+      "Foreground must await background completion before any tool reads the planned tasks/gates.",
+    ],
+  },
+  gsd_execute: {
+    toolName: "gsd_execute",
+    // No `unitType` set on purpose — the underlying tool is safe, but the
+    // unit-level orchestrations that invoke it (`execute-task`,
+    // `execute-task-simple`, `reactive-execute`) wrap additional prompt and
+    // harness work whose safety is a separate analysis. Default-deny those
+    // units until that analysis is recorded; adding `unitType` here would
+    // promote them silently.
+    verdict: "good",
+    rationale:
+      "No DB writes; UUID-isolated stdout/stderr/meta files; existing reactive-execute parallel-subagent precedent.",
+  },
+  gsd_validate_milestone: {
+    toolName: "gsd_validate_milestone",
+    unitType: "validate-milestone",
+    verdict: "good",
+    rationale:
+      "Verdict pre-computed by parallel reviewers; atomic DB tx plus isolated VALIDATION.md write; no user interaction.",
+  },
+  gsd_reassess_roadmap: {
+    toolName: "gsd_reassess_roadmap",
+    unitType: "reassess-roadmap",
+    verdict: "good",
+    rationale:
+      "Narrower mutation scope than plan_milestone; structural guards prevent modification of completed slices.",
+  },
+  gsd_doctor: {
+    toolName: "gsd_doctor",
+    verdict: "risky",
+    rationale:
+      "Diagnostic-only mode (fix=false) is safe to background; fix=true writes STATE.md/ROADMAP.md without session-lock coordination and can race the foreground flow.",
+    constraints: [
+      "Background only with fix=false (diagnostic-only).",
+      "Apply fixes synchronously, only when no foreground unit is dispatched.",
+    ],
+  },
+  gsd_plan_milestone: {
+    toolName: "gsd_plan_milestone",
+    unitType: "plan-milestone",
+    verdict: "risky",
+    rationale:
+      "Inputs require CONTEXT.md from discuss-milestone, so initial questioning is already done by the time it can start; TOCTOU guards and projection coherence make concurrency unsafe.",
+  },
+  gsd_replan_slice: {
+    toolName: "gsd_replan_slice",
+    unitType: "replan-slice",
+    verdict: "risky",
+    rationale:
+      "Blocks the replanning→executing state transition on a gate that waits for S##-REPLAN.md; background failure leaves the flow stuck.",
+  },
+  gsd_plan_task: {
+    toolName: "gsd_plan_task",
+    verdict: "no",
+    rationale:
+      "plan-slice prompt explicitly forbids calling gsd_plan_task separately; per-task granularity multiplies manifest writes and projection re-renders with no payoff.",
+  },
+};
+
+// 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;
+}
+
+export function getDelegationVerdict(toolName: string): DelegationPolicyEntry | null {
+  return POLICY[resolveCanonical(toolName)] ?? null;
+}
+
+export function isBackgroundable(toolName: string): boolean {
+  const entry = getDelegationVerdict(toolName);
+  return entry?.verdict === "good";
+}
+
+export function listBackgroundableTools(): string[] {
+  return Object.values(POLICY)
+    .filter((entry) => entry.verdict === "good")
+    .map((entry) => entry.toolName)
+    .sort();
+}
+
+export function getVerdictByUnitType(unitType: string): DelegationPolicyEntry | null {
+  for (const entry of Object.values(POLICY)) {
+    if (entry.unitType === unitType) return entry;
+  }
+  return null;
+}
+
+/**
+ * Minimal shape of a dispatch action that the annotator needs to operate on.
+ * Matches the `dispatch` and non-dispatch variants of auto-dispatch.ts'
+ * DispatchAction without depending on it (so this module stays free of
+ * workspace-package transitive imports).
+ */
+export type AnnotatableDispatchAction =
+  | { action: "dispatch"; unitType: string; backgroundable?: boolean; [k: string]: unknown }
+  | { action: "stop"; [k: string]: unknown }
+  | { action: "skip"; [k: string]: unknown };
+
+/**
+ * Annotates a dispatch action in place with `backgroundable: true` when its
+ * unitType has a `good` verdict in the policy. Stop/skip actions pass through
+ * unchanged. Default-deny: unknown unit types resolve to `false`.
+ *
+ * **Mutation contract.** The `backgroundable` field is written directly onto
+ * the passed action object. This is intentional — every dispatch path in
+ * `auto-dispatch.ts` constructs a fresh action object per `where(ctx)` /
+ * `evaluateDispatch(ctx)` invocation, so in-place mutation cannot leak across
+ * dispatch cycles. Future dispatch rules MUST follow that convention: never
+ * cache or share `DispatchAction` objects across calls. If you need to cache,
+ * either freeze the cached object (`Object.freeze`) and clone on read, or
+ * stop calling `annotateBackgroundable` on the shared instance. The annotator
+ * always recomputes from the policy on every call (no internal cache), so
+ * repeated invocations on the same object will overwrite stale values
+ * deterministically — see the `annotateBackgroundable recomputes on each call`
+ * test for the contract pin.
+ */
+export function annotateBackgroundable<T extends AnnotatableDispatchAction>(action: T): T {
+  if (action.action !== "dispatch") return action;
+  const verdict = getVerdictByUnitType(action.unitType);
+  action.backgroundable = verdict?.verdict === "good";
+  return action;
+}

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

@@ -10,8 +10,8 @@ import { existsSync, openSync, readSync, closeSync, readdirSync, readFileSync, s
 import { dirname, join, parse as parsePath } from "node:path";
 import { homedir } from "node:os";
 import { gsdRoot } from "./paths.js";
+import { gsdHome } from "./gsd-home.js";
 
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 
 // ─── Types ──────────────────────────────────────────────────────────────────────
 
@@ -720,8 +720,8 @@ function detectVerificationCommands(
  */
 export function hasGlobalSetup(): boolean {
   return (
-    existsSync(join(gsdHome, "PREFERENCES.md")) ||
-    existsSync(join(gsdHome, "preferences.md"))
+    existsSync(join(gsdHome(), "PREFERENCES.md")) ||
+    existsSync(join(gsdHome(), "preferences.md"))
   );
 }
 
@@ -730,18 +730,18 @@ export function hasGlobalSetup(): boolean {
  * Returns true if ~/.gsd/ doesn't exist or has no preferences or auth.
  */
 export function isFirstEverLaunch(): boolean {
-  if (!existsSync(gsdHome)) return true;
+  if (!existsSync(gsdHome())) return true;
 
   // If we have preferences, not first launch
   if (
-    existsSync(join(gsdHome, "PREFERENCES.md")) ||
-    existsSync(join(gsdHome, "preferences.md"))
+    existsSync(join(gsdHome(), "PREFERENCES.md")) ||
+    existsSync(join(gsdHome(), "preferences.md"))
   ) {
     return false;
   }
 
   // If we have auth.json, not first launch (onboarding.ts already ran)
-  if (existsSync(join(gsdHome, "agent", "auth.json"))) return false;
+  if (existsSync(join(gsdHome(), "agent", "auth.json"))) return false;
 
   // Check legacy path too
   const legacyPath = join(homedir(), ".pi", "agent", "gsd-preferences.md");

package/src/resources/extensions/gsd/dispatch-guard.ts

@@ -54,21 +54,16 @@ export function getPriorSliceCompletionBlocker(
     // completion, which is wrong when the SUMMARY is a failure-path report
     // (verification FAILED, blocker placeholder, etc.). Resolve as follows:
     //   1. When DB is available and status is closed → skip (authoritative).
-    //   2. When SUMMARY exists but looks like a failure/blocker report →
-    //      do not short-circuit; fall through to the slice-level check so
-    //      the guard can still block dependents of an active milestone.
-    //   3. Otherwise (SUMMARY without failure markers) → skip. Preserves
-    //      the #1716 contract where a completed milestone with unchecked
-    //      remediation slices is still treated as done.
-    const summaryPath = resolveMilestoneFile(base, mid, "SUMMARY");
+    //   2. When DB is unavailable, legacy SUMMARY.md fallback may skip.
+    //      DB-backed projects must not treat SUMMARY.md as authoritative.
     if (isDbAvailable()) {
       const milestoneRow = getMilestone(mid);
       if (milestoneRow && isClosedStatus(milestoneRow.status)) continue;
-    }
-    if (summaryPath) {
+    } else {
+      const summaryPath = resolveMilestoneFile(base, mid, "SUMMARY");
       let summaryContent: string | null = null;
-      try { summaryContent = readFileSync(summaryPath, "utf-8"); } catch { /* ignore */ }
-      if (!summaryContent || classifyMilestoneSummaryContent(summaryContent) !== "failure") {
+      try { summaryContent = summaryPath ? readFileSync(summaryPath, "utf-8") : null; } catch { /* ignore */ }
+      if (summaryContent && classifyMilestoneSummaryContent(summaryContent) !== "failure") {
         continue;
       }
     }

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

@@ -87,7 +87,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   | `git.push_branches`    | `false`      | `true`       |
   | `git.pre_merge_check`  | `false`      | `true`       |
   | `git.merge_strategy`   | `"squash"`   | `"squash"`   |
-  | `git.isolation`        | `"worktree"` | `"worktree"` |
+  | `git.isolation`        | `"none"`     | `"none"`     |
   | `unique_milestone_ids` | `false`      | `true`       |
 
   Quick setup: `/gsd mode` (global) or `/gsd mode project` (project-level).
@@ -126,6 +126,8 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `idle_timeout_minutes`: minutes of inactivity before the supervisor intervenes (default: 10).
   - `hard_timeout_minutes`: minutes before the supervisor forces termination (default: 30).
 
+- `min_request_interval_ms`: number — minimum integer milliseconds between auto-mode LLM request dispatches. Non-integer values are rounded down (e.g., `1000.9 → 1000`). Use this to proactively slow auto-mode on rate-limited providers and reduce 429 errors. Set to `0` to disable. Default: `0` (disabled).
+
 - `git`: configures GSD's git behavior. All fields are optional — omit any to use defaults. Keys:
   - `auto_push`: boolean — automatically push commits to the remote after committing. Default: `false`.
   - `push_branches`: boolean — push the milestone branch to the remote after commits. Default: `false`.
@@ -135,7 +137,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `commit_type`: string — override the conventional commit type prefix. Must be one of: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`, `build`, `style`. Default: inferred from diff content.
   - `main_branch`: string — the primary branch name for new git repos (e.g., `"main"`, `"master"`, `"trunk"`). Also used by `getMainBranch()` as the preferred branch when auto-detection is ambiguous. Default: `"main"`.
   - `merge_strategy`: `"squash"` or `"merge"` — controls how worktree branches are merged back. `"squash"` combines all commits into one; `"merge"` preserves individual commits. Default: `"squash"`.
-  - `isolation`: `"worktree"`, `"branch"`, or `"none"` — controls auto-mode git isolation strategy. `"worktree"` creates a milestone worktree for isolated work; `"branch"` works directly in the project root but creates a milestone branch (useful for submodule-heavy repos); `"none"` works directly on the current branch with no worktree or milestone branch (ideal for step-mode with hot reloads). Default: `"worktree"`.
+  - `isolation`: `"none"`, `"worktree"`, or `"branch"` — controls auto-mode git isolation strategy. `"none"` works directly on the current branch with no worktree or milestone branch (default, ideal for step-mode with hot reloads); `"worktree"` creates a milestone worktree for isolated work; `"branch"` works directly in the project root but creates a milestone branch (useful for submodule-heavy repos). `worktree` requires a committed `HEAD`; in a zero-commit repo, GSD temporarily treats it as `none` until the first commit exists. Default: `"none"`.
   - `manage_gitignore`: boolean — when `false`, GSD will not touch `.gitignore` at all. Useful when your project has a strictly managed `.gitignore` and you don't want GSD adding entries. Default: `true`.
   - `worktree_post_create`: string — script to run after a worktree is created (both auto-mode and manual `/worktree`). Receives `SOURCE_DIR` and `WORKTREE_DIR` as environment variables. Can be absolute or relative to project root. Runs with 30-second timeout. Failure is non-fatal (logged as warning). Default: none.
   - `auto_pr`: boolean — automatically create a GitHub pull request after a milestone branch is merged. Requires `gh` CLI to be installed. Default: `false`.
@@ -157,12 +159,20 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
 - `token_profile`: `"budget"`, `"balanced"`, `"quality"`, or `"burn-max"` — coordinates model selection, phase skipping, and context compression. `budget` skips research/reassessment and uses cheaper models; `balanced` (default) skips research/reassessment to reduce token burn; `quality` prefers higher-quality models; `burn-max` keeps full-context defaults, disables downgrade routing, and keeps phase skips off.
 
+- `planning_depth`: `"light"` or `"deep"` — controls project-level discovery before milestone planning. `"light"` is the default milestone discussion flow. `"deep"` runs workflow preferences, project discussion, requirements discussion, a research-decision gate, and optional project research before milestone planning. Enable it with `/gsd new-project --deep`, `/gsd new-milestone --deep`, or by setting `planning_depth: deep` in project-local `.gsd/PREFERENCES.md`. Global `~/.gsd/PREFERENCES.md` does not opt every fresh repo into deep mode. Deep mode writes `.gsd/PROJECT.md`, `.gsd/REQUIREMENTS.md`, `.gsd/runtime/research-decision.json`, and, when research is approved, `.gsd/research/STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, and `PITFALLS.md`.
+
 - `phases`: fine-grained control over which phases run. Usually set by `token_profile`, but can be overridden. Keys:
   - `skip_research`: boolean — skip milestone-level research. Default: `false`.
   - `reassess_after_slice`: boolean — run a dedicated roadmap-reassessment unit after each completed slice. Default: `false` (per ADR-003 §4). The plan-slice agent for the next slice performs JIT reassessment via a prompt preamble at zero additional token cost; a dedicated reassess session is opt-in. Set to `true` (e.g. via the `burn-max` profile) if you want the explicit session.
   - `skip_reassess`: boolean — force-disable roadmap reassessment even if `reassess_after_slice` is enabled. Default: `false`.
   - `skip_slice_research`: boolean — skip per-slice research. Default: `false`.
 
+- `reactive_execution`: controls automatic parallel task dispatch inside a slice. Reactive execution is enabled by default when omitted; set `enabled: false` to opt out. With default-on behavior, GSD only attempts a reactive batch when at least three ready tasks are available and the task-plan IO graph is non-ambiguous. If you set `enabled: true` explicitly, GSD uses the earlier opt-in threshold of two ready tasks. Keys:
+  - `enabled`: boolean — set `false` to force sequential task execution. Default: `true`.
+  - `max_parallel`: number — maximum tasks to dispatch in one batch, range `1`-`8`. Default: `2`.
+  - `isolation_mode`: `"same-tree"` — currently the only supported value.
+  - `subagent_model`: string — optional model override for reactive task subagents. Falls back to the `models.subagent` routing when omitted.
+
 - `remote_questions`: route interactive questions to Slack/Discord for headless auto-mode. Keys:
   - `channel`: `"slack"` or `"discord"` — channel type.
   - `channel_id`: string or number — channel ID.
@@ -193,6 +203,8 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `hooks`: boolean — enable routing hooks. Default: `true`.
   - `capability_routing`: boolean — enable capability-profile scoring for model selection within a tier. Requires `enabled: true`. Default: `false`.
 
+- `disabled_model_providers`: string[] — provider IDs to hide from model selection and routing (for example `["google-gemini-cli"]`). This only affects model availability (`/model`, auto-model selection, routing); it does not disable tool auth flows like `google_search`.
+
 - `uok`: Unified Orchestration Kernel controls. Keys:
   - `enabled`: boolean — enable kernel wrappers and contract observers. Default: `true`.
   - `legacy_fallback.enabled`: boolean — emergency release fallback that forces legacy orchestration behavior even when `uok.enabled` is `true`. Default: `false`.
@@ -292,7 +304,7 @@ mode: solo
 ---
 ```
 
-Equivalent to setting `git.auto_push: true`, `git.push_branches: false`, `git.pre_merge_check: false`, `git.merge_strategy: squash`, `git.isolation: worktree`, `unique_milestone_ids: false`.
+Equivalent to setting `git.auto_push: true`, `git.push_branches: false`, `git.pre_merge_check: false`, `git.merge_strategy: squash`, `git.isolation: none`, `unique_milestone_ids: false`.
 
 **Team — unique IDs, push branches, pre-merge checks:**
 
@@ -303,7 +315,7 @@ mode: team
 ---
 ```
 
-Equivalent to setting `git.auto_push: false`, `git.push_branches: true`, `git.pre_merge_check: true`, `git.merge_strategy: squash`, `git.isolation: worktree`, `unique_milestone_ids: true`.
+Equivalent to setting `git.auto_push: false`, `git.push_branches: true`, `git.pre_merge_check: true`, `git.merge_strategy: squash`, `git.isolation: none`, `unique_milestone_ids: true`.
 
 **Mode with overrides — team mode but with auto-push:**
 

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

@@ -3,7 +3,7 @@ import { join } from "node:path";
 
 import type { DoctorIssue } from "./doctor-types.js";
 import { isDbAvailable, _getAdapter } from "./gsd-db.js";
-import { resolveMilestoneFile } from "./paths.js";
+import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
 import { deriveState } from "./state.js";
 import { readEvents } from "./workflow-events.js";
 import { renderAllProjections } from "./workflow-projections.js";
@@ -13,7 +13,7 @@ export async function checkEngineHealth(
   issues: DoctorIssue[],
   fixesApplied: string[],
 ): Promise<void> {
-  const dbPath = join(basePath, ".gsd", "gsd.db");
+  const dbPath = resolveGsdPathContract(basePath).projectDb;
 
   if (!isDbAvailable() && existsSync(dbPath)) {
     issues.push({

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

@@ -17,6 +17,7 @@ import { AuthStorage } from "@gsd/pi-coding-agent";
 import { getEnvApiKey } from "@gsd/pi-ai";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getAuthPath, PROVIDER_REGISTRY, type ProviderCategory } from "./key-manager.js";
+import { homedir } from "node:os";
 
 // ── Types ──────────────────────────────────────────────────────────────────────
 
@@ -194,7 +195,7 @@ function isCliBinaryInPath(providerId: string): boolean {
 }
 
 function modelsJsonPaths(): string[] {
-  const home = process.env.HOME ?? "~";
+  const home = homedir();
   return [
     join(home, ".gsd", "agent", "models.json"),
     // Keep parity with custom-provider discovery during auto bootstrap.

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

@@ -4,7 +4,7 @@ import { basename, dirname, join } from "node:path";
 import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
 import { cleanNumberedGsdVariants } from "./repo-identity.js";
 import { milestonesDir, gsdRoot, resolveGsdRootFile } from "./paths.js";
-import { deriveState } from "./state.js";
+import { deriveState, isGhostMilestone, isReusableGhostMilestone } from "./state.js";
 import { saveFile } from "./files.js";
 import { nativeIsRepo, nativeForEachRef, nativeUpdateRef } from "./native-git-bridge.js";
 import { readCrashLock, isLockProcessAlive, clearLock } from "./crash-recovery.js";
@@ -12,6 +12,19 @@ import { ensureGitignore, isGsdGitignored } from "./gitignore.js";
 import { readAllSessionStatuses, isSessionStale, removeSessionStatus } from "./session-status-io.js";
 import { recoverFailedMigration } from "./migrate-external.js";
 import { splitCompletedKey } from "./forensics.js";
+import { findMilestoneIds } from "./milestone-ids.js";
+
+const MAX_UAT_ATTEMPTS = 3;
+
+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;
+  try {
+    return /^\s*verdict\s*:\s*(PASS|FAIL|PARTIAL)\b/im.test(readFileSync(assessmentPath, "utf-8"));
+  } catch {
+    return false;
+  }
+}
 
 export async function checkRuntimeHealth(
   basePath: string,
@@ -190,6 +203,47 @@ export async function checkRuntimeHealth(
     // Non-fatal — hook state check failed
   }
 
+  // ── Exhausted run-uat retry counters ──────────────────────────────────
+  try {
+    const runtimeDir = join(root, "runtime");
+    if (existsSync(runtimeDir)) {
+      const uatCounterPattern = /^uat-count-(M\d+)-(S\d+)\.json$/;
+      for (const fileName of readdirSync(runtimeDir)) {
+        const match = fileName.match(uatCounterPattern);
+        if (!match) continue;
+        const [, mid, sid] = match;
+        if (!mid || !sid || hasAssessmentVerdict(basePath, mid, sid)) continue;
+
+        const filePath = join(runtimeDir, fileName);
+        let count = 0;
+        try {
+          const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+          count = typeof parsed.count === "number" ? parsed.count : 0;
+        } catch {
+          count = MAX_UAT_ATTEMPTS + 1;
+        }
+        if (count <= MAX_UAT_ATTEMPTS) continue;
+
+        issues.push({
+          severity: "warning",
+          code: "uat_retry_exhausted",
+          scope: "slice",
+          unitId: `${mid}/${sid}`,
+          message: `run-uat for ${mid}/${sid} exhausted ${count - 1} retry attempt(s) without an ASSESSMENT verdict. Reset the retry counter after fixing the underlying UAT/tool issue, then rerun /gsd auto.`,
+          file: `.gsd/runtime/${fileName}`,
+          fixable: true,
+        });
+
+        if (shouldFix("uat_retry_exhausted")) {
+          rmSync(filePath, { force: true });
+          fixesApplied.push(`reset exhausted run-uat retry counter for ${mid}/${sid}`);
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — UAT retry counter check failed
+  }
+
   // ── Activity log bloat ────────────────────────────────────────────────
   try {
     const activityDir = join(root, "activity");
@@ -593,6 +647,43 @@ export async function checkRuntimeHealth(
   } catch {
     // Non-fatal — snapshot ref check failed
   }
+
+  // ── Orphan milestone directories (#4996) ──────────────────────────────
+  // Walk every milestone ID on disk. Any dir that has no DB row, no worktree,
+  // and no content files is an orphaned stub — it skews nextMilestoneId and
+  // was likely created by ensurePreconditions or showHeadlessMilestoneCreation
+  // for a phantom forward-reference. Surface as a fixable warning.
+  try {
+    const milestoneIds = findMilestoneIds(basePath);
+    const hasDbFile = existsSync(join(root, "gsd.db"));
+    for (const mid of milestoneIds) {
+      const isOrphan = isReusableGhostMilestone(basePath, mid)
+        || (!hasDbFile && isGhostMilestone(basePath, mid));
+      if (isOrphan) {
+        issues.push({
+          severity: "warning",
+          code: "orphan_milestone_dir",
+          scope: "milestone",
+          unitId: mid,
+          message: `Orphan milestone directory: ${mid} — directory exists on disk with no DB row, no worktree, and no content files. This stub skews milestone ID generation and should be removed.`,
+          file: `.gsd/milestones/${mid}`,
+          fixable: true,
+        });
+
+        if (shouldFix("orphan_milestone_dir")) {
+          try {
+            const orphanPath = join(milestonesDir(basePath), mid);
+            rmSync(orphanPath, { recursive: true, force: true });
+            fixesApplied.push(`removed orphan milestone directory: ${mid}`);
+          } catch {
+            // Non-fatal — leave for manual cleanup
+          }
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — orphan milestone directory check failed
+  }
 }
 
 /**

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

@@ -19,6 +19,7 @@ export type DoctorIssueCode =
   | "stale_parallel_session"
   | "orphaned_completed_units"
   | "stale_hook_state"
+  | "uat_retry_exhausted"
   | "activity_log_bloat"
   | "state_file_stale"
   | "state_file_missing"
@@ -80,7 +81,9 @@ export type DoctorIssueCode =
   | "db_done_task_no_summary"
   | "db_duplicate_id"
   | "db_unavailable"
-  | "projection_drift";
+  | "projection_drift"
+  // Milestone filesystem/DB drift (#4996)
+  | "orphan_milestone_dir";
 
 /**
  * Issue codes that represent global or completion-critical state.

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

@@ -59,7 +59,7 @@ const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fet
 // 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/gsd-build/gsd-2/issues/4528
-const SERVER_RE = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable|context (?:window|length) exceed|context window exceed/i;
+const SERVER_RE = /internal(?: server)?[ _-]?error|500|502|503|overloaded|server_error|api_error|service.?unavailable|context (?:window|length) exceed|context window exceed/i;
 // ECONNRESET/ECONNREFUSED are in NETWORK_RE (same-model retry first).
 const CONNECTION_RE = /terminated|connection.?(?:refused|error)|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
 // Catch-all for V8 JSON.parse errors: all modern variants end with "in JSON at position \d+".