gsd-pi 2.71.0 → 2.72.0-dev.de4c4b3

package/README.md

@@ -27,36 +27,68 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.68
+## What's New in v2.71
 
-### MCP Workflow Tools
+### MCP Secure Env Collect
 
-- **Full workflow over MCP** — slice replanning, milestone management, slice completion, task completion, and core planning tools are now exposed over MCP for external integrations.
-- **Transport-gated MCP** — workflow tool availability adapts to provider transport capabilities automatically.
-- **Write gate enforcement** — workflow MCP respects write gates, preventing unauthorized state mutations from external clients.
+- **Secure credential collection over MCP** — the new `secure_env_collect` tool uses MCP form elicitation to collect secrets (API keys, tokens) from external clients without exposing values in tool output. Masks input in interactive mode.
+- **Hardened elicitation schema** — MCP elicitation schema handling is stricter, with proper validation and fallback for providers that don't support forms.
 
-### Reliability & Recovery
+### MCP Reliability
 
-- **False degraded-mode fix** — eliminates spurious degraded-mode warnings when the DB hasn't been initialized yet.
-- **Stale session resume suppression** — prevents stale interrupted-session resume prompts from hijacking fresh sessions.
-- **Merge conflict recovery** — `autoCommitDirtyState` guarded with cwd restore on `MergeConflictError`.
-- **Auto-resume hardening** — `autoStartTime` restored on resume, managed resources resynced on auto resume.
+- **Stream ordering preserved** — MCP tool output now renders in the correct order, fixing interleaved output in Claude Code and other MCP clients.
+- **isError flag propagation** — workflow tool execution failures now correctly return `isError: true`, so MCP clients can distinguish success from failure.
+- **Multi-round discuss questions** — new-project discuss phase supports multi-round questioning with structured question gates.
 
-### TUI & Developer Experience
+### Model Selection Hardening
 
-- **Contextual tips system** — TUI and web terminal now surface contextual tips based on workflow state.
-- **Claude Code MCP streaming** — real-time streaming and tool output rendering for Claude Code MCP connections.
+- **Unconfigured models blocked** — models without a configured provider are filtered from selection surfaces, preventing dispatch failures.
+- **Provider readiness required** — saved default model selection now verifies the provider is ready before accepting it.
+- **Session override honored** — `/gsd model` selection persists as a session override across all dispatch phases.
+- **Minimal context guard** — model override logic is skipped in minimal command contexts where it doesn't apply.
 
-### Infrastructure
+### Auto-Mode Resilience
 
-- **Weekly model registry refresh** — CI workflow auto-regenerates the model registry on a weekly schedule.
-- **Codebase cache auto-refresh** — stale codebase cache is refreshed automatically without manual intervention.
+- **Credential cooldown recovery** — auto-mode survives transient 429 rate-limit responses with structured cooldown errors and a bounded retry budget.
+- **Fire-and-forget auto start** — auto start is detached from active turns to prevent blocking.
+- **Scoped forensics** — stuck-loop forensics are now scoped to auto sessions only, preventing false positives in interactive use.
+
+### TUI Improvements
+
+- **Overlay subscription fix** — resolved overlay subscription lifecycle and `Ctrl+Shift+P` shortcut conflict.
+- **Improved overlays and shortcuts** — GSD overlays, keyboard shortcuts, and notification flows redesigned for consistency.
+- **Pinned output restored** — pinned output bar displays above the editor during tool execution again.
+- **Turn completion cleanup** — pinned latest output is cleared on turn completion, preventing stale output from persisting.
+- **Secure input masking** — extension input values are masked in interactive mode when collecting secrets.
+
+### Provider Fixes
+
+- **Full OAuth login URLs** — OAuth login URLs are now displayed in full instead of being truncated.
+- **MiniMax bearer auth** — MiniMax Anthropic API requests use proper bearer authentication.
+- **Case-insensitive tool rendering** — renderable tool matching is now case-insensitive, fixing missed tool output.
+- **Headless idle timeout** — idle timeout is kept off during interactive tool execution in headless mode.
+
+### Reliability & Internals
+
+- **TOCTOU file locking** — race conditions in event log and custom workflow graph file locking are fixed with proper atomic lock acquisition.
+- **State derive refactor** — `deriveStateFromDb` god function extracted into composable, testable helpers.
+- **Windows portability** — hardened cross-platform portability across runtime, tooling, and CI.
+- **Model routing transparency** — dynamic routing is skipped for interactive dispatches; model changes are always shown in the banner.
+- **Capability-aware routing (ADR-004)** — full implementation of capability scoring, `before_model_select` hook, and task metadata extraction.
+- **Multi-model provider strategy (ADR-005)** — infrastructure for multi-provider model selection wired into live paths.
+- **Anti-fabrication guardrails** — discuss prompts enforce turn-taking to prevent fabricated user responses.
+- **Milestone worktree cleanup** — merged worktree cleanup uses the milestone branch instead of generic lookups.
+- **Tool cache control** — `cache_control` breakpoints added to tool definitions for improved prompt caching.
 
 See the full [Changelog](./CHANGELOG.md) for details on every release.
 
 <details>
-<summary>Previous highlights (v2.67 and earlier)</summary>
+<summary>Previous highlights (v2.70 and earlier)</summary>
 
+- **Full workflow over MCP (v2.68)** — slice replanning, milestone management, slice completion, task completion, and core planning tools exposed over MCP
+- **Transport-gated MCP (v2.68)** — workflow tool availability adapts to provider transport capabilities automatically
+- **Contextual tips system (v2.68)** — TUI and web terminal surface contextual tips based on workflow state
+- **Ask user questions over MCP (v2.70)** — interactive questions exposed via elicitation for external integrations
 - **Tiered Context Injection (M005)** — relevance-scoped context with 65%+ token reduction
 - **Resilient transient error recovery** — defers to Core RetryHandler and fixes cmdCtx race conditions
 - **Anthropic subscription routing** — auto-routed through Claude Code CLI provider with proper display names
@@ -725,6 +757,14 @@ Use expensive models where quality matters (planning, complex execution) and che
 
 ---
 
+## Ecosystem
+
+| Project | Description |
+| ------- | ----------- |
+| [GSD2 Config Utility](https://github.com/jeremymcs/gsd2-config) | Standalone configuration tool for managing GSD preferences, providers, and API keys |
+
+---
+
 ## Star History
 
 <a href="https://star-history.com/#gsd-build/gsd-2&Date">

package/dist/cli.js

@@ -7,6 +7,7 @@ import { ensureManagedTools } from './tool-bootstrap.js';
 import { loadStoredEnvKeys } from './wizard.js';
 import { migratePiCredentials } from './pi-migration.js';
 import { validateConfiguredModel } from './startup-model-validation.js';
+import { shouldMigrateAnthropicToClaudeCode } from './provider-migrations.js';
 import { shouldRunOnboarding, runOnboarding } from './onboarding.js';
 import chalk from 'chalk';
 import { checkForUpdates } from './update-check.js';
@@ -233,6 +234,14 @@ if (cliFlags.messages[0] === 'sessions') {
         rl.question(chalk.bold('  Enter session number to resume (or q to quit): '), resolve);
     });
     rl.close();
+    // Clean up stdin state left by readline.createInterface().
+    // Without this, downstream TUI initialization gets corrupted listeners and exhibits
+    // duplicate terminal I/O. Match the pattern used after onboarding cleanup.
+    process.stdin.removeAllListeners('data');
+    process.stdin.removeAllListeners('keypress');
+    if (process.stdin.setRawMode)
+        process.stdin.setRawMode(false);
+    process.stdin.pause();
     const choice = parseInt(answer, 10);
     if (isNaN(choice) || choice < 1 || choice > toShow.length) {
         process.stderr.write(chalk.dim('Cancelled.\n'));
@@ -285,7 +294,7 @@ const { resolveModelsJsonPath } = await import('./models-resolver.js');
 const modelsJsonPath = resolveModelsJsonPath();
 const modelRegistry = new ModelRegistry(authStorage, modelsJsonPath);
 markStartup('ModelRegistry');
-const settingsManager = SettingsManager.create(agentDir);
+const settingsManager = SettingsManager.create(process.cwd(), agentDir);
 applySecurityOverrides(settingsManager);
 markStartup('SettingsManager.create');
 // Run onboarding wizard on first launch (no LLM provider configured)
@@ -401,7 +410,11 @@ if (isPrintMode) {
     // Migrate anthropic OAuth users to claude-code provider when CLI is available (#3772).
     // Anthropic blocks third-party apps from using subscription quotas — routing through
     // the local claude CLI binary is TOS-compliant.
-    if (modelRegistry.isProviderRequestReady('claude-code') && settingsManager.getDefaultProvider() === 'anthropic') {
+    if (shouldMigrateAnthropicToClaudeCode({
+        authStorage,
+        isClaudeCodeReady: modelRegistry.isProviderRequestReady('claude-code'),
+        defaultProvider: settingsManager.getDefaultProvider(),
+    })) {
         const currentModelId = settingsManager.getDefaultModel();
         if (currentModelId) {
             const ccModel = modelRegistry.find('claude-code', currentModelId);
@@ -466,6 +479,15 @@ if (isPrintMode) {
     if (mode === 'mcp') {
         printStartupTimings();
         const { startMcpServer } = await import('./mcp-server.js');
+        // Activate every registered tool before starting the MCP transport.
+        // `session.agent.state.tools` is the *active* subset, not the full
+        // registry — if we expose only the active set, extension-registered
+        // tools (gsd workflow, browser-tools, mac-tools, search-the-web, …)
+        // are invisible to MCP clients. Flipping the active set to every
+        // known tool name makes `state.tools` mirror the full registry for
+        // this MCP session, which is what an external client expects.
+        const allToolNames = session.getAllTools().map((t) => t.name);
+        session.setActiveToolsByName(allToolNames);
         await startMcpServer({
             tools: session.agent.state.tools ?? [],
             version: process.env.GSD_VERSION || '0.0.0',
@@ -576,7 +598,11 @@ markStartup('createAgentSession');
 // Migrate anthropic OAuth users to claude-code provider when CLI is available (#3772).
 // Anthropic blocks third-party apps from using subscription quotas — routing through
 // the local claude CLI binary is TOS-compliant.
-if (modelRegistry.isProviderRequestReady('claude-code') && settingsManager.getDefaultProvider() === 'anthropic') {
+if (shouldMigrateAnthropicToClaudeCode({
+    authStorage,
+    isClaudeCodeReady: modelRegistry.isProviderRequestReady('claude-code'),
+    defaultProvider: settingsManager.getDefaultProvider(),
+})) {
     const currentModelId = settingsManager.getDefaultModel();
     if (currentModelId) {
         const ccModel = modelRegistry.find('claude-code', currentModelId);

package/dist/headless-events.d.ts

@@ -43,6 +43,8 @@ export declare const NEW_MILESTONE_IDLE_TIMEOUT_MS = 120000;
 export declare function isTerminalNotification(event: Record<string, unknown>): boolean;
 export declare function isBlockedNotification(event: Record<string, unknown>): boolean;
 export declare function isMilestoneReadyNotification(event: Record<string, unknown>): boolean;
+export declare function isInteractiveHeadlessTool(toolName: string | undefined): boolean;
+export declare function shouldArmHeadlessIdleTimeout(toolCallCount: number, interactiveToolCount: number): boolean;
 export declare const FIRE_AND_FORGET_METHODS: Set<string>;
 export declare const QUICK_COMMANDS: Set<string>;
 export declare function isQuickCommand(command: string): boolean;

package/dist/headless-events.js

@@ -65,6 +65,7 @@ export const IDLE_TIMEOUT_MS = 15_000;
 // between tool calls (e.g. after mkdir, before writing files). Use a
 // longer idle timeout to avoid killing the session prematurely (#808).
 export const NEW_MILESTONE_IDLE_TIMEOUT_MS = 120_000;
+const INTERACTIVE_HEADLESS_TOOLS = new Set(['ask_user_questions', 'secure_env_collect']);
 export function isTerminalNotification(event) {
     if (event.type !== 'extension_ui_request' || event.method !== 'notify')
         return false;
@@ -83,6 +84,12 @@ export function isMilestoneReadyNotification(event) {
         return false;
     return /milestone\s+m\d+.*ready/i.test(String(event.message ?? ''));
 }
+export function isInteractiveHeadlessTool(toolName) {
+    return INTERACTIVE_HEADLESS_TOOLS.has(String(toolName ?? ''));
+}
+export function shouldArmHeadlessIdleTimeout(toolCallCount, interactiveToolCount) {
+    return toolCallCount > 0 && interactiveToolCount === 0;
+}
 // ---------------------------------------------------------------------------
 // Quick Command Detection
 // ---------------------------------------------------------------------------

package/dist/headless.js

@@ -17,7 +17,7 @@ import { resolve } from 'node:path';
 import { RpcClient, SessionManager } from '@gsd/pi-coding-agent';
 import { getProjectSessionsDir } from './project-sessions.js';
 import { loadAndValidateAnswerFile, AnswerInjector } from './headless-answers.js';
-import { isTerminalNotification, isBlockedNotification, isMilestoneReadyNotification, isQuickCommand, FIRE_AND_FORGET_METHODS, IDLE_TIMEOUT_MS, NEW_MILESTONE_IDLE_TIMEOUT_MS, EXIT_SUCCESS, EXIT_ERROR, EXIT_BLOCKED, EXIT_CANCELLED, mapStatusToExitCode, } from './headless-events.js';
+import { isTerminalNotification, isBlockedNotification, isMilestoneReadyNotification, isQuickCommand, FIRE_AND_FORGET_METHODS, IDLE_TIMEOUT_MS, NEW_MILESTONE_IDLE_TIMEOUT_MS, isInteractiveHeadlessTool, shouldArmHeadlessIdleTimeout, EXIT_SUCCESS, EXIT_ERROR, EXIT_BLOCKED, EXIT_CANCELLED, mapStatusToExitCode, } from './headless-events.js';
 import { VALID_OUTPUT_FORMATS } from './headless-types.js';
 import { handleExtensionUIRequest, formatProgress, formatThinkingLine, formatTextStart, formatTextEnd, formatThinkingStart, formatThinkingEnd, startSupervisedStdinReader, } from './headless-ui.js';
 import { loadContext, bootstrapGsdProject, } from './headless-context.js';
@@ -282,6 +282,7 @@ async function runHeadlessOnce(options, restartCount) {
     let exitCode = 0;
     let milestoneReady = false; // tracks "Milestone X ready." for auto-chaining
     const recentEvents = [];
+    const interactiveToolCallIds = new Set();
     // JSON batch mode: cost aggregation (cumulative-max pattern per K004)
     let cumulativeCostUsd = 0;
     let cumulativeInputTokens = 0;
@@ -365,7 +366,7 @@ async function runHeadlessOnce(options, restartCount) {
     function resetIdleTimer() {
         if (idleTimer)
             clearTimeout(idleTimer);
-        if (toolCallCount > 0) {
+        if (shouldArmHeadlessIdleTimeout(toolCallCount, interactiveToolCallIds.size)) {
             idleTimer = setTimeout(() => {
                 completed = true;
                 resolveCompletion();
@@ -386,13 +387,25 @@ async function runHeadlessOnce(options, restartCount) {
     client.onEvent((event) => {
         const eventObj = event;
         trackEvent(eventObj);
+        const eventType = String(eventObj.type ?? '');
+        if (eventType === 'tool_execution_start') {
+            const toolCallId = String(eventObj.toolCallId ?? eventObj.id ?? '');
+            if (toolCallId && isInteractiveHeadlessTool(String(eventObj.toolName ?? ''))) {
+                interactiveToolCallIds.add(toolCallId);
+            }
+        }
+        else if (eventType === 'tool_execution_end') {
+            const toolCallId = String(eventObj.toolCallId ?? eventObj.id ?? '');
+            if (toolCallId) {
+                interactiveToolCallIds.delete(toolCallId);
+            }
+        }
         resetIdleTimer();
         // Answer injector: observe events for question metadata
         injector?.observeEvent(eventObj);
         // --json / --output-format stream-json: forward events as JSONL to stdout (filtered if --events)
         // --output-format json (batch mode): suppress streaming, track cost for final result
         if (options.json && options.outputFormat === 'stream-json') {
-            const eventType = String(eventObj.type ?? '');
             if (!options.eventFilter || options.eventFilter.has(eventType)) {
                 process.stdout.write(JSON.stringify(eventObj) + '\n');
             }

package/dist/mcp-server.js

@@ -1,10 +1,15 @@
-// MCP SDK subpath imports use wildcard exports (./*) that NodeNext resolves
-// at runtime but TypeScript cannot statically type-check. We construct the
-// specifiers dynamically so tsc treats them as `any`.
-// Use createRequire to resolve wildcard subpaths — CJS resolver auto-appends
-// .js, which the ESM wildcard export map does not (#3603).
-import { createRequire } from 'node:module';
-const _require = createRequire(import.meta.url);
+// MCP SDK subpath imports use wildcard exports (./*) in @modelcontextprotocol/sdk's
+// package.json export map. The wildcard maps "./foo" → "./dist/cjs/foo" (no .js
+// suffix), so bare subpath specifiers like `${MCP_PKG}/server/stdio` resolve to
+// a non-existent file. Historically the workaround (#3603) used createRequire so
+// the CJS resolver could auto-append `.js`; that no longer works with current
+// Node + SDK releases (#3914) — `_require.resolve` also fails with
+// "Cannot find module .../dist/cjs/server/stdio".
+//
+// The reliable convention (matching packages/mcp-server/{server,cli}.ts) is to
+// write the `.js` suffix explicitly on every wildcard subpath. Specifiers are
+// built via a template string so TypeScript's NodeNext resolver treats them as
+// `any` and skips static checking.
 const MCP_PKG = '@modelcontextprotocol/sdk';
 /**
  * Starts a native MCP (Model Context Protocol) server over stdin/stdout.
@@ -22,9 +27,9 @@ const MCP_PKG = '@modelcontextprotocol/sdk';
  */
 export async function startMcpServer(options) {
     const { tools, version = '0.0.0' } = options;
-    const serverMod = await import(`${MCP_PKG}/server`);
-    const stdioMod = await import(_require.resolve(`${MCP_PKG}/server/stdio`));
-    const typesMod = await import(_require.resolve(`${MCP_PKG}/types`));
+    const serverMod = await import(`${MCP_PKG}/server/index.js`);
+    const stdioMod = await import(`${MCP_PKG}/server/stdio.js`);
+    const typesMod = await import(`${MCP_PKG}/types.js`);
     const Server = serverMod.Server;
     const StdioServerTransport = stdioMod.StdioServerTransport;
     const { ListToolsRequestSchema, CallToolRequestSchema } = typesMod;
@@ -42,8 +47,14 @@ export async function startMcpServer(options) {
             inputSchema: t.parameters,
         })),
     }));
-    // tools/call — execute the requested tool and return content blocks
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    // tools/call — execute the requested tool and return content blocks.
+    //
+    // The MCP SDK passes an `extra` argument to request handlers that includes
+    // an AbortSignal scoped to the RPC request (cancelled when the client
+    // cancels the tool call or the transport closes). Threading it into
+    // AgentTool.execute ensures long-running tools (Bash, WebFetch, grep on
+    // huge trees) actually stop when the client gives up on the result.
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         const { name, arguments: args } = request.params;
         const tool = toolMap.get(name);
         if (!tool) {
@@ -52,20 +63,32 @@ export async function startMcpServer(options) {
                 content: [{ type: 'text', text: `Unknown tool: ${name}` }],
             };
         }
+        const signal = extra?.signal;
         try {
-            const result = await tool.execute(`mcp-${Date.now()}`, args ?? {}, undefined, // no AbortSignal
-            undefined);
-            // Convert AgentToolResult content blocks to MCP content format
+            const result = await tool.execute(`mcp-${Date.now()}`, args ?? {}, signal, undefined);
+            // Convert AgentToolResult content blocks to MCP content format.
+            // text and image pass through; any other shape is serialized as text
+            // so the client sees the payload rather than an empty response.
             const content = result.content.map((block) => {
                 if (block.type === 'text')
                     return { type: 'text', text: block.text ?? '' };
-                if (block.type === 'image')
-                    return { type: 'image', data: block.data ?? '', mimeType: block.mimeType ?? 'image/png' };
+                if (block.type === 'image') {
+                    return {
+                        type: 'image',
+                        data: block.data ?? '',
+                        mimeType: block.mimeType ?? 'image/png',
+                    };
+                }
+                // Preserve unknown block types (resource, resource_link, audio, ...)
+                // by stringifying into a text block so clients see the payload.
                 return { type: 'text', text: JSON.stringify(block) };
             });
             return { content };
         }
         catch (err) {
+            // AbortError from a cancelled tool surfaces as a normal error — MCP
+            // clients interpret `isError: true` as a failed call, which is the
+            // correct behaviour for a cancelled request.
             const message = err instanceof Error ? err.message : String(err);
             return { isError: true, content: [{ type: 'text', text: message }] };
         }

package/dist/provider-migrations.d.ts

@@ -0,0 +1,10 @@
+import type { AuthStorage } from "@gsd/pi-coding-agent";
+type AnthropicMigrationDeps = {
+    authStorage: Pick<AuthStorage, "getCredentialsForProvider">;
+    isClaudeCodeReady: boolean;
+    defaultProvider: string | undefined;
+    env?: NodeJS.ProcessEnv;
+};
+export declare function hasDirectAnthropicApiKey(authStorage: Pick<AuthStorage, "getCredentialsForProvider">, env?: NodeJS.ProcessEnv): boolean;
+export declare function shouldMigrateAnthropicToClaudeCode({ authStorage, isClaudeCodeReady, defaultProvider, env, }: AnthropicMigrationDeps): boolean;
+export {};

package/dist/provider-migrations.js

@@ -0,0 +1,12 @@
+export function hasDirectAnthropicApiKey(authStorage, env = process.env) {
+    if ((env.ANTHROPIC_API_KEY ?? "").trim()) {
+        return true;
+    }
+    return authStorage.getCredentialsForProvider("anthropic").some((credential) => credential?.type === "api_key" && typeof credential?.key === "string" && credential.key.trim().length > 0);
+}
+export function shouldMigrateAnthropicToClaudeCode({ authStorage, isClaudeCodeReady, defaultProvider, env = process.env, }) {
+    if (!isClaudeCodeReady || defaultProvider !== "anthropic") {
+        return false;
+    }
+    return !hasDirectAnthropicApiKey(authStorage, env);
+}

package/dist/resource-loader.js

@@ -2,7 +2,7 @@ import { DefaultResourceLoader, sortExtensionPaths } from '@gsd/pi-coding-agent'
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { chmodSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, openSync, closeSync, readFileSync, readlinkSync, readdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname, join, relative, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { compareSemver } from './update-check.js';
 import { discoverExtensionEntryPaths } from './extension-discovery.js';
@@ -254,34 +254,160 @@ function copyDirRecursive(src, dest) {
  * ~/.gsd/agent/extensions/ have no ancestor node_modules, so imports of
  * @gsd/* packages fail. The symlink makes Node's standard resolution find
  * them without requiring every call site to use jiti.
+ *
+ * Layout differences by install method:
+ * - Source/monorepo: packageRoot/node_modules has everything → simple symlink
+ * - npm/bun global: deps hoisted to dirname(packageRoot), including @gsd/* → simple symlink
+ * - pnpm global: external deps hoisted, but @gsd/* stays in packageRoot/node_modules
+ *   → merged directory with symlinks from both roots (#3529, #3564)
  */
 function ensureNodeModulesSymlink(agentDir) {
     const agentNodeModules = join(agentDir, 'node_modules');
-    const gsdNodeModules = join(packageRoot, 'node_modules');
+    const internalNodeModules = join(packageRoot, 'node_modules');
+    const hoistedNodeModules = dirname(packageRoot);
+    const isGlobalInstall = basename(hoistedNodeModules) === 'node_modules';
+    if (!isGlobalInstall) {
+        // Source/monorepo: internal node_modules has everything
+        reconcileSymlink(agentNodeModules, internalNodeModules);
+        return;
+    }
+    // Global install: check if workspace scopes (@gsd/*) are hoisted.
+    // npm/bun hoist everything; pnpm keeps workspace packages internal.
+    if (!hasMissingWorkspaceScopes(hoistedNodeModules, internalNodeModules)) {
+        // Everything is hoisted — simple symlink to parent node_modules
+        reconcileSymlink(agentNodeModules, hoistedNodeModules);
+        return;
+    }
+    // pnpm-style layout: create a real directory merging both roots
+    reconcileMergedNodeModules(agentNodeModules, hoistedNodeModules, internalNodeModules);
+}
+/** Check if any @gsd* scopes exist in internal but not in hoisted node_modules */
+function hasMissingWorkspaceScopes(hoisted, internal) {
+    if (!existsSync(internal))
+        return false;
     try {
-        const stat = lstatSync(agentNodeModules);
+        for (const entry of readdirSync(internal, { withFileTypes: true })) {
+            if (entry.isDirectory() && entry.name.startsWith('@gsd') &&
+                !existsSync(join(hoisted, entry.name))) {
+                return true;
+            }
+        }
+    }
+    catch { /* non-fatal */ }
+    return false;
+}
+/** Ensure a symlink at `link` points to `target`, fixing stale/wrong entries */
+function reconcileSymlink(link, target) {
+    try {
+        const stat = lstatSync(link);
         if (stat.isSymbolicLink()) {
-            const existing = readlinkSync(agentNodeModules);
-            // Symlink exists — verify it points to the correct, existing target
-            if (existing === gsdNodeModules && existsSync(agentNodeModules))
+            const existing = readlinkSync(link);
+            if (existing === target && existsSync(link))
                 return; // correct and target exists
-            // Stale or wrong target — remove and recreate
+            unlinkSync(link);
+        }
+        else {
+            // Real directory (or merged dir from previous pnpm fix) — remove it
+            rmSync(link, { recursive: true, force: true });
+        }
+    }
+    catch {
+        // lstatSync throws if path doesn't exist — fine, we'll create below
+    }
+    try {
+        symlinkSync(target, link, 'junction');
+    }
+    catch (err) {
+        console.error(`[gsd] WARN: Failed to symlink ${link} → ${target}: ${err instanceof Error ? err.message : err}`);
+    }
+}
+/**
+ * Create a real node_modules directory containing symlinks from both the
+ * hoisted root (external deps) and internal root (@gsd/* workspace packages).
+ * Used for pnpm global installs where @gsd/* isn't hoisted.
+ */
+function reconcileMergedNodeModules(agentNodeModules, hoisted, internal) {
+    // Fast path: if already merged for this packageRoot + same directory contents, skip.
+    // The fingerprint includes entry names from both roots so `pnpm add/remove` triggers rebuild.
+    const marker = join(agentNodeModules, '.gsd-merged');
+    const fingerprint = mergedFingerprint(hoisted, internal);
+    try {
+        if (existsSync(marker) && readFileSync(marker, 'utf-8').trim() === fingerprint)
+            return;
+    }
+    catch { /* rebuild */ }
+    // Remove any existing symlink or stale merged directory
+    try {
+        const stat = lstatSync(agentNodeModules);
+        if (stat.isSymbolicLink()) {
             unlinkSync(agentNodeModules);
         }
         else {
-            // Real directory (not a symlink) is blocking — remove it
             rmSync(agentNodeModules, { recursive: true, force: true });
         }
     }
-    catch {
-        // lstatSync throws if path doesn't exist — that's fine, we'll create below
+    catch { /* doesn't exist */ }
+    mkdirSync(agentNodeModules, { recursive: true });
+    let linkedCount = 0;
+    // Symlink entries from the hoisted node_modules (external deps)
+    try {
+        for (const entry of readdirSync(hoisted, { withFileTypes: true })) {
+            // Skip the gsd-pi package itself and dotfiles
+            if (entry.name === basename(packageRoot))
+                continue;
+            if (entry.name.startsWith('.'))
+                continue;
+            try {
+                symlinkSync(join(hoisted, entry.name), join(agentNodeModules, entry.name));
+                linkedCount++;
+            }
+            catch { /* skip individual */ }
+        }
     }
+    catch (err) {
+        console.error(`[gsd] WARN: Failed to read hoisted node_modules at ${hoisted}: ${err instanceof Error ? err.message : err}`);
+    }
+    // Overlay internal node_modules entries that weren't hoisted.
+    // This covers @gsd/* workspace packages AND optional deps like
+    // @anthropic-ai/claude-agent-sdk that npm keeps internal.
     try {
-        symlinkSync(gsdNodeModules, agentNodeModules, 'junction');
+        for (const entry of readdirSync(internal, { withFileTypes: true })) {
+            if (entry.name.startsWith('.'))
+                continue;
+            const link = join(agentNodeModules, entry.name);
+            // Replace hoisted symlink with internal version (internal takes precedence)
+            try {
+                lstatSync(link);
+                unlinkSync(link);
+            }
+            catch { /* didn't exist — will create below */ }
+            try {
+                symlinkSync(join(internal, entry.name), link);
+                linkedCount++;
+            }
+            catch { /* skip individual */ }
+        }
     }
     catch (err) {
-        // This failure makes GSD non-functional — extensions can't resolve @gsd/* packages
-        console.error(`[gsd] WARN: Failed to symlink ${agentNodeModules} → ${gsdNodeModules}: ${err instanceof Error ? err.message : err}`);
+        console.error(`[gsd] WARN: Failed to read internal node_modules at ${internal}: ${err instanceof Error ? err.message : err}`);
+    }
+    // Only stamp marker if we actually linked something — avoids caching a broken state
+    if (linkedCount > 0) {
+        try {
+            writeFileSync(marker, fingerprint);
+        }
+        catch { /* non-fatal */ }
+    }
+}
+/** Build a cache fingerprint from packageRoot + sorted entry names of both directories */
+function mergedFingerprint(hoisted, internal) {
+    try {
+        const h = readdirSync(hoisted).sort().join(',');
+        const i = readdirSync(internal).sort().join(',');
+        return `${packageRoot}\n${h}\n${i}`;
+    }
+    catch {
+        return packageRoot; // fallback: at least invalidate on version change
     }
 }
 /**

package/dist/resources/GSD-WORKFLOW.md

@@ -275,7 +275,7 @@ Work flows through these phases. Each phase produces a file.
 **How to do it manually:**
 1. Read the roadmap to understand the scope.
 2. Identify 3-5 gray areas — implementation decisions the user cares about.
-3. Use `ask_user_questions` to discuss each area.
+3. Use `ask_user_questions` to discuss each area, one round at a time. Never fabricate user input; wait for the user's actual response before the next round.
 4. Write decisions to the appropriate context file (`M###-CONTEXT.md` or `S##-CONTEXT.md`).
 5. Do NOT discuss how to implement — only what the user wants.
 

package/dist/resources/agents/debugger.md

@@ -0,0 +1,58 @@
+---
+name: debugger
+description: Hypothesis-driven bug investigation with root cause analysis
+model: sonnet
+---
+
+You are a debugger. Investigate bugs using a systematic, hypothesis-driven approach. Your goal is to find the root cause, not just suppress symptoms.
+
+## Process
+
+1. **Reproduce**: Understand the symptoms — what happens vs. what should happen
+2. **Hypothesize**: List 2-3 most likely causes based on symptoms
+3. **Investigate**: For each hypothesis, gather evidence (read code, check logs, trace execution)
+4. **Narrow**: Eliminate hypotheses that don't match the evidence
+5. **Root cause**: Identify the actual cause with file:line references
+6. **Fix**: Propose the minimal change that addresses the root cause
+
+## Investigation Tools
+
+- Read source files at specific line ranges
+- Grep for error messages, function names, variable usage
+- Check git blame for recent changes to suspect areas
+- Read test files to understand expected behavior
+- Run tests to reproduce failures
+
+## Output Format
+
+## Symptoms
+
+What's happening vs. what's expected.
+
+## Hypotheses
+
+1. **[hypothesis]** — why this could be the cause
+2. **[hypothesis]** — why this could be the cause
+
+## Investigation
+
+### Hypothesis 1: [name]
+
+Evidence gathered, files read, what was found.
+**Verdict:** Confirmed / Eliminated — reason.
+
+### Hypothesis 2: [name]
+
+(same structure)
+
+## Root Cause
+
+**File:** `path/to/file.ts:42`
+**Cause:** Clear explanation of the bug.
+**Why it wasn't caught:** Missing test, edge case, etc.
+
+## Recommended Fix
+
+```typescript
+// minimal fix with explanation
+```