@opengsd/gsd-pi 1.1.1-dev.616a1a1 → 1.1.1-dev.75048e7

package/dist/resources/extensions/gsd/unit-context-manifest.js

@@ -83,6 +83,10 @@ const COMMON_BUDGET_SMALL = 250_000; // ~65K tokens
 const TOOLS_ALL = { mode: "all" };
 const TOOLS_PLANNING = { mode: "planning" };
 const TOOLS_VERIFICATION = { mode: "verification" };
+const TOOLS_VERIFICATION_DISPATCH_UAT = {
+    mode: "verification",
+    allowedSubagents: ["mnemo", "scout", "reviewer", "tester"],
+};
 // Like TOOLS_PLANNING but permits dispatch to read-only recon/planning
 // specialists. Runtime-enforced by write-gate.ts before the subagent tool runs.
 const TOOLS_PLANNING_DISPATCH_RECON = {
@@ -372,7 +376,7 @@ export const UNIT_MANIFESTS = {
         codebaseMap: false,
         preferences: "active-only",
         contextMode: "verification",
-        tools: TOOLS_VERIFICATION,
+        tools: TOOLS_VERIFICATION_DISPATCH_UAT,
         artifacts: {
             inline: ["slice-uat"],
             excerpt: ["slice-summary"],
@@ -551,9 +555,10 @@ export function compileSubagentPermissionContract(policy) {
     if (policy.mode === "all") {
         return { allowed: true, allowedSubagents: ["*"], toolsMode: policy.mode };
     }
-    if (policy.mode === "planning-dispatch") {
+    if ((policy.mode === "planning-dispatch" || policy.mode === "verification") &&
+        Array.isArray(policy.allowedSubagents)) {
         return {
-            allowed: true,
+            allowed: policy.allowedSubagents.length > 0,
             allowedSubagents: [...policy.allowedSubagents],
             toolsMode: policy.mode,
         };

package/dist/resources/extensions/gsd/unit-tool-contracts.js

@@ -0,0 +1,169 @@
+// Project/App: gsd-pi
+// File Purpose: Central Unit-to-tool contracts for phase-aware GSD tool surfaces.
+export const RUN_UAT_WORKFLOW_TOOL_NAMES = [
+    "gsd_uat_exec",
+    "gsd_uat_result_save",
+    "gsd_resume",
+    "gsd_milestone_status",
+    "gsd_journal_query",
+];
+export const RUN_UAT_READ_ONLY_TOOL_NAMES = [
+    "find",
+    "glob",
+    "grep",
+    "ls",
+    "read",
+];
+export const RUN_UAT_BROWSER_TOOL_NAMES = [
+    "browser_navigate",
+    "browser_click",
+    "browser_type",
+    "browser_fill_form",
+    "browser_click_ref",
+    "browser_fill_ref",
+    "browser_wait_for",
+    "browser_assert",
+    "browser_verify",
+    "browser_screenshot",
+    "browser_snapshot_refs",
+    "browser_find",
+    "browser_get_console_logs",
+    "browser_get_network_logs",
+    "browser_evaluate",
+    "browser_reload",
+    "browser_batch",
+    "browser_act",
+];
+export const RUN_UAT_TOOL_PRESENTATION_PLAN_ID = "run-uat/default-v1";
+export const UNIT_TOOL_CONTRACTS = {
+    "research-milestone": {
+        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_summary_save"],
+    },
+    "plan-milestone": {
+        allowedGsdTools: ["gsd_plan_milestone", "gsd_decision_save", "gsd_requirement_update"],
+        requiredWorkflowTools: ["gsd_plan_milestone"],
+    },
+    "discuss-milestone": {
+        allowedGsdTools: [
+            "gsd_summary_save",
+            "gsd_decision_save",
+            "gsd_requirement_save",
+            "gsd_requirement_update",
+            "gsd_plan_milestone",
+            "gsd_milestone_generate_id",
+        ],
+        requiredWorkflowTools: [
+            "gsd_summary_save",
+            "gsd_requirement_save",
+            "gsd_requirement_update",
+            "gsd_plan_milestone",
+            "gsd_milestone_generate_id",
+        ],
+    },
+    "discuss-slice": {
+        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_summary_save"],
+    },
+    "validate-milestone": {
+        allowedGsdTools: ["gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
+        requiredWorkflowTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap"],
+    },
+    "complete-milestone": {
+        allowedGsdTools: ["gsd_complete_milestone", "subagent"],
+        requiredWorkflowTools: ["gsd_milestone_status", "gsd_complete_milestone"],
+    },
+    "research-slice": {
+        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_summary_save"],
+    },
+    "plan-slice": {
+        allowedGsdTools: ["gsd_plan_slice", "gsd_plan_task", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_plan_slice"],
+    },
+    "refine-slice": {
+        allowedGsdTools: ["gsd_plan_slice", "gsd_plan_task", "gsd_decision_save"],
+        requiredWorkflowTools: [],
+    },
+    "replan-slice": {
+        allowedGsdTools: ["gsd_replan_slice", "gsd_plan_task", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_replan_slice"],
+    },
+    "complete-slice": {
+        allowedGsdTools: [
+            "gsd_slice_complete",
+            "gsd_task_reopen",
+            "gsd_replan_slice",
+            "gsd_decision_save",
+            "gsd_requirement_update",
+            "subagent",
+        ],
+        requiredWorkflowTools: ["gsd_slice_complete", "gsd_task_reopen", "gsd_replan_slice"],
+        forbiddenGsdTools: {
+            gsd_uat_result_save: "Run UAT owns persisted UAT Assessment.",
+        },
+    },
+    "reassess-roadmap": {
+        allowedGsdTools: ["gsd_reassess_roadmap"],
+        requiredWorkflowTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
+    },
+    "execute-task": {
+        allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_task_complete"],
+    },
+    "execute-task-simple": {
+        allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_task_complete"],
+    },
+    "reactive-execute": {
+        allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_task_complete"],
+    },
+    "run-uat": {
+        allowedGsdTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent"],
+        requiredWorkflowTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES],
+        forbiddenGsdTools: {
+            gsd_exec: "Use gsd_uat_exec so acceptance evidence is typed as UAT-owned.",
+            gsd_save_gate_result: "gsd_uat_result_save owns the aggregate UAT gate.",
+            gsd_summary_save: "gsd_uat_result_save owns persisted UAT Assessment writes.",
+        },
+    },
+    "gate-evaluate": {
+        allowedGsdTools: ["gsd_save_gate_result"],
+        requiredWorkflowTools: ["gsd_save_gate_result"],
+    },
+    "rewrite-docs": {
+        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+        requiredWorkflowTools: [],
+    },
+    "workflow-preferences": {
+        allowedGsdTools: ["gsd_summary_save"],
+        requiredWorkflowTools: [],
+    },
+    "discuss-project": {
+        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
+        requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
+    },
+    "discuss-requirements": {
+        allowedGsdTools: ["gsd_requirement_save", "gsd_summary_save"],
+        requiredWorkflowTools: ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"],
+    },
+    "research-decision": {
+        allowedGsdTools: ["gsd_summary_save"],
+        requiredWorkflowTools: ["ask_user_questions"],
+    },
+    "research-project": {
+        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+        requiredWorkflowTools: [],
+    },
+};
+export const AUTO_UNIT_SCOPED_TOOLS = Object.fromEntries(Object.entries(UNIT_TOOL_CONTRACTS).map(([unitType, contract]) => [unitType, contract.allowedGsdTools]));
+export function getUnitToolSurfaceContract(unitType) {
+    return UNIT_TOOL_CONTRACTS[unitType];
+}
+export function getRequiredWorkflowToolsForUnit(unitType) {
+    return [...(UNIT_TOOL_CONTRACTS[unitType]?.requiredWorkflowTools ?? [])];
+}
+export function getForbiddenGsdToolReason(unitType, toolName) {
+    return UNIT_TOOL_CONTRACTS[unitType]?.forbiddenGsdTools?.[toolName];
+}

package/dist/resources/extensions/gsd/validation-block-guard.js

@@ -8,6 +8,8 @@ import { deriveState } from "./state.js";
 import { detectWorktreeName } from "./worktree.js";
 const VALIDATION_BLOCK_RE = /milestone validation returned needs-(?:attention|remediation)|validation verdict is needs-(?:attention|remediation)/i;
 const VALIDATION_SAFE_DISPATCH_COMMANDS = new Set([
+    "reassess",
+    "reassess-roadmap",
     "validate",
     "validate-milestone",
 ]);

package/dist/resources/extensions/gsd/verdict-parser.js

@@ -5,7 +5,62 @@
  * (e.g. `passed` → `pass`) are applied consistently across the codebase.
  */
 import { extractUatType } from "./files.js";
+import { splitFrontmatter, parseFrontmatterMap } from "../shared/frontmatter.js";
+import { parse as parseYaml } from "yaml";
+function normalizeVerdict(value) {
+    if (typeof value !== "string")
+        return undefined;
+    let verdict = value.trim().toLowerCase();
+    if (!verdict)
+        return undefined;
+    if (verdict === "passed")
+        verdict = "pass";
+    return verdict;
+}
+function getCaseInsensitive(obj, key) {
+    const lowerKey = key.toLowerCase();
+    for (const [candidate, value] of Object.entries(obj)) {
+        if (candidate.toLowerCase() === lowerKey)
+            return value;
+    }
+    return undefined;
+}
 // ── Verdict extraction ──────────────────────────────────────────────────
+/**
+ * Extract and normalize the frontmatter `verdict` value.
+ *
+ * Supports both top-level `verdict` and the hook outcome shape
+ * `outcome.verdict`. Returns `undefined` when frontmatter is absent or has no
+ * verdict field.
+ */
+export function extractFrontmatterVerdict(content) {
+    const [frontmatterLines] = splitFrontmatter(content);
+    if (!frontmatterLines)
+        return undefined;
+    try {
+        const parsed = parseYaml(frontmatterLines.join("\n"));
+        if (parsed && typeof parsed === "object") {
+            const root = parsed;
+            const topLevel = normalizeVerdict(getCaseInsensitive(root, "verdict"));
+            if (topLevel)
+                return topLevel;
+            const outcome = getCaseInsensitive(root, "outcome");
+            if (outcome && typeof outcome === "object") {
+                const nested = normalizeVerdict(getCaseInsensitive(outcome, "verdict"));
+                if (nested)
+                    return nested;
+            }
+        }
+    }
+    catch {
+        // Fall through to the permissive parser used by legacy frontmatter paths.
+    }
+    const frontmatter = parseFrontmatterMap(frontmatterLines);
+    const topLevel = normalizeVerdict(getCaseInsensitive(frontmatter, "verdict"));
+    if (topLevel)
+        return topLevel;
+    return undefined;
+}
 /**
  * Extract and normalize the `verdict` value from YAML frontmatter.
  *
@@ -17,25 +72,14 @@ import { extractUatType } from "./files.js";
  */
 export function extractVerdict(content) {
     // Primary: YAML frontmatter verdict (canonical format)
-    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
-    if (fmMatch) {
-        const verdictMatch = fmMatch[1].match(/verdict:\s*([\w-]+)/i);
-        if (verdictMatch) {
-            let v = verdictMatch[1].toLowerCase();
-            if (v === "passed")
-                v = "pass";
-            return v;
-        }
-        return undefined;
-    }
+    const [frontmatterLines] = splitFrontmatter(content);
+    if (frontmatterLines)
+        return extractFrontmatterVerdict(content);
     // Fallback: detect verdict in markdown body (LLM manual writes, #2960).
     // Matches patterns like: **Verdict:** PASS, **Verdict:** ✅ PASS, **Verdict** needs-remediation
     const bodyMatch = content.match(/\*\*Verdict:?\*\*\s*(?:✅\s*)?(\w[\w-]*)/i);
     if (bodyMatch) {
-        let v = bodyMatch[1].toLowerCase();
-        if (v === "passed")
-            v = "pass";
-        return v;
+        return normalizeVerdict(bodyMatch[1]);
     }
     return undefined;
 }

package/dist/resources/extensions/gsd/verification-gate.js

@@ -246,6 +246,76 @@ function hasUnsafeShellSyntax(cmd) {
     }
     return false;
 }
+function splitLeadingShellWords(cmd) {
+    const words = [];
+    let current = "";
+    let inSingle = false;
+    let inDouble = false;
+    let escaped = false;
+    for (let i = 0; i < cmd.length; i += 1) {
+        const ch = cmd[i];
+        if (escaped) {
+            current += ch;
+            escaped = false;
+            continue;
+        }
+        if (ch === "\\" && !inSingle) {
+            escaped = true;
+            continue;
+        }
+        if (ch === "'" && !inDouble) {
+            inSingle = !inSingle;
+            continue;
+        }
+        if (ch === "\"" && !inSingle) {
+            inDouble = !inDouble;
+            continue;
+        }
+        if (!inSingle && !inDouble) {
+            if (/\s/.test(ch)) {
+                if (current) {
+                    words.push(current);
+                    current = "";
+                }
+                continue;
+            }
+            if ([";", "|", "&", "<", ">"].includes(ch)) {
+                break;
+            }
+        }
+        current += ch;
+    }
+    if (current) {
+        words.push(current);
+    }
+    return words;
+}
+function isCountFlag(token) {
+    return (token === "--count" ||
+        token.startsWith("--count=") ||
+        token === "--count-matches" ||
+        token.startsWith("--count-matches=") ||
+        /^-[A-Za-z]*c[A-Za-z]*$/.test(token));
+}
+function countSearchWarning(command, exitCode) {
+    if (exitCode !== 1)
+        return null;
+    const trimmed = command.trim();
+    if (trimmed.startsWith("!"))
+        return null;
+    const [tool, ...args] = splitLeadingShellWords(trimmed);
+    if (tool !== "grep" && tool !== "rg")
+        return null;
+    if (!args.some(isCountFlag))
+        return null;
+    return `verification-gate: warning: '${tool} -c' returns exit 1 when count=0; for absence checks use '! ${tool} -q ...' instead.`;
+}
+function appendStderrWarning(stderr, warning) {
+    if (!warning)
+        return stderr;
+    const trimmed = stderr.trimEnd();
+    return trimmed ? `${trimmed}\n${warning}` : warning;
+}
 /**
  * Known executable first-tokens that are safe to run.
  * Lowercase commands, common build/test tools, and npm/yarn/pnpm invocations.
@@ -411,11 +481,12 @@ export function runVerificationGate(options) {
             exitCode = result.status ?? 1;
             stderr = truncate(result.stderr, MAX_OUTPUT_BYTES);
         }
+        const warning = countSearchWarning(command, exitCode);
         checks.push({
             command,
             exitCode,
             stdout: truncate(result.stdout, MAX_OUTPUT_BYTES),
-            stderr,
+            stderr: truncate(appendStderrWarning(stderr, warning), MAX_OUTPUT_BYTES),
             durationMs,
         });
     }

package/dist/resources/extensions/gsd/workflow-mcp-auto-prep.js

@@ -33,6 +33,8 @@ export function shouldAutoPrepareWorkflowMcp(ctx) {
     const authMode = getAuthModeSafe(ctx, provider);
     if (provider !== "claude-code")
         return false;
+    if (authMode === undefined)
+        return true;
     return usesWorkflowMcpTransport(authMode, baseUrl) || authMode === "externalCli";
 }
 export function prepareWorkflowMcpForProject(ctx, projectRoot, modelOverride) {
@@ -42,7 +44,7 @@ export function prepareWorkflowMcpForProject(ctx, projectRoot, modelOverride) {
     try {
         const result = ensureProjectWorkflowMcpConfig(projectRoot);
         if (result.status !== "unchanged") {
-            prepCtx.ui?.notify?.(`Claude Code MCP prepared at ${result.configPath}`, "info");
+            prepCtx.ui?.notify?.(`GSD MCP Server Prepared at ${result.configPath}`, "info");
         }
         return result;
     }

package/dist/resources/extensions/gsd/workflow-mcp.js

@@ -2,6 +2,7 @@ import { execSync } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import { dirname, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
 /** Session cwd may be a milestone worktree; MCP config and server discovery use the project root. */
 export function resolveWorkflowMcpProjectRoot(sessionCwd) {
     let resolved;
@@ -77,6 +78,8 @@ const MCP_WORKFLOW_TOOL_SURFACE = new Set([
     "gsd_task_complete",
     "gsd_task_reopen",
     "gsd_update_requirement",
+    "gsd_uat_exec",
+    "gsd_uat_result_save",
     "gsd_validate_milestone",
 ]);
 /** Workflow MCP tools are validated by transport compatibility, not pi tool-compat profiles. */
@@ -347,81 +350,10 @@ export function buildWorkflowMcpServers(projectRoot = process.cwd(), env = proce
     };
 }
 export function getRequiredWorkflowToolsForGuidedUnit(unitType) {
-    switch (unitType) {
-        case "discuss-project":
-            return ["ask_user_questions", "gsd_summary_save"];
-        case "discuss-requirements":
-            return ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"];
-        case "research-decision":
-            return ["ask_user_questions"];
-        case "discuss-milestone":
-            return [
-                "gsd_summary_save",
-                "gsd_requirement_save",
-                "gsd_requirement_update",
-                "gsd_plan_milestone",
-                "gsd_milestone_generate_id",
-            ];
-        case "discuss-slice":
-            return ["gsd_summary_save"];
-        case "research-milestone":
-        case "research-slice":
-            return ["gsd_summary_save"];
-        case "plan-milestone":
-            return ["gsd_plan_milestone"];
-        case "plan-slice":
-            return ["gsd_plan_slice"];
-        case "execute-task":
-            return ["gsd_task_complete"];
-        case "complete-slice":
-            return ["gsd_slice_complete", "gsd_task_reopen", "gsd_replan_slice"];
-        default:
-            return [];
-    }
+    return getRequiredWorkflowToolsForUnit(unitType);
 }
 export function getRequiredWorkflowToolsForAutoUnit(unitType) {
-    switch (unitType) {
-        case "discuss-project":
-            return ["ask_user_questions", "gsd_summary_save"];
-        case "discuss-requirements":
-            return ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"];
-        case "research-decision":
-            return ["ask_user_questions"];
-        case "discuss-milestone":
-            return [
-                "gsd_summary_save",
-                "gsd_requirement_save",
-                "gsd_requirement_update",
-                "gsd_plan_milestone",
-                "gsd_milestone_generate_id",
-            ];
-        case "research-milestone":
-        case "research-slice":
-        case "run-uat":
-            return ["gsd_summary_save"];
-        case "plan-milestone":
-            return ["gsd_plan_milestone"];
-        case "plan-slice":
-            return ["gsd_plan_slice"];
-        case "execute-task":
-        case "execute-task-simple":
-        case "reactive-execute":
-            return ["gsd_task_complete"];
-        case "complete-slice":
-            return ["gsd_slice_complete", "gsd_task_reopen", "gsd_replan_slice"];
-        case "replan-slice":
-            return ["gsd_replan_slice"];
-        case "reassess-roadmap":
-            return ["gsd_milestone_status", "gsd_reassess_roadmap"];
-        case "gate-evaluate":
-            return ["gsd_save_gate_result"];
-        case "validate-milestone":
-            return ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap"];
-        case "complete-milestone":
-            return ["gsd_milestone_status", "gsd_complete_milestone"];
-        default:
-            return [];
-    }
+    return getRequiredWorkflowToolsForUnit(unitType);
 }
 export function usesWorkflowMcpTransport(authMode, baseUrl) {
     return authMode === "externalCli" && typeof baseUrl === "string" && baseUrl.startsWith("local://");

package/dist/resources/extensions/gsd/worktree-lifecycle.js

@@ -34,6 +34,8 @@ import { getCollapseCadence, getMilestoneResquash, resquashMilestoneOnMain, } fr
 import { loadEffectiveGSDPreferences, getIsolationMode } from "./preferences.js";
 import { invalidateAllCaches } from "./cache.js";
 import { resolveMilestoneFile } from "./paths.js";
+import { getMilestone, insertMilestone, isDbAvailable, updateMilestoneStatus } from "./gsd-db.js";
+import { isClosedStatus } from "./status-guards.js";
 import { createWorkspace, scopeMilestone } from "./workspace.js";
 // ADR-016 phase 2 / C1 (#5624): file-system + git-CLI leaf primitives
 // inlined as direct imports rather than injected through `WorktreeLifecycleDeps`.
@@ -55,6 +57,26 @@ const MERGE_FAILURE_DEDUPE_MS = 60_000;
 export function resetRecentWorktreeMergeFailuresForTest() {
     recentWorktreeMergeFailures.clear();
 }
+function markMilestoneClosedAfterMerge(milestoneId, completedAt) {
+    if (!isDbAvailable())
+        return;
+    try {
+        const existing = getMilestone(milestoneId);
+        if (!existing) {
+            insertMilestone({ id: milestoneId, title: milestoneId, status: "complete" });
+            updateMilestoneStatus(milestoneId, "complete", completedAt);
+            invalidateAllCaches();
+            return;
+        }
+        if (!isClosedStatus(existing.status)) {
+            updateMilestoneStatus(milestoneId, "complete", completedAt);
+            invalidateAllCaches();
+        }
+    }
+    catch (err) {
+        logWarning("worktree", `Merged ${milestoneId} but failed to mark milestone complete in DB: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 /**
  * Internal sentinel — thrown by `_mergeBranchMode` when it has already
  * emitted a user-visible error. The outer `mergeAndExit` catches the type
@@ -1195,6 +1217,8 @@ export class WorktreeLifecycle {
         }
         // #4764 — record merge completion. Only reaches here when an actual
         // merge ran; failure paths throw out before this point.
+        const mergeCompletedAt = new Date().toISOString();
+        markMilestoneClosedAfterMerge(milestoneId, mergeCompletedAt);
         try {
             emitWorktreeMerged(this.s.originalBasePath || this.s.basePath, milestoneId, {
                 reason: "milestone-complete",

package/dist/resources/extensions/mcp-client/manager.js

@@ -29,6 +29,7 @@ const CHILD_ENV_ALLOWLIST = new Set([
     "XDG_CONFIG_HOME",
     "XDG_CACHE_HOME",
 ]);
+const MCP_STDERR_MAX_BYTES = 4096;
 let cachedStatus = null;
 let cachedStatusKey = "";
 export function clearMcpConfigCache() {
@@ -126,6 +127,33 @@ export function resolveMcpEnv(env) {
 export function resolveMcpString(value) {
     return value.replace(/\$\{([^}]+)\}/g, (_match, varName) => process.env[varName] ?? "");
 }
+function captureTransportStderr(transport) {
+    const chunks = [];
+    let totalBytes = 0;
+    const stderr = transport.stderr;
+    stderr?.on("data", (chunk) => {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        totalBytes += buffer.byteLength;
+        chunks.push(buffer);
+        while (chunks.reduce((sum, entry) => sum + entry.byteLength, 0) > MCP_STDERR_MAX_BYTES) {
+            chunks.shift();
+        }
+    });
+    return () => {
+        const captured = Buffer.concat(chunks).toString("utf-8").trim();
+        if (!captured)
+            return "";
+        return totalBytes > MCP_STDERR_MAX_BYTES
+            ? `[stderr truncated to last ${MCP_STDERR_MAX_BYTES} bytes]\n${captured}`
+            : captured;
+    };
+}
+function formatConnectionError(error, stderr) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!stderr)
+        return message;
+    return `${message}\nStderr:\n${stderr}`;
+}
 export function upsertProjectLocalMcpServer(input, options = {}) {
     const projectDir = options.projectDir ?? process.cwd();
     const nextName = input.name.trim();
@@ -224,6 +252,7 @@ export async function testMcpServerConnection(nameOrConfig, options = {}) {
     }
     const client = new Client({ name: "gsd", version: "1.0.0" });
     let transport;
+    let readCapturedStderr;
     const timeout = options.timeoutMs ?? 30_000;
     try {
         if (config.transport === "stdio") {
@@ -234,6 +263,7 @@ export async function testMcpServerConnection(nameOrConfig, options = {}) {
                 cwd: config.cwd,
                 stderr: "pipe",
             });
+            readCapturedStderr = captureTransportStderr(transport);
         }
         else {
             const resolvedUrl = resolveMcpString(config.url ?? "");
@@ -259,7 +289,7 @@ export async function testMcpServerConnection(nameOrConfig, options = {}) {
             toolCount: 0,
             tools: [],
             warnings: config.envWarnings,
-            error: error instanceof Error ? error.message : String(error),
+            error: formatConnectionError(error, readCapturedStderr?.() ?? ""),
         };
     }
     finally {