gsd-pi 2.67.0-dev.5399650 → 2.67.0-dev.fe39184

package/README.md

@@ -95,7 +95,7 @@ See the full [Changelog](./CHANGELOG.md) for details on every release.
 
 ## Documentation
 
-Full documentation is available in the [`docs/`](./docs/) directory:
+Full documentation is available at **[gsd.build](https://gsd.build)** (powered by Mintlify) and in the [`docs/`](./docs/) directory:
 
 - **[Getting Started](./docs/getting-started.md)** — install, first run, basic usage
 - **[Auto Mode](./docs/auto-mode.md)** — autonomous execution deep-dive

package/dist/resources/extensions/claude-code-cli/stream-adapter.js

@@ -124,70 +124,6 @@ export function makeStreamExhaustedErrorMessage(model, lastTextContent) {
     }
     return message;
 }
-/**
- * Claude Code executes its own internal tool loop inside the SDK call. The
- * streamed and final assistant messages should therefore contain only
- * user-facing content (text/thinking), not replayable tool blocks that GSD
- * would render again.
- */
-function isUserFacingClaudeCodeBlock(block) {
-    return block.type === "text" || block.type === "thinking";
-}
-function filterUserFacingClaudeCodeContent(blocks) {
-    return blocks.filter(isUserFacingClaudeCodeBlock);
-}
-function remapClaudeCodeContentIndex(blocks, contentIndex) {
-    let visibleCount = 0;
-    for (let i = 0; i <= contentIndex && i < blocks.length; i++) {
-        if (isUserFacingClaudeCodeBlock(blocks[i]))
-            visibleCount++;
-    }
-    return Math.max(0, visibleCount - 1);
-}
-function sanitizeClaudeCodePartial(partial) {
-    return {
-        ...partial,
-        content: filterUserFacingClaudeCodeContent(partial.content),
-    };
-}
-export function sanitizeClaudeCodeStreamingEvent(event) {
-    switch (event.type) {
-        case "toolcall_start":
-        case "toolcall_delta":
-        case "toolcall_end":
-        case "server_tool_use":
-        case "web_search_result":
-            return null;
-        case "text_start":
-        case "text_delta":
-        case "text_end":
-        case "thinking_start":
-        case "thinking_delta":
-        case "thinking_end":
-            return {
-                ...event,
-                contentIndex: remapClaudeCodeContentIndex(event.partial.content, event.contentIndex),
-                partial: sanitizeClaudeCodePartial(event.partial),
-            };
-        default:
-            return event;
-    }
-}
-export function buildFinalClaudeCodeContent(blocks, lastThinkingContent, lastTextContent, resultText) {
-    const finalContent = filterUserFacingClaudeCodeContent(blocks);
-    if (finalContent.length > 0)
-        return finalContent;
-    if (lastThinkingContent) {
-        finalContent.push({ type: "thinking", thinking: lastThinkingContent });
-    }
-    if (lastTextContent) {
-        finalContent.push({ type: "text", text: lastTextContent });
-    }
-    if (finalContent.length === 0 && resultText) {
-        finalContent.push({ type: "text", text: resultText });
-    }
-    return finalContent;
-}
 // ---------------------------------------------------------------------------
 // SDK options builder
 // ---------------------------------------------------------------------------
@@ -213,6 +149,94 @@ export function buildSdkOptions(modelId, prompt) {
         betas: modelId.includes("sonnet") ? ["context-1m-2025-08-07"] : [],
     };
 }
+function normalizeToolResultContent(content) {
+    if (typeof content === "string") {
+        return [{ type: "text", text: content }];
+    }
+    if (!Array.isArray(content)) {
+        if (content == null)
+            return [{ type: "text", text: "" }];
+        return [{ type: "text", text: JSON.stringify(content) }];
+    }
+    const blocks = [];
+    for (const item of content) {
+        if (typeof item === "string") {
+            blocks.push({ type: "text", text: item });
+            continue;
+        }
+        if (!item || typeof item !== "object") {
+            blocks.push({ type: "text", text: String(item) });
+            continue;
+        }
+        const block = item;
+        if (block.type === "text") {
+            blocks.push({ type: "text", text: typeof block.text === "string" ? block.text : "" });
+            continue;
+        }
+        if (block.type === "image"
+            && typeof block.data === "string"
+            && typeof block.mimeType === "string") {
+            blocks.push({ type: "image", data: block.data, mimeType: block.mimeType });
+            continue;
+        }
+        blocks.push({ type: "text", text: JSON.stringify(block) });
+    }
+    return blocks.length > 0 ? blocks : [{ type: "text", text: "" }];
+}
+export function extractToolResultsFromSdkUserMessage(message) {
+    const extracted = [];
+    const seen = new Set();
+    const rawMessage = message.message;
+    const content = Array.isArray(rawMessage?.content) ? rawMessage.content : [];
+    for (const item of content) {
+        if (!item || typeof item !== "object")
+            continue;
+        const block = item;
+        const type = typeof block.type === "string" ? block.type : "";
+        if (type !== "tool_result" && type !== "mcp_tool_result")
+            continue;
+        const toolUseId = typeof block.tool_use_id === "string" ? block.tool_use_id : "";
+        if (!toolUseId || seen.has(toolUseId))
+            continue;
+        seen.add(toolUseId);
+        extracted.push({
+            toolUseId,
+            result: {
+                content: normalizeToolResultContent(block.content),
+                details: {},
+                isError: block.is_error === true,
+            },
+        });
+    }
+    if (extracted.length === 0) {
+        const fallback = message.tool_use_result;
+        if (fallback && typeof fallback === "object") {
+            const toolResult = fallback;
+            const toolUseId = typeof toolResult.tool_use_id === "string" ? toolResult.tool_use_id : "";
+            if (toolUseId) {
+                extracted.push({
+                    toolUseId,
+                    result: {
+                        content: normalizeToolResultContent(toolResult.content),
+                        details: {},
+                        isError: toolResult.is_error === true,
+                    },
+                });
+            }
+        }
+    }
+    return extracted;
+}
+function attachExternalResultsToToolCalls(toolCalls, toolResultsById) {
+    for (const block of toolCalls) {
+        if (block.type !== "toolCall")
+            continue;
+        const externalResult = toolResultsById.get(block.id);
+        if (!externalResult)
+            continue;
+        block.externalResult = externalResult;
+    }
+}
 // ---------------------------------------------------------------------------
 // streamSimple implementation
 // ---------------------------------------------------------------------------
@@ -234,6 +258,10 @@ async function pumpSdkMessages(model, context, options, stream) {
     /** Track the last text content seen across all assistant turns for the final message. */
     let lastTextContent = "";
     let lastThinkingContent = "";
+    /** Collect tool calls from intermediate SDK turns for tool_execution events. */
+    const intermediateToolCalls = [];
+    /** Preserve real external tool results from Claude Code's synthetic user messages. */
+    const toolResultsById = new Map();
     try {
         // Dynamic import — the SDK is an optional dependency.
         const sdkModule = "@anthropic-ai/claude-agent-sdk";
@@ -285,11 +313,9 @@ async function pumpSdkMessages(model, context, options, stream) {
                     if (!builder)
                         break;
                     const assistantEvent = builder.handleEvent(event);
-                    const sanitizedEvent = assistantEvent
-                        ? sanitizeClaudeCodeStreamingEvent(assistantEvent)
-                        : null;
-                    if (sanitizedEvent)
-                        stream.push(sanitizedEvent);
+                    if (assistantEvent) {
+                        stream.push(assistantEvent);
+                    }
                     break;
                 }
                 // -- Complete assistant message (non-streaming fallback) --
@@ -317,6 +343,36 @@ async function pumpSdkMessages(model, context, options, stream) {
                             else if (block.type === "thinking" && block.thinking) {
                                 lastThinkingContent = block.thinking;
                             }
+                            else if (block.type === "toolCall") {
+                                // Collect tool calls for externalToolExecution rendering
+                                intermediateToolCalls.push(block);
+                            }
+                        }
+                    }
+                    // Extract tool results from the SDK's synthetic user message
+                    // and attach to corresponding tool call blocks immediately.
+                    for (const { toolUseId, result } of extractToolResultsFromSdkUserMessage(msg)) {
+                        toolResultsById.set(toolUseId, result);
+                    }
+                    attachExternalResultsToToolCalls(intermediateToolCalls, toolResultsById);
+                    // Push a synthetic toolcall_end for each tool call from this turn
+                    // so the TUI can render tool results in real-time during the SDK
+                    // session instead of waiting until the entire session completes.
+                    if (builder) {
+                        for (const block of builder.message.content) {
+                            if (block.type !== "toolCall")
+                                continue;
+                            const extResult = block.externalResult;
+                            if (!extResult)
+                                continue;
+                            // Push a toolcall_end with result attached so the chat-controller
+                            // can call updateResult on the pending ToolExecutionComponent.
+                            stream.push({
+                                type: "toolcall_end",
+                                contentIndex: builder.message.content.indexOf(block),
+                                toolCall: block,
+                                partial: builder.message,
+                            });
                         }
                     }
                     builder = null;
@@ -325,7 +381,33 @@ async function pumpSdkMessages(model, context, options, stream) {
                 // -- Result (terminal) --
                 case "result": {
                     const result = msg;
-                    const finalContent = buildFinalClaudeCodeContent(builder?.message.content ?? [], lastThinkingContent, lastTextContent, result.subtype === "success" ? result.result : undefined);
+                    // Build final message. Include intermediate tool calls so the
+                    // agent loop's externalToolExecution path emits tool_execution
+                    // events for proper TUI rendering, followed by the text response.
+                    const finalContent = [];
+                    // Add tool calls from intermediate turns first (renders above text)
+                    attachExternalResultsToToolCalls(intermediateToolCalls, toolResultsById);
+                    finalContent.push(...intermediateToolCalls);
+                    // Add text/thinking from the last turn
+                    if (builder && builder.message.content.length > 0) {
+                        for (const block of builder.message.content) {
+                            if (block.type === "text" || block.type === "thinking") {
+                                finalContent.push(block);
+                            }
+                        }
+                    }
+                    else {
+                        if (lastThinkingContent) {
+                            finalContent.push({ type: "thinking", thinking: lastThinkingContent });
+                        }
+                        if (lastTextContent) {
+                            finalContent.push({ type: "text", text: lastTextContent });
+                        }
+                    }
+                    // Fallback: use the SDK's result text if we have no content
+                    if (finalContent.length === 0 && result.subtype === "success" && result.result) {
+                        finalContent.push({ type: "text", text: result.result });
+                    }
                     const finalMessage = {
                         role: "assistant",
                         content: finalContent,

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

@@ -250,6 +250,18 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
                 logWarning("engine", `mkdir failed: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
+        if (ctx.model?.provider === "claude-code") {
+            try {
+                const { ensureProjectWorkflowMcpConfig } = await import("./mcp-project-config.js");
+                const result = ensureProjectWorkflowMcpConfig(base);
+                if (result.status !== "unchanged") {
+                    ctx.ui.notify(`Claude Code MCP prepared at ${result.configPath}`, "info");
+                }
+            }
+            catch (err) {
+                ctx.ui.notify(`Claude Code MCP prep failed: ${err instanceof Error ? err.message : String(err)}`, "warning");
+            }
+        }
         // Initialize GitServiceImpl
         s.gitService = new GitServiceImpl(s.basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
         // Check for crash from previous session. Skip our own fresh bootstrap lock.

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

@@ -58,7 +58,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "templates", desc: "List available workflow templates" },
     { cmd: "extensions", desc: "Manage extensions (list, enable, disable, info)" },
     { cmd: "fast", desc: "Toggle OpenAI service tier (on/off/flex/status)" },
-    { cmd: "mcp", desc: "MCP server status and connectivity check (status, check <server>)" },
+    { cmd: "mcp", desc: "MCP server status, connectivity, and local config bootstrap (status, check, init)" },
     { cmd: "rethink", desc: "Conversational project reorganization — reorder, park, discard, add milestones" },
     { cmd: "workflow", desc: "Custom workflow lifecycle (new, run, list, validate, pause, resume)" },
     { cmd: "codebase", desc: "Generate, refresh, and inspect the codebase map cache (.gsd/CODEBASE.md)" },
@@ -188,6 +188,7 @@ const NESTED_COMPLETIONS = {
     mcp: [
         { cmd: "status", desc: "Show all MCP server statuses (default)" },
         { cmd: "check", desc: "Detailed status for a specific server" },
+        { cmd: "init", desc: "Write .mcp.json for the local GSD workflow MCP server" },
     ],
     doctor: [
         { cmd: "fix", desc: "Auto-fix detected issues" },

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

@@ -55,7 +55,7 @@ export function showHelp(ctx) {
         "  /gsd hooks          Show post-unit hook configuration",
         "  /gsd extensions     Manage extensions  [list|enable|disable|info]",
         "  /gsd fast           Toggle OpenAI service tier  [on|off|flex|status]",
-        "  /gsd mcp            MCP server status and connectivity  [status|check <server>]",
+        "  /gsd mcp            MCP server status and connectivity  [status|check <server>|init [dir]]",
         "",
         "MAINTENANCE",
         "  /gsd doctor         Diagnose and repair .gsd/ state  [audit|fix|heal] [scope]",

package/dist/resources/extensions/gsd/commands-mcp-status.js

@@ -7,9 +7,26 @@
  *   /gsd mcp             — Overview of all servers (alias: /gsd mcp status)
  *   /gsd mcp status      — Same as bare /gsd mcp
  *   /gsd mcp check <srv> — Detailed status for a specific server
+ *   /gsd mcp init [dir]  — Write project-local GSD workflow MCP config
  */
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
+import { ensureProjectWorkflowMcpConfig } from "./mcp-project-config.js";
+export function formatMcpInitResult(status, configPath, targetPath) {
+    const summary = status === "created"
+        ? "Created project MCP config."
+        : status === "updated"
+            ? "Updated project MCP config."
+            : "Project MCP config is already up to date.";
+    return [
+        summary,
+        "",
+        `Project: ${targetPath}`,
+        `Config:   ${configPath}`,
+        "",
+        "Claude Code can now load the GSD workflow MCP server from this folder.",
+    ].join("\n");
+}
 function readMcpConfigs() {
     const servers = [];
     const seen = new Set();
@@ -61,6 +78,7 @@ export function formatMcpStatusReport(servers) {
             "No MCP servers configured.",
             "",
             "Add servers to .mcp.json or .gsd/mcp.json to enable MCP integrations.",
+            "Tip: run /gsd mcp init . to write the local GSD workflow MCP config.",
             "See: https://modelcontextprotocol.io/quickstart",
         ].join("\n");
     }
@@ -109,11 +127,28 @@ export function formatMcpServerDetail(server) {
  * Handle `/gsd mcp [status|check <server>]`.
  */
 export async function handleMcpStatus(args, ctx) {
-    const trimmed = args.trim().toLowerCase();
+    const trimmed = args.trim();
+    const lowered = trimmed.toLowerCase();
     const configs = readMcpConfigs();
+    // /gsd mcp init [dir]
+    if (!lowered || lowered === "status") {
+        // handled below
+    }
+    else if (lowered === "init" || lowered.startsWith("init ")) {
+        const rawPath = trimmed.slice("init".length).trim();
+        const targetPath = resolve(rawPath || ".");
+        try {
+            const result = ensureProjectWorkflowMcpConfig(targetPath);
+            ctx.ui.notify(formatMcpInitResult(result.status, result.configPath, targetPath), "info");
+        }
+        catch (err) {
+            ctx.ui.notify(`Failed to prepare MCP config for ${targetPath}: ${err instanceof Error ? err.message : String(err)}`, "error");
+        }
+        return;
+    }
     // /gsd mcp check <server>
-    if (trimmed.startsWith("check ")) {
-        const serverName = args.trim().slice("check ".length).trim();
+    if (lowered.startsWith("check ")) {
+        const serverName = trimmed.slice("check ".length).trim();
         const config = configs.find((c) => c.name === serverName);
         if (!config) {
             const available = configs.map((c) => c.name).join(", ") || "(none)";
@@ -149,7 +184,7 @@ export async function handleMcpStatus(args, ctx) {
         return;
     }
     // /gsd mcp or /gsd mcp status
-    if (!trimmed || trimmed === "status") {
+    if (!lowered || lowered === "status") {
         // Build status for each server
         const statuses = [];
         for (const config of configs) {
@@ -181,7 +216,8 @@ export async function handleMcpStatus(args, ctx) {
         return;
     }
     // Unknown subcommand
-    ctx.ui.notify("Usage: /gsd mcp [status|check <server>]\n\n" +
+    ctx.ui.notify("Usage: /gsd mcp [status|check <server>|init [dir]]\n\n" +
         "  status           Show all MCP server statuses (default)\n" +
-        "  check <server>   Detailed status for a specific server", "warning");
+        "  check <server>   Detailed status for a specific server\n" +
+        "  init [dir]       Write .mcp.json for the local GSD workflow MCP server", "warning");
 }

package/dist/resources/extensions/gsd/doctor-git-checks.js

@@ -8,7 +8,7 @@ import { deriveState, isMilestoneComplete } from "./state.js";
 import { listWorktrees, resolveGitDir, worktreesDir } from "./worktree-manager.js";
 import { abortAndReset } from "./git-self-heal.js";
 import { RUNTIME_EXCLUSION_PATHS, resolveMilestoneIntegrationBranch, writeIntegrationBranch } from "./git-service.js";
-import { nativeIsRepo, nativeWorktreeList, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddAllWithExclusions, nativeCommit } from "./native-git-bridge.js";
+import { nativeIsRepo, nativeWorktreeList, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddTracked, nativeCommit } from "./native-git-bridge.js";
 import { getAllWorktreeHealth } from "./worktree-health.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 /**
@@ -380,19 +380,19 @@ export async function checkGitHealth(basePath, issues, fixesApplied, shouldFix,
                         code: "stale_uncommitted_changes",
                         scope: "project",
                         unitId: "project",
-                        message: `Uncommitted changes detected with no commit in ${mins} minute${mins === 1 ? "" : "s"} (threshold: ${thresholdMinutes}m). Snapshotting uncommitted changes.`,
+                        message: `Uncommitted changes detected with no commit in ${mins} minute${mins === 1 ? "" : "s"} (threshold: ${thresholdMinutes}m). Snapshotting tracked files.`,
                         fixable: true,
                     });
                     if (shouldFix("stale_uncommitted_changes")) {
                         try {
-                            nativeAddAllWithExclusions(basePath, RUNTIME_EXCLUSION_PATHS);
+                            nativeAddTracked(basePath);
                             const commitMsg = `gsd snapshot: uncommitted changes after ${mins}m inactivity`;
                             const result = nativeCommit(basePath, commitMsg);
                             if (result) {
                                 fixesApplied.push(`created gsd snapshot after ${mins}m of uncommitted changes`);
                             }
                             else {
-                                fixesApplied.push("gsd snapshot skipped — nothing to commit after staging changes");
+                                fixesApplied.push("gsd snapshot skipped — nothing to commit after staging tracked files");
                             }
                         }
                         catch {

package/dist/resources/extensions/gsd/doctor-proactive.js

@@ -20,8 +20,8 @@ import { readCrashLock, isLockProcessAlive, clearLock } from "./crash-recovery.j
 import { abortAndReset } from "./git-self-heal.js";
 import { rebuildState } from "./doctor.js";
 import { deriveState } from "./state.js";
-import { RUNTIME_EXCLUSION_PATHS, resolveMilestoneIntegrationBranch } from "./git-service.js";
-import { nativeIsRepo, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddAllWithExclusions, nativeCommit } from "./native-git-bridge.js";
+import { resolveMilestoneIntegrationBranch } from "./git-service.js";
+import { nativeIsRepo, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddTracked, nativeCommit } from "./native-git-bridge.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { runEnvironmentChecks } from "./doctor-environment.js";
 /** In-memory health history for the current auto-mode session. */
@@ -247,7 +247,7 @@ export async function preDispatchHealthGate(basePath) {
                 if (minutesSinceCommit >= thresholdMinutes) {
                     const mins = Math.floor(minutesSinceCommit);
                     try {
-                        nativeAddAllWithExclusions(basePath, RUNTIME_EXCLUSION_PATHS);
+                        nativeAddTracked(basePath);
                         const commitMsg = `gsd snapshot: pre-dispatch, uncommitted changes after ${mins}m inactivity`;
                         const result = nativeCommit(basePath, commitMsg);
                         if (result) {

package/dist/resources/extensions/gsd/init-wizard.js

@@ -190,16 +190,12 @@ export async function showProjectInit(ctx, pi, basePath, detection) {
     // Initialize SQLite database so GSD starts in full-capability mode (#3880).
     // Without this, isDbAvailable() returns false and GSD enters degraded
     // markdown-only mode until a tool handler happens to call ensureDbOpen().
-    let dbReady = false;
     try {
         const { ensureDbOpen } = await import("./bootstrap/dynamic-tools.js");
-        dbReady = await ensureDbOpen(basePath);
+        await ensureDbOpen(basePath);
     }
     catch {
-        // Swallowed — warning surfaced below
-    }
-    if (!dbReady) {
-        ctx.ui.notify("Warning: database initialization failed — GSD will run in degraded mode until the next /gsd invocation.", "warning");
+        // Non-fatal — DB creation failure should not block project init
     }
     // Ensure .gitignore
     ensureGitignore(basePath);
@@ -218,7 +214,6 @@ export async function showProjectInit(ctx, pi, basePath, detection) {
     // Write initial STATE.md so it exists before the first /gsd invocation.
     // The explicit /gsd init path (ops.ts) returns without entering showSmartEntry(),
     // which would otherwise generate STATE.md at guided-flow.ts:1358.
-    let stateReady = false;
     try {
         const { deriveState } = await import("./state.js");
         const { buildStateMarkdown } = await import("./doctor.js");
@@ -226,13 +221,21 @@ export async function showProjectInit(ctx, pi, basePath, detection) {
         const { resolveGsdRootFile } = await import("./paths.js");
         const state = await deriveState(basePath);
         await saveFile(resolveGsdRootFile(basePath, "STATE"), buildStateMarkdown(state));
-        stateReady = true;
     }
     catch {
-        // Swallowed — warning surfaced below
-    }
-    if (!stateReady) {
-        ctx.ui.notify("Warning: initial STATE.md generation failed — it will be created on the next /gsd invocation.", "warning");
+        // Non-fatal — STATE.md will be regenerated on next /gsd invocation
+    }
+    if (ctx.model?.provider === "claude-code") {
+        try {
+            const { ensureProjectWorkflowMcpConfig } = await import("./mcp-project-config.js");
+            const result = ensureProjectWorkflowMcpConfig(basePath);
+            if (result.status !== "unchanged") {
+                ctx.ui.notify(`Claude Code MCP prepared at ${result.configPath}`, "info");
+            }
+        }
+        catch (err) {
+            ctx.ui.notify(`Claude Code MCP prep failed: ${err instanceof Error ? err.message : String(err)}`, "warning");
+        }
     }
     ctx.ui.notify("GSD initialized. Starting your first milestone...", "info");
     return { completed: true, bootstrapped: true };

package/dist/resources/extensions/gsd/mcp-project-config.js

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { assertSafeDirectory } from "./validate-directory.js";
+import { detectWorkflowMcpLaunchConfig } from "./workflow-mcp.js";
+export const GSD_WORKFLOW_MCP_SERVER_NAME = "gsd-workflow";
+export function resolveBundledGsdCliPath(env = process.env) {
+    const explicit = env.GSD_CLI_PATH?.trim() || env.GSD_BIN_PATH?.trim();
+    if (explicit)
+        return explicit;
+    const candidates = [
+        resolve(fileURLToPath(new URL("../../../../scripts/dev-cli.js", import.meta.url))),
+        resolve(fileURLToPath(new URL("../../../../dist/loader.js", import.meta.url))),
+        resolve(fileURLToPath(new URL("../../../loader.js", import.meta.url))),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+export function buildProjectWorkflowMcpServerConfig(projectRoot, env = process.env) {
+    const resolvedProjectRoot = resolve(projectRoot);
+    const gsdCliPath = resolveBundledGsdCliPath(env);
+    const launch = detectWorkflowMcpLaunchConfig(resolvedProjectRoot, {
+        ...env,
+        ...(gsdCliPath ? { GSD_CLI_PATH: gsdCliPath, GSD_BIN_PATH: gsdCliPath } : {}),
+    });
+    if (!launch) {
+        throw new Error("Unable to resolve the GSD workflow MCP server. Build this checkout or install gsd-mcp-server on PATH.");
+    }
+    return {
+        command: launch.command,
+        ...(launch.args && launch.args.length > 0 ? { args: launch.args } : {}),
+        ...(launch.cwd ? { cwd: launch.cwd } : {}),
+        ...(launch.env ? { env: launch.env } : {}),
+    };
+}
+function readExistingConfig(configPath) {
+    if (!existsSync(configPath))
+        return {};
+    const raw = readFileSync(configPath, "utf-8");
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch (err) {
+        throw new Error(`Failed to parse ${configPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export function ensureProjectWorkflowMcpConfig(projectRoot, env = process.env) {
+    const resolvedProjectRoot = resolve(projectRoot);
+    assertSafeDirectory(resolvedProjectRoot);
+    const configPath = resolve(resolvedProjectRoot, ".mcp.json");
+    const existing = readExistingConfig(configPath);
+    const desiredServer = buildProjectWorkflowMcpServerConfig(resolvedProjectRoot, env);
+    const previousServers = existing.mcpServers ?? {};
+    const nextServers = {
+        ...previousServers,
+        [GSD_WORKFLOW_MCP_SERVER_NAME]: desiredServer,
+    };
+    const alreadyPresent = existsSync(configPath);
+    const unchanged = JSON.stringify(previousServers[GSD_WORKFLOW_MCP_SERVER_NAME] ?? null)
+        === JSON.stringify(desiredServer)
+        && existing.mcpServers !== undefined;
+    if (unchanged) {
+        return {
+            configPath,
+            serverName: GSD_WORKFLOW_MCP_SERVER_NAME,
+            status: "unchanged",
+        };
+    }
+    const nextConfig = {
+        ...existing,
+        mcpServers: nextServers,
+    };
+    writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf-8");
+    return {
+        configPath,
+        serverName: GSD_WORKFLOW_MCP_SERVER_NAME,
+        status: alreadyPresent ? "updated" : "created",
+    };
+}