gsd-pi 2.37.1 → 2.38.0-dev.63ad7e5

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

@@ -12,10 +12,7 @@ import { resolveSkillDiscoveryMode, resolveInlineLevel, loadEffectiveGSDPreferen
 import { join } from "node:path";
 import { existsSync } from "node:fs";
 import { computeBudgets, resolveExecutorContextWindow } from "./context-budget.js";
-import { compressToTarget } from "./prompt-compressor.js";
-import { distillSummaries } from "./summary-distiller.js";
 import { formatDecisionsCompact, formatRequirementsCompact } from "./structured-data-formatter.js";
-import { chunkByRelevance, formatChunks } from "./semantic-chunker.js";
 // ─── Executor Constraints ─────────────────────────────────────────────────────
 /**
  * Format executor context constraints for injection into the plan-slice prompt.
@@ -126,14 +123,10 @@ export async function inlineFileSmart(absPath, relPath, label, query, threshold
     if (content.length <= threshold || !query) {
         return `### ${label}\nSource: \`${relPath}\`\n\n${content.trim()}`;
     }
-    // Use semantic chunking for large files
-    const result = chunkByRelevance(content, query, { maxChunks: 5, minScore: 0.05 });
-    // If chunking didn't save much (< 20%), just include full content
-    if (result.savingsPercent < 20) {
-        return `### ${label}\nSource: \`${relPath}\`\n\n${content.trim()}`;
-    }
-    const formatted = formatChunks(result, relPath);
-    return `### ${label} (${result.omittedChunks} sections omitted for relevance)\nSource: \`${relPath}\`\n\n${formatted}`;
+    // For large files, truncate at section boundary
+    const { truncateAtSectionBoundary } = await import("./context-budget.js");
+    const truncated = truncateAtSectionBoundary(content, threshold).content;
+    return `### ${label}\nSource: \`${relPath}\`\n\n${truncated}`;
 }
 /**
  * Load and inline dependency slice summaries (full content, not just paths).
@@ -165,20 +158,6 @@ export async function inlineDependencySummaries(mid, sid, base, budgetChars) {
     }
     const result = sections.join("\n\n");
     if (budgetChars !== undefined && result.length > budgetChars) {
-        // For 3+ summaries, try distillation first (preserves more information)
-        if (sections.length >= 3) {
-            const rawSummaries = sections.map(s => {
-                // Extract content after the header line
-                const lines = s.split("\n");
-                const contentStart = lines.findIndex(l => l.startsWith("Source:"));
-                return contentStart >= 0 ? lines.slice(contentStart + 1).join("\n").trim() : s;
-            });
-            const distilled = distillSummaries(rawSummaries, budgetChars);
-            if (distilled.content.length <= budgetChars) {
-                return distilled.content;
-            }
-        }
-        // Fall back to section-boundary truncation
         const { truncateAtSectionBoundary } = await import("./context-budget.js");
         return truncateAtSectionBoundary(result, budgetChars).content;
     }
@@ -414,6 +393,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 +696,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)";
@@ -745,15 +756,12 @@ export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base
     const contextWindow = resolveExecutorContextWindow(undefined, prefs?.preferences);
     const budgets = computeBudgets(contextWindow);
     const verificationBudget = `~${Math.round(budgets.verificationBudgetChars / 1000)}K chars`;
-    // Compress carry-forward section when it exceeds 40% of inline context budget.
-    // Only compress when compression_strategy is "compress" (budget/balanced profiles).
+    // Truncate carry-forward section when it exceeds 40% of inline context budget.
     const carryForwardBudget = Math.floor(budgets.inlineContextBudgetChars * 0.4);
     let finalCarryForward = carryForwardSection;
     if (carryForwardSection.length > carryForwardBudget) {
-        const { resolveCompressionStrategy } = await import("./preferences.js");
-        if (resolveCompressionStrategy() === "compress") {
-            finalCarryForward = compressToTarget(carryForwardSection, carryForwardBudget).content;
-        }
+        const { truncateAtSectionBoundary } = await import("./context-budget.js");
+        finalCarryForward = truncateAtSectionBoundary(carryForwardSection, carryForwardBudget).content;
     }
     return loadPrompt("execute-task", {
         overridesSection,
@@ -1090,6 +1098,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

@@ -11,7 +11,7 @@
 import { deriveState } from "./state.js";
 import { loadFile, getManifestStatus } from "./files.js";
 import { loadEffectiveGSDPreferences, resolveSkillDiscoveryMode, getIsolationMode, } from "./preferences.js";
-import { ensureGsdSymlink } from "./repo-identity.js";
+import { ensureGsdSymlink, validateProjectId } from "./repo-identity.js";
 import { migrateToExternalState, recoverFailedMigration } from "./migrate-external.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
 import { gsdRoot, resolveMilestoneFile } from "./paths.js";
@@ -63,6 +63,12 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         return false;
     }
     try {
+        // Validate GSD_PROJECT_ID early so the user gets immediate feedback
+        const customProjectId = process.env.GSD_PROJECT_ID;
+        if (customProjectId && !validateProjectId(customProjectId)) {
+            ctx.ui.notify(`GSD_PROJECT_ID must contain only alphanumeric characters, hyphens, and underscores. Got: "${customProjectId}"`, "error");
+            return releaseLockAndReturn();
+        }
         // Ensure git repo exists
         if (!nativeIsRepo(base)) {
             const mainBranch = loadEffectiveGSDPreferences()?.preferences?.git?.main_branch || "main";
@@ -303,11 +309,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

@@ -13,6 +13,7 @@ import { existsSync, readFileSync, unlinkSync, readdirSync, } from "node:fs";
 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 ─────────────────────────────────────────
 /**
  * Sync milestone artifacts from project root INTO worktree before deriveState.
@@ -75,7 +76,7 @@ export function syncStateToProjectRoot(worktreePath, projectRoot, milestoneId) {
  * doesn't falsely trigger staleness (#804).
  */
 export function readResourceVersion() {
-    const agentDir = process.env.GSD_CODING_AGENT_DIR || join(homedir(), ".gsd", "agent");
+    const agentDir = 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"));
@@ -115,10 +116,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/auto.js

@@ -297,116 +297,163 @@ export async function stopAuto(ctx, pi, reason) {
         return;
     const loadedPreferences = loadEffectiveGSDPreferences()?.preferences;
     const reasonSuffix = reason ? ` — ${reason}` : "";
-    clearUnitTimeout();
-    if (lockBase())
-        clearLock(lockBase());
-    if (lockBase())
-        releaseSessionLock(lockBase());
-    clearSkillSnapshot();
-    resetSkillTelemetry();
-    // Remove SIGTERM handler registered at auto-mode start
-    deregisterSigtermHandler();
-    // ── Auto-worktree: exit worktree and reset s.basePath on stop ──
-    if (s.currentMilestoneId) {
-        const notifyCtx = ctx
-            ? { notify: ctx.ui.notify.bind(ctx.ui) }
-            : { notify: () => { } };
-        buildResolver().exitMilestone(s.currentMilestoneId, notifyCtx, {
-            preserveBranch: true,
-        });
-    }
-    // ── DB cleanup: close the SQLite connection ──
-    if (isDbAvailable()) {
+    try {
+        // ── Step 1: Timers and locks ──
         try {
-            const { closeDatabase } = await import("./gsd-db.js");
-            closeDatabase();
+            clearUnitTimeout();
+            if (lockBase())
+                clearLock(lockBase());
+            if (lockBase())
+                releaseSessionLock(lockBase());
         }
         catch (e) {
-            debugLog("db-close-failed", {
-                error: e instanceof Error ? e.message : String(e),
-            });
+            debugLog("stop-cleanup-locks", { error: e instanceof Error ? e.message : String(e) });
         }
-    }
-    if (s.originalBasePath) {
-        s.basePath = s.originalBasePath;
+        // ── Step 2: Skill state ──
         try {
-            process.chdir(s.basePath);
+            clearSkillSnapshot();
+            resetSkillTelemetry();
         }
-        catch {
-            /* best-effort */
+        catch (e) {
+            debugLog("stop-cleanup-skills", { error: e instanceof Error ? e.message : String(e) });
         }
-    }
-    const ledger = getLedger();
-    if (ledger && ledger.units.length > 0) {
-        const totals = getProjectTotals(ledger.units);
-        ctx?.ui.notify(`Auto-mode stopped${reasonSuffix}. Session: ${formatCost(totals.cost)} · ${formatTokenCount(totals.tokens.total)} tokens · ${ledger.units.length} units`, "info");
-    }
-    else {
-        ctx?.ui.notify(`Auto-mode stopped${reasonSuffix}.`, "info");
-    }
-    if (s.basePath) {
+        // ── Step 3: SIGTERM handler ──
         try {
-            await rebuildState(s.basePath);
+            deregisterSigtermHandler();
         }
         catch (e) {
-            debugLog("stop-rebuild-state-failed", {
-                error: e instanceof Error ? e.message : String(e),
-            });
+            debugLog("stop-cleanup-sigterm", { error: e instanceof Error ? e.message : String(e) });
         }
-    }
-    clearCmuxSidebar(loadedPreferences);
-    logCmuxEvent(loadedPreferences, `Auto-mode stopped${reasonSuffix || ""}.`, reason?.startsWith("Blocked:") ? "warning" : "info");
-    if (isDebugEnabled()) {
-        const logPath = writeDebugSummary();
-        if (logPath) {
-            ctx?.ui.notify(`Debug log written → ${logPath}`, "info");
+        // ── Step 4: Auto-worktree exit ──
+        try {
+            if (s.currentMilestoneId) {
+                const notifyCtx = ctx
+                    ? { notify: ctx.ui.notify.bind(ctx.ui) }
+                    : { notify: () => { } };
+                buildResolver().exitMilestone(s.currentMilestoneId, notifyCtx, {
+                    preserveBranch: true,
+                });
+            }
+        }
+        catch (e) {
+            debugLog("stop-cleanup-worktree", { error: e instanceof Error ? e.message : String(e) });
+        }
+        // ── Step 5: DB cleanup ──
+        if (isDbAvailable()) {
+            try {
+                const { closeDatabase } = await import("./gsd-db.js");
+                closeDatabase();
+            }
+            catch (e) {
+                debugLog("db-close-failed", {
+                    error: e instanceof Error ? e.message : String(e),
+                });
+            }
+        }
+        // ── Step 6: Restore basePath and chdir ──
+        try {
+            if (s.originalBasePath) {
+                s.basePath = s.originalBasePath;
+                try {
+                    process.chdir(s.basePath);
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+        }
+        catch (e) {
+            debugLog("stop-cleanup-basepath", { error: e instanceof Error ? e.message : String(e) });
+        }
+        // ── Step 7: Ledger notification ──
+        try {
+            const ledger = getLedger();
+            if (ledger && ledger.units.length > 0) {
+                const totals = getProjectTotals(ledger.units);
+                ctx?.ui.notify(`Auto-mode stopped${reasonSuffix}. Session: ${formatCost(totals.cost)} · ${formatTokenCount(totals.tokens.total)} tokens · ${ledger.units.length} units`, "info");
+            }
+            else {
+                ctx?.ui.notify(`Auto-mode stopped${reasonSuffix}.`, "info");
+            }
+        }
+        catch (e) {
+            debugLog("stop-cleanup-ledger", { error: e instanceof Error ? e.message : String(e) });
+        }
+        // ── Step 8: Rebuild state ──
+        if (s.basePath) {
+            try {
+                await rebuildState(s.basePath);
+            }
+            catch (e) {
+                debugLog("stop-rebuild-state-failed", {
+                    error: e instanceof Error ? e.message : String(e),
+                });
+            }
+        }
+        // ── Step 9: Cmux sidebar / event log ──
+        try {
+            clearCmuxSidebar(loadedPreferences);
+            logCmuxEvent(loadedPreferences, `Auto-mode stopped${reasonSuffix || ""}.`, reason?.startsWith("Blocked:") ? "warning" : "info");
+        }
+        catch (e) {
+            debugLog("stop-cleanup-cmux", { error: e instanceof Error ? e.message : String(e) });
+        }
+        // ── Step 10: Debug summary ──
+        try {
+            if (isDebugEnabled()) {
+                const logPath = writeDebugSummary();
+                if (logPath) {
+                    ctx?.ui.notify(`Debug log written → ${logPath}`, "info");
+                }
+            }
+        }
+        catch (e) {
+            debugLog("stop-cleanup-debug", { error: e instanceof Error ? e.message : String(e) });
+        }
+        // ── Step 11: Reset metrics, routing, hooks ──
+        try {
+            resetMetrics();
+            resetRoutingHistory();
+            resetHookState();
+            if (s.basePath)
+                clearPersistedHookState(s.basePath);
+        }
+        catch (e) {
+            debugLog("stop-cleanup-metrics", { error: e instanceof Error ? e.message : String(e) });
+        }
+        // ── Step 12: Remove paused-session metadata (#1383) ──
+        try {
+            const pausedPath = join(gsdRoot(s.originalBasePath || s.basePath), "runtime", "paused-session.json");
+            if (existsSync(pausedPath))
+                unlinkSync(pausedPath);
+        }
+        catch { /* non-fatal */ }
+        // ── Step 13: Restore original model (before reset clears IDs) ──
+        try {
+            if (pi && ctx && s.originalModelId && s.originalModelProvider) {
+                const original = ctx.modelRegistry.find(s.originalModelProvider, s.originalModelId);
+                if (original)
+                    await pi.setModel(original);
+            }
+        }
+        catch (e) {
+            debugLog("stop-cleanup-model", { error: e instanceof Error ? e.message : String(e) });
         }
     }
-    resetMetrics();
-    resetRoutingHistory();
-    resetHookState();
-    if (s.basePath)
-        clearPersistedHookState(s.basePath);
-    // Remove paused-session metadata if present (#1383)
-    try {
-        const pausedPath = join(gsdRoot(s.originalBasePath || s.basePath), "runtime", "paused-session.json");
-        if (existsSync(pausedPath))
-            unlinkSync(pausedPath);
-    }
-    catch { /* non-fatal */ }
-    s.active = false;
-    s.paused = false;
-    s.stepMode = false;
-    s.unitDispatchCount.clear();
-    s.unitRecoveryCount.clear();
-    clearInFlightTools();
-    s.lastBudgetAlertLevel = 0;
-    s.lastStateRebuildAt = 0;
-    s.unitLifetimeDispatches.clear();
-    s.currentUnit = null;
-    s.autoModeStartModel = null;
-    s.currentMilestoneId = null;
-    s.originalBasePath = "";
-    s.completedUnits = [];
-    s.pendingQuickTasks = [];
-    clearSliceProgressCache();
-    clearActivityLogState();
-    resetProactiveHealing();
-    s.pendingCrashRecovery = null;
-    s.pendingVerificationRetry = null;
-    s.verificationRetryCount.clear();
-    s.pausedSessionFile = null;
-    ctx?.ui.setStatus("gsd-auto", undefined);
-    ctx?.ui.setWidget("gsd-progress", undefined);
-    ctx?.ui.setFooter(undefined);
-    if (pi && ctx && s.originalModelId && s.originalModelProvider) {
-        const original = ctx.modelRegistry.find(s.originalModelProvider, s.originalModelId);
-        if (original)
-            await pi.setModel(original);
-        s.originalModelId = null;
-        s.originalModelProvider = null;
+    finally {
+        // ── Critical invariants: these MUST execute regardless of errors ──
+        // External cleanup (not covered by session reset)
+        clearInFlightTools();
+        clearSliceProgressCache();
+        clearActivityLogState();
+        resetProactiveHealing();
+        // UI cleanup
+        ctx?.ui.setStatus("gsd-auto", undefined);
+        ctx?.ui.setWidget("gsd-progress", undefined);
+        ctx?.ui.setFooter(undefined);
+        // Reset all session state in one call
+        s.reset();
     }
-    s.cmdCtx = null;
 }
 /**
  * Pause auto-mode without destroying state. Context is preserved.

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-extensions.js

@@ -8,12 +8,13 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 // ─── Registry I/O ───────────────────────────────────────────────────────────
 function getRegistryPath() {
-    return join(homedir(), ".gsd", "extensions", "registry.json");
+    return join(gsdHome, "extensions", "registry.json");
 }
 function getAgentExtensionsDir() {
-    return join(homedir(), ".gsd", "agent", "extensions");
+    return join(gsdHome, "agent", "extensions");
 }
 function loadRegistry() {
     const filePath = getRegistryPath();

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",