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

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

@@ -1,8 +1,8 @@
-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, } from "./workflow-event-ledger.js";
 import { logWarning } from "./workflow-logger.js";
 // ─── Session ID ───────────────────────────────────────────────────────────
 /**
@@ -20,19 +20,7 @@ export function getSessionId() {
  * Creates .gsd directory if needed.
  */
 export function appendEvent(basePath, event) {
-    const hash = createHash("sha256")
-        .update(JSON.stringify({ cmd: event.cmd, params: event.params }))
-        .digest("hex")
-        .slice(0, 16);
-    const fullEvent = {
-        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 ──────────────────────────────────────────────────────────
 /**
@@ -87,8 +75,8 @@ export function findForkPoint(logA, logB) {
  * @returns { archived: number } — count of events moved to archive
  */
 export function compactMilestoneEvents(basePath, milestoneId) {
-    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);
         // Single-pass partition to halve the work (per reviewer agent)

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

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

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

@@ -0,0 +1,105 @@
+// 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;
+const cacheByProject = new Map();
+const probeInFlightByProject = new Map();
+let activeWorkflowMcpSdkSessions = 0;
+function cacheKey(projectRoot) {
+    return resolveWorkflowMcpProjectRoot(projectRoot);
+}
+export function beginWorkflowMcpSdkSession() {
+    activeWorkflowMcpSdkSessions++;
+}
+export function endWorkflowMcpSdkSession() {
+    activeWorkflowMcpSdkSessions = Math.max(0, activeWorkflowMcpSdkSessions - 1);
+}
+export function getCachedWorkflowMcpProbe(projectRoot) {
+    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, serverName, tools) {
+    cacheByProject.set(cacheKey(projectRoot), {
+        serverName,
+        tools: [...tools],
+        probedAt: Date.now(),
+    });
+}
+export function clearWorkflowMcpProbeCache(projectRoot) {
+    if (projectRoot === undefined) {
+        cacheByProject.clear();
+        probeInFlightByProject.clear();
+        activeWorkflowMcpSdkSessions = 0;
+        return;
+    }
+    const key = cacheKey(projectRoot);
+    cacheByProject.delete(key);
+    probeInFlightByProject.delete(key);
+}
+export function workflowMcpProbeAdvertisesSurface(tools) {
+    return tools.some((tool) => isWorkflowToolSurfaceName(tool));
+}
+export function cachedWorkflowMcpCoversRequired(projectRoot, serverName, required) {
+    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, options = {}) {
+    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, options = {}) {
+    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) {
+    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/dist/resources/extensions/gsd/workflow-reconcile.js

@@ -2,6 +2,8 @@ import { join } from "node:path";
 import { mkdirSync, existsSync, readFileSync, unlinkSync } from "node:fs";
 import { logWarning, logError } from "./workflow-logger.js";
 import { readEvents, findForkPoint, getSessionId } 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, updateSliceStatus, updateMilestoneStatus, getSliceTasks, insertMilestone, getMilestoneSlices, insertVerificationEvidence, upsertDecision, setTaskBlockerDiscovered, insertOrIgnoreSlice, insertOrIgnoreTask, } from "./gsd-db.js";
 import { openWorkflowDatabasePath } from "./db-workspace.js";
 import { isClosedStatus } from "./status-guards.js";
@@ -48,14 +50,11 @@ function replayEvents(events) {
     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"];
@@ -199,43 +198,7 @@ function replayEvents(events) {
  * (e.g. unknown or future cmds).
  */
 export function extractEntityKey(event) {
-    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 ──────────────────────────────────────────────────────────
 /**
@@ -302,12 +265,6 @@ function rewriteDivergedEventsForEntity(divergedEvents, entityType, entityId, re
     }
     return rewritten;
 }
-function writeEventLog(basePath, events) {
-    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 ───────────────────────────────────────────────────────
 /**
  * Write a human-readable CONFLICTS.md to basePath/.gsd/CONFLICTS.md.
@@ -375,10 +332,15 @@ export function reconcileWorktreeLogs(mainBasePath, worktreeBasePath) {
 }
 function _reconcileWorktreeLogsInner(mainBasePath, worktreeBasePath) {
     // 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);
     // Step 3: Slice diverged sets
@@ -412,9 +374,7 @@ function _reconcileWorktreeLogsInner(mainBasePath, worktreeBasePath) {
     }
     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);
     replayEvents(merged);
@@ -533,8 +493,8 @@ pick) {
         throw new Error(`No conflict found for entity ${entityKey}`);
     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);
@@ -547,7 +507,12 @@ pick) {
         : rewriteDivergedEventsForEntity(mainDiverged, entityType, entityId, eventsToReplay);
     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);
     replayEvents(eventsToReplay);

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

@@ -32,6 +32,7 @@ import { getCollapseCadence, getMilestoneResquash, resquashMilestoneOnMain, } fr
 // 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";
@@ -343,7 +344,7 @@ export function _enterMilestoneCore(s, deps, milestoneId, ctx, opts = {}) {
                 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) {
@@ -517,7 +518,7 @@ export function _enterMilestoneCore(s, deps, milestoneId, ctx, opts = {}) {
             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/dist/resources/extensions/gsd/worktree-manager.js

@@ -528,7 +528,13 @@ export function removeWorktree(basePath, name, opts = {}) {
     // inside .gsd/worktrees/ — a symlink inside the directory could point out.
     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;
+    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/dist/resources/extensions/gsd/worktree-safety.js

@@ -90,38 +90,40 @@ export function createWorktreeSafetyModule(deps = defaultDeps) {
                 return failure("worktree-git-marker-not-file", `Worktree root ${unitRoot} has a .git directory, not a registered worktree .git file.`, "Use a registered GSD worktree instead of a copied or nested repository.", { gitMarker });
             }
             let registered;
-            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;
+            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 {
+                                unregisteredRecoveryFailed.add(unitRoot);
+                            }
                         }
-                        else {
+                        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);
-                        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) });
+                    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 (!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) {
                 return failure("empty-worktree-with-project-content", `Worktree root ${unitRoot} has no project content, but the project root does.`, "Resolve untracked project-root content or recreate the worktree so source writes stay isolated.", { unitRoot, projectRoot });

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

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

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

@@ -30,6 +30,8 @@ const CHILD_ENV_ALLOWLIST = new Set([
     "XDG_CACHE_HOME",
 ]);
 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 = null;
 let cachedStatusKey = "";
 export function clearMcpConfigCache() {
@@ -259,7 +261,10 @@ export async function testMcpServerConnection(nameOrConfig, options = {}) {
             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/dist/resources/extensions/shared/gsd-browser-cli.js

@@ -38,6 +38,22 @@ function compareSemverLocal(a, b) {
 function parseGsdBrowserVersion(output) {
     return output.match(/\b(\d+\.\d+\.\d+)\b/)?.[1] ?? null;
 }
+function splitCommandLine(commandLine) {
+    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) {
+    if (platform === "win32") {
+        return { command: "cmd", args: ["/d", "/s", "/c", "gsd-browser", "--version"] };
+    }
+    return { command: "gsd-browser", args: ["--version"] };
+}
 function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -67,7 +83,8 @@ function resolvePathGsdBrowserVersion(env) {
     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"],
@@ -176,7 +193,8 @@ export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env,
     const serverName = env.GSD_BROWSER_MCP_NAME?.trim() || GSD_BROWSER_MCP_SERVER_NAME;
     const explicitArgs = parseJsonEnv(env, "GSD_BROWSER_MCP_ARGS");
     const explicitEnv = parseJsonEnv(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
@@ -187,6 +205,9 @@ export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env,
     // 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
         || (preferPathCli ? "gsd-browser" : undefined)
@@ -195,6 +216,7 @@ export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env,
     const args = Array.isArray(explicitArgs) && explicitArgs.length > 0
         ? explicitArgs.map(String)
         : [
+            ...explicitCommandArgs,
             ...(bundledCliPath ? [bundledCliPath] : []),
             "mcp",
             "--session",
@@ -204,7 +226,7 @@ export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env,
             "--identity-key",
             identityKey,
             "--identity-project",
-            resolvedProjectRoot,
+            identityProject,
         ];
     const cwd = env.GSD_BROWSER_MCP_CWD?.trim() || resolvedProjectRoot;
     return {
@@ -217,3 +239,23 @@ export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env,
         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, env = process.env, options = {}) {
+    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 } : {}),
+    };
+}