@opengsd/gsd-pi 1.1.1-dev.74e8dd1 → 1.1.1-dev.75048e7

package/src/resources/extensions/gsd/unit-tool-contracts.ts

@@ -0,0 +1,186 @@
+// Project/App: gsd-pi
+// File Purpose: Central Unit-to-tool contracts for phase-aware GSD tool surfaces.
+
+export interface UnitToolSurfaceContract {
+  allowedGsdTools: readonly string[];
+  requiredWorkflowTools: readonly string[];
+  forbiddenGsdTools?: Readonly<Record<string, string>>;
+}
+
+export const RUN_UAT_WORKFLOW_TOOL_NAMES = [
+  "gsd_uat_exec",
+  "gsd_uat_result_save",
+  "gsd_resume",
+  "gsd_milestone_status",
+  "gsd_journal_query",
+] as const;
+
+export const RUN_UAT_READ_ONLY_TOOL_NAMES = [
+  "find",
+  "glob",
+  "grep",
+  "ls",
+  "read",
+] as const;
+
+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",
+] as const;
+
+export const RUN_UAT_TOOL_PRESENTATION_PLAN_ID = "run-uat/default-v1";
+
+export const UNIT_TOOL_CONTRACTS: Record<string, UnitToolSurfaceContract> = {
+  "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: Record<string, readonly string[]> = Object.fromEntries(
+  Object.entries(UNIT_TOOL_CONTRACTS).map(([unitType, contract]) => [unitType, contract.allowedGsdTools]),
+);
+
+export function getUnitToolSurfaceContract(unitType: string): UnitToolSurfaceContract | undefined {
+  return UNIT_TOOL_CONTRACTS[unitType];
+}
+
+export function getRequiredWorkflowToolsForUnit(unitType: string): string[] {
+  return [...(UNIT_TOOL_CONTRACTS[unitType]?.requiredWorkflowTools ?? [])];
+}
+
+export function getForbiddenGsdToolReason(unitType: string, toolName: string): string | undefined {
+  return UNIT_TOOL_CONTRACTS[unitType]?.forbiddenGsdTools?.[toolName];
+}

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.ts

@@ -2,7 +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";
+import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
 
 type WorkflowExecutorsModule = typeof import("./tools/workflow-tool-executors.js");
 
@@ -414,83 +414,11 @@ export function buildWorkflowMcpServers(
 }
 
 export function getRequiredWorkflowToolsForGuidedUnit(unitType: string): string[] {
-  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: string): string[] {
-  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":
-      return ["gsd_summary_save"];
-    case "run-uat":
-      return [...RUN_UAT_WORKFLOW_TOOL_NAMES];
-    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(

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,
+  };
+}