gsd-pi 2.78.0 → 2.78.1-dev.8a893322c

package/src/resources/extensions/gsd/commands-handlers.ts

@@ -11,6 +11,7 @@ import { join, resolve as resolvePath, sep } from "node:path";
 import { homedir } from "node:os";
 import { deriveState } from "./state.js";
 import { gsdRoot } from "./paths.js";
+import { getHomeDir } from "./home-dir.js";
 import { appendCapture, hasPendingCaptures, loadPendingCaptures } from "./captures.js";
 import { appendOverride, appendKnowledge } from "./files.js";
 import {
@@ -68,7 +69,7 @@ async function fetchLatestVersionForCommand(): Promise<string | null> {
 }
 
 export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportText: string, structuredIssues: string): void {
-  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".gsd", "agent", "GSD-WORKFLOW.md");
+  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(getHomeDir(), ".gsd", "agent", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
   const prompt = loadPrompt("doctor-heal", {
     doctorSummary: reportText,
@@ -255,7 +256,7 @@ export async function handleTriage(ctx: ExtensionCommandContext, pi: ExtensionAP
     roadmapContext: roadmapContext || "(no active roadmap)",
   });
 
-  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".gsd", "agent", "GSD-WORKFLOW.md");
+  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(getHomeDir(), ".gsd", "agent", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
 
   pi.sendMessage(

package/src/resources/extensions/gsd/commands-mcp-status.ts

@@ -13,6 +13,7 @@
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
 import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
 import { ensureProjectWorkflowMcpConfig } from "./mcp-project-config.js";
@@ -69,6 +70,7 @@ function readMcpConfigs(): McpServerRawConfig[] {
   const configPaths = [
     join(process.cwd(), ".mcp.json"),
     join(process.cwd(), ".gsd", "mcp.json"),
+    join(process.env.GSD_HOME || join(homedir(), ".gsd"), "mcp.json"),
   ];
 
   for (const configPath of configPaths) {
@@ -118,7 +120,7 @@ export function formatMcpStatusReport(servers: McpServerStatus[]): string {
     return [
       "No MCP servers configured.",
       "",
-      "Add servers to .mcp.json or .gsd/mcp.json to enable MCP integrations.",
+      "Add servers to .mcp.json, .gsd/mcp.json, or $GSD_HOME/mcp.json (default: ~/.gsd/mcp.json) to enable MCP integrations.",
       "Tip: run /gsd mcp init . to write the local GSD workflow MCP config.",
       "See: https://modelcontextprotocol.io/quickstart",
     ].join("\n");

package/src/resources/extensions/gsd/commands-prefs-wizard.ts

@@ -1524,6 +1524,18 @@ async function configureAdvanced(ctx: ExtensionCommandContext, prefs: Record<str
   const tokenCost = await promptBoolean(ctx, "Show token cost in footer", prefs.show_token_cost, false);
   if (tokenCost !== undefined) prefs.show_token_cost = tokenCost;
 
+  const minRequestInterval = await promptInteger(
+    ctx,
+    "Minimum interval between auto-mode LLM requests (ms, 0 to disable)",
+    prefs.min_request_interval_ms,
+    "0",
+  );
+  if (minRequestInterval === "clear") {
+    delete prefs.min_request_interval_ms;
+  } else if (minRequestInterval !== undefined) {
+    prefs.min_request_interval_ms = minRequestInterval;
+  }
+
   const widget = await promptEnum(ctx, "Auto-mode widget display", prefs.widget_mode, ["full", "small", "min", "off"], "full");
   if (widget !== undefined) prefs.widget_mode = widget;
 
@@ -1715,8 +1727,10 @@ export function serializePreferencesToFrontmatter(prefs: Record<string, unknown>
     "budget_ceiling", "budget_enforcement", "context_pause_threshold",
     "notifications", "cmux", "remote_questions", "git",
     "stale_commit_threshold_minutes",
+    "min_request_interval_ms",
     "post_unit_hooks", "pre_dispatch_hooks",
-    "dynamic_routing", "uok", "token_profile", "service_tier", "flat_rate_providers",
+    "dynamic_routing", "disabled_model_providers", "uok", "token_profile",
+    "service_tier", "flat_rate_providers",
     "phases", "parallel", "slice_parallel",
     "reactive_execution", "gate_evaluation",
     "auto_visualize", "auto_report",

package/src/resources/extensions/gsd/commands-worktree.ts

@@ -0,0 +1,383 @@
+// GSD-2 — In-TUI handler for /gsd worktree commands (list, merge, clean, remove).
+//
+// Mirrors the CLI subcommands in src/worktree-cli.ts but emits results via
+// ctx.ui.notify() instead of writing colored output to stderr. Reuses the
+// same extension modules (worktree-manager, native-git-bridge, etc.) so the
+// behavior is identical to the CLI surface.
+
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { existsSync } from "node:fs";
+
+import { projectRoot } from "./commands/context.js";
+import {
+  listWorktrees,
+  removeWorktree,
+  mergeWorktreeToMain,
+  diffWorktreeAll,
+  diffWorktreeNumstat,
+  worktreeBranchName,
+} from "./worktree-manager.js";
+import {
+  nativeHasChanges,
+  nativeDetectMainBranch,
+  nativeCommitCountBetween,
+} from "./native-git-bridge.js";
+import { inferCommitType } from "./git-service.js";
+import { autoCommitCurrentBranch } from "./worktree.js";
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface WorktreeStatus {
+  name: string;
+  path: string;
+  branch: string;
+  exists: boolean;
+  filesChanged: number;
+  linesAdded: number;
+  linesRemoved: number;
+  uncommitted: boolean;
+  commits: number;
+}
+
+// ─── Status helper ─────────────────────────────────────────────────────────
+
+function getStatus(basePath: string, name: string, wtPath: string): WorktreeStatus {
+  const diff = diffWorktreeAll(basePath, name);
+  const numstat = diffWorktreeNumstat(basePath, name);
+  const filesChanged = diff.added.length + diff.modified.length + diff.removed.length;
+  let linesAdded = 0;
+  let linesRemoved = 0;
+  for (const s of numstat) {
+    linesAdded += s.added;
+    linesRemoved += s.removed;
+  }
+
+  let uncommitted = false;
+  try {
+    uncommitted = existsSync(wtPath) && nativeHasChanges(wtPath);
+  } catch {
+    // native check failure → treat as clean for display purposes
+  }
+
+  let commits = 0;
+  try {
+    const main = nativeDetectMainBranch(basePath);
+    commits = nativeCommitCountBetween(basePath, main, worktreeBranchName(name));
+  } catch {
+    // commit count unavailable → leave at 0
+  }
+
+  return {
+    name,
+    path: wtPath,
+    branch: worktreeBranchName(name),
+    exists: existsSync(wtPath),
+    filesChanged,
+    linesAdded,
+    linesRemoved,
+    uncommitted,
+    commits,
+  };
+}
+
+// ─── Formatters (exported for tests) ────────────────────────────────────────
+
+export function formatWorktreeList(statuses: WorktreeStatus[]): string {
+  if (statuses.length === 0) {
+    return "No worktrees.\n\nCreate one from the CLI: gsd -w <name>";
+  }
+
+  const lines: string[] = [`Worktrees — ${statuses.length}`, ""];
+  for (const s of statuses) {
+    const badge = s.uncommitted
+      ? "(uncommitted)"
+      : s.filesChanged > 0
+        ? "(unmerged)"
+        : "(clean)";
+    lines.push(`  ${s.name} ${badge}`);
+    lines.push(`    branch  ${s.branch}`);
+    lines.push(`    path    ${s.path}`);
+    if (s.filesChanged > 0) {
+      lines.push(
+        `    diff    ${s.filesChanged} file${s.filesChanged === 1 ? "" : "s"}, +${s.linesAdded} -${s.linesRemoved}, ${s.commits} commit${s.commits === 1 ? "" : "s"}`,
+      );
+    }
+    lines.push("");
+  }
+  lines.push("Commands:");
+  lines.push("  /gsd worktree merge <name>   Merge into main and clean up");
+  lines.push("  /gsd worktree remove <name>  Remove a worktree (--force to skip safety checks)");
+  lines.push("  /gsd worktree clean          Remove all merged/empty worktrees");
+  return lines.join("\n");
+}
+
+export function formatCleanKeepReason(status: WorktreeStatus): string {
+  if (!status.exists) {
+    return "directory missing — run 'git worktree prune' to unregister";
+  }
+
+  if (status.filesChanged > 0) {
+    return `${status.filesChanged} changed file${status.filesChanged === 1 ? "" : "s"}${status.uncommitted ? ", uncommitted" : ""}`;
+  }
+
+  return "uncommitted changes";
+}
+
+// ─── Subcommand: list ───────────────────────────────────────────────────────
+
+async function handleList(ctx: ExtensionCommandContext): Promise<void> {
+  const basePath = projectRoot();
+  const worktrees = listWorktrees(basePath);
+  const statuses = worktrees.map((wt) => getStatus(basePath, wt.name, wt.path));
+  ctx.ui.notify(formatWorktreeList(statuses), "info");
+}
+
+// ─── Subcommand: merge ──────────────────────────────────────────────────────
+
+async function handleMerge(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const basePath = projectRoot();
+  const worktrees = listWorktrees(basePath);
+  const trimmed = args.trim();
+
+  let target = trimmed;
+  if (!target) {
+    if (worktrees.length === 1) {
+      target = worktrees[0].name;
+    } else if (worktrees.length === 0) {
+      ctx.ui.notify("No worktrees to merge.", "info");
+      return;
+    } else {
+      const names = worktrees.map((w) => w.name).join(", ");
+      ctx.ui.notify(`Usage: /gsd worktree merge <name>\n\nWorktrees: ${names}`, "warning");
+      return;
+    }
+  }
+
+  const wt = worktrees.find((w) => w.name === target);
+  if (!wt) {
+    const available = worktrees.map((w) => w.name).join(", ") || "(none)";
+    ctx.ui.notify(`Worktree "${target}" not found.\n\nAvailable: ${available}`, "error");
+    return;
+  }
+
+  const status = getStatus(basePath, target, wt.path);
+  if (status.filesChanged === 0 && !status.uncommitted) {
+    try {
+      removeWorktree(basePath, target, { deleteBranch: true });
+      ctx.ui.notify(`Removed empty worktree ${target}.`, "info");
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      ctx.ui.notify(
+        `Worktree partially removed: ${msg}\n\nRun 'git worktree prune' to clean up any dangling registrations.`,
+        "error",
+      );
+    }
+    return;
+  }
+
+  if (status.uncommitted) {
+    try {
+      autoCommitCurrentBranch(wt.path, "worktree-merge", target);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      ctx.ui.notify(
+        [
+          `Auto-commit before merge failed: ${msg}`,
+          "",
+          `Commit or stash changes in ${wt.path}, then re-run /gsd worktree merge ${target}.`,
+        ].join("\n"),
+        "error",
+      );
+      return;
+    }
+  }
+
+  const commitType = inferCommitType(target);
+  const mainBranch = nativeDetectMainBranch(basePath);
+  const commitMessage = `${commitType}: merge worktree ${target}\n\nGSD-Worktree: ${target}`;
+
+  try {
+    mergeWorktreeToMain(basePath, target, commitMessage);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (err instanceof GSDError && err.code === GSD_GIT_ERROR) {
+      ctx.ui.notify(
+        `Merge requires the main branch to be checked out: ${msg}\n\nSwitch to ${mainBranch} (e.g. 'git checkout ${mainBranch}'), then re-run /gsd worktree merge ${target}.`,
+        "error",
+      );
+    } else {
+      ctx.ui.notify(
+        `Merge failed: ${msg}\n\nResolve conflicts manually, then run /gsd worktree merge ${target} again.`,
+        "error",
+      );
+    }
+    return;
+  }
+
+  const successLines = [
+    `Merged ${target} → ${mainBranch}`,
+    `  ${status.filesChanged} file${status.filesChanged === 1 ? "" : "s"}, +${status.linesAdded} -${status.linesRemoved}`,
+    `  commit: ${commitMessage.split("\n")[0]}`,
+  ];
+
+  try {
+    removeWorktree(basePath, target, { deleteBranch: true });
+    ctx.ui.notify(successLines.join("\n"), "info");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const cleanupLines = [
+      ...successLines,
+      "",
+      `Cleanup failed after the merge succeeded: ${msg}`,
+      err instanceof GSDError && err.code === GSD_GIT_ERROR
+        ? `Switch to ${mainBranch} (e.g. 'git checkout ${mainBranch}'), then remove the worktree manually with /gsd worktree remove ${target} --force.`
+        : `Remove the worktree manually with /gsd worktree remove ${target} --force, or run 'git worktree prune' to clean up dangling registrations.`,
+    ];
+    ctx.ui.notify(cleanupLines.join("\n"), "warning");
+  }
+}
+
+// ─── Subcommand: clean ──────────────────────────────────────────────────────
+
+async function handleClean(ctx: ExtensionCommandContext): Promise<void> {
+  const basePath = projectRoot();
+  const worktrees = listWorktrees(basePath);
+  if (worktrees.length === 0) {
+    ctx.ui.notify("No worktrees to clean.", "info");
+    return;
+  }
+
+  const removed: string[] = [];
+  const kept: string[] = [];
+  for (const wt of worktrees) {
+    const status = getStatus(basePath, wt.name, wt.path);
+    if (status.filesChanged === 0 && !status.uncommitted) {
+      try {
+        removeWorktree(basePath, wt.name, { deleteBranch: true });
+        removed.push(wt.name);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        kept.push(`${wt.name} (failed: ${msg})`);
+      }
+    } else {
+      const reason = formatCleanKeepReason(status);
+      kept.push(`${wt.name} (${reason})`);
+    }
+  }
+
+  const lines: string[] = [`Cleaned ${removed.length} worktree${removed.length === 1 ? "" : "s"}.`];
+  if (removed.length > 0) {
+    lines.push("", "Removed:");
+    for (const n of removed) lines.push(`  ✓ ${n}`);
+  }
+  if (kept.length > 0) {
+    lines.push("", "Kept:");
+    for (const n of kept) lines.push(`  ─ ${n}`);
+  }
+  ctx.ui.notify(lines.join("\n"), "info");
+}
+
+// ─── Subcommand: remove ─────────────────────────────────────────────────────
+
+async function handleRemove(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const basePath = projectRoot();
+  const tokens = args.trim().split(/\s+/).filter(Boolean);
+  const force = tokens.includes("--force");
+  const name = tokens.find((t) => t !== "--force");
+  if (!name) {
+    ctx.ui.notify("Usage: /gsd worktree remove <name> [--force]", "warning");
+    return;
+  }
+
+  const worktrees = listWorktrees(basePath);
+  const wt = worktrees.find((w) => w.name === name);
+  if (!wt) {
+    const available = worktrees.map((w) => w.name).join(", ") || "(none)";
+    ctx.ui.notify(`Worktree "${name}" not found.\n\nAvailable: ${available}`, "error");
+    return;
+  }
+
+  const status = getStatus(basePath, name, wt.path);
+  if ((status.filesChanged > 0 || status.uncommitted) && !force) {
+    ctx.ui.notify(
+      [
+        `Worktree "${name}" has pending changes (${formatCleanKeepReason(status)}).`,
+        "",
+        `  Merge first:     /gsd worktree merge ${name}`,
+        `  Or force-remove: /gsd worktree remove ${name} --force`,
+      ].join("\n"),
+      "warning",
+    );
+    return;
+  }
+
+  try {
+    removeWorktree(basePath, name, { deleteBranch: true });
+    ctx.ui.notify(`Removed worktree ${name}.`, "info");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(
+      `Worktree partially removed: ${msg}\n\nRun 'git worktree prune' to clean up any dangling registrations.`,
+      "error",
+    );
+  }
+}
+
+// ─── Help text ──────────────────────────────────────────────────────────────
+
+const HELP_TEXT = [
+  "Usage: /gsd worktree <command> [args]",
+  "",
+  "Commands:",
+  "  list                       Show all worktrees with status",
+  "  merge [name]               Merge a worktree into main, then remove it",
+  "  remove <name> [--force]    Remove a worktree (refuses unmerged changes without --force)",
+  "  clean                      Remove all merged/empty worktrees",
+  "",
+  "The -w flag (CLI only) creates/resumes worktrees on session start:",
+  "  gsd -w               Auto-name a new worktree, or resume the only active one",
+  "  gsd -w my-feature    Create or resume a named worktree",
+].join("\n");
+
+// ─── Dispatcher ─────────────────────────────────────────────────────────────
+
+export async function handleWorktree(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const trimmed = args.trim();
+  const lowered = trimmed.toLowerCase();
+
+  if (!lowered || lowered === "help" || lowered === "--help" || lowered === "-h") {
+    ctx.ui.notify(HELP_TEXT, "info");
+    return;
+  }
+
+  try {
+    if (lowered === "list" || lowered === "ls") {
+      await handleList(ctx);
+      return;
+    }
+    if (lowered === "merge" || lowered.startsWith("merge ")) {
+      await handleMerge(trimmed.replace(/^merge\s*/i, ""), ctx);
+      return;
+    }
+    if (lowered === "clean") {
+      await handleClean(ctx);
+      return;
+    }
+    if (
+      lowered === "remove" ||
+      lowered.startsWith("remove ") ||
+      lowered === "rm" ||
+      lowered.startsWith("rm ")
+    ) {
+      const stripped = trimmed.replace(/^(remove|rm)\s*/i, "");
+      await handleRemove(stripped, ctx);
+      return;
+    }
+
+    ctx.ui.notify(`Unknown worktree command: ${trimmed}\n\n${HELP_TEXT}`, "warning");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Worktree command failed: ${msg}`, "error");
+  }
+}

package/src/resources/extensions/gsd/dashboard-overlay.ts

@@ -21,7 +21,7 @@ import {
   type UnitMetrics,
 } from "./metrics.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { getActiveWorktreeName } from "./worktree-command.js";
+import { getActiveWorktreeName } from "./worktree-session-state.js";
 import { getWorkerBatches, hasActiveWorkers, type WorkerEntry } from "../subagent/worker-registry.js";
 import { formatDuration, padRight, joinColumns, centerLine, fitColumns, STATUS_GLYPH, STATUS_COLOR } from "../shared/mod.js";
 import { estimateTimeRemaining } from "./auto-dashboard.js";

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

@@ -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`.
@@ -163,6 +165,12 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `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 +201,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`.

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 { getHomeDir } from "./home-dir.js";
 
 // ── Types ──────────────────────────────────────────────────────────────────────
 
@@ -194,7 +195,7 @@ function isCliBinaryInPath(providerId: string): boolean {
 }
 
 function modelsJsonPaths(): string[] {
-  const home = process.env.HOME ?? "~";
+  const home = getHomeDir();
   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,7 @@ 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";
 
 export async function checkRuntimeHealth(
   basePath: string,
@@ -593,6 +594,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

@@ -80,7 +80,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+".

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

@@ -12,7 +12,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { join, dirname, relative } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
+import { getHomeDir } from "./home-dir.js";
 
 import { extractTrace, type ExecutionTrace } from "./session-forensics.js";
 import { nativeParseJsonlTail } from "./native-parser-bridge.js";
@@ -244,7 +244,7 @@ export async function handleForensics(
   // when import.meta.url resolves to the npm-global install path (Windows).
   let gsdSourceDir = dirname(fileURLToPath(import.meta.url));
   if (!existsSync(join(gsdSourceDir, "prompts"))) {
-    const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+    const gsdHome = process.env.GSD_HOME || join(getHomeDir(), ".gsd");
     const fallback = join(gsdHome, "agent", "extensions", "gsd");
     if (existsSync(join(fallback, "prompts"))) gsdSourceDir = fallback;
   }
@@ -804,7 +804,7 @@ function detectMissingArtifacts(completedKeys: string[], basePath: string, activ
  * the forensics memory-bloat guard in forensics-journal.test.ts — per-event
  * detail stays in the journal itself where the LLM can query it on demand.
  */
-function detectWorktreeOrphans(
+export function detectWorktreeOrphans(
   summary: WorktreeTelemetrySummary,
   anomalies: ForensicAnomaly[],
 ): void {
@@ -822,7 +822,7 @@ function detectWorktreeOrphans(
         reason === "in-progress-unmerged"
           ? "Auto-mode exited without completing a milestone; live work sits on an unmerged milestone branch. Run `/gsd auto` to resume, or merge manually."
           : reason === "complete-unmerged"
-            ? "A completed milestone's branch was never merged back to main. Run `/gsd health --fix` to resolve."
+            ? "A completed milestone's branch was never merged back to main. Run `/gsd doctor fix` to resolve."
             : `Reason: ${reason}.`,
     });
   }
@@ -1299,10 +1299,15 @@ function formatReportForPrompt(report: ForensicReport): string {
 function redactForGitHub(text: string, basePath: string): string {
   let result = text;
 
+  // Build regex that matches both / and \ separator variants (Windows)
+  // Normalize to / first, escape for regex, then replace each / with [/\\]
+  const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pathRe = (p: string) =>
+    new RegExp(esc(p.replace(/\\/g, "/")).replace(/\//g, "[/\\\\]"), "gi");
+
   // Replace absolute paths
-  result = result.replaceAll(basePath, ".");
-  const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
-  if (home) result = result.replaceAll(home, "~");
+  result = result.replace(pathRe(basePath), ".");
+  result = result.replace(pathRe(getHomeDir()), "~");
 
   // Strip API key patterns
   result = result.replace(/sk-[a-zA-Z0-9]{20,}/g, "sk-***");