@opengsd/gsd-pi 1.2.0-dev.84c56d87 → 1.2.0-dev.8e6112e9

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

@@ -1,8 +1,13 @@
-import { createHash, randomUUID } from "node:crypto";
-import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { readFileSync, existsSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { withFileLockSync } from "./file-lock.js";
+import {
+  appendWorkflowEvent,
+  workflowEventArchivePath,
+  workflowEventLogPath,
+  type WorkflowEventInput,
+} from "./workflow-event-ledger.js";
 import { logWarning } from "./workflow-logger.js";
 
 // ─── Session ID ───────────────────────────────────────────────────────────
@@ -40,22 +45,9 @@ export interface WorkflowEvent {
  */
 export function appendEvent(
   basePath: string,
-  event: Omit<WorkflowEvent, "hash" | "session_id"> & { actor_name?: string; trigger_reason?: string },
+  event: WorkflowEventInput,
 ): void {
-  const hash = createHash("sha256")
-    .update(JSON.stringify({ cmd: event.cmd, params: event.params }))
-    .digest("hex")
-    .slice(0, 16);
-
-  const fullEvent: WorkflowEvent = {
-    v: 2,
-    ...event,
-    hash,
-    session_id: ENGINE_SESSION_ID,
-  };
-  const dir = join(basePath, ".gsd");
-  mkdirSync(dir, { recursive: true });
-  appendFileSync(join(dir, "event-log.jsonl"), JSON.stringify(fullEvent) + "\n", "utf-8");
+  appendWorkflowEvent(basePath, event, ENGINE_SESSION_ID);
 }
 
 // ─── readEvents ──────────────────────────────────────────────────────────
@@ -125,8 +117,8 @@ export function compactMilestoneEvents(
   basePath: string,
   milestoneId: string,
 ): { archived: number } {
-  const logPath = join(basePath, ".gsd", "event-log.jsonl");
-  const archivePath = join(basePath, ".gsd", `event-log-${milestoneId}.jsonl.archived`);
+  const logPath = workflowEventLogPath(basePath);
+  const archivePath = workflowEventArchivePath(basePath, milestoneId);
 
   return withFileLockSync(logPath, () => {
     const allEvents = readEvents(logPath);

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

@@ -4,6 +4,7 @@ import {
   type EnsureProjectWorkflowMcpConfigResult,
   ensureProjectWorkflowMcpConfig,
 } from "./mcp-project-config.js";
+import { warmWorkflowMcpProbeInBackground } from "./workflow-mcp-readiness-cache.js";
 import { usesWorkflowMcpTransport } from "./workflow-mcp.js";
 
 interface WorkflowMcpAutoPrepContext {
@@ -75,6 +76,7 @@ export function prepareWorkflowMcpForProject(
     if (result.status !== "unchanged") {
       prepCtx.ui?.notify?.(`GSD MCP Server Prepared at ${result.configPath}`, "info");
     }
+    warmWorkflowMcpProbeInBackground(projectRoot);
     return result;
   } catch (err) {
     prepCtx.ui?.notify?.(

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

@@ -0,0 +1,150 @@
+// Project/App: gsd-pi
+// File Purpose: Share recent workflow MCP probe results across guided-flow and Claude Code SDK preflight.
+
+import { testMcpServerConnection } from "../mcp-client/manager.js";
+import { mcpToolMatchesBaseName } from "./mcp-tool-name.js";
+import {
+  detectWorkflowMcpLaunchConfig,
+  resolveWorkflowMcpProjectRoot,
+} from "./workflow-mcp.js";
+import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
+
+/** Reuse a recent successful probe instead of spawning another stdio server. */
+export const WORKFLOW_MCP_PROBE_CACHE_TTL_MS = 120_000;
+/** Per-probe connect + tools/list budget (server typically ready in ~1–2s). */
+export const WORKFLOW_MCP_PROBE_TIMEOUT_MS = 5_000;
+
+export interface WorkflowMcpProbeCacheEntry {
+  serverName: string;
+  tools: readonly string[];
+  probedAt: number;
+}
+
+type WorkflowMcpProbeResult = {
+  ok: boolean;
+  tools: readonly string[];
+  serverName?: string;
+  error?: string;
+};
+
+const cacheByProject = new Map<string, WorkflowMcpProbeCacheEntry>();
+const probeInFlightByProject = new Map<string, Promise<WorkflowMcpProbeResult>>();
+let activeWorkflowMcpSdkSessions = 0;
+
+function cacheKey(projectRoot: string): string {
+  return resolveWorkflowMcpProjectRoot(projectRoot);
+}
+
+export function beginWorkflowMcpSdkSession(): void {
+  activeWorkflowMcpSdkSessions++;
+}
+
+export function endWorkflowMcpSdkSession(): void {
+  activeWorkflowMcpSdkSessions = Math.max(0, activeWorkflowMcpSdkSessions - 1);
+}
+
+export function getCachedWorkflowMcpProbe(projectRoot: string): WorkflowMcpProbeCacheEntry | null {
+  const entry = cacheByProject.get(cacheKey(projectRoot));
+  if (!entry) return null;
+  if (Date.now() - entry.probedAt > WORKFLOW_MCP_PROBE_CACHE_TTL_MS) {
+    cacheByProject.delete(cacheKey(projectRoot));
+    return null;
+  }
+  return entry;
+}
+
+export function recordWorkflowMcpProbe(
+  projectRoot: string,
+  serverName: string,
+  tools: readonly string[],
+): void {
+  cacheByProject.set(cacheKey(projectRoot), {
+    serverName,
+    tools: [...tools],
+    probedAt: Date.now(),
+  });
+}
+
+export function clearWorkflowMcpProbeCache(projectRoot?: string): void {
+  if (projectRoot === undefined) {
+    cacheByProject.clear();
+    probeInFlightByProject.clear();
+    activeWorkflowMcpSdkSessions = 0;
+    return;
+  }
+  const key = cacheKey(projectRoot);
+  cacheByProject.delete(key);
+  probeInFlightByProject.delete(key);
+}
+
+export function workflowMcpProbeAdvertisesSurface(tools: readonly string[]): boolean {
+  return tools.some((tool) => isWorkflowToolSurfaceName(tool));
+}
+
+export function cachedWorkflowMcpCoversRequired(
+  projectRoot: string,
+  serverName: string,
+  required: readonly string[],
+): boolean {
+  const entry = getCachedWorkflowMcpProbe(projectRoot);
+  if (!entry || entry.serverName !== serverName) return false;
+  return required.every((tool) =>
+    entry.tools.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)),
+  );
+}
+
+async function runProbeAndCacheWorkflowMcp(
+  projectRoot: string,
+  options: { timeoutMs?: number } = {},
+): Promise<WorkflowMcpProbeResult> {
+  const root = cacheKey(projectRoot);
+  const launch = detectWorkflowMcpLaunchConfig(root);
+  const serverName = launch?.name ?? "gsd-workflow";
+
+  const cached = getCachedWorkflowMcpProbe(projectRoot);
+  if (cached && workflowMcpProbeAdvertisesSurface(cached.tools)) {
+    return { ok: true, tools: cached.tools, serverName: cached.serverName };
+  }
+
+  const result = await testMcpServerConnection(serverName, {
+    projectDir: root,
+    timeoutMs: options.timeoutMs ?? WORKFLOW_MCP_PROBE_TIMEOUT_MS,
+  });
+  if (result.ok && workflowMcpProbeAdvertisesSurface(result.tools)) {
+    recordWorkflowMcpProbe(projectRoot, serverName, result.tools);
+  }
+  return {
+    ok: result.ok,
+    tools: result.tools,
+    serverName,
+    error: result.error,
+  };
+}
+
+export async function probeAndCacheWorkflowMcp(
+  projectRoot: string,
+  options: { timeoutMs?: number } = {},
+): Promise<WorkflowMcpProbeResult> {
+  const key = cacheKey(projectRoot);
+  const inFlight = probeInFlightByProject.get(key);
+  if (inFlight) return inFlight;
+
+  const promise = runProbeAndCacheWorkflowMcp(projectRoot, options).finally(() => {
+    probeInFlightByProject.delete(key);
+  });
+  probeInFlightByProject.set(key, promise);
+  return promise;
+}
+
+/** Fire-and-forget probe so /gsd dispatch often hits a warm cache. */
+export function warmWorkflowMcpProbeInBackground(projectRoot: string): void {
+  if (activeWorkflowMcpSdkSessions > 0) return;
+
+  const key = cacheKey(projectRoot);
+  if (getCachedWorkflowMcpProbe(projectRoot)) return;
+  if (probeInFlightByProject.has(key)) return;
+
+  void probeAndCacheWorkflowMcp(projectRoot).catch(() => {
+    // Background warm is best-effort.
+  });
+}

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

@@ -3,6 +3,16 @@ import { mkdirSync, existsSync, readFileSync, unlinkSync } from "node:fs";
 import { logWarning, logError } from "./workflow-logger.js";
 import { readEvents, findForkPoint, getSessionId } from "./workflow-events.js";
 import type { WorkflowEvent } from "./workflow-events.js";
+import {
+  normalizeWorkflowEventCommand,
+  workflowEventEntityKey,
+} from "./workflow-event-vocabulary.js";
+import {
+  readWorktreeEventLogPath,
+  workflowEventLogPath,
+  writeWorkflowEventLog,
+  writeWorktreeEventLog,
+} from "./workflow-event-ledger.js";
 import {
   transaction,
   updateTaskStatus,
@@ -82,14 +92,11 @@ function replayEvents(events: WorkflowEvent[]): void {
   transaction(() => {
   for (const event of events) {
     const p = event.params;
-    // Normalize cmd format: completion tools write hyphens ("complete-task"),
-    // legacy logs use underscores ("complete_task"). Accept both formats.
-    // Type guard: malformed event lines with non-string cmd are skipped.
-    if (typeof event.cmd !== "string") {
+    const cmd = normalizeWorkflowEventCommand(event.cmd);
+    if (!cmd) {
       logWarning("reconcile", `Event with non-string cmd skipped: ${JSON.stringify(event.cmd)}`);
       continue;
     }
-    const cmd = event.cmd.replace(/-/g, "_");
     switch (cmd) {
       case "complete_task": {
         const milestoneId = p["milestoneId"] as string;
@@ -235,48 +242,7 @@ function replayEvents(events: WorkflowEvent[]): void {
 export function extractEntityKey(
   event: WorkflowEvent,
 ): { type: string; id: string } | null {
-  const p = event.params;
-  // Normalize cmd format: accept both hyphens and underscores
-  if (typeof event.cmd !== "string") return null;
-  const cmd = event.cmd.replace(/-/g, "_");
-
-  switch (cmd) {
-    case "complete_task":
-    case "start_task":
-    case "skip_task":
-    case "report_blocker":
-    case "record_verification":
-    case "plan_task":
-      return typeof p["taskId"] === "string"
-        ? { type: "task", id: p["taskId"] }
-        : null;
-
-    case "complete_slice":
-    case "replan_slice":
-      return typeof p["sliceId"] === "string"
-        ? { type: "slice", id: p["sliceId"] }
-        : null;
-
-    case "plan_slice":
-      return typeof p["sliceId"] === "string"
-        ? { type: "slice_plan", id: p["sliceId"] }
-        : null;
-
-    case "complete_milestone":
-    case "plan_milestone":
-      return typeof p["milestoneId"] === "string"
-        ? { type: "milestone", id: p["milestoneId"] }
-        : null;
-
-    case "save_decision":
-      if (typeof p["scope"] === "string" && typeof p["decision"] === "string") {
-        return { type: "decision", id: `${p["scope"]}:${p["decision"]}` };
-      }
-      return null;
-
-    default:
-      return null;
-  }
+  return workflowEventEntityKey(event);
 }
 
 // ─── detectConflicts ──────────────────────────────────────────────────────────
@@ -360,13 +326,6 @@ function rewriteDivergedEventsForEntity(
   return rewritten;
 }
 
-function writeEventLog(basePath: string, events: WorkflowEvent[]): void {
-  const dir = join(basePath, ".gsd");
-  mkdirSync(dir, { recursive: true });
-  const content = events.map((e) => JSON.stringify(e)).join("\n") + (events.length > 0 ? "\n" : "");
-  atomicWriteSync(join(dir, "event-log.jsonl"), content);
-}
-
 // ─── writeConflictsFile ───────────────────────────────────────────────────────
 
 /**
@@ -450,12 +409,18 @@ function _reconcileWorktreeLogsInner(
   worktreeBasePath: string,
 ): ReconcileResult {
   // Step 1: Read both logs
-  const mainLogPath = join(mainBasePath, ".gsd", "event-log.jsonl");
-  const wtLogPath = join(worktreeBasePath, ".gsd", "event-log.jsonl");
+  const mainLogPath = workflowEventLogPath(mainBasePath);
+  const wtLogPath = readWorktreeEventLogPath(worktreeBasePath);
 
   const mainEvents = readEvents(mainLogPath);
   const wtEvents = readEvents(wtLogPath);
 
+  // Canonical worktree appends are already durable in the project ledger.
+  // Empty/missing worktree shards are legacy-only absence, not divergence.
+  if (wtEvents.length === 0) {
+    return { autoMerged: 0, conflicts: [] };
+  }
+
   // Step 2: Find fork point
   const forkPoint = findForkPoint(mainEvents, wtEvents);
 
@@ -495,9 +460,7 @@ function _reconcileWorktreeLogsInner(
 
   const baseEvents = mainEvents.slice(0, forkPoint + 1);
   const mergedLog = baseEvents.concat(merged);
-  const logContent = mergedLog.map((e) => JSON.stringify(e)).join("\n") + (mergedLog.length > 0 ? "\n" : "");
-  mkdirSync(join(mainBasePath, ".gsd"), { recursive: true });
-  atomicWriteSync(join(mainBasePath, ".gsd", "event-log.jsonl"), logContent);
+  writeWorkflowEventLog(mainBasePath, mergedLog);
 
   // Step 8: Replay into DB (wrapped in a transaction by replayEvents)
   openWorkflowDatabasePath(resolveGsdPathContract(mainBasePath).projectDb);
@@ -636,8 +599,8 @@ export function resolveConflict(
   const conflict = conflicts[idx]!;
   const eventsToReplay = pick === "main" ? conflict.mainSideEvents : conflict.worktreeSideEvents;
 
-  const mainLogPath = join(basePath, ".gsd", "event-log.jsonl");
-  const wtLogPath = join(worktreeBasePath, ".gsd", "event-log.jsonl");
+  const mainLogPath = workflowEventLogPath(basePath);
+  const wtLogPath = readWorktreeEventLogPath(worktreeBasePath);
   const mainEvents = readEvents(mainLogPath);
   const wtEvents = readEvents(wtLogPath);
   const forkPoint = findForkPoint(mainEvents, wtEvents);
@@ -652,7 +615,11 @@ export function resolveConflict(
 
   const targetBasePath = pick === "main" ? worktreeBasePath : basePath;
   const targetBaseEvents = pick === "main" ? wtBaseEvents : mainBaseEvents;
-  writeEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
+  if (pick === "main") {
+    writeWorktreeEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
+  } else {
+    writeWorkflowEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
+  }
 
   // Replay resolved events through the DB (updates DB state)
   openWorkflowDatabasePath(resolveGsdPathContract(basePath).projectDb);

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

@@ -47,6 +47,7 @@ import {
 // callers — production wiring previously injected them via deps; the seam
 // added type churn without enabling test variation.
 import { loadEffectiveGSDPreferences, getIsolationMode } from "./preferences.js";
+import { isolationDegradedFallbackGuidance, worktreeCreationFailedGuidance } from "./guidance.js";
 import { invalidateAllCaches } from "./cache.js";
 import { resolveMilestoneFile } from "./paths.js";
 import { getMilestone, insertMilestone, isDbAvailable, updateMilestoneStatus } from "./gsd-db.js";
@@ -693,10 +694,7 @@ export function _enterMilestoneCore(
         s.basePath = basePath;
         rebuildGitService(s, deps);
         invalidateAllCaches();
-        ctx.notify(
-          `Worktree isolation is degraded. Fell back to branch milestone/${milestoneId}.`,
-          "warning",
-        );
+        ctx.notify(isolationDegradedFallbackGuidance(milestoneId), "warning");
         return { ok: true, mode: "branch", path: basePath };
       } catch (err) {
         debugLog("WorktreeLifecycle", {
@@ -883,10 +881,7 @@ export function _enterMilestoneCore(
       eventType: "worktree-create-failed",
       data: { milestoneId, error: msg, fallback: "project-root" },
     });
-    ctx.notify(
-      `Auto-worktree creation for ${milestoneId} failed: ${msg}. Continuing in project root.`,
-      "warning",
-    );
+    ctx.notify(worktreeCreationFailedGuidance(milestoneId, msg), "warning");
     // Degrade isolation for the rest of this session so mergeAndExit
     // doesn't try to merge a nonexistent worktree branch (#2483)
     s.isolationDegraded = true;

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

@@ -656,7 +656,12 @@ export function removeWorktree(
   const resolvedPathSafe = isInsideWorktreesDir(basePath, resolvedWtPath);
 
   // If we're inside the worktree, move out first — git can't remove an in-use directory
-  const cwd = process.cwd();
+  let cwd: string;
+  try {
+    cwd = process.cwd();
+  } catch {
+    cwd = basePath;
+  }
   const resolvedCwd = existsSync(cwd) ? realpathSync(cwd) : cwd;
   if (resolvedCwd === resolvedWtPath || resolvedCwd.startsWith(resolvedWtPath + sep)) {
     process.chdir(basePath);

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

@@ -218,52 +218,54 @@ export function createWorktreeSafetyModule(
       }
 
       let registered: readonly RegisteredWorktree[] | undefined;
-      try {
-        registered = deps.listRegisteredWorktrees?.(projectRoot);
-      } catch (error) {
-        return failure(
-          "worktree-git-probe-failed",
-          `Unable to list registered worktrees for project root ${projectRoot}.`,
-          "Recover or recreate the milestone worktree before dispatching the source-writing Unit.",
-          { projectRoot, error: errorMessage(error) },
-        );
-      }
-      if (registered && !registered.some((worktree) => samePath(worktree.path, unitRoot))) {
-        const wasPreviouslyTracked = unregisteredRecoveryFailed.has(unitRoot);
-        let attemptedPrune = false;
+      if (isolationMode === "worktree") {
+        try {
+          registered = deps.listRegisteredWorktrees?.(projectRoot);
+        } catch (error) {
+          return failure(
+            "worktree-git-probe-failed",
+            `Unable to list registered worktrees for project root ${projectRoot}.`,
+            "Recover or recreate the milestone worktree before dispatching the source-writing Unit.",
+            { projectRoot, error: errorMessage(error) },
+          );
+        }
+        if (registered && !registered.some((worktree) => samePath(worktree.path, unitRoot))) {
+          const wasPreviouslyTracked = unregisteredRecoveryFailed.has(unitRoot);
+          let attemptedPrune = false;
 
-        if (!wasPreviouslyTracked && deps.pruneRegisteredWorktrees) {
-          attemptedPrune = true;
-          try {
-            deps.pruneRegisteredWorktrees(projectRoot);
-            const rechecked = deps.listRegisteredWorktrees?.(projectRoot);
-            if (rechecked?.some((worktree) => samePath(worktree.path, unitRoot))) {
-              unregisteredRecoveryFailed.delete(unitRoot);
-              registered = rechecked;
-            } else {
+          if (!wasPreviouslyTracked && deps.pruneRegisteredWorktrees) {
+            attemptedPrune = true;
+            try {
+              deps.pruneRegisteredWorktrees(projectRoot);
+              const rechecked = deps.listRegisteredWorktrees?.(projectRoot);
+              if (rechecked?.some((worktree) => samePath(worktree.path, unitRoot))) {
+                unregisteredRecoveryFailed.delete(unitRoot);
+                registered = rechecked;
+              } else {
+                unregisteredRecoveryFailed.add(unitRoot);
+              }
+            } catch (error) {
               unregisteredRecoveryFailed.add(unitRoot);
+              return failure(
+                "worktree-git-probe-failed",
+                `Unable to recover unregistered worktree root ${unitRoot}.`,
+                "Run 'git worktree prune', then recreate or re-register the milestone worktree before dispatching the source-writing Unit.",
+                { projectRoot, unitRoot, error: errorMessage(error) },
+              );
             }
-          } catch (error) {
-            unregisteredRecoveryFailed.add(unitRoot);
+          }
+
+          if (!registered?.some((worktree) => samePath(worktree.path, unitRoot))) {
             return failure(
-              "worktree-git-probe-failed",
-              `Unable to recover unregistered worktree root ${unitRoot}.`,
-              "Run 'git worktree prune', then recreate the milestone worktree before dispatching the source-writing Unit.",
-              { projectRoot, unitRoot, error: errorMessage(error) },
+              "worktree-unregistered",
+              `Worktree root ${unitRoot} is not registered with git worktree list.`,
+              attemptedPrune || wasPreviouslyTracked
+                ? "Worktree recovery was attempted but the root is still unregistered. Recreate or re-register the milestone worktree before dispatching the source-writing Unit."
+                : "Run 'git worktree prune'. If still unregistered, recreate or re-register the milestone worktree before dispatching the source-writing Unit.",
+              { unitRoot, attemptedPrune, trackedAsFailed: unregisteredRecoveryFailed.has(unitRoot) },
             );
           }
         }
-
-        if (!registered?.some((worktree) => samePath(worktree.path, unitRoot))) {
-          return failure(
-            "worktree-unregistered",
-            `Worktree root ${unitRoot} is not registered with git worktree list.`,
-            attemptedPrune || wasPreviouslyTracked
-              ? "Worktree recovery was attempted but the root is still unregistered. Recreate or re-register the milestone worktree before dispatching the source-writing Unit."
-              : "Run 'git worktree prune'. If still unregistered, recreate or re-register the milestone worktree before dispatching the source-writing Unit.",
-            { unitRoot, attemptedPrune, trackedAsFailed: unregisteredRecoveryFailed.has(unitRoot) },
-          );
-        }
       }
 
       if (input.emptyWorktreeWithProjectContent) {

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

@@ -224,7 +224,13 @@ export function resolveGitHeadPath(dir: string): string | null {
  */
 export function nudgeGitBranchCache(previousCwd: string): void {
   const now = new Date();
-  for (const dir of [previousCwd, process.cwd()]) {
+  let currentCwd: string | null = null;
+  try {
+    currentCwd = process.cwd();
+  } catch {
+    currentCwd = null;
+  }
+  for (const dir of [previousCwd, currentCwd].filter((dir): dir is string => Boolean(dir))) {
     try {
       const headPath = resolveGitHeadPath(dir);
       if (headPath) utimesSync(headPath, now, now);

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

@@ -105,6 +105,9 @@ const CHILD_ENV_ALLOWLIST = new Set([
 
 const MCP_STDERR_MAX_BYTES = 4096;
 
+/** Short-lived stdio probes must not register/kill production MCP PIDs (see probe-mode.ts). */
+export const GSD_MCP_PROBE_ENV = "GSD_MCP_PROBE";
+
 let cachedStatus: ManagedMcpStatus | null = null;
 let cachedStatusKey = "";
 
@@ -385,7 +388,10 @@ export async function testMcpServerConnection(
 			transport = new StdioClientTransport({
 				command: config.command ?? "",
 				args: config.args,
-				env: buildMcpChildEnv(config.env),
+				env: {
+					...buildMcpChildEnv(config.env),
+					[GSD_MCP_PROBE_ENV]: "1",
+				},
 				cwd: config.cwd,
 				stderr: "pipe",
 			});

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

@@ -55,6 +55,24 @@ function parseGsdBrowserVersion(output: string): string | null {
   return output.match(/\b(\d+\.\d+\.\d+)\b/)?.[1] ?? null;
 }
 
+function splitCommandLine(commandLine: string): string[] {
+  const parts = commandLine.match(/(?:"[^"]*"|'[^']*'|[^\s"']+)/g) ?? [];
+  return parts.map((part) => {
+    const quote = part[0];
+    if ((quote === '"' || quote === "'") && part.endsWith(quote)) {
+      return part.slice(1, -1);
+    }
+    return part;
+  });
+}
+
+function buildPathGsdBrowserVersionInvocation(platform: NodeJS.Platform): { command: string; args: string[] } {
+  if (platform === "win32") {
+    return { command: "cmd", args: ["/d", "/s", "/c", "gsd-browser", "--version"] };
+  }
+  return { command: "gsd-browser", args: ["--version"] };
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -86,7 +104,8 @@ function resolvePathGsdBrowserVersion(env: NodeJS.ProcessEnv): string | null {
   if (cachedPathProbeVersion !== undefined) return cachedPathProbeVersion;
 
   try {
-    cachedPathProbeVersion = parseGsdBrowserVersion(execFileSync("gsd-browser", ["--version"], {
+    const invocation = buildPathGsdBrowserVersionInvocation(process.platform);
+    cachedPathProbeVersion = parseGsdBrowserVersion(execFileSync(invocation.command, invocation.args, {
       encoding: "utf-8",
       env,
       stdio: ["ignore", "pipe", "ignore"],
@@ -216,7 +235,8 @@ export function resolveGsdBrowserMcpLaunchConfig(
   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 explicitCommandLine = env.GSD_BROWSER_MCP_COMMAND?.trim();
+  const [explicitCommand, ...explicitCommandArgs] = explicitCommandLine ? splitCommandLine(explicitCommandLine) : [];
   const explicitCliPath = resolveExplicitGsdBrowserCliPath(env);
   const preferPathCli = !explicitCommand && !explicitCliPath && shouldPreferPathGsdBrowser(env);
   const bundledCliPath = !explicitCommand && !explicitCliPath && !preferPathCli
@@ -228,6 +248,10 @@ export function resolveGsdBrowserMcpLaunchConfig(
   // profile/cookies persist across pi sessions for the same project. gsd-browser
   // rejects --identity-scope unless --identity-key is also supplied.
   const identityKey = env.GSD_BROWSER_IDENTITY_KEY?.trim() || buildGsdBrowserSessionName(resolvedProjectRoot);
+  // identity-project must be a safe identifier (no path separators); full paths
+  // cause daemon startup to fail with "invalid name".
+  const identityProject =
+    env.GSD_BROWSER_IDENTITY_PROJECT?.trim() || buildGsdBrowserSessionName(resolvedProjectRoot);
   const command =
     explicitCommand
     || explicitCliPath
@@ -237,6 +261,7 @@ export function resolveGsdBrowserMcpLaunchConfig(
   const args = Array.isArray(explicitArgs) && explicitArgs.length > 0
     ? explicitArgs.map(String)
     : [
+        ...explicitCommandArgs,
         ...(bundledCliPath ? [bundledCliPath] : []),
         "mcp",
         "--session",
@@ -246,7 +271,7 @@ export function resolveGsdBrowserMcpLaunchConfig(
         "--identity-key",
         identityKey,
         "--identity-project",
-        resolvedProjectRoot,
+        identityProject,
       ];
   const cwd = env.GSD_BROWSER_MCP_CWD?.trim() || resolvedProjectRoot;
 
@@ -260,3 +285,29 @@ export function resolveGsdBrowserMcpLaunchConfig(
     sessionName,
   };
 }
+
+/**
+ * CLI invocation that starts the gsd-browser session daemon with the same
+ * session and identity flags as {@link resolveGsdBrowserMcpLaunchConfig}, so
+ * browser UAT can warm Chrome/CDP before the first MCP navigation.
+ */
+export function resolveGsdBrowserDaemonStartInvocation(
+  projectRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+  options: GsdBrowserMcpLaunchOptions = {},
+): Pick<GsdBrowserMcpLaunchConfig, "command" | "args" | "cwd" | "env"> {
+  const launch = resolveGsdBrowserMcpLaunchConfig(projectRoot, env, options);
+  const mcpIndex = launch.args.indexOf("mcp");
+  if (mcpIndex < 0) {
+    throw new Error("gsd-browser launch config is missing mcp subcommand");
+  }
+
+  const prefix = launch.args.slice(0, mcpIndex);
+  const sessionFlags = launch.args.slice(mcpIndex + 1);
+  return {
+    command: launch.command,
+    args: [...prefix, "daemon", "start", ...sessionFlags],
+    cwd: launch.cwd,
+    ...(launch.env ? { env: launch.env } : {}),
+  };
+}