@opengsd/gsd-pi 1.2.0-dev.955e4da0 → 1.2.0-dev.a6376d75

package/src/resources/extensions/gsd/workflow-tool-surface.ts

@@ -28,7 +28,7 @@ export const WORKFLOW_TOOL_ALIAS_PAIRS: readonly WorkflowToolAliasPair[] =
 export const WORKFLOW_TOOL_ALIAS_TO_CANONICAL: Readonly<Record<string, string>> =
   Object.fromEntries(WORKFLOW_TOOL_ALIAS_PAIRS.map(({ alias, canonical }) => [alias, canonical]));
 
-const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
+export const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
   "gsd_cancel",
   "gsd_captures",
   "ask_user_questions",
@@ -45,6 +45,9 @@ const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
   "gsd_status",
 ] as const;
 
+/** Session-orchestration tools exposed by the workflow MCP adapter alongside the contract tools. */
+export type WorkflowMcpAdapterToolName = (typeof WORKFLOW_MCP_ADAPTER_TOOL_NAMES)[number];
+
 export const WORKFLOW_TOOL_SURFACE_NAMES = [
   ...WORKFLOW_MCP_ADAPTER_TOOL_NAMES,
   ...DB_WORKFLOW_TOOL_NAMES,

package/src/resources/extensions/gsd/worktree-git-recovery.ts

@@ -8,8 +8,9 @@
  * git operations during worktree transitions:
  *
  *   - `checkoutBranchWithStashGuard` — branch switch with stash protection,
- *     including the stash-pop EEXIST collision recovery for `.gsd/` runtime
- *     files (force-checkout + targeted stash drop).
+ *     including the stash-pop EEXIST collision recovery for untracked files
+ *     (force-checkout + targeted stash drop; #645 broadened it beyond `.gsd/`,
+ *     guarded by "no non-.gsd unmerged entries remain").
  *   - `removeMergeStateFiles` — clears SQUASH_MSG / MERGE_HEAD / etc. left by
  *     a failed merge so subsequent merges don't fail on stale state.
  *   - `cleanupConflictState` — merge-abort + index reset + state-file cleanup
@@ -257,23 +258,28 @@ export function checkoutBranchWithStashGuard(
           : "";
       const stashPopMessage = `${stderrText}\n${msg}`.trim();
       const alreadyExists = stashAlreadyExistsFilesFromError(popErr);
-      const gsdAlreadyExists = alreadyExists.filter((f) => f.startsWith(".gsd/"));
-      const nonGsdAlreadyExists = alreadyExists.filter((f) => !f.startsWith(".gsd/"));
       const isUntrackedRestoreFailure = stashPopMessage.includes("could not restore untracked files from stash");
       const stashRefForDrop = stashRefFromError(popErr);
-      const nonGsdUnmerged = nativeConflictFiles(basePath).filter((f) => !f.startsWith(".gsd/"));
+      const allConflictFiles = nativeConflictFiles(basePath);
+      const nonGsdUnmerged = allConflictFiles.filter((f) => !f.startsWith(".gsd/"));
+      const gsdUnmerged = allConflictFiles.filter((f) => f.startsWith(".gsd/"));
       const gsdContentConflicts = isUntrackedRestoreFailure
         ? gsdJsonlFilesWithConflictMarkers(basePath)
         : [];
-      const gsdConflictFiles = [...new Set([...gsdAlreadyExists, ...gsdContentConflicts])];
+      // Resolve ALL untracked-collision files by accepting HEAD — files in
+      // alreadyExists were untracked on the source branch by definition of the
+      // "already exists, no checkout" failure, so target HEAD is authoritative.
+      // gsdUnmerged: .gsd/ index conflicts left by the partial stash pop are
+      // also resolved via HEAD — .gsd/ runtime state is always authoritative
+      // on the target branch, so accepting HEAD is safe here too.
+      const resolvable = [...new Set([...alreadyExists, ...gsdContentConflicts, ...gsdUnmerged])];
 
       if (
         isUntrackedRestoreFailure &&
-        gsdConflictFiles.length > 0 &&
-        nonGsdAlreadyExists.length === 0 &&
+        resolvable.length > 0 &&
         nonGsdUnmerged.length === 0
       ) {
-        for (const f of gsdConflictFiles) {
+        for (const f of resolvable) {
           execFileSync("git", ["checkout", "HEAD", "--", f], {
             cwd: basePath,
             stdio: ["ignore", "pipe", "pipe"],

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

@@ -69,6 +69,18 @@ export function isGsdWorktreePath(path: string): boolean {
   return findWorktreeSegment(path.replaceAll("\\", "/")) !== null;
 }
 
+/**
+ * Project-root prefix of a GSD worktree path, or null when the path is not
+ * inside a recognized worktree layout. Pure string split — no env handling,
+ * HOME guard, or filesystem fallbacks (resolveWorktreeProjectRoot adds
+ * those). Separator normalization is 1:1 on characters, so the prefix is
+ * sliced from the ORIGINAL string and keeps its separators.
+ */
+export function projectRootFromWorktreePath(path: string): string | null {
+  const segment = findWorktreeSegment(path.replaceAll("\\", "/"));
+  return segment ? path.slice(0, segment.gsdIdx) : null;
+}
+
 /**
  * When a milestone worktree lives under the external-state layout
  * (`<gsdHome>/projects/<hash>/worktrees/<MID>/`, or the `GSD_STATE_DIR`

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

@@ -1,5 +1,5 @@
 // GSD worktree session state
-import { findWorktreeSegment } from "./worktree-root.js";
+import { findWorktreeSegment, projectRootFromWorktreePath } from "./worktree-root.js";
 
 let originalCwd: string | null = null;
 
@@ -17,10 +17,8 @@ export function clearWorktreeOriginalCwd(): void {
 
 export function ensureWorktreeOriginalCwdFromPath(cwd: string = process.cwd()): string | null {
   if (originalCwd) return originalCwd;
-  const segment = findWorktreeSegment(cwd.replaceAll("\\", "/"));
-  if (segment) {
-    originalCwd = cwd.slice(0, segment.gsdIdx);
-  }
+  const root = projectRootFromWorktreePath(cwd);
+  if (root) originalCwd = root;
   return originalCwd;
 }
 

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/search-the-web/native-search.ts

@@ -243,9 +243,11 @@ export function registerNativeSearchHooks(pi: NativeSearchPI): { getIsAnthropic:
       // Anthropic-only tool never leaks into OpenAI Responses requests.
       isAnthropic = isAnthropicProvider && payloadLooksAnthropic !== false;
     } else {
-      // Last resort: session-restore paths where the SDK doesn't pass model.
-      // The model-name prefix is best-effort and assumes direct Anthropic.
-      isAnthropic = payloadLooksAnthropic === true;
+      // No authoritative provider info available (no event.model, no model_select).
+      // Do NOT inject native web_search — guessing on model name alone causes 400
+      // "unsupported_value" errors when the actual provider (copilot, openrouter,
+      // proxy, etc.) doesn't expose the server-side search tool (#648).
+      isAnthropic = false;
     }
     if (!isAnthropic) return;
 

package/src/resources/extensions/shared/browser-contract.ts

@@ -0,0 +1,66 @@
+// Project/App: gsd-pi
+// File Purpose: Browser Automation Contract — the single source for the canonical
+// Pi-facing browser tool vocabulary. Engine adapters (legacy Playwright, managed
+// gsd-browser), UAT policy, dispatch preflight, and evidence detection all derive
+// their browser tool knowledge from this module instead of re-listing names.
+
+/**
+ * Canonical `browser_*` tool names of the Browser Automation Contract.
+ *
+ * These are the product-level names Units see regardless of which Browser
+ * Automation Engine serves them (ADR-024). Adding a capability here is the
+ * one-line vocabulary change; the engine adapters and presentation surfaces
+ * are typed against this list, so missing coverage fails typecheck.
+ */
+export const BROWSER_CONTRACT_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 type BrowserContractToolName = (typeof BROWSER_CONTRACT_TOOL_NAMES)[number];
+
+const BROWSER_CONTRACT_TOOL_NAME_SET: ReadonlySet<string> = new Set(BROWSER_CONTRACT_TOOL_NAMES);
+
+export function isBrowserContractToolName(name: string): name is BrowserContractToolName {
+  return BROWSER_CONTRACT_TOOL_NAME_SET.has(name);
+}
+
+/**
+ * Whether a canonical (non-MCP-prefixed) tool name belongs to the browser tool
+ * family. Broader than the contract list on purpose: an External MCP Client or
+ * host integration may supply additional `browser_*` tools that still satisfy
+ * browser-backed UAT.
+ */
+export function hasBrowserContractPrefix(canonicalToolName: string): boolean {
+  return canonicalToolName.startsWith("browser_");
+}
+
+/**
+ * Contract tool names whose appearance in prose marks browser-backed UAT
+ * activity (requirement or evidence language). Consumed by the
+ * browser-evidence regexes so textual detection stays derived from the
+ * contract vocabulary.
+ */
+export const BROWSER_EVIDENCE_SIGNAL_TOOL_NAMES = [
+  "browser_assert",
+  "browser_batch",
+  "browser_find",
+  "browser_verify",
+  "browser_snapshot_refs",
+] as const satisfies readonly BrowserContractToolName[];

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

@@ -55,6 +55,32 @@ 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);
+}
+
+function resolveExplicitGsdBrowserCliPath(env: NodeJS.ProcessEnv): string | undefined {
+  return env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim() || undefined;
+}
+
 function resolveBundledGsdBrowserPackageVersion(): string | null {
   try {
     const requireFromHere = createRequire(import.meta.url);
@@ -66,20 +92,29 @@ function resolveBundledGsdBrowserPackageVersion(): string | null {
   }
 }
 
+// The `gsd-browser --version` subprocess result cannot change mid-session (the
+// engine-switch guard forbids restarting with a different engine), and both the
+// availability probe and the launch-config resolution ask for it at session
+// start — memoize so the up-to-2s spawn happens once per process.
+let cachedPathProbeVersion: string | null | undefined;
+
 function resolvePathGsdBrowserVersion(env: NodeJS.ProcessEnv): string | null {
   const explicit = env.GSD_BROWSER_PATH_VERSION?.trim();
   if (explicit) return parseGsdBrowserVersion(explicit);
+  if (cachedPathProbeVersion !== undefined) return cachedPathProbeVersion;
 
   try {
-    return 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"],
       timeout: 2000,
     }));
   } catch {
-    return null;
+    cachedPathProbeVersion = null;
   }
+  return cachedPathProbeVersion;
 }
 
 function shouldPreferPathGsdBrowser(env: NodeJS.ProcessEnv): boolean {
@@ -91,7 +126,7 @@ function shouldPreferPathGsdBrowser(env: NodeJS.ProcessEnv): boolean {
 }
 
 export function resolveBundledGsdBrowserCliPath(env: NodeJS.ProcessEnv = process.env): string | null {
-  const explicit = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim();
+  const explicit = resolveExplicitGsdBrowserCliPath(env);
   if (explicit) return explicit;
 
   try {
@@ -115,6 +150,45 @@ export function resolveBundledGsdBrowserCliPath(env: NodeJS.ProcessEnv = process
   return null;
 }
 
+export type GsdBrowserCliAvailability =
+  | { available: true; via: "explicit-env" | "bundled" | "path"; detail: string }
+  | { available: false; detail: string };
+
+/**
+ * Cheap availability probe for the gsd-browser CLI: explicit env overrides,
+ * then the bundled @opengsd/gsd-browser binary (filesystem checks only), then
+ * a PATH lookup (one short subprocess, memoized). Used by Browser Automation
+ * Engine resolution to decide whether the managed engine is provable before
+ * preferring it over legacy Playwright. `via` names the provable source, not
+ * necessarily the launch source — resolveGsdBrowserMcpLaunchConfig may still
+ * prefer a newer PATH CLI over the bundled one.
+ */
+export function resolveGsdBrowserCliAvailability(env: NodeJS.ProcessEnv = process.env): GsdBrowserCliAvailability {
+  const explicitCommand = env.GSD_BROWSER_MCP_COMMAND?.trim();
+  if (explicitCommand) {
+    return { available: true, via: "explicit-env", detail: `GSD_BROWSER_MCP_COMMAND=${explicitCommand}` };
+  }
+
+  const explicitCliPath = resolveExplicitGsdBrowserCliPath(env);
+  if (explicitCliPath) {
+    return existsSync(explicitCliPath)
+      ? { available: true, via: "explicit-env", detail: `CLI at ${explicitCliPath}` }
+      : { available: false, detail: `configured gsd-browser CLI path does not exist: ${explicitCliPath}` };
+  }
+
+  const bundledCliPath = resolveBundledGsdBrowserCliPath(env);
+  if (bundledCliPath) {
+    return { available: true, via: "bundled", detail: `bundled CLI at ${bundledCliPath}` };
+  }
+
+  const pathVersion = resolvePathGsdBrowserVersion(env);
+  if (pathVersion) {
+    return { available: true, via: "path", detail: `gsd-browser ${pathVersion} on PATH` };
+  }
+
+  return { available: false, detail: "no bundled or PATH gsd-browser CLI found" };
+}
+
 export function buildGsdBrowserSessionName(projectRoot: string, suffix?: string): string {
   const resolvedProjectRoot = resolve(projectRoot);
   const base = sanitizeSessionSegment(basename(resolvedProjectRoot)) || "project";
@@ -123,6 +197,35 @@ export function buildGsdBrowserSessionName(projectRoot: string, suffix?: string)
   return cleanSuffix ? `gsd-${base}-${hash}-${cleanSuffix}` : `gsd-${base}-${hash}`;
 }
 
+/**
+ * Recognize an MCP server config (from .mcp.json / Claude settings) as a
+ * gsd-browser server. Paired with resolveGsdBrowserMcpLaunchConfig: this module
+ * writes the config shape, so it also owns recognizing it. New launch shapes
+ * are taught here, in one place.
+ */
+export function isGsdBrowserMcpServerConfig(config: unknown): boolean {
+  if (!isRecord(config)) return false;
+
+  const command = typeof config.command === "string" ? config.command : "";
+  if (command.includes("gsd-browser") || command.includes("@opengsd/gsd-browser")) {
+    return true;
+  }
+
+  if (isRecord(config.env)) {
+    const env = config.env;
+    if (
+      typeof env.GSD_BROWSER_CLI_PATH === "string"
+      || typeof env.GSD_BROWSER_BIN_PATH === "string"
+      || typeof env.GSD_BROWSER_MCP_COMMAND === "string"
+    ) {
+      return true;
+    }
+  }
+
+  const args = Array.isArray(config.args) ? config.args.filter((arg): arg is string => typeof arg === "string") : [];
+  return args.some((arg) => arg.includes("gsd-browser") || arg.includes("@opengsd/gsd-browser"));
+}
+
 export function resolveGsdBrowserMcpLaunchConfig(
   projectRoot: string,
   env: NodeJS.ProcessEnv = process.env,
@@ -132,8 +235,9 @@ 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 explicitCliPath = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.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
     ? resolveBundledGsdBrowserCliPath(env)
@@ -144,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
@@ -153,6 +261,7 @@ export function resolveGsdBrowserMcpLaunchConfig(
   const args = Array.isArray(explicitArgs) && explicitArgs.length > 0
     ? explicitArgs.map(String)
     : [
+        ...explicitCommandArgs,
         ...(bundledCliPath ? [bundledCliPath] : []),
         "mcp",
         "--session",
@@ -162,7 +271,7 @@ export function resolveGsdBrowserMcpLaunchConfig(
         "--identity-key",
         identityKey,
         "--identity-project",
-        resolvedProjectRoot,
+        identityProject,
       ];
   const cwd = env.GSD_BROWSER_MCP_CWD?.trim() || resolvedProjectRoot;
 
@@ -176,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 } : {}),
+  };
+}