@opengsd/gsd-pi 1.2.0-dev.5457a158 → 1.2.0-dev.84c56d87

package/dist/resources/extensions/browser-tools/index.js

@@ -1,7 +1,7 @@
 /** browser-tools — Pi Browser Automation Contract adapter. */
 import { importExtensionModule } from "@gsd/pi-coding-agent";
 import { closeManagedGsdBrowser, registerManagedGsdBrowserTools, warmUpManagedGsdBrowser } from "./engine/managed-gsd-browser.js";
-import { resolveBrowserEngineMode } from "./engine/selection.js";
+import { commitBrowserEngineResolution, resolveAmbientBrowserEngineResolution } from "./engine/selection.js";
 import { setArtifactRootForCwd } from "./state.js";
 import { detectWebApp } from "./web-app-detect.js";
 let legacyRegistrationPromise = null;
@@ -130,12 +130,56 @@ function withBrowserArtifactCwdScope(pi) {
         },
     };
 }
-async function registerBrowserTools(pi) {
-    const engine = resolveBrowserEngineMode();
+/** Daemon-connect budget when the probe-resolved managed engine is verified at session start. */
+const PROBE_WARMUP_TIMEOUT_MS = 10_000;
+async function registerBrowserTools(pi, ctx) {
+    const projectRoot = ctx.cwd || process.cwd();
+    const resolution = resolveAmbientBrowserEngineResolution(projectRoot);
+    let engine = resolution.engine;
     if (engine === "off")
         return;
+    // A probe-resolved managed engine is only a prediction that gsd-browser
+    // works — prove it by connecting the daemon before committing the session's
+    // tool registrations to it. Connect failure falls back to legacy Playwright
+    // (the failure mode that made ADR-024 freeze the old default) and commits
+    // the outcome so ambient readers see the engine actually in use. When eager
+    // warm-up is disabled the daemon-connect proof cannot run, so the probe
+    // default treats the managed engine as unprovable and falls back to legacy
+    // rather than registering it unverified. An explicit
+    // GSD_BROWSER_ENGINE=gsd-browser override skips the gate and is honored
+    // verbatim, matching prior behavior.
+    if (engine === "gsd-browser" && resolution.source === "probe" && !registeredEngine) {
+        if (isWarmUpDisabled()) {
+            engine = commitLegacyFallback(projectRoot, "warm-up disabled; managed engine unverifiable; using legacy Playwright");
+        }
+        else {
+            const warmUp = await warmUpManagedGsdBrowser(ctx, AbortSignal.timeout(PROBE_WARMUP_TIMEOUT_MS));
+            if (!warmUp.ok) {
+                engine = commitLegacyFallback(projectRoot, `gsd-browser daemon connect failed (${warmUp.error}); using legacy Playwright`);
+                if (ctx.hasUI) {
+                    ctx.ui.notify(`gsd-browser engine unavailable (${warmUp.error}); using Playwright browser tools for this session.`, "warning");
+                }
+            }
+            else if (warmUp.coverageWarning && ctx.hasUI) {
+                ctx.ui.notify(warmUp.coverageWarning, "warning");
+            }
+        }
+    }
+    // Browser tool registrations are process-global and cannot be swapped once
+    // live. When an earlier session in this process already registered an engine
+    // and this project resolved a different one (per-project probe resolution can
+    // diverge across projects in a multi-session process), adopt the registered
+    // engine rather than throwing — a throw surfaces as "browser-tools failed to
+    // load" and leaves this session with no browser tools at all. Commit the
+    // adoption so ambient readers (UAT guidance, warm-up) describe the engine
+    // actually in use.
     if (registeredEngine && registeredEngine !== engine) {
-        throw new Error(`Browser tools already registered with GSD_BROWSER_ENGINE=${registeredEngine}. Restart GSD before switching to ${engine}.`);
+        engine = registeredEngine;
+        commitBrowserEngineResolution(projectRoot, {
+            engine,
+            source: "probe",
+            reason: `browser tools already registered with ${engine} earlier in this process; adopting it`,
+        });
     }
     let registration;
     if (engine === "legacy") {
@@ -165,27 +209,40 @@ async function registerBrowserTools(pi) {
         throw error;
     }
 }
+function commitLegacyFallback(projectRoot, reason) {
+    commitBrowserEngineResolution(projectRoot, { engine: "legacy", source: "probe", reason });
+    return "legacy";
+}
 function isWarmUpDisabled() {
     const value = process.env.GSD_BROWSER_WARMUP?.trim().toLowerCase();
     return value === "0" || value === "false" || value === "off";
 }
 /**
- * Auto-initialize the managed gsd-browser engine only when explicitly selected
- * for a web app. Best-effort and non-blocking: warm-up runs in the background
- * and only surfaces a warning if it fails.
+ * Auto-initialize the managed gsd-browser engine when it was selected via the
+ * explicit GSD_BROWSER_ENGINE override, which registers without the
+ * daemon-connect gate. Best-effort and non-blocking: warm-up runs in the
+ * background and only surfaces a warning if it fails. Probe-resolved sessions
+ * already connected (or fell back) during registration, so they are excluded
+ * to avoid re-warming and double-notifying.
  */
 function maybeWarmUpManagedEngine(pi, ctx) {
     if (isWarmUpDisabled())
         return;
-    if (resolveBrowserEngineMode() !== "gsd-browser")
-        return;
     const projectRoot = ctx.cwd || process.cwd();
+    const resolution = resolveAmbientBrowserEngineResolution(projectRoot);
+    if (resolution.engine !== "gsd-browser" || resolution.source !== "env")
+        return;
     if (!detectWebApp(projectRoot))
         return;
     void warmUpManagedGsdBrowser(ctx).then((result) => {
-        if (!result.ok && ctx.hasUI) {
+        if (!ctx.hasUI)
+            return;
+        if (!result.ok) {
             ctx.ui.notify(`gsd-browser auto-init failed: ${result.error}. Browser UAT tools will retry on first use; run /gsd doctor if this persists.`, "warning");
         }
+        else if (result.coverageWarning) {
+            ctx.ui.notify(result.coverageWarning, "warning");
+        }
     });
 }
 async function closeActiveBrowserEngines() {
@@ -198,14 +255,14 @@ async function closeActiveBrowserEngines() {
 export default function (pi) {
     pi.on("session_start", async (_event, ctx) => {
         if (ctx.hasUI) {
-            void registerBrowserTools(pi)
+            void registerBrowserTools(pi, ctx)
                 .then(() => maybeWarmUpManagedEngine(pi, ctx))
                 .catch((error) => {
                 ctx.ui.notify(`browser-tools failed to load: ${error instanceof Error ? error.message : String(error)}`, "warning");
             });
             return;
         }
-        await registerBrowserTools(pi);
+        await registerBrowserTools(pi, ctx);
         maybeWarmUpManagedEngine(pi, ctx);
     });
     pi.on("session_shutdown", async () => {

package/dist/resources/extensions/claude-code-cli/stream-adapter.js

@@ -25,6 +25,7 @@ import { markInteractiveElicitationStart, markInteractiveElicitationEnd, } from
 import { discoverBrowserMcpServerName, discoverMcpServers, discoverMcpServerNames, discoverUserMcpServerNames, discoverWorkflowMcpServerName, computeMcpDisallowedTools, } from "../gsd/mcp-filter.js";
 import { RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES, RUN_UAT_FORBIDDEN_TOOL_NAMES, RUN_UAT_WORKFLOW_TOOL_NAMES, resolveToolPresentationPlan } from "../gsd/tool-presentation-plan.js";
 import { getToolSurfaceReadinessError } from "../gsd/tool-surface-readiness.js";
+import { hasBrowserContractPrefix } from "../shared/browser-contract.js";
 import { showInterviewRound } from "../shared/tui.js";
 export { buildFinalAssistantContent, extractToolResultsFromSdkUserMessage, handleClaudeCodePartialStreamEvent, mergePendingToolCalls, } from "./turn-assembler.js";
 export function serverToolUseToToolCallLike(block) {
@@ -1290,7 +1291,7 @@ function browserMcpServerNameFromAllowedTools(allowedTools) {
         const parsed = parseAllowedMcpToolName(toolName);
         if (!parsed)
             continue;
-        if (parsed.server === "gsd-browser" || parsed.tool.startsWith("browser_")) {
+        if (parsed.server === "gsd-browser" || hasBrowserContractPrefix(parsed.tool)) {
             return parsed.server;
         }
     }
@@ -1304,7 +1305,7 @@ function workflowMcpServerNameFromAllowedTools(allowedTools) {
         if (typeof toolName !== "string")
             continue;
         const parsed = parseAllowedMcpToolName(toolName);
-        if (!parsed || parsed.server === browserServerName || parsed.tool.startsWith("browser_"))
+        if (!parsed || parsed.server === browserServerName || hasBrowserContractPrefix(parsed.tool))
             continue;
         return parsed.server;
     }

package/dist/resources/extensions/gsd/bootstrap/register-extension.js

@@ -13,6 +13,7 @@ import { registerHooks } from "./register-hooks.js";
 import { registerShortcuts } from "./register-shortcuts.js";
 import { writeCrashLog } from "./crash-log.js";
 import { logWarning } from "../workflow-logger.js";
+import { UNIT_TOOL_CONTRACTS } from "../unit-tool-contracts.js";
 // Static import so cmux event listeners are registered synchronously during
 // extension bootstrap. Prior implementation used `void import().then()` which
 // queued listener registration as a microtask — any CMUX_CHANNELS emit fired
@@ -30,6 +31,9 @@ const EPIPE_STORM_THRESHOLD = 100;
 const EPIPE_STORM_WINDOW_MS = 10_000;
 let epipeCount = 0;
 let epipeWindowStart = 0;
+export const CRITICAL_GSD_WORKFLOW_TOOL_NAMES = [...new Set(Object.values(UNIT_TOOL_CONTRACTS)
+        .flatMap((contract) => contract.requiredWorkflowTools)
+        .filter((toolName) => toolName.startsWith("gsd_")))].sort();
 /** Write to stderr without ever re-throwing — stderr can EPIPE too, which would
  *  re-enter this handler and re-loop. */
 function safeStderr(msg) {
@@ -121,6 +125,20 @@ export function installEpipeGuard() {
         process.on("unhandledRejection", _gsdRejectionGuard);
     }
 }
+function assertCriticalGsdWorkflowToolsRegistered(pi) {
+    if (typeof pi.getAllTools !== "function")
+        return;
+    const registered = new Set(pi.getAllTools().map((tool) => tool.name));
+    const missing = CRITICAL_GSD_WORKFLOW_TOOL_NAMES.filter((toolName) => !registered.has(toolName));
+    if (missing.length === 0)
+        return;
+    const message = [
+        `Critical GSD workflow tool registration failed; missing required tool(s): ${missing.join(", ")}.`,
+        "Check earlier bootstrap warnings for the registration slot that failed.",
+    ].join(" ");
+    logWarning("bootstrap", message);
+    throw new Error(message);
+}
 export function registerGsdExtension(pi) {
     // Note: registerGSDCommand is called by index.ts before this function,
     // so we intentionally skip it here to avoid double-registration.
@@ -186,4 +204,5 @@ export function registerGsdExtension(pi) {
             logWarning("bootstrap", `Failed to register ${name}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    assertCriticalGsdWorkflowToolsRegistered(pi);
 }

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -32,12 +32,14 @@ import { applyUnitSkillVisibility, unitHasSkillManifest } from "../skill-scope.j
 import { getGuidedUnitContext } from "../guided-unit-context.js";
 import { registerPlanMilestoneSchemaRecovery } from "./plan-milestone-schema-recovery.js";
 import { AUTO_UNIT_SCOPED_TOOLS, RUN_UAT_BROWSER_TOOL_NAMES, canonicalWorkflowToolName, isWorkflowAliasTool } from "../auto-unit-tool-scope.js";
+import { hasBrowserContractPrefix } from "../../shared/browser-contract.js";
 import { filterToolsForProvider } from "../model-router.js";
 import { mcpToolMatchesBaseName } from "../mcp-tool-name.js";
 import { RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_WORKFLOW_TOOL_NAMES } from "../tool-presentation-plan.js";
 import { supportsSourceObservationsForUnit } from "../source-observations.js";
 import { clearPendingAutoStart } from "../pending-auto-start.js";
 import { resolveWorkflowToolBasePath } from "./dynamic-tools.js";
+import { getRequiredWorkflowToolsForUnit } from "../unit-tool-contracts.js";
 let approvalQuestionAbortInFlight = false;
 async function loadWelcomeScreenModule() {
     const candidates = [];
@@ -140,7 +142,7 @@ function withPreservedShimTools(toolNames) {
 }
 /** True for the browser automation tools (browser_navigate, browser_click, ...). */
 function isBrowserTool(toolName) {
-    return canonicalToolName(toolName).startsWith("browser_");
+    return hasBrowserContractPrefix(canonicalToolName(toolName));
 }
 /**
  * True when any message in the request is driven by a GSD workflow command
@@ -202,7 +204,7 @@ export function buildMinimalGsdToolSet(activeToolNames) {
     const minimal = resolveScopedToolNames(activeToolNames, MINIMAL_GSD_TOOL_NAMES);
     return withPreservedShimTools([...new Set([...preserved, ...minimal])]);
 }
-export function buildMinimalAutoGsdToolSet(activeToolNames, unitType, registeredToolNames = activeToolNames) {
+export function buildMinimalAutoGsdToolSet(activeToolNames, unitType, registeredToolNames = activeToolNames, warnOnUnresolvedRequiredTools = registeredToolNames !== activeToolNames) {
     if (unitType === "run-uat") {
         return buildRunUatGsdToolSet(activeToolNames, registeredToolNames);
     }
@@ -214,7 +216,20 @@ export function buildMinimalAutoGsdToolSet(activeToolNames, unitType, registered
             ...availableBaseTools,
         ])];
     const scoped = resolveScopedToolNames([...activeToolNames, ...registeredToolNames], [...MINIMAL_GSD_TOOL_NAMES, ...unitTools]);
-    return withPreservedShimTools([...new Set([...preserved, ...scoped])]);
+    const result = withPreservedShimTools([...new Set([...preserved, ...scoped])]);
+    warnIfRequiredWorkflowToolsUnresolved(unitType, result, warnOnUnresolvedRequiredTools);
+    return result;
+}
+function hasResolvedWorkflowTool(resolvedToolNames, requiredToolName) {
+    return resolvedToolNames.some((name) => name === requiredToolName || mcpToolMatchesBaseName(name, requiredToolName));
+}
+function warnIfRequiredWorkflowToolsUnresolved(unitType, scopedToolNames, shouldWarn) {
+    if (!unitType || !shouldWarn)
+        return;
+    const unresolved = getRequiredWorkflowToolsForUnit(unitType).filter((toolName) => !hasResolvedWorkflowTool(scopedToolNames, toolName));
+    if (unresolved.length === 0)
+        return;
+    safetyLogWarning("bootstrap", `buildMinimalAutoGsdToolSet(${unitType}): required workflow tool(s) not in active/registered surface after scoping: ${unresolved.join(", ")}. Tool registration may have partially failed, provider filtering may have removed a required tool, or workflow MCP may be disconnected.`);
 }
 export function buildRunUatGsdToolSet(activeToolNames, registeredToolNames = activeToolNames) {
     const scoped = resolveScopedToolNames([...activeToolNames, ...registeredToolNames], [
@@ -240,7 +255,7 @@ export function buildMinimalGsdWorkflowToolSet(activeToolNames, registeredToolNa
     const scoped = resolveScopedToolNames([...activeToolNames, ...registeredToolNames], WORKFLOW_GSD_TOOL_NAMES);
     return withPreservedShimTools([...new Set([...preserved, ...scoped])]);
 }
-export function buildRequestScopedGsdToolSet(activeToolNames, requestCustomMessages, registeredToolNames = activeToolNames, guidedUnitType) {
+export function buildRequestScopedGsdToolSet(activeToolNames, requestCustomMessages, registeredToolNames = activeToolNames, guidedUnitType, warnOnUnresolvedRequiredTools = registeredToolNames !== activeToolNames) {
     for (let index = (requestCustomMessages?.length ?? 0) - 1; index >= 0; index--) {
         const currentCustomType = requestCustomMessages?.[index]?.customType;
         if (currentCustomType === "gsd-run" ||
@@ -248,7 +263,7 @@ export function buildRequestScopedGsdToolSet(activeToolNames, requestCustomMessa
             currentCustomType === "gsd-doctor-heal" ||
             currentCustomType === "gsd-triage") {
             if (guidedUnitType) {
-                return buildMinimalAutoGsdToolSet(activeToolNames, guidedUnitType, registeredToolNames);
+                return buildMinimalAutoGsdToolSet(activeToolNames, guidedUnitType, registeredToolNames, warnOnUnresolvedRequiredTools);
             }
             return buildMinimalGsdWorkflowToolSet(activeToolNames, registeredToolNames);
         }
@@ -282,8 +297,9 @@ function applyMinimalGsdToolSurface(pi) {
     const dash = getAutoRuntimeSnapshot();
     if (dash.active && dash.currentUnit) {
         const currentToolNames = pi.getActiveTools();
+        const hasRegisteredSurface = typeof pi.getAllTools === "function";
         const registeredToolNames = resolveRegisteredToolNames(pi, currentToolNames);
-        const scopedToolNames = buildMinimalAutoGsdToolSet(currentToolNames, dash.currentUnit.type, registeredToolNames);
+        const scopedToolNames = buildMinimalAutoGsdToolSet(currentToolNames, dash.currentUnit.type, registeredToolNames, hasRegisteredSurface);
         recordAutoToolSurfaceSnapshot({
             source: "runtime-scope",
             unitType: dash.currentUnit.type,
@@ -302,9 +318,10 @@ export function scopeGsdWorkflowToolsForDispatch(pi, unitType) {
     if (isFullGsdToolSurfaceRequested())
         return null;
     const current = pi.getActiveTools();
+    const hasRegisteredSurface = typeof pi.getAllTools === "function";
     const registeredToolNames = resolveRegisteredToolNames(pi, current);
     const scoped = unitType
-        ? buildMinimalAutoGsdToolSet(current, unitType, registeredToolNames)
+        ? buildMinimalAutoGsdToolSet(current, unitType, registeredToolNames, hasRegisteredSurface)
         : buildMinimalGsdWorkflowToolSet(current, registeredToolNames);
     recordAutoToolSurfaceSnapshot({
         source: "dispatch-scope",
@@ -1303,12 +1320,13 @@ export function registerHooks(pi, ecosystemHandlers) {
             return surfaceReduced ? { toolNames: providerCompatible } : undefined;
         }
         const registeredToolNames = resolveRegisteredToolNames(pi, event.activeToolNames);
+        const hasRegisteredSurface = typeof pi.getAllTools === "function";
         const compatibleRegisteredToolNames = filterToolsForProvider(registeredToolNames, event.selectedModelApi, event.selectedModelProvider).compatible.filter((name) => !(dropAliases && isWorkflowAliasTool(name)));
         const guidedUnit = getGuidedUnitContext();
         const requestRegisteredToolNames = guidedUnit?.unitType === "run-uat"
             ? compatibleRegisteredToolNames
             : registeredToolNames;
-        const requestScoped = buildRequestScopedGsdToolSet(guidedUnit?.unitType === "run-uat" ? aliasFilteredCompatible : providerCompatible, event.requestCustomMessages, requestRegisteredToolNames, guidedUnit?.unitType);
+        const requestScoped = buildRequestScopedGsdToolSet(guidedUnit?.unitType === "run-uat" ? aliasFilteredCompatible : providerCompatible, event.requestCustomMessages, requestRegisteredToolNames, guidedUnit?.unitType, hasRegisteredSurface);
         if (requestScoped) {
             recordAutoToolSurfaceSnapshot({
                 source: "provider-adjustment",
@@ -1324,7 +1342,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             const registeredForUnit = dash.currentUnit.type === "run-uat"
                 ? compatibleRegisteredToolNames
                 : resolveRegisteredToolNames(pi, event.activeToolNames);
-            const scopedToolNames = buildMinimalAutoGsdToolSet(dash.currentUnit.type === "run-uat" ? aliasFilteredCompatible : providerCompatible, dash.currentUnit.type, registeredForUnit);
+            const scopedToolNames = buildMinimalAutoGsdToolSet(dash.currentUnit.type === "run-uat" ? aliasFilteredCompatible : providerCompatible, dash.currentUnit.type, registeredForUnit, hasRegisteredSurface);
             recordAutoToolSurfaceSnapshot({
                 source: "provider-adjustment",
                 unitType: dash.currentUnit.type,

package/dist/resources/extensions/gsd/browser-evidence.js

@@ -1,8 +1,14 @@
 // Project/App: gsd-pi
 // File Purpose: Shared browser-observable UAT requirement and evidence detection.
-export const BROWSER_REQUIREMENT_RE = /\b(?:file:\/\/|localhost|playwright|chrome|screenshot|snapshot|browser_(?:assert|batch|find|verify|snapshot_refs))\b|\b(?:open|launch|navigate|load|visit|serve|start)\b.{0,80}\b(?:browser|page|localhost|file:\/\/)\b|\bbrowser\s+(?:check|session|test|uat|tool|automation|interaction|flow)\b/i;
+import { BROWSER_EVIDENCE_SIGNAL_TOOL_NAMES } from "../shared/browser-contract.js";
+// Alternation fragment over the contract's evidence-signal names, e.g.
+// `browser_(?:assert|batch|...)`. The names are `browser_`-prefixed
+// identifiers (pinned by tests/browser-contract.test.ts), so no escaping is
+// needed.
+const BROWSER_TOOL_SIGNAL = `browser_(?:${BROWSER_EVIDENCE_SIGNAL_TOOL_NAMES.map((name) => name.slice("browser_".length)).join("|")})`;
+export const BROWSER_REQUIREMENT_RE = new RegExp(String.raw `\b(?:file://|localhost|playwright|chrome|screenshot|snapshot|${BROWSER_TOOL_SIGNAL})\b|\b(?:open|launch|navigate|load|visit|serve|start)\b.{0,80}\b(?:browser|page|localhost|file://)\b|\bbrowser\s+(?:check|session|test|uat|tool|automation|interaction|flow)\b`, "i");
 export const NO_BROWSER_EVIDENCE_RE = /\b(?:no|without|not|wasn'?t|isn'?t)\s+(?:automated\s+)?(?:live\s+)?browser(?:\s+(?:session|test|uat))?|\bno\s+automated\s+browser\b|\bnot\s+conducted\b/i;
-export const BROWSER_RUNTIME_RE = /\b(?:browser|playwright|chrome|camoufox|browser_(?:assert|batch|find|verify|snapshot_refs)|screenshot|snapshot|file:\/\/|localhost)\b/i;
+export const BROWSER_RUNTIME_RE = new RegExp(String.raw `\b(?:browser|playwright|chrome|camoufox|${BROWSER_TOOL_SIGNAL}|screenshot|snapshot|file://|localhost)\b`, "i");
 export const BROWSER_ACTION_RE = /\b(?:open(?:ed)?|navigate(?:d)?|click(?:ed)?|type(?:d)?|reload(?:ed)?|capture(?:d)?|screenshot|snapshot)\b/i;
 export const BROWSER_ASSERTION_RE = /\b(?:assert(?:ed|ion)?|observed|confirmed|verified|expected|visible|text|count|label|strikethrough|localstorage|screenshot|snapshot|passed)\b/i;
 const NON_REQUIREMENT_BROWSER_HEADING_RE = /^(?:not\s+proven|not\s+covered|out\s+of\s+scope|deferred|follow-?ups?|known\s+limitations|notes\s+for\s+tester)\b/i;

package/dist/resources/extensions/gsd/mcp-filter.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import { isGsdBrowserMcpServerConfig } from "../shared/gsd-browser-cli.js";
 import { toMcpWildcardToolName } from "./mcp-tool-name.js";
 import { resolveModelMcpConfig } from "./preferences-mcp.js";
 function isRecord(value) {
@@ -63,29 +64,11 @@ function isWorkflowMcpServerConfig(config) {
     const args = Array.isArray(config.args) ? config.args.filter((arg) => typeof arg === "string") : [];
     return args.some((arg) => arg.includes("gsd-mcp-server") || arg.includes("packages/mcp-server"));
 }
-function isBrowserMcpServerConfig(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;
-    }
-    const env = config.env;
-    if (isRecord(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 discoverWorkflowMcpServerName(projectDir) {
     return discoverMcpServers(projectDir).find((server) => isWorkflowMcpServerConfig(server.config))?.name;
 }
 export function discoverBrowserMcpServerName(projectDir) {
-    return discoverMcpServers(projectDir).find((server) => isBrowserMcpServerConfig(server.config))?.name;
+    return discoverMcpServers(projectDir).find((server) => isGsdBrowserMcpServerConfig(server.config))?.name;
 }
 export function discoverMcpServerNames(projectDir) {
     return discoverMcpServers(projectDir).map((server) => server.name);

package/dist/resources/extensions/gsd/uat-policy.js

@@ -1,5 +1,6 @@
 // Project/App: gsd-pi
 // File Purpose: Central UAT mode policy for dispatch, tool presentation, and result validation.
+import { hasBrowserContractPrefix } from "../shared/browser-contract.js";
 import { extractUatType } from "./files.js";
 import { hasBrowserRequiredText } from "./browser-evidence.js";
 import { parseMcpToolName } from "./mcp-tool-name.js";
@@ -84,7 +85,7 @@ export function uatTypeIncludesBrowser(uatType) {
 export function isUatBrowserToolName(toolName) {
     const parsed = parseMcpToolName(toolName);
     const canonicalName = parsed?.toolName ?? toolName;
-    if (canonicalName.startsWith("browser_"))
+    if (hasBrowserContractPrefix(canonicalName))
         return true;
     return parsed?.toolName === "*" && parsed.serverName.toLowerCase().includes("browser");
 }

package/dist/resources/extensions/gsd/unit-registry.js

@@ -22,6 +22,7 @@
 // (`UNIT_MANIFESTS` stays in unit-context-manifest.ts, already type-enforced
 // against the registry's `UnitType`) and prompt-template association (still
 // implicit in auto-prompts.ts builders).
+import { BROWSER_CONTRACT_TOOL_NAMES } from "../shared/browser-contract.js";
 // ─── Shared tool-name constants (used by registry rows) ──────────────────
 export const RUN_UAT_WORKFLOW_TOOL_NAMES = [
     "gsd_uat_exec",
@@ -37,26 +38,12 @@ export const RUN_UAT_READ_ONLY_TOOL_NAMES = [
     "ls",
     "read",
 ];
-export const RUN_UAT_BROWSER_TOOL_NAMES = [
-    "browser_navigate",
-    "browser_click",
-    "browser_type",
-    "browser_fill_form",
-    "browser_click_ref",
-    "browser_fill_ref",
-    "browser_wait_for",
-    "browser_assert",
-    "browser_verify",
-    "browser_screenshot",
-    "browser_snapshot_refs",
-    "browser_find",
-    "browser_get_console_logs",
-    "browser_get_network_logs",
-    "browser_evaluate",
-    "browser_reload",
-    "browser_batch",
-    "browser_act",
-];
+/**
+ * Browser tools presented to run-uat. A derived view of the Browser Automation
+ * Contract vocabulary (shared/browser-contract.ts) — the contract module is the
+ * only place browser tool names are declared.
+ */
+export const RUN_UAT_BROWSER_TOOL_NAMES = BROWSER_CONTRACT_TOOL_NAMES;
 // ─── The registry ─────────────────────────────────────────────────────────
 export const UNIT_REGISTRY = {
     "research-milestone": {

package/dist/resources/extensions/gsd/web-app-uat.js

@@ -1,8 +1,10 @@
 // Project/App: gsd-pi
-// File Purpose: Web-app detection and Playwright/UAT guidance for planning and slice closeout.
+// File Purpose: Web-app detection and browser-UAT guidance for planning and slice closeout.
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { resolveAmbientBrowserEngineResolution } from "../browser-tools/engine/selection.js";
 import { detectWebApp } from "../browser-tools/web-app-detect.js";
+import { UAT_MODE_POLICIES } from "./uat-policy.js";
 export { detectWebApp };
 function readPackageJson(projectRoot) {
     const packageJsonPath = resolve(projectRoot, "package.json");
@@ -39,24 +41,56 @@ export function findPlaywrightTestScript(projectRoot) {
     }
     return null;
 }
+function describeBrowserToolBacking(engineResolution) {
+    switch (engineResolution.engine) {
+        case "gsd-browser":
+            return "This project looks browser-facing. GSD exposes `browser_*` tools backed by the managed gsd-browser engine for run-uat.";
+        case "legacy":
+            return "This project looks browser-facing. GSD exposes Playwright-backed `browser_*` tools for run-uat.";
+        case "off":
+            return "This project looks browser-facing, but Pi browser tools are disabled (GSD_BROWSER_ENGINE=off) — prefer `runtime-executable` UAT with automated browser test commands.";
+    }
+}
+// One bullet per recommended UAT mode; `mode` keys into UAT_MODE_POLICIES so
+// modes that require browser tools drop out of the guidance when the resolved
+// engine provides none (mixed/live-runtime share one bullet and one policy bit).
+const UAT_MODE_GUIDANCE = [
+    {
+        mode: "browser-executable",
+        bullet: "- `browser-executable` — navigate to `http://localhost:…`, click, screenshot, assert via `browser_*` tools during run-uat",
+    },
+    {
+        mode: "runtime-executable",
+        bullet: "- `runtime-executable` — run an automated browser test command via `gsd_uat_exec` (for example `npx playwright test`)",
+    },
+    {
+        mode: "mixed",
+        bullet: "- `mixed` / `live-runtime` — combine runtime startup checks with interactive browser verification",
+    },
+];
 /**
  * Markdown block injected into plan/complete-slice prompts when the project
- * looks browser-facing. Returns null for CLI/library-only repos.
+ * looks browser-facing. Returns null for CLI/library-only repos. Guidance is
+ * composed from the resolved Browser Automation Engine so prompts never claim
+ * an engine the runtime is not using; `engineResolution` is injectable for
+ * tests and defaults to the ambient resolution.
  */
-export function buildWebAppUatGuidanceBlock(projectRoot) {
+export function buildWebAppUatGuidanceBlock(projectRoot, engineResolution) {
     if (!detectWebApp(projectRoot))
         return null;
+    const resolvedEngine = engineResolution ?? resolveAmbientBrowserEngineResolution(projectRoot);
+    const browserToolsAvailable = resolvedEngine.engine !== "off";
     const playwrightScript = findPlaywrightTestScript(projectRoot);
     const hasPlaywright = hasPlaywrightTestDependency(projectRoot) || playwrightScript !== null;
     const lines = [
         "### Web App UAT (detected)",
         "",
-        "This project looks browser-facing. GSD exposes Playwright-backed `browser_*` tools by default for run-uat.",
+        describeBrowserToolBacking(resolvedEngine),
         "",
         "**UAT modes (pick one per slice — do not use `artifact-driven` for browser steps):**",
-        "- `browser-executable` — navigate to `http://localhost:…`, click, screenshot, assert via `browser_*` tools during run-uat",
-        "- `runtime-executable` — run an automated browser test command via `gsd_uat_exec` (for example `npx playwright test`)",
-        "- `mixed` / `live-runtime` — combine runtime startup checks with interactive browser verification",
+        ...UAT_MODE_GUIDANCE
+            .filter(({ mode }) => browserToolsAvailable || !UAT_MODE_POLICIES[mode].browserTools)
+            .map(({ bullet }) => bullet),
         "",
         "**Planning / closeout rules:**",
         "- Preconditions must name the dev-server command and URL (for example `npm run dev` → `http://localhost:3000`)",
@@ -74,7 +108,10 @@ export function buildWebAppUatGuidanceBlock(projectRoot) {
         lines.push("- Name concrete spec paths in slice Verification (for example `e2e/smoke.spec.ts`)");
     }
     else {
-        lines.push("", "**Playwright scaffolding (first UI slice):** no `playwright` / `@playwright/test` dependency yet.", "- Add a planning task that installs Playwright, adds `playwright.config.ts`, and creates a minimal smoke spec (for example `e2e/smoke.spec.ts`)", "- Task `verify` should run `npx playwright test` (or the focused spec) with a safe, simple command", "- Until specs exist, use `browser-executable` UAT with localhost preconditions and interactive `browser_*` checks at slice closeout");
+        lines.push("", "**Playwright scaffolding (first UI slice):** no `playwright` / `@playwright/test` dependency yet.", "- Add a planning task that installs Playwright, adds `playwright.config.ts`, and creates a minimal smoke spec (for example `e2e/smoke.spec.ts`)", "- Task `verify` should run `npx playwright test` (or the focused spec) with a safe, simple command");
+        if (browserToolsAvailable) {
+            lines.push("- Until specs exist, use `browser-executable` UAT with localhost preconditions and interactive `browser_*` checks at slice closeout");
+        }
     }
     return lines.join("\n");
 }

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",
+];