@opengsd/gsd-pi 1.1.1-dev.616a1a1 → 1.1.1-dev.9bb7453

package/src/resources/extensions/gsd/unit-context-manifest.ts

@@ -137,7 +137,9 @@ export type ContextModePolicy =
  *                    edits project markdown outside .gsd/.
  *   - "verification"
  *                  — Read tools + Bash for verification commands, writes
- *                    restricted to .gsd/**, no subagents.
+ *                    restricted to .gsd/**. Subagent dispatch is denied unless
+ *                    `allowedSubagents` opts a unit into controlled read-only
+ *                    specialist delegation.
  *
  * The allowlist for "docs" is declared per-manifest rather than hardcoded so
  * projects with non-standard doc layouts can extend it without forking the
@@ -150,7 +152,7 @@ export type ToolsPolicy =
   | { readonly mode: "planning" }
   | { readonly mode: "planning-dispatch"; readonly allowedSubagents: readonly string[] }
   | { readonly mode: "docs"; readonly allowedPathGlobs: readonly string[] }
-  | { readonly mode: "verification" };
+  | { readonly mode: "verification"; readonly allowedSubagents?: readonly string[] };
 
 // ─── Computed-artifact registry (#4924 v2 contract) ───────────────────────
 
@@ -305,6 +307,10 @@ const COMMON_BUDGET_SMALL = 250_000;    // ~65K tokens
 const TOOLS_ALL: ToolsPolicy = { mode: "all" };
 const TOOLS_PLANNING: ToolsPolicy = { mode: "planning" };
 const TOOLS_VERIFICATION: ToolsPolicy = { mode: "verification" };
+const TOOLS_VERIFICATION_DISPATCH_UAT: ToolsPolicy = {
+  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: ToolsPolicy = {
@@ -601,7 +607,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     codebaseMap: false,
     preferences: "active-only",
     contextMode: "verification",
-    tools: TOOLS_VERIFICATION,
+    tools: TOOLS_VERIFICATION_DISPATCH_UAT,
     artifacts: {
       inline: ["slice-uat"],
       excerpt: ["slice-summary"],
@@ -792,9 +798,12 @@ export function compileSubagentPermissionContract(
   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/src/resources/extensions/gsd/validation-block-guard.ts

@@ -14,6 +14,8 @@ 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/src/resources/extensions/gsd/verdict-parser.ts

@@ -7,9 +7,60 @@
 
 import { extractUatType } from "./files.js";
 import type { UatType } from "./files.js";
+import { splitFrontmatter, parseFrontmatterMap } from "../shared/frontmatter.js";
+import { parse as parseYaml } from "yaml";
+
+function normalizeVerdict(value: unknown): string | undefined {
+  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: Record<string, unknown>, key: string): unknown {
+  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: string): string | undefined {
+  const [frontmatterLines] = splitFrontmatter(content);
+  if (!frontmatterLines) return undefined;
+
+  try {
+    const parsed = parseYaml(frontmatterLines.join("\n")) as unknown;
+    if (parsed && typeof parsed === "object") {
+      const root = parsed as Record<string, unknown>;
+      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 as Record<string, unknown>, "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.
  *
@@ -21,24 +72,14 @@ import type { UatType } from "./files.js";
  */
 export function extractVerdict(content: string): string | undefined {
   // 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/src/resources/extensions/gsd/verification-gate.ts

@@ -295,6 +295,90 @@ function hasUnsafeShellSyntax(cmd: string): boolean {
   return false;
 }
 
+function splitLeadingShellWords(cmd: string): string[] {
+  const words: string[] = [];
+  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: string): boolean {
+  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: string, exitCode: number): string | null {
+  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: string, warning: string | null): string {
+  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.
@@ -486,11 +570,13 @@ export function runVerificationGate(options: RunVerificationGateOptions): Verifi
       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/src/resources/extensions/gsd/workflow-mcp-auto-prep.ts

@@ -58,6 +58,7 @@ export function shouldAutoPrepareWorkflowMcp(ctx: WorkflowMcpAutoPrepContext): b
   const authMode = getAuthModeSafe(ctx, provider);
 
   if (provider !== "claude-code") return false;
+  if (authMode === undefined) return true;
   return usesWorkflowMcpTransport(authMode as any, baseUrl) || authMode === "externalCli";
 }
 
@@ -72,7 +73,7 @@ export function prepareWorkflowMcpForProject(
   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;
   } catch (err) {

package/src/resources/extensions/gsd/workflow-mcp.ts

@@ -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 { RUN_UAT_WORKFLOW_TOOL_NAMES } from "./tool-presentation-plan.js";
 
 type WorkflowExecutorsModule = typeof import("./tools/workflow-tool-executors.js");
 
@@ -100,6 +101,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",
 ]);
 
@@ -462,8 +465,9 @@ export function getRequiredWorkflowToolsForAutoUnit(unitType: string): string[]
       ];
     case "research-milestone":
     case "research-slice":
-    case "run-uat":
       return ["gsd_summary_save"];
+    case "run-uat":
+      return [...RUN_UAT_WORKFLOW_TOOL_NAMES];
     case "plan-milestone":
       return ["gsd_plan_milestone"];
     case "plan-slice":

package/src/resources/extensions/gsd/worktree-lifecycle.ts

@@ -49,6 +49,8 @@ import {
 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 type { WorktreeStateProjection } from "./worktree-state-projection.js";
 import { createWorkspace, scopeMilestone } from "./workspace.js";
 // ADR-016 phase 2 / C1 (#5624): file-system + git-CLI leaf primitives
@@ -85,6 +87,28 @@ export function resetRecentWorktreeMergeFailuresForTest(): void {
   recentWorktreeMergeFailures.clear();
 }
 
+function markMilestoneClosedAfterMerge(milestoneId: string, completedAt: string): void {
+  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)}`,
+    );
+  }
+}
+
 // ─── Types ───────────────────────────────────────────────────────────────
 
 export interface NotifyCtx {
@@ -1716,6 +1740,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,

package/src/resources/extensions/mcp-client/manager.ts

@@ -103,6 +103,8 @@ const CHILD_ENV_ALLOWLIST = new Set([
 	"XDG_CACHE_HOME",
 ]);
 
+const MCP_STDERR_MAX_BYTES = 4096;
+
 let cachedStatus: ManagedMcpStatus | null = null;
 let cachedStatusKey = "";
 
@@ -231,6 +233,34 @@ export function resolveMcpString(value: string): string {
 	);
 }
 
+function captureTransportStderr(transport: StdioClientTransport): () => string {
+	const chunks: Buffer[] = [];
+	let totalBytes = 0;
+	const stderr = transport.stderr;
+	stderr?.on("data", (chunk: Buffer | string) => {
+		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: unknown, stderr: string): string {
+	const message = error instanceof Error ? error.message : String(error);
+	if (!stderr) return message;
+	return `${message}\nStderr:\n${stderr}`;
+}
+
 export function upsertProjectLocalMcpServer(
 	input: ManagedMcpServerInput,
 	options: { projectDir?: string; previousName?: string } = {},
@@ -348,6 +378,7 @@ export async function testMcpServerConnection(
 
 	const client = new Client({ name: "gsd", version: "1.0.0" });
 	let transport: StdioClientTransport | StreamableHTTPClientTransport | undefined;
+	let readCapturedStderr: (() => string) | undefined;
 	const timeout = options.timeoutMs ?? 30_000;
 	try {
 		if (config.transport === "stdio") {
@@ -358,6 +389,7 @@ export async function testMcpServerConnection(
 				cwd: config.cwd,
 				stderr: "pipe",
 			});
+			readCapturedStderr = captureTransportStderr(transport);
 		} else {
 			const resolvedUrl = resolveMcpString(config.url ?? "");
 			transport = new StreamableHTTPClientTransport(
@@ -385,7 +417,7 @@ export async function testMcpServerConnection(
 			toolCount: 0,
 			tools: [],
 			warnings: config.envWarnings,
-			error: error instanceof Error ? error.message : String(error),
+			error: formatConnectionError(error, readCapturedStderr?.() ?? ""),
 		};
 	} finally {
 		if (transport) {

package/src/resources/extensions/mcp-client/tests/manager.test.ts

@@ -163,3 +163,38 @@ test("MCP connection test performs handshake and tools/list without invoking too
 		cleanup();
 	}
 });
+
+test("MCP connection test includes stdio stderr when discovery fails", async () => {
+	const { projectDir, cleanup } = makeProject();
+	try {
+		const serverPath = join(projectDir, "crashing-mcp-server.mjs");
+		writeFileSync(
+			serverPath,
+			[
+				'console.error("fatal browser bootstrap failed");',
+				'console.error("missing browser profile");',
+				"process.exit(1);",
+			].join("\n"),
+			"utf-8",
+		);
+
+		const result = await testMcpServerConnection({
+			name: "crashing",
+			transport: "stdio",
+			sourcePath: join(projectDir, ".gsd", "mcp.json"),
+			sourceKind: "project-local",
+			disabled: false,
+			command: process.execPath,
+			args: [serverPath],
+			envWarnings: [],
+		} satisfies ManagedMcpServerConfig, { projectDir, timeoutMs: 10_000 });
+
+		assert.equal(result.ok, false);
+		assert.match(result.error ?? "", /Connection closed|closed|exit/i);
+		assert.match(result.error ?? "", /Stderr:/);
+		assert.match(result.error ?? "", /fatal browser bootstrap failed/);
+		assert.match(result.error ?? "", /missing browser profile/);
+	} finally {
+		cleanup();
+	}
+});

package/src/resources/extensions/shared/gsd-browser-cli.ts

@@ -0,0 +1,172 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const GSD_BROWSER_MCP_SERVER_NAME = "gsd-browser";
+
+export interface GsdBrowserMcpLaunchConfig {
+  serverName: string;
+  command: string;
+  args: string[];
+  cwd: string;
+  env?: Record<string, string>;
+  projectRoot: string;
+  sessionName: string;
+}
+
+export interface GsdBrowserMcpLaunchOptions {
+  sessionName?: string;
+  sessionSuffix?: string;
+}
+
+function parseJsonEnv<T>(env: NodeJS.ProcessEnv, name: string): T | undefined {
+  const raw = env[name];
+  if (!raw) return undefined;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    throw new Error(`Invalid JSON in ${name}`);
+  }
+}
+
+function sanitizeSessionSegment(value: string): string {
+  return value
+    .replace(/[^a-zA-Z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+}
+
+function compareSemverLocal(a: string, b: string): number {
+  const left = a.split(".").map(Number);
+  const right = b.split(".").map(Number);
+  for (let index = 0; index < Math.max(left.length, right.length); index++) {
+    const leftValue = left[index] || 0;
+    const rightValue = right[index] || 0;
+    if (leftValue > rightValue) return 1;
+    if (leftValue < rightValue) return -1;
+  }
+  return 0;
+}
+
+function parseGsdBrowserVersion(output: string): string | null {
+  return output.match(/\b(\d+\.\d+\.\d+)\b/)?.[1] ?? null;
+}
+
+function resolveBundledGsdBrowserPackageVersion(): string | null {
+  try {
+    const requireFromHere = createRequire(import.meta.url);
+    const packageJsonPath = requireFromHere.resolve("@opengsd/gsd-browser/package.json");
+    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as { version?: unknown };
+    return typeof pkg.version === "string" ? parseGsdBrowserVersion(pkg.version) : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolvePathGsdBrowserVersion(env: NodeJS.ProcessEnv): string | null {
+  const explicit = env.GSD_BROWSER_PATH_VERSION?.trim();
+  if (explicit) return parseGsdBrowserVersion(explicit);
+
+  try {
+    return parseGsdBrowserVersion(execFileSync("gsd-browser", ["--version"], {
+      encoding: "utf-8",
+      env,
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2000,
+    }));
+  } catch {
+    return null;
+  }
+}
+
+function shouldPreferPathGsdBrowser(env: NodeJS.ProcessEnv): boolean {
+  const pathVersion = resolvePathGsdBrowserVersion(env);
+  if (!pathVersion) return false;
+
+  const bundledVersion = resolveBundledGsdBrowserPackageVersion();
+  return !bundledVersion || compareSemverLocal(pathVersion, bundledVersion) > 0;
+}
+
+export function resolveBundledGsdBrowserCliPath(env: NodeJS.ProcessEnv = process.env): string | null {
+  const explicit = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim();
+  if (explicit) return explicit;
+
+  try {
+    const requireFromHere = createRequire(import.meta.url);
+    const packageJsonPath = requireFromHere.resolve("@opengsd/gsd-browser/package.json");
+    const candidate = resolve(packageJsonPath, "..", "bin", "gsd-browser");
+    if (existsSync(candidate)) return candidate;
+  } catch {
+    // Fall through to path candidates for source/dist layouts.
+  }
+
+  const candidates = [
+    resolve(fileURLToPath(new URL("../../../../node_modules/@opengsd/gsd-browser/bin/gsd-browser", import.meta.url))),
+    resolve(fileURLToPath(new URL("../../../../node_modules/.bin/gsd-browser", import.meta.url))),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  return null;
+}
+
+export function buildGsdBrowserSessionName(projectRoot: string, suffix?: string): string {
+  const resolvedProjectRoot = resolve(projectRoot);
+  const base = sanitizeSessionSegment(basename(resolvedProjectRoot)) || "project";
+  const hash = createHash("sha1").update(resolvedProjectRoot).digest("hex").slice(0, 8);
+  const cleanSuffix = suffix ? sanitizeSessionSegment(suffix) : "";
+  return cleanSuffix ? `gsd-${base}-${hash}-${cleanSuffix}` : `gsd-${base}-${hash}`;
+}
+
+export function resolveGsdBrowserMcpLaunchConfig(
+  projectRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+  options: GsdBrowserMcpLaunchOptions = {},
+): GsdBrowserMcpLaunchConfig {
+  const resolvedProjectRoot = resolve(projectRoot);
+  const serverName = env.GSD_BROWSER_MCP_NAME?.trim() || GSD_BROWSER_MCP_SERVER_NAME;
+  const explicitArgs = parseJsonEnv<unknown>(env, "GSD_BROWSER_MCP_ARGS");
+  const explicitEnv = parseJsonEnv<Record<string, string>>(env, "GSD_BROWSER_MCP_ENV");
+  const explicitCommand = env.GSD_BROWSER_MCP_COMMAND?.trim();
+  const explicitCliPath = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim();
+  const preferPathCli = !explicitCommand && !explicitCliPath && shouldPreferPathGsdBrowser(env);
+  const bundledCliPath = !explicitCommand && !explicitCliPath && !preferPathCli
+    ? resolveBundledGsdBrowserCliPath(env)
+    : null;
+  const sessionName =
+    options.sessionName?.trim() || buildGsdBrowserSessionName(resolvedProjectRoot, options.sessionSuffix);
+  const command =
+    explicitCommand
+    || explicitCliPath
+    || (preferPathCli ? "gsd-browser" : undefined)
+    || (bundledCliPath ? process.execPath : undefined)
+    || "gsd-browser";
+  const args = Array.isArray(explicitArgs) && explicitArgs.length > 0
+    ? explicitArgs.map(String)
+    : [
+        ...(bundledCliPath ? [bundledCliPath] : []),
+        "mcp",
+        "--session",
+        sessionName,
+        "--identity-scope",
+        "project",
+        "--identity-project",
+        resolvedProjectRoot,
+      ];
+  const cwd = env.GSD_BROWSER_MCP_CWD?.trim() || resolvedProjectRoot;
+
+  return {
+    serverName,
+    command,
+    args,
+    cwd,
+    ...(explicitEnv ? { env: explicitEnv } : {}),
+    projectRoot: resolvedProjectRoot,
+    sessionName,
+  };
+}