@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.6ccd27b3

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

@@ -14,10 +14,16 @@ export function normalizeWorktreePathForCompare(path) {
     return process.platform === "win32" ? (trimmed || "/").toLowerCase() : (trimmed || "/");
 }
 /**
- * Find the GSD worktree segment in both direct project layout and the
- * symlink-resolved external-state layout used by ~/.gsd/projects/<hash>.
+ * Find the GSD worktree segment in the canonical layout (.gsd-worktrees/),
+ * the legacy direct layout (.gsd/worktrees/), and the symlink-resolved
+ * external-state layout used by ~/.gsd/projects/<hash>.
  */
 export function findWorktreeSegment(normalizedPath) {
+    const canonicalMarker = "/.gsd-worktrees/";
+    const canonicalIdx = normalizedPath.indexOf(canonicalMarker);
+    if (canonicalIdx !== -1) {
+        return { gsdIdx: canonicalIdx, afterWorktrees: canonicalIdx + canonicalMarker.length };
+    }
     const directMarker = "/.gsd/worktrees/";
     const directIdx = normalizedPath.indexOf(directMarker);
     if (directIdx !== -1) {
@@ -51,6 +57,17 @@ export function findWorktreeSegment(normalizedPath) {
 export function isGsdWorktreePath(path) {
     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) {
+    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`
@@ -60,7 +77,9 @@ export function isGsdWorktreePath(path) {
  */
 export function resolveExternalStateProjectGsdFromWorktreePath(projectPath) {
     const normalized = resolve(projectPath).replaceAll("\\", "/");
-    // Direct layout — parent state is resolved via repoIdentity(git root).
+    // Canonical/direct layouts — parent state is resolved via repoIdentity(git root).
+    if (normalized.includes("/.gsd-worktrees/"))
+        return null;
     if (normalized.includes("/.gsd/worktrees/") && !normalized.includes("/.gsd/projects/")) {
         return null;
     }
@@ -117,12 +136,15 @@ function resolveProjectRootFromPath(path) {
     if (!segment) {
         return resolveNearestBootstrappedGsdRoot(path) ?? resolveGitWorkingTreeRoot(path) ?? path;
     }
+    // Slice at the first `.gsd` boundary, but never past the worktree segment:
+    // in the canonical layout (`<root>/.gsd-worktrees/<MID>/.gsd/...`) the first
+    // `/.gsd/` occurrence is the worktree-local projection dir, not the project
+    // root's state dir.
     const sepChar = path.includes("\\") ? "\\" : "/";
     const gsdMarker = `${sepChar}.gsd${sepChar}`;
     const markerIdx = path.indexOf(gsdMarker);
-    const candidate = markerIdx !== -1
-        ? path.slice(0, markerIdx)
-        : path.slice(0, segment.gsdIdx);
+    const sliceIdx = markerIdx !== -1 ? Math.min(markerIdx, segment.gsdIdx) : segment.gsdIdx;
+    const candidate = path.slice(0, sliceIdx);
     const gsdHomeNorm = normalizeWorktreePathForCompare(gsdHome());
     const candidateGsdPath = normalizeWorktreePathForCompare(join(candidate, ".gsd"));
     if (candidateGsdPath === gsdHomeNorm || candidateGsdPath.startsWith(`${gsdHomeNorm}/`)) {

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

@@ -4,6 +4,7 @@ import { existsSync, lstatSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { join, resolve } from "node:path";
 import { normalizeWorktreePathForCompare } from "./worktree-root.js";
+import { worktreesDirs } from "./worktree-placement.js";
 import { listWorktrees } from "./worktree-manager.js";
 import { getCurrentBranch } from "./worktree.js";
 const fsOnlyDeps = {
@@ -59,15 +60,17 @@ export function createWorktreeSafetyModule(deps = defaultDeps) {
             const projectRoot = resolve(input.projectRoot);
             const unitRoot = resolve(input.unitRoot);
             const isolationMode = input.isolationMode ?? "worktree";
-            const expectedRoot = isolationMode === "worktree"
-                ? join(projectRoot, ".gsd", "worktrees", milestoneId)
-                : projectRoot;
-            if (!samePath(unitRoot, expectedRoot)) {
+            // A milestone worktree may live in the canonical container or the
+            // legacy one (pre-placement-change worktrees keep their location).
+            const expectedRoots = isolationMode === "worktree"
+                ? worktreesDirs(projectRoot).map((dir) => join(dir, milestoneId))
+                : [projectRoot];
+            if (!expectedRoots.some((expectedRoot) => samePath(unitRoot, expectedRoot))) {
                 return failure("invalid-root", isolationMode === "worktree"
                     ? `Unit root ${unitRoot} is not the expected worktree root for ${milestoneId}.`
                     : `Unit root ${unitRoot} is not the project root while isolation mode is ${isolationMode}.`, isolationMode === "worktree"
                     ? "Prepare the Unit in its canonical milestone worktree before allowing source writes."
-                    : "Run the Unit from the project root when worktree isolation is disabled.", { expectedRoot, unitRoot });
+                    : "Run the Unit from the project root when worktree isolation is disabled.", { expectedRoot: expectedRoots[0], unitRoot });
             }
             if (!deps.existsSync(unitRoot)) {
                 return failure("worktree-missing", `Worktree root ${unitRoot} does not exist.`, "Create or recover the milestone worktree before dispatching the source-writing Unit.", { unitRoot });
@@ -87,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-session-state.js

@@ -1,4 +1,5 @@
 // GSD worktree session state
+import { findWorktreeSegment, projectRootFromWorktreePath } from "./worktree-root.js";
 let originalCwd = null;
 export function getWorktreeOriginalCwd() {
     return originalCwd;
@@ -12,22 +13,22 @@ export function clearWorktreeOriginalCwd() {
 export function ensureWorktreeOriginalCwdFromPath(cwd = process.cwd()) {
     if (originalCwd)
         return originalCwd;
-    const marker = `${/\\/.test(cwd) ? "\\" : "/"}.gsd${/\\/.test(cwd) ? "\\" : "/"}worktrees${/\\/.test(cwd) ? "\\" : "/"}`;
-    const markerIdx = cwd.indexOf(marker);
-    if (markerIdx !== -1) {
-        originalCwd = cwd.slice(0, markerIdx);
-    }
+    const root = projectRootFromWorktreePath(cwd);
+    if (root)
+        originalCwd = root;
     return originalCwd;
 }
 export function getActiveWorktreeName() {
     if (!originalCwd)
         return null;
-    const cwd = process.cwd();
-    const wtDir = `${originalCwd.replace(/[\\/]+$/, "")}/.gsd/worktrees`.replaceAll("\\", "/");
-    const normalizedCwd = cwd.replaceAll("\\", "/");
-    if (!normalizedCwd.startsWith(`${wtDir}/`))
+    const normalizedCwd = process.cwd().replaceAll("\\", "/");
+    const normalizedOriginal = originalCwd.replace(/[\\/]+$/, "").replaceAll("\\", "/");
+    const segment = findWorktreeSegment(normalizedCwd);
+    if (!segment)
         return null;
-    const rel = normalizedCwd.slice(wtDir.length + 1);
-    const name = rel.split("/")[0];
+    // Only treat the cwd as an active worktree of OUR project root.
+    if (normalizedCwd.slice(0, segment.gsdIdx) !== normalizedOriginal)
+        return null;
+    const name = normalizedCwd.slice(segment.afterWorktrees).split("/")[0];
     return name || null;
 }

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

@@ -214,9 +214,11 @@ export function registerNativeSearchHooks(pi) {
             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/dist/resources/extensions/shared/browser-contract.js

@@ -0,0 +1,59 @@
+// 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",
+];
+const BROWSER_CONTRACT_TOOL_NAME_SET = new Set(BROWSER_CONTRACT_TOOL_NAMES);
+export function isBrowserContractToolName(name) {
+    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) {
+    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",
+];

package/dist/resources/extensions/shared/gsd-browser-cli.js

@@ -38,6 +38,28 @@ 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);
+}
+function resolveExplicitGsdBrowserCliPath(env) {
+    return env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim() || undefined;
+}
 function resolveBundledGsdBrowserPackageVersion() {
     try {
         const requireFromHere = createRequire(import.meta.url);
@@ -49,12 +71,20 @@ function resolveBundledGsdBrowserPackageVersion() {
         return 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;
 function resolvePathGsdBrowserVersion(env) {
     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"],
@@ -62,8 +92,9 @@ function resolvePathGsdBrowserVersion(env) {
         }));
     }
     catch {
-        return null;
+        cachedPathProbeVersion = null;
     }
+    return cachedPathProbeVersion;
 }
 function shouldPreferPathGsdBrowser(env) {
     const pathVersion = resolvePathGsdBrowserVersion(env);
@@ -73,7 +104,7 @@ function shouldPreferPathGsdBrowser(env) {
     return !bundledVersion || compareSemverLocal(pathVersion, bundledVersion) > 0;
 }
 export function resolveBundledGsdBrowserCliPath(env = process.env) {
-    const explicit = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim();
+    const explicit = resolveExplicitGsdBrowserCliPath(env);
     if (explicit)
         return explicit;
     try {
@@ -96,6 +127,36 @@ export function resolveBundledGsdBrowserCliPath(env = process.env) {
     }
     return null;
 }
+/**
+ * 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 = process.env) {
+    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, suffix) {
     const resolvedProjectRoot = resolve(projectRoot);
     const base = sanitizeSessionSegment(basename(resolvedProjectRoot)) || "project";
@@ -103,13 +164,38 @@ export function buildGsdBrowserSessionName(projectRoot, suffix) {
     const cleanSuffix = suffix ? sanitizeSessionSegment(suffix) : "";
     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) {
+    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) => typeof arg === "string") : [];
+    return args.some((arg) => arg.includes("gsd-browser") || arg.includes("@opengsd/gsd-browser"));
+}
 export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env, options = {}) {
     const resolvedProjectRoot = resolve(projectRoot);
     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 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)
@@ -119,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)
@@ -127,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",
@@ -136,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 {
@@ -149,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 } : {}),
+    };
+}