gsd-pi 2.37.1 → 2.38.0-dev.e40f839

package/src/resources/extensions/cmux/index.ts

@@ -289,10 +289,17 @@ export class CmuxClient {
   }
 
   async createSplit(direction: "right" | "down" | "left" | "up"): Promise<string | null> {
+    return this.createSplitFrom(this.config.surfaceId, direction);
+  }
+
+  async createSplitFrom(
+    sourceSurfaceId: string | undefined,
+    direction: "right" | "down" | "left" | "up",
+  ): Promise<string | null> {
     if (!this.config.splits) return null;
     const before = new Set(await this.listSurfaceIds());
     const args = ["new-split", direction];
-    const scopedArgs = this.appendSurface(this.appendWorkspace(args), this.config.surfaceId);
+    const scopedArgs = this.appendSurface(this.appendWorkspace(args), sourceSurfaceId);
     await this.runAsync(scopedArgs);
     const after = await this.listSurfaceIds();
     for (const id of after) {
@@ -301,6 +308,55 @@ export class CmuxClient {
     return null;
   }
 
+  /**
+   * Create a grid of surfaces for parallel agent execution.
+   *
+   * Layout strategy (gsd stays in the original surface):
+   *   1 agent:  [gsd | A]
+   *   2 agents: [gsd | A]
+   *             [    | B]
+   *   3 agents: [gsd | A]
+   *             [ C  | B]
+   *   4 agents: [gsd | A]
+   *             [ C  | B]  (D splits from B downward)
+   *             [    | D]
+   *
+   * Returns surface IDs in order, or empty array on failure.
+   */
+  async createGridLayout(count: number): Promise<string[]> {
+    if (!this.config.splits || count <= 0) return [];
+    const surfaces: string[] = [];
+
+    // First split: create right column from the gsd surface
+    const rightCol = await this.createSplitFrom(this.config.surfaceId, "right");
+    if (!rightCol) return [];
+    surfaces.push(rightCol);
+    if (count === 1) return surfaces;
+
+    // Second split: split right column down → bottom-right
+    const bottomRight = await this.createSplitFrom(rightCol, "down");
+    if (!bottomRight) return surfaces;
+    surfaces.push(bottomRight);
+    if (count === 2) return surfaces;
+
+    // Third split: split gsd surface down → bottom-left
+    const bottomLeft = await this.createSplitFrom(this.config.surfaceId, "down");
+    if (!bottomLeft) return surfaces;
+    surfaces.push(bottomLeft);
+    if (count === 3) return surfaces;
+
+    // Fourth+: split subsequent surfaces down from the last created
+    let lastSurface = bottomRight;
+    for (let i = 3; i < count; i++) {
+      const next = await this.createSplitFrom(lastSurface, "down");
+      if (!next) break;
+      surfaces.push(next);
+      lastSurface = next;
+    }
+
+    return surfaces;
+  }
+
   async sendSurface(surfaceId: string, text: string): Promise<boolean> {
     const payload = text.endsWith("\n") ? text : `${text}\n`;
     const stdout = await this.runAsync(["send-surface", "--surface", surfaceId, payload]);

package/src/resources/extensions/env-utils.ts

@@ -0,0 +1,31 @@
+// GSD Extension — Environment variable utilities
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+//
+// Pure utility for checking existing env keys in .env files and process.env.
+// Extracted from get-secrets-from-user.ts to avoid pulling in @gsd/pi-tui
+// when only env-checking is needed (e.g. from files.ts during report generation).
+
+import { readFile } from "node:fs/promises";
+
+/**
+ * Check which keys already exist in a .env file or process.env.
+ * Returns the subset of `keys` that are already set.
+ */
+export async function checkExistingEnvKeys(keys: string[], envFilePath: string): Promise<string[]> {
+	let fileContent = "";
+	try {
+		fileContent = await readFile(envFilePath, "utf8");
+	} catch {
+		// ENOENT or other read error — proceed with empty content
+	}
+
+	const existing: string[] = [];
+	for (const key of keys) {
+		const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		const regex = new RegExp(`^${escaped}\\s*=`, "m");
+		if (regex.test(fileContent) || key in process.env) {
+			existing.push(key);
+		}
+	}
+	return existing;
+}

package/src/resources/extensions/get-secrets-from-user.ts

@@ -67,30 +67,11 @@ async function writeEnvKey(filePath: string, key: string, value: string): Promis
 
 // ─── Exported utilities ───────────────────────────────────────────────────────
 
-/**
- * Check which keys already exist in the .env file or process.env.
- * Returns the subset of `keys` that are already set.
- * Handles ENOENT gracefully (still checks process.env).
- * Empty-string values count as existing.
- */
-export async function checkExistingEnvKeys(keys: string[], envFilePath: string): Promise<string[]> {
-	let fileContent = "";
-	try {
-		fileContent = await readFile(envFilePath, "utf8");
-	} catch {
-		// ENOENT or other read error — proceed with empty content
-	}
-
-	const existing: string[] = [];
-	for (const key of keys) {
-		const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-		const regex = new RegExp(`^${escaped}\\s*=`, "m");
-		if (regex.test(fileContent) || key in process.env) {
-			existing.push(key);
-		}
-	}
-	return existing;
-}
+// Re-export from env-utils.ts so existing consumers still work.
+// The implementation lives in env-utils.ts to avoid pulling @gsd/pi-tui
+// into modules that only need env-checking (e.g. files.ts during reports).
+import { checkExistingEnvKeys } from "./env-utils.js";
+export { checkExistingEnvKeys };
 
 /**
  * Detect the write destination based on project files in basePath.

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

@@ -38,6 +38,7 @@ import {
   buildRunUatPrompt,
   buildReassessRoadmapPrompt,
   buildRewriteDocsPrompt,
+  buildReactiveExecutePrompt,
   checkNeedsReassessment,
   checkNeedsRunUat,
 } from "./auto-prompts.js";
@@ -309,6 +310,98 @@ const DISPATCH_RULES: DispatchRule[] = [
       };
     },
   },
+  {
+    name: "executing → reactive-execute (parallel dispatch)",
+    match: async ({ state, mid, midTitle, basePath, prefs }) => {
+      if (state.phase !== "executing" || !state.activeTask) return null;
+      if (!state.activeSlice) return null; // fall through
+
+      // Only activate when reactive_execution is explicitly enabled
+      const reactiveConfig = prefs?.reactive_execution;
+      if (!reactiveConfig?.enabled) return null;
+
+      const sid = state.activeSlice.id;
+      const sTitle = state.activeSlice.title;
+      const maxParallel = reactiveConfig.max_parallel ?? 2;
+
+      // Dry-run mode: max_parallel=1 means graph is derived and logged but
+      // execution remains sequential
+      if (maxParallel <= 1) return null;
+
+      try {
+        const {
+          loadSliceTaskIO,
+          deriveTaskGraph,
+          isGraphAmbiguous,
+          getReadyTasks,
+          chooseNonConflictingSubset,
+          graphMetrics,
+        } = await import("./reactive-graph.js");
+
+        const taskIO = await loadSliceTaskIO(basePath, mid, sid);
+        if (taskIO.length < 2) return null; // single task, no point
+
+        const graph = deriveTaskGraph(taskIO);
+
+        // Ambiguous graph → fall through to sequential
+        if (isGraphAmbiguous(graph)) return null;
+
+        const completed = new Set(graph.filter((n) => n.done).map((n) => n.id));
+        const readyIds = getReadyTasks(graph, completed, new Set());
+
+        // Only activate reactive dispatch when >1 task is ready
+        if (readyIds.length <= 1) return null;
+
+        const selected = chooseNonConflictingSubset(
+          readyIds,
+          graph,
+          maxParallel,
+          new Set(),
+        );
+        if (selected.length <= 1) return null;
+
+        // Log graph metrics for observability
+        const metrics = graphMetrics(graph);
+        process.stderr.write(
+          `gsd-reactive: ${mid}/${sid} graph — tasks:${metrics.taskCount} edges:${metrics.edgeCount} ` +
+          `ready:${metrics.readySetSize} dispatching:${selected.length} ambiguous:${metrics.ambiguous}\n`,
+        );
+
+        // Persist dispatched batch so verification and recovery can check
+        // exactly which tasks were sent.
+        const { saveReactiveState } = await import("./reactive-graph.js");
+        saveReactiveState(basePath, mid, sid, {
+          sliceId: sid,
+          completed: [...completed],
+          dispatched: selected,
+          graphSnapshot: metrics,
+          updatedAt: new Date().toISOString(),
+        });
+
+        // Encode selected task IDs in unitId for artifact verification.
+        // Format: M001/S01/reactive+T02,T03
+        const batchSuffix = selected.join(",");
+
+        return {
+          action: "dispatch",
+          unitType: "reactive-execute",
+          unitId: `${mid}/${sid}/reactive+${batchSuffix}`,
+          prompt: await buildReactiveExecutePrompt(
+            mid,
+            midTitle,
+            sid,
+            sTitle,
+            selected,
+            basePath,
+          ),
+        };
+      } catch (err) {
+        // Non-fatal — fall through to sequential execution
+        process.stderr.write(`gsd-reactive: graph derivation failed: ${(err as Error).message}\n`);
+        return null;
+      }
+    },
+  },
   {
     name: "executing → execute-task (recover missing task plan → plan-slice)",
     match: async ({ state, mid, midTitle, basePath }) => {

package/src/resources/extensions/gsd/auto-loop.ts

@@ -787,7 +787,7 @@ export async function autoLoop(
           (m: { status: string }) =>
             m.status !== "complete" && m.status !== "parked",
         );
-        if (incomplete.length === 0) {
+        if (incomplete.length === 0 && state.registry.length > 0) {
           // All milestones complete — merge milestone branch before stopping
           if (s.currentMilestoneId) {
             deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
@@ -804,6 +804,18 @@ export async function autoLoop(
             "success",
           );
           await deps.stopAuto(ctx, pi, "All milestones complete");
+        } else if (incomplete.length === 0 && state.registry.length === 0) {
+          // Empty registry — no milestones visible, likely a path resolution bug
+          const diag = `basePath=${s.basePath}, phase=${state.phase}`;
+          ctx.ui.notify(
+            `No milestones visible in current scope. Possible path resolution issue.\n   Diagnostic: ${diag}`,
+            "error",
+          );
+          await deps.stopAuto(
+            ctx,
+            pi,
+            `No milestones found — check basePath resolution`,
+          );
         } else if (state.phase === "blocked") {
           const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
           await deps.stopAuto(ctx, pi, blockerMsg);

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -217,6 +217,20 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
       }
     }
 
+    // Reactive state cleanup on slice completion
+    if (s.currentUnit.type === "complete-slice") {
+      try {
+        const parts = s.currentUnit.id.split("/");
+        const [mid, sid] = parts;
+        if (mid && sid) {
+          const { clearReactiveState } = await import("./reactive-graph.js");
+          clearReactiveState(s.basePath, mid, sid);
+        }
+      } catch {
+        // Non-fatal
+      }
+    }
+
     // Post-triage: execute actionable resolutions
     if (s.currentUnit.type === "triage-captures") {
       try {

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -485,6 +485,41 @@ export async function getPriorTaskSummaryPaths(
     .map(f => `${sRel}/tasks/${f}`);
 }
 
+/**
+ * Get carry-forward summary paths scoped to a task's derived dependencies.
+ *
+ * Instead of all prior tasks (order-based), returns only summaries for task
+ * IDs in `dependsOn`. Used by reactive-execute to give each subagent only
+ * the context it actually needs — not sibling tasks from a parallel batch.
+ *
+ * Falls back to order-based when dependsOn is empty (root tasks still get
+ * any available prior summaries for continuity).
+ */
+export async function getDependencyTaskSummaryPaths(
+  mid: string, sid: string, currentTid: string,
+  dependsOn: string[], base: string,
+): Promise<string[]> {
+  // If no dependencies, fall back to order-based for root tasks
+  if (dependsOn.length === 0) {
+    return getPriorTaskSummaryPaths(mid, sid, currentTid, base);
+  }
+
+  const tDir = resolveTasksDir(base, mid, sid);
+  if (!tDir) return [];
+
+  const summaryFiles = resolveTaskFiles(tDir, "SUMMARY");
+  const sRel = relSlicePath(base, mid, sid);
+  const depSet = new Set(dependsOn.map((d) => d.toUpperCase()));
+
+  return summaryFiles
+    .filter((f) => {
+      // Extract task ID from filename: "T02-SUMMARY.md" → "T02"
+      const tid = f.replace(/-SUMMARY\.md$/i, "").toUpperCase();
+      return depSet.has(tid);
+    })
+    .map((f) => `${sRel}/tasks/${f}`);
+}
+
 // ─── Adaptive Replanning Checks ────────────────────────────────────────────
 
 /**
@@ -772,13 +807,24 @@ export async function buildPlanSlicePrompt(
   });
 }
 
+/** Options for customizing execute-task prompt construction. */
+export interface ExecuteTaskPromptOptions {
+  level?: InlineLevel;
+  /** Override carry-forward paths (dependency-based instead of order-based). */
+  carryForwardPaths?: string[];
+}
+
 export async function buildExecuteTaskPrompt(
   mid: string, sid: string, sTitle: string,
-  tid: string, tTitle: string, base: string, level?: InlineLevel,
+  tid: string, tTitle: string, base: string,
+  level?: InlineLevel | ExecuteTaskPromptOptions,
 ): Promise<string> {
-  const inlineLevel = level ?? resolveInlineLevel();
+  const opts: ExecuteTaskPromptOptions = typeof level === "object" && level !== null && !Array.isArray(level)
+    ? level
+    : { level: level as InlineLevel | undefined };
+  const inlineLevel = opts.level ?? resolveInlineLevel();
 
-  const priorSummaries = await getPriorTaskSummaryPaths(mid, sid, tid, base);
+  const priorSummaries = opts.carryForwardPaths ?? await getPriorTaskSummaryPaths(mid, sid, tid, base);
   const priorLines = priorSummaries.length > 0
     ? priorSummaries.map(p => `- \`${p}\``).join("\n")
     : "- (no prior tasks)";
@@ -1234,6 +1280,82 @@ export async function buildReassessRoadmapPrompt(
   });
 }
 
+// ─── Reactive Execute Prompt ──────────────────────────────────────────────
+
+export async function buildReactiveExecutePrompt(
+  mid: string, midTitle: string, sid: string, sTitle: string,
+  readyTaskIds: string[], base: string,
+): Promise<string> {
+  const { loadSliceTaskIO, deriveTaskGraph, graphMetrics } = await import("./reactive-graph.js");
+
+  // Build graph for context
+  const taskIO = await loadSliceTaskIO(base, mid, sid);
+  const graph = deriveTaskGraph(taskIO);
+  const metrics = graphMetrics(graph);
+
+  // Build graph context section
+  const graphLines: string[] = [];
+  for (const node of graph) {
+    const status = node.done ? "✅ done" : readyTaskIds.includes(node.id) ? "🟢 ready" : "⏳ waiting";
+    const deps = node.dependsOn.length > 0 ? ` (depends on: ${node.dependsOn.join(", ")})` : "";
+    graphLines.push(`- **${node.id}: ${node.title}** — ${status}${deps}`);
+    if (node.outputFiles.length > 0) {
+      graphLines.push(`  - Outputs: ${node.outputFiles.map(f => `\`${f}\``).join(", ")}`);
+    }
+  }
+  const graphContext = [
+    `Tasks: ${metrics.taskCount}, Edges: ${metrics.edgeCount}, Ready: ${metrics.readySetSize}`,
+    "",
+    ...graphLines,
+  ].join("\n");
+
+  // Build individual subagent prompts for each ready task
+  const subagentSections: string[] = [];
+  const readyTaskListLines: string[] = [];
+
+  for (const tid of readyTaskIds) {
+    const node = graph.find((n) => n.id === tid);
+    const tTitle = node?.title ?? tid;
+    readyTaskListLines.push(`- **${tid}: ${tTitle}**`);
+
+    // Build dependency-scoped carry-forward paths for this task
+    const depPaths = await getDependencyTaskSummaryPaths(
+      mid, sid, tid, node?.dependsOn ?? [], base,
+    );
+
+    // Build a full execute-task prompt with dependency-based carry-forward
+    const taskPrompt = await buildExecuteTaskPrompt(
+      mid, sid, sTitle, tid, tTitle, base,
+      { carryForwardPaths: depPaths },
+    );
+
+    subagentSections.push([
+      `### ${tid}: ${tTitle}`,
+      "",
+      "Use this as the prompt for a `subagent` call:",
+      "",
+      "```",
+      taskPrompt,
+      "```",
+    ].join("\n"));
+  }
+
+  const inlinedTemplates = inlineTemplate("task-summary", "Task Summary");
+
+  return loadPrompt("reactive-execute", {
+    workingDirectory: base,
+    milestoneId: mid,
+    milestoneTitle: midTitle,
+    sliceId: sid,
+    sliceTitle: sTitle,
+    graphContext,
+    readyTaskCount: String(readyTaskIds.length),
+    readyTaskList: readyTaskListLines.join("\n"),
+    subagentPrompts: subagentSections.join("\n\n---\n\n"),
+    inlinedTemplates,
+  });
+}
+
 export async function buildRewriteDocsPrompt(
   mid: string, midTitle: string,
   activeSlice: { id: string; title: string } | null,

package/src/resources/extensions/gsd/auto-recovery.ts

@@ -26,6 +26,7 @@ import {
   resolveSlicePath,
   resolveSliceFile,
   resolveTasksDir,
+  resolveTaskFiles,
   relMilestoneFile,
   relSliceFile,
   relSlicePath,
@@ -110,6 +111,9 @@ export function resolveExpectedArtifactPath(
     }
     case "rewrite-docs":
       return null;
+    case "reactive-execute":
+      // Reactive execute produces multiple task summaries — verified separately
+      return null;
     default:
       return null;
   }
@@ -148,6 +152,44 @@ export function verifyExpectedArtifact(
     return !content.includes("**Scope:** active");
   }
 
+  // Reactive-execute: verify that each dispatched task's summary exists.
+  // The unitId encodes the batch: "{mid}/{sid}/reactive+T02,T03"
+  if (unitType === "reactive-execute") {
+    const parts = unitId.split("/");
+    const mid = parts[0];
+    const sidAndBatch = parts[1];
+    const batchPart = parts[2]; // "reactive+T02,T03"
+    if (!mid || !sidAndBatch || !batchPart) return false;
+
+    const sid = sidAndBatch;
+    const plusIdx = batchPart.indexOf("+");
+    if (plusIdx === -1) {
+      // Legacy format "reactive" without batch IDs — fall back to "any summary"
+      const tDir = resolveTasksDir(base, mid, sid);
+      if (!tDir) return false;
+      const summaryFiles = resolveTaskFiles(tDir, "SUMMARY");
+      return summaryFiles.length > 0;
+    }
+
+    const batchIds = batchPart.slice(plusIdx + 1).split(",").filter(Boolean);
+    if (batchIds.length === 0) return false;
+
+    const tDir = resolveTasksDir(base, mid, sid);
+    if (!tDir) return false;
+
+    const existingSummaries = new Set(
+      resolveTaskFiles(tDir, "SUMMARY").map((f) =>
+        f.replace(/-SUMMARY\.md$/i, "").toUpperCase(),
+      ),
+    );
+
+    // Every dispatched task must have a summary file
+    for (const tid of batchIds) {
+      if (!existingSummaries.has(tid.toUpperCase())) return false;
+    }
+    return true;
+  }
+
   const absPath = resolveExpectedArtifactPath(unitType, unitId, base);
   // For unit types with no verifiable artifact (null path), the parent directory
   // is missing on disk — treat as stale completion state so the key gets evicted (#313).

package/src/resources/extensions/gsd/auto-start.ts

@@ -429,10 +429,16 @@ export async function bootstrapAutoSession(
     s.originalBasePath = base;
 
     const isUnderGsdWorktrees = (p: string): boolean => {
+      // Direct layout: /.gsd/worktrees/
       const marker = `${pathSep}.gsd${pathSep}worktrees${pathSep}`;
       if (p.includes(marker)) return true;
       const worktreesSuffix = `${pathSep}.gsd${pathSep}worktrees`;
-      return p.endsWith(worktreesSuffix);
+      if (p.endsWith(worktreesSuffix)) return true;
+      // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/
+      const symlinkRe = new RegExp(
+        `\\${pathSep}\\.gsd\\${pathSep}projects\\${pathSep}[a-f0-9]+\\${pathSep}worktrees(?:\\${pathSep}|$)`,
+      );
+      return symlinkRe.test(p);
     };
 
     if (

package/src/resources/extensions/gsd/auto-worktree-sync.ts

@@ -22,6 +22,8 @@ import { join, sep as pathSep } from "node:path";
 import { homedir } from "node:os";
 import { safeCopy, safeCopyRecursive } from "./safe-fs.js";
 
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+
 // ─── Project Root → Worktree Sync ─────────────────────────────────────────
 
 /**
@@ -111,7 +113,7 @@ export function syncStateToProjectRoot(
  */
 export function readResourceVersion(): string | null {
   const agentDir =
-    process.env.GSD_CODING_AGENT_DIR || join(homedir(), ".gsd", "agent");
+    process.env.GSD_CODING_AGENT_DIR || join(gsdHome, "agent");
   const manifestPath = join(agentDir, "managed-resources.json");
   try {
     const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
@@ -153,9 +155,18 @@ export function checkResourcesStale(
  * Returns the corrected base path.
  */
 export function escapeStaleWorktree(base: string): string {
-  const marker = `${pathSep}.gsd${pathSep}worktrees${pathSep}`;
-  const idx = base.indexOf(marker);
-  if (idx === -1) return base;
+  // Direct layout: /.gsd/worktrees/
+  const directMarker = `${pathSep}.gsd${pathSep}worktrees${pathSep}`;
+  let idx = base.indexOf(directMarker);
+  if (idx === -1) {
+    // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/
+    const symlinkRe = new RegExp(
+      `\\${pathSep}\\.gsd\\${pathSep}projects\\${pathSep}[a-f0-9]+\\${pathSep}worktrees\\${pathSep}`,
+    );
+    const match = base.match(symlinkRe);
+    if (!match || match.index === undefined) return base;
+    idx = match.index;
+  }
 
   // base is inside .gsd/worktrees/<something> — extract the project root
   const projectRoot = base.slice(0, idx);

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

@@ -59,8 +59,17 @@ const VALID_CLASSIFICATIONS: readonly string[] = [
  */
 export function resolveCapturesPath(basePath: string): string {
   const resolved = resolve(basePath);
+  // Direct layout: /.gsd/worktrees/
   const worktreeMarker = `${sep}.gsd${sep}worktrees${sep}`;
-  const idx = resolved.indexOf(worktreeMarker);
+  let idx = resolved.indexOf(worktreeMarker);
+  if (idx === -1) {
+    // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/
+    const symlinkRe = new RegExp(
+      `\\${sep}\\.gsd\\${sep}projects\\${sep}[a-f0-9]+\\${sep}worktrees\\${sep}`,
+    );
+    const match = resolved.match(symlinkRe);
+    if (match && match.index !== undefined) idx = match.index;
+  }
   if (idx !== -1) {
     // basePath is inside a worktree — resolve to project root
     const projectRoot = resolved.slice(0, idx);

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

@@ -11,6 +11,8 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFile
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+
 // ─── Types (mirrored from extension-registry.ts) ────────────────────────────
 
 interface ExtensionManifest {
@@ -48,11 +50,11 @@ interface ExtensionRegistry {
 // ─── Registry I/O ───────────────────────────────────────────────────────────
 
 function getRegistryPath(): string {
-  return join(homedir(), ".gsd", "extensions", "registry.json");
+  return join(gsdHome, "extensions", "registry.json");
 }
 
 function getAgentExtensionsDir(): string {
-  return join(homedir(), ".gsd", "agent", "extensions");
+  return join(gsdHome, "agent", "extensions");
 }
 
 function loadRegistry(): ExtensionRegistry {

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

@@ -15,6 +15,7 @@ import { appendOverride, appendKnowledge } from "./files.js";
 import {
   formatDoctorIssuesForPrompt,
   formatDoctorReport,
+  formatDoctorReportJson,
   runGSDDoctor,
   selectDoctorScope,
   filterDoctorIssues,
@@ -43,16 +44,30 @@ export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined,
 
 export async function handleDoctor(args: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
   const trimmed = args.trim();
-  const parts = trimmed ? trimmed.split(/\s+/) : [];
+  // Extract flags before positional parsing
+  const jsonMode = trimmed.includes("--json");
+  const dryRun = trimmed.includes("--dry-run");
+  const includeBuild = trimmed.includes("--build");
+  const includeTests = trimmed.includes("--test");
+  const stripped = trimmed.replace(/--json|--dry-run|--build|--test/g, "").trim();
+  const parts = stripped ? stripped.split(/\s+/) : [];
   const mode = parts[0] === "fix" || parts[0] === "heal" || parts[0] === "audit" ? parts[0] : "doctor";
   const requestedScope = mode === "doctor" ? parts[0] : parts[1];
   const scope = await selectDoctorScope(projectRoot(), requestedScope);
   const effectiveScope = mode === "audit" ? requestedScope : scope;
   const report = await runGSDDoctor(projectRoot(), {
-    fix: mode === "fix" || mode === "heal",
+    fix: mode === "fix" || mode === "heal" || dryRun,
+    dryRun,
     scope: effectiveScope,
+    includeBuild,
+    includeTests,
   });
 
+  if (jsonMode) {
+    ctx.ui.notify(formatDoctorReportJson(report), "info");
+    return;
+  }
+
   const reportText = formatDoctorReport(report, {
     scope: effectiveScope,
     includeWarnings: mode === "audit",