fix(gsd): validate inline workflow MCP preflight config

[jeremymcs]

TL;DR

What: Workflow MCP preflight now probes the same inline MCP server config passed to Claude Code SDK runs.
Why: Issue #808 showed readiness could falsely fail with Unknown MCP server when the SDK had inline MCP config but persisted project config did not.
How: The stream adapter resolves the workflow MCP server from SDK mcpServers, the readiness probe accepts that inline config, and timeout diagnostics preserve the final useful probe error.

What

• Validate workflow MCP readiness against the inline MCP server configuration selected for Claude SDK runs.
• Preserve MCP probe errors in preflight timeout messages.
• Clear stale probe errors after later successful-but-incomplete probes so diagnostics reflect the final probe state.
• Reuse MCP env-warning validation for inline workflow MCP configs.
• Keep inline MCP transport detection aligned with existing transport priority rules.
• Add regression coverage for inline workflow MCP preflight behavior and stream-adapter config selection.
• Update related MCP preflight docs.

Closes #808

Why

Claude Code can receive workflow MCP config inline through the SDK while the project has no persisted MCP server by that name. The old readiness preflight only checked persisted config by server name, so it could report tool readiness failure before dispatch even though the SDK run itself had the correct MCP config.

How

stream-adapter selects the workflow MCP server entry from the SDK config and passes it into awaitWorkflowMcpToolRegistration. tool-surface-readiness normalizes that inline config using the same manager helpers for env warnings and transport detection, probes it directly, and keeps timeout errors actionable by appending the last relevant probe error.

Verification

• Focused regression tests passed:
  • node --import ./src/resources/extensions/gsd/tests/resolve-ts.mjs --experimental-strip-types --test src/resources/extensions/gsd/tests/workflow-mcp-preflight.test.ts src/resources/extensions/claude-code-cli/tests/stream-adapter.test.ts
• Evidence transcript confirmed:
  • project root had no persisted MCP config
  • stream adapter selected inline SDK config
  • inline config preflight reached READY
  • timeout included last probe error: Unknown MCP server.
• Documentation verification passed:
  • pnpm run verify:fast
• GitHub CI passed on commit 69b2921e6390d96cee0228ea46fdc7f27ad3ac71.

Impact analysis

• Blast radius: moderate but contained to Claude Code workflow MCP startup readiness and diagnostics.
• Affected workflows: GSD phase/unit runs that use Claude Code SDK workflow MCP tools, especially when the SDK receives inline mcpServers.
• Compatibility: name-based persisted MCP probing remains the fallback when no inline config is supplied.

Change type checklist

• fix - Bug fix
• test - Adding or updating tests
• docs - Documentation updates

---

Note

Medium Risk
Changes Claude Code workflow MCP startup readiness and probing only, but that path is on the critical path before tool-dependent units run; fallback to name-based persisted config remains when no inline config is passed.

Overview
Fixes false workflow MCP readiness failures when Claude Code gets gsd-workflow only via inline SDK mcpServers, not from persisted project MCP config (e.g. Unknown MCP server before the first turn).

Before starting the SDK query, the stream adapter resolves the workflow server entry with resolveWorkflowMcpPreflightServerConfig and passes it into awaitWorkflowMcpToolRegistration. The readiness layer normalizes that inline config (transport detection and env warnings aligned with the MCP manager) and probes that config directly instead of looking up the server by name alone. Preflight timeouts append the last useful probe error; stale errors are cleared when a later probe connects without an error but tools are still missing.

detectTransport and collectMcpEnvWarnings are exported from the MCP manager for reuse. ADR-036 and user docs describe inline preflight behavior. Regression tests cover config resolution, end-to-end preflight with inline config, and timeout diagnostics.

^{Reviewed by Cursor Bugbot for commit 69b2921. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

🟢 PR Risk Report — LOW

Files changed	8
Systems affected	0
Overall risk	🟢 LOW

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Stale last probe error text
  • The polling loop now updates lastProbeError from each probe result (including clearing it when a successful probe has no error), so timeout diagnostics reflect the final probe state.
• ✅ Fixed: Inline preflight skips env validation
  • normalizeInlineWorkflowMcpServerConfig now populates envWarnings via the shared collectMcpEnvWarnings helper so inline configs fail fast on unset ${ENV} placeholders like name-based lookups.

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Inline transport detection mismatch
  • Exported detectTransport from the MCP manager and used it in normalizeInlineWorkflowMcpServerConfig so inline preflight selects the same transport as persisted config normalization.

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 016a05f. Configure here.}