gsd-pi 2.37.1 → 2.38.0-dev.96dc7fb

package/README.md

@@ -629,7 +629,7 @@ GSD isn't locked to one provider. It runs on the [Pi SDK](https://github.com/bad
 
 ### Built-in Providers
 
-Anthropic, OpenAI, Google (Gemini), OpenRouter, GitHub Copilot, Amazon Bedrock, Azure OpenAI, Google Vertex, Groq, Cerebras, Mistral, xAI, HuggingFace, Vercel AI Gateway, and more.
+Anthropic, Anthropic (Vertex AI), OpenAI, Google (Gemini), OpenRouter, GitHub Copilot, Amazon Bedrock, Azure OpenAI, Google Vertex, Groq, Cerebras, Mistral, xAI, HuggingFace, Vercel AI Gateway, and more.
 
 ### OAuth / Max Plans
 

package/dist/cli.js

@@ -505,6 +505,15 @@ if (enabledModelPatterns && enabledModelPatterns.length > 0) {
         session.setScopedModels(scopedModels);
     }
 }
+// Welcome screen — shown on every fresh interactive session before TUI takes over
+{
+    const { printWelcomeScreen } = await import('./welcome-screen.js');
+    printWelcomeScreen({
+        version: process.env.GSD_VERSION || '0.0.0',
+        modelName: settingsManager.getDefaultModel() || undefined,
+        provider: settingsManager.getDefaultProvider() || undefined,
+    });
+}
 const interactiveMode = new InteractiveMode(session);
 markStartup('InteractiveMode');
 printStartupTimings();

package/dist/extension-discovery.d.ts

@@ -1,9 +1,11 @@
 /**
  * Resolves the entry-point file(s) for a single extension directory.
  *
- * 1. If the directory contains a package.json with a `pi.extensions` array,
- *    each entry is resolved relative to the directory and returned (if it exists).
- * 2. Otherwise falls back to `index.ts` → `index.js`.
+ * 1. If the directory contains a package.json with a `pi` manifest object,
+ *    the manifest is authoritative:
+ *    - `pi.extensions` array → resolve each entry relative to the directory.
+ *    - `pi: {}` (no extensions) → return empty (library opt-out, e.g. cmux).
+ * 2. Only when no `pi` manifest exists does it fall back to `index.ts` → `index.js`.
  */
 export declare function resolveExtensionEntries(dir: string): string[];
 /**

package/dist/extension-discovery.js

@@ -6,24 +6,29 @@ function isExtensionFile(name) {
 /**
  * Resolves the entry-point file(s) for a single extension directory.
  *
- * 1. If the directory contains a package.json with a `pi.extensions` array,
- *    each entry is resolved relative to the directory and returned (if it exists).
- * 2. Otherwise falls back to `index.ts` → `index.js`.
+ * 1. If the directory contains a package.json with a `pi` manifest object,
+ *    the manifest is authoritative:
+ *    - `pi.extensions` array → resolve each entry relative to the directory.
+ *    - `pi: {}` (no extensions) → return empty (library opt-out, e.g. cmux).
+ * 2. Only when no `pi` manifest exists does it fall back to `index.ts` → `index.js`.
  */
 export function resolveExtensionEntries(dir) {
     const packageJsonPath = join(dir, 'package.json');
     if (existsSync(packageJsonPath)) {
         try {
             const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
-            const declared = pkg?.pi?.extensions;
-            if (Array.isArray(declared)) {
-                const resolved = declared
+            if (pkg?.pi && typeof pkg.pi === 'object') {
+                // When a pi manifest exists, it is authoritative — don't fall through
+                // to index.ts/index.js auto-detection. This allows library directories
+                // (like cmux) to opt out by declaring "pi": {} with no extensions.
+                const declared = pkg.pi.extensions;
+                if (!Array.isArray(declared) || declared.length === 0) {
+                    return [];
+                }
+                return declared
                     .filter((entry) => typeof entry === 'string')
                     .map((entry) => resolve(dir, entry))
                     .filter((entry) => existsSync(entry));
-                if (resolved.length > 0) {
-                    return resolved;
-                }
             }
         }
         catch {

package/dist/onboarding.js

@@ -38,6 +38,7 @@ const TOOL_KEYS = [
 /** Known LLM provider IDs that, if authed, mean the user doesn't need onboarding */
 const LLM_PROVIDER_IDS = [
     'anthropic',
+    'anthropic-vertex',
     'openai',
     'github-copilot',
     'openai-codex',

package/dist/resources/extensions/browser-tools/package.json

@@ -7,7 +7,9 @@
     "test": "node --test tests/*.test.mjs"
   },
   "pi": {
-    "extensions": ["./index.ts"]
+    "extensions": [
+      "./index.js"
+    ]
   },
   "peerDependencies": {
     "playwright": ">=1.40.0",

package/dist/resources/extensions/cmux/index.js

@@ -237,11 +237,14 @@ export class CmuxClient {
         return extractSurfaceIds(parsed);
     }
     async createSplit(direction) {
+        return this.createSplitFrom(this.config.surfaceId, direction);
+    }
+    async createSplitFrom(sourceSurfaceId, direction) {
         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) {
@@ -250,6 +253,57 @@ 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) {
+        if (!this.config.splits || count <= 0)
+            return [];
+        const surfaces = [];
+        // 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, text) {
         const payload = text.endsWith("\n") ? text : `${text}\n`;
         const stdout = await this.runAsync(["send-surface", "--surface", surfaceId, payload]);

package/dist/resources/extensions/context7/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "pi": {
     "extensions": [
-      "./index.ts"
+      "./index.js"
     ]
   }
 }

package/dist/resources/extensions/google-search/package.json

@@ -4,6 +4,8 @@
   "version": "1.0.0",
   "type": "module",
   "pi": {
-    "extensions": ["./index.ts"]
+    "extensions": [
+      "./index.js"
+    ]
   }
 }

package/dist/resources/extensions/gsd/auto-dispatch.js

@@ -12,7 +12,7 @@ import { loadFile, loadActiveOverrides, parseRoadmap } from "./files.js";
 import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveTaskFile, relSliceFile, buildMilestoneFileName, } from "./paths.js";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { buildResearchMilestonePrompt, buildPlanMilestonePrompt, buildResearchSlicePrompt, buildPlanSlicePrompt, buildExecuteTaskPrompt, buildCompleteSlicePrompt, buildCompleteMilestonePrompt, buildValidateMilestonePrompt, buildReplanSlicePrompt, buildRunUatPrompt, buildReassessRoadmapPrompt, buildRewriteDocsPrompt, checkNeedsReassessment, checkNeedsRunUat, } from "./auto-prompts.js";
+import { buildResearchMilestonePrompt, buildPlanMilestonePrompt, buildResearchSlicePrompt, buildPlanSlicePrompt, buildExecuteTaskPrompt, buildCompleteSlicePrompt, buildCompleteMilestonePrompt, buildValidateMilestonePrompt, buildReplanSlicePrompt, buildRunUatPrompt, buildReassessRoadmapPrompt, buildRewriteDocsPrompt, buildReactiveExecutePrompt, checkNeedsReassessment, checkNeedsRunUat, } from "./auto-prompts.js";
 function missingSliceStop(mid, phase) {
     return {
         action: "stop",
@@ -223,6 +223,72 @@ const DISPATCH_RULES = [
             };
         },
     },
+    {
+        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.message}\n`);
+                return null;
+            }
+        },
+    },
     {
         name: "executing → execute-task (recover missing task plan → plan-slice)",
         match: async ({ state, mid, midTitle, basePath }) => {

package/dist/resources/extensions/gsd/auto-loop.js

@@ -373,7 +373,7 @@ export async function autoLoop(ctx, pi, s, deps) {
                     await deps.closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, deps.buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
                 }
                 const incomplete = state.registry.filter((m) => 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);
@@ -382,6 +382,12 @@ export async function autoLoop(ctx, pi, s, deps) {
                     deps.logCmuxEvent(deps.loadEffectiveGSDPreferences()?.preferences, "All milestones complete.", "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/dist/resources/extensions/gsd/auto-post-unit.js

@@ -171,6 +171,20 @@ export async function postUnitPreVerification(pctx) {
                 // Non-fatal
             }
         }
+        // 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/dist/resources/extensions/gsd/auto-prompts.js

@@ -414,6 +414,35 @@ export async function getPriorTaskSummaryPaths(mid, sid, currentTid, base) {
     })
         .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, sid, currentTid, dependsOn, base) {
+    // 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 ────────────────────────────────────────────
 /**
  * Check if the most recently completed slice needs reassessment.
@@ -688,8 +717,11 @@ export async function buildPlanSlicePrompt(mid, _midTitle, sid, sTitle, base, le
     });
 }
 export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base, level) {
-    const inlineLevel = level ?? resolveInlineLevel();
-    const priorSummaries = await getPriorTaskSummaryPaths(mid, sid, tid, base);
+    const opts = typeof level === "object" && level !== null && !Array.isArray(level)
+        ? level
+        : { level: level };
+    const inlineLevel = opts.level ?? resolveInlineLevel();
+    const priorSummaries = opts.carryForwardPaths ?? await getPriorTaskSummaryPaths(mid, sid, tid, base);
     const priorLines = priorSummaries.length > 0
         ? priorSummaries.map(p => `- \`${p}\``).join("\n")
         : "- (no prior tasks)";
@@ -1090,6 +1122,63 @@ export async function buildReassessRoadmapPrompt(mid, midTitle, completedSliceId
         commitInstruction: reassessCommitInstruction,
     });
 }
+// ─── Reactive Execute Prompt ──────────────────────────────────────────────
+export async function buildReactiveExecutePrompt(mid, midTitle, sid, sTitle, readyTaskIds, base) {
+    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 = [];
+    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 = [];
+    const readyTaskListLines = [];
+    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, midTitle, activeSlice, base, overrides) {
     const sid = activeSlice?.id;
     const sTitle = activeSlice?.title ?? "";

package/dist/resources/extensions/gsd/auto-recovery.js

@@ -11,7 +11,7 @@ import { clearUnitRuntimeRecord } from "./unit-runtime.js";
 import { clearParseCache, parseRoadmap, parsePlan } from "./files.js";
 import { isValidationTerminal } from "./state.js";
 import { nativeConflictFiles, nativeCommit, nativeCheckoutTheirs, nativeAddPaths, nativeMergeAbort, nativeResetHard, } from "./native-git-bridge.js";
-import { resolveMilestonePath, resolveSlicePath, resolveSliceFile, resolveTasksDir, relMilestoneFile, relSliceFile, relSlicePath, relTaskFile, buildMilestoneFileName, buildSliceFileName, buildTaskFileName, resolveMilestoneFile, clearPathCache, resolveGsdRootFile, } from "./paths.js";
+import { resolveMilestonePath, resolveSlicePath, resolveSliceFile, resolveTasksDir, resolveTaskFiles, relMilestoneFile, relSliceFile, relSlicePath, relTaskFile, buildMilestoneFileName, buildSliceFileName, buildTaskFileName, resolveMilestoneFile, clearPathCache, resolveGsdRootFile, } from "./paths.js";
 import { markSliceDoneInRoadmap } from "./roadmap-mutations.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, } from "node:fs";
 import { dirname, join } from "node:path";
@@ -73,6 +73,9 @@ export function resolveExpectedArtifactPath(unitType, unitId, base) {
         }
         case "rewrite-docs":
             return null;
+        case "reactive-execute":
+            // Reactive execute produces multiple task summaries — verified separately
+            return null;
         default:
             return null;
     }
@@ -105,6 +108,39 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
         const content = readFileSync(overridesPath, "utf-8");
         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/dist/resources/extensions/gsd/auto-start.js

@@ -303,11 +303,16 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // ── Auto-worktree setup ──
         s.originalBasePath = base;
         const isUnderGsdWorktrees = (p) => {
+            // 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 (s.currentMilestoneId &&
             shouldUseWorktreeIsolation() &&

package/dist/resources/extensions/gsd/auto-worktree-sync.js

@@ -115,10 +115,17 @@ export function checkResourcesStale(versionOnStart) {
  * Returns the corrected base path.
  */
 export function escapeStaleWorktree(base) {
-    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);
     try {

package/dist/resources/extensions/gsd/captures.js

@@ -30,8 +30,16 @@ const VALID_CLASSIFICATIONS = [
  */
 export function resolveCapturesPath(basePath) {
     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/dist/resources/extensions/gsd/commands-handlers.js

@@ -10,7 +10,7 @@ import { deriveState } from "./state.js";
 import { gsdRoot } from "./paths.js";
 import { appendCapture, hasPendingCaptures, loadPendingCaptures } from "./captures.js";
 import { appendOverride, appendKnowledge } from "./files.js";
-import { formatDoctorIssuesForPrompt, formatDoctorReport, runGSDDoctor, selectDoctorScope, filterDoctorIssues, } from "./doctor.js";
+import { formatDoctorIssuesForPrompt, formatDoctorReport, formatDoctorReportJson, runGSDDoctor, selectDoctorScope, filterDoctorIssues, } from "./doctor.js";
 import { isAutoActive } from "./auto.js";
 import { projectRoot } from "./commands.js";
 import { loadPrompt } from "./prompt-loader.js";
@@ -28,15 +28,28 @@ export function dispatchDoctorHeal(pi, scope, reportText, structuredIssues) {
 }
 export async function handleDoctor(args, ctx, pi) {
     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",

package/dist/resources/extensions/gsd/commands.js

@@ -135,7 +135,7 @@ async function guardRemoteSession(ctx, pi) {
 }
 export function registerGSDCommand(pi) {
     pi.registerCommand("gsd", {
-        description: "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|visualize|queue|quick|capture|triage|dispatch|history|undo|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|update",
+        description: "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|capture|triage|dispatch|history|undo|rate|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update",
         getArgumentCompletions: (prefix) => {
             const subcommands = [
                 { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -186,7 +186,11 @@ export function registerGSDCommand(pi) {
                 { cmd: "templates", desc: "List available workflow templates" },
                 { cmd: "extensions", desc: "Manage extensions (list, enable, disable, info)" },
             ];
+            const hasTrailingSpace = prefix.endsWith(" ");
             const parts = prefix.trim().split(/\s+/);
+            if (hasTrailingSpace && parts.length >= 1) {
+                parts.push("");
+            }
             if (parts.length <= 1) {
                 return subcommands
                     .filter((item) => item.cmd.startsWith(parts[0] ?? ""))
@@ -468,6 +472,10 @@ export function registerGSDCommand(pi) {
                     { cmd: "fix", desc: "Auto-fix detected issues" },
                     { cmd: "heal", desc: "AI-driven deep healing" },
                     { cmd: "audit", desc: "Run health audit without fixing" },
+                    { cmd: "--dry-run", desc: "Show what --fix would change without applying" },
+                    { cmd: "--json", desc: "Output report as JSON (CI/tooling friendly)" },
+                    { cmd: "--build", desc: "Include slow build health check (npm run build)" },
+                    { cmd: "--test", desc: "Include slow test health check (npm test)" },
                 ];
                 if (parts.length <= 2) {
                     return modes
@@ -491,6 +499,17 @@ export function registerGSDCommand(pi) {
                     .filter((p) => p.cmd.startsWith(phasePrefix))
                     .map((p) => ({ value: `dispatch ${p.cmd}`, label: p.cmd, description: p.desc }));
             }
+            if (parts[0] === "rate" && parts.length <= 2) {
+                const tierPrefix = parts[1] ?? "";
+                const tiers = [
+                    { cmd: "over", desc: "Model was overqualified for this task" },
+                    { cmd: "ok", desc: "Model was appropriate for this task" },
+                    { cmd: "under", desc: "Model was underqualified for this task" },
+                ];
+                return tiers
+                    .filter((t) => t.cmd.startsWith(tierPrefix))
+                    .map((t) => ({ value: `rate ${t.cmd}`, label: t.cmd, description: t.desc }));
+            }
             return [];
         },
         async handler(args, ctx) {