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

package/src/resources/extensions/browser-tools/engine/selection.ts

@@ -1,11 +1,38 @@
+/**
+ * Browser Automation Engine resolution (ADR-037).
+ *
+ * The engine choice behind the canonical `browser_*` tools is a runtime
+ * decision with a recorded reason, not a static default:
+ *   - An explicit `GSD_BROWSER_ENGINE` override is honored verbatim.
+ *   - Otherwise, browser-facing projects prefer the managed gsd-browser engine
+ *     when the availability probe can prove a CLI exists, and fall back to
+ *     legacy Playwright with the failure reason recorded.
+ *   - Non-browser-facing projects keep legacy Playwright (browser tools are
+ *     incidental there; the managed daemon is not worth its startup risk).
+ *
+ * This module owns the committed resolution, not just the prediction: when
+ * registration verifies a probe-resolved managed engine (daemon connect) and
+ * falls back, the outcome is committed here so every ambient reader — UAT
+ * guidance, re-warm-up, later sessions in the same process — sees the engine
+ * the session actually registered.
+ */
+import path from "node:path";
+
+import { resolveGsdBrowserCliAvailability } from "../../shared/gsd-browser-cli.js";
+import { detectWebApp } from "../web-app-detect.js";
+
 export type BrowserEngineMode = "gsd-browser" | "legacy" | "off";
 
-const DEFAULT_BROWSER_ENGINE: BrowserEngineMode = "legacy";
+export interface BrowserEngineResolution {
+  engine: BrowserEngineMode;
+  /** "env" = explicit GSD_BROWSER_ENGINE override; "probe" = default path decided by availability. */
+  source: "env" | "probe";
+  reason: string;
+}
 
-export function resolveBrowserEngineMode(env: NodeJS.ProcessEnv = process.env): BrowserEngineMode {
-  const raw = env.GSD_BROWSER_ENGINE?.trim();
-  if (!raw) return DEFAULT_BROWSER_ENGINE;
+const committedResolutionByProjectRoot = new Map<string, BrowserEngineResolution>();
 
+function parseExplicitEngineMode(raw: string): BrowserEngineMode {
   const normalized = raw.toLowerCase();
   if (normalized === "gsd-browser" || normalized === "gsd_browser" || normalized === "gsdbrowser") {
     return "gsd-browser";
@@ -17,3 +44,62 @@ export function resolveBrowserEngineMode(env: NodeJS.ProcessEnv = process.env):
 
   throw new Error(`Invalid GSD_BROWSER_ENGINE="${raw}". Expected "gsd-browser", "legacy", or "off".`);
 }
+
+/** Pure resolution from explicit inputs. Never cached; probes on every call. */
+export function resolveBrowserEngineResolution(
+  env: NodeJS.ProcessEnv,
+  projectRoot?: string,
+): BrowserEngineResolution {
+  const raw = env.GSD_BROWSER_ENGINE?.trim();
+  if (raw) {
+    return { engine: parseExplicitEngineMode(raw), source: "env", reason: `GSD_BROWSER_ENGINE=${raw}` };
+  }
+
+  if (!projectRoot) {
+    return { engine: "legacy", source: "probe", reason: "no project root to probe; using legacy Playwright" };
+  }
+
+  if (!detectWebApp(projectRoot)) {
+    return {
+      engine: "legacy",
+      source: "probe",
+      reason: "project is not browser-facing; using legacy Playwright",
+    };
+  }
+
+  const availability = resolveGsdBrowserCliAvailability(env);
+  return availability.available
+    ? {
+        engine: "gsd-browser",
+        source: "probe",
+        reason: `web app detected and managed gsd-browser engine available (${availability.detail})`,
+      }
+    : {
+        engine: "legacy",
+        source: "probe",
+        reason: `web app detected but gsd-browser unavailable (${availability.detail}); falling back to legacy Playwright`,
+      };
+}
+
+/**
+ * Session-facing resolution: the committed record for this project root, or
+ * the ambient probe result, cached as the initial commitment (the probe
+ * touches the filesystem and at worst one short subprocess).
+ */
+export function resolveAmbientBrowserEngineResolution(projectRoot: string): BrowserEngineResolution {
+  const key = path.resolve(projectRoot);
+  const committed = committedResolutionByProjectRoot.get(key);
+  if (committed) return committed;
+
+  const resolution = resolveBrowserEngineResolution(process.env, projectRoot);
+  committedResolutionByProjectRoot.set(key, resolution);
+  return resolution;
+}
+
+/**
+ * Record a verified outcome for this project root — e.g. the probe predicted
+ * gsd-browser but the daemon-connect gate fell back to legacy Playwright.
+ */
+export function commitBrowserEngineResolution(projectRoot: string, resolution: BrowserEngineResolution): void {
+  committedResolutionByProjectRoot.set(path.resolve(projectRoot), resolution);
+}

package/src/resources/extensions/browser-tools/index.ts

@@ -2,7 +2,7 @@
 import { importExtensionModule, type ExtensionAPI, type ExtensionContext } from "@gsd/pi-coding-agent";
 
 import { closeManagedGsdBrowser, registerManagedGsdBrowserTools, warmUpManagedGsdBrowser } from "./engine/managed-gsd-browser.js";
-import { resolveBrowserEngineMode, type BrowserEngineMode } from "./engine/selection.js";
+import { commitBrowserEngineResolution, resolveAmbientBrowserEngineResolution, type BrowserEngineMode } from "./engine/selection.js";
 import { setArtifactRootForCwd } from "./state.js";
 import { detectWebApp } from "./web-app-detect.js";
 
@@ -167,13 +167,59 @@ function withBrowserArtifactCwdScope(pi: ExtensionAPI): ExtensionAPI {
   };
 }
 
-async function registerBrowserTools(pi: ExtensionAPI): Promise<void> {
-  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: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+  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: Promise<void>;
@@ -202,29 +248,41 @@ async function registerBrowserTools(pi: ExtensionAPI): Promise<void> {
   }
 }
 
+function commitLegacyFallback(projectRoot: string, reason: string): "legacy" {
+  commitBrowserEngineResolution(projectRoot, { engine: "legacy", source: "probe", reason });
+  return "legacy";
+}
+
 function isWarmUpDisabled(): boolean {
   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: ExtensionAPI, ctx: ExtensionContext): void {
   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");
     }
   });
 }
@@ -240,7 +298,7 @@ async function closeActiveBrowserEngines(): Promise<void> {
 export default function (pi: ExtensionAPI) {
   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");
@@ -248,7 +306,7 @@ export default function (pi: ExtensionAPI) {
       return;
     }
 
-    await registerBrowserTools(pi);
+    await registerBrowserTools(pi, ctx);
     maybeWarmUpManagedEngine(pi, ctx);
   });
 

package/src/resources/extensions/browser-tools/tests/browser-engine-selection.test.mjs

@@ -1,35 +1,105 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
 const jiti = require("jiti")(__dirname, { interopDefault: true, debug: false });
 
-const { resolveBrowserEngineMode } = jiti("../engine/selection.ts");
+const {
+  commitBrowserEngineResolution,
+  resolveAmbientBrowserEngineResolution,
+  resolveBrowserEngineResolution,
+} = jiti("../engine/selection.ts");
 
-describe("resolveBrowserEngineMode", () => {
-  it("defaults to the Playwright engine", () => {
-    assert.equal(resolveBrowserEngineMode({}), "legacy");
-  });
+function makeProject({ webApp }) {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-engine-selection-"));
+  const pkg = webApp ? { dependencies: { react: "^18.0.0" } } : { name: "cli-tool" };
+  writeFileSync(join(dir, "package.json"), JSON.stringify(pkg));
+  return dir;
+}
+
+function makeFakeCli() {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-fake-cli-"));
+  const cliPath = join(dir, "gsd-browser");
+  writeFileSync(cliPath, "#!/bin/sh\n");
+  return cliPath;
+}
 
-  it("accepts the explicit engine modes", () => {
-    assert.equal(resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "gsd-browser" }), "gsd-browser");
-    assert.equal(resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "legacy" }), "legacy");
-    assert.equal(resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "off" }), "off");
+describe("resolveBrowserEngineResolution", () => {
+  it("honors the explicit engine modes verbatim with env source", () => {
+    assert.deepEqual(
+      ["gsd-browser", "legacy", "off"].map(
+        (mode) => resolveBrowserEngineResolution({ GSD_BROWSER_ENGINE: mode }).engine,
+      ),
+      ["gsd-browser", "legacy", "off"],
+    );
+    assert.equal(resolveBrowserEngineResolution({ GSD_BROWSER_ENGINE: "gsd-browser" }).source, "env");
   });
 
   it("accepts compatibility aliases", () => {
-    assert.equal(resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "playwright" }), "legacy");
-    assert.equal(resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "false" }), "off");
+    assert.equal(resolveBrowserEngineResolution({ GSD_BROWSER_ENGINE: "playwright" }).engine, "legacy");
+    assert.equal(resolveBrowserEngineResolution({ GSD_BROWSER_ENGINE: "false" }).engine, "off");
   });
 
   it("rejects unknown engine modes", () => {
     assert.throws(
-      () => resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "surprise" }),
+      () => resolveBrowserEngineResolution({ GSD_BROWSER_ENGINE: "surprise" }),
       /Expected "gsd-browser", "legacy", or "off"/,
     );
   });
+
+  it("defaults to legacy Playwright when no project root is known", () => {
+    const resolution = resolveBrowserEngineResolution({});
+    assert.equal(resolution.engine, "legacy");
+    assert.equal(resolution.source, "probe");
+  });
+
+  it("keeps legacy Playwright for non-browser-facing projects", () => {
+    const cliPath = makeFakeCli();
+    const resolution = resolveBrowserEngineResolution(
+      { GSD_BROWSER_CLI_PATH: cliPath },
+      makeProject({ webApp: false }),
+    );
+    assert.equal(resolution.engine, "legacy");
+    assert.match(resolution.reason, /not browser-facing/);
+  });
+
+  it("prefers the managed gsd-browser engine for web apps when the CLI is provable", () => {
+    const cliPath = makeFakeCli();
+    const resolution = resolveBrowserEngineResolution(
+      { GSD_BROWSER_CLI_PATH: cliPath },
+      makeProject({ webApp: true }),
+    );
+    assert.equal(resolution.engine, "gsd-browser");
+    assert.equal(resolution.source, "probe");
+    assert.match(resolution.reason, /web app detected/);
+  });
+
+  it("falls back to legacy Playwright with a recorded reason when the CLI is unavailable", () => {
+    const resolution = resolveBrowserEngineResolution(
+      { GSD_BROWSER_CLI_PATH: "/nonexistent/gsd-browser" },
+      makeProject({ webApp: true }),
+    );
+    assert.equal(resolution.engine, "legacy");
+    assert.equal(resolution.source, "probe");
+    assert.match(resolution.reason, /falling back to legacy Playwright/);
+  });
+});
+
+describe("committed resolution", () => {
+  it("ambient readers see a committed verification outcome instead of the prediction", () => {
+    const projectRoot = makeProject({ webApp: true });
+    const fallback = {
+      engine: "legacy",
+      source: "probe",
+      reason: "gsd-browser daemon connect failed (test); using legacy Playwright",
+    };
+    commitBrowserEngineResolution(projectRoot, fallback);
+    assert.deepEqual(resolveAmbientBrowserEngineResolution(projectRoot), fallback);
+  });
 });

package/src/resources/extensions/browser-tools/tests/managed-gsd-browser-tools.test.mjs

@@ -2,10 +2,33 @@ import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 
 const {
+  MANAGED_BROWSER_TOOL_SPECS,
   MANAGED_GSD_BROWSER_TOOL_NAMES,
+  findMissingContractCoverage,
+  normalizeManagedArgs,
   registerManagedGsdBrowserTools,
 } = await import("../engine/managed-gsd-browser.ts");
 
+// The tools @opengsd/gsd-browser actually serves over MCP (subset relevant to
+// the contract). Notably absent: browser_click, browser_type, browser_verify,
+// browser_reload — those are satisfied through translations.
+const GSD_BROWSER_SERVED_TOOLS = [
+  "browser_navigate",
+  "browser_snapshot",
+  "browser_click_ref",
+  "browser_fill_ref",
+  "browser_fill_form",
+  "browser_wait_for",
+  "browser_assert",
+  "browser_screenshot",
+  "browser_find_element",
+  "browser_console",
+  "browser_network",
+  "browser_evaluate",
+  "browser_batch",
+  "browser_act",
+];
+
 describe("registerManagedGsdBrowserTools", () => {
   it("registers the curated Pi browser contract", () => {
     const tools = [];
@@ -31,3 +54,116 @@ describe("registerManagedGsdBrowserTools", () => {
     assert.equal(screenshot?.compatibility?.producesImages, true);
   });
 });
+
+describe("findMissingContractCoverage", () => {
+  it("reports nothing for the tool list gsd-browser actually serves", () => {
+    assert.deepEqual(findMissingContractCoverage(GSD_BROWSER_SERVED_TOOLS), []);
+  });
+
+  it("reports contract tools none of whose MCP candidates are served", () => {
+    const served = GSD_BROWSER_SERVED_TOOLS.filter((name) => name !== "browser_assert");
+    // browser_verify also depends on browser_assert through its translation.
+    assert.deepEqual(findMissingContractCoverage(served), ["browser_assert", "browser_verify"]);
+  });
+
+  it("reports translated tools when a required MCP tool is missing", () => {
+    const served = GSD_BROWSER_SERVED_TOOLS.filter((name) => name !== "browser_batch");
+    assert.deepEqual(findMissingContractCoverage(served), ["browser_click", "browser_type", "browser_batch"]);
+  });
+});
+
+describe("contract tool translations", () => {
+  it("translates browser_click into a single-step batch call", () => {
+    const calls = MANAGED_BROWSER_TOOL_SPECS.browser_click.translate.build({ selector: "#save" });
+    assert.deepEqual(calls, [{
+      mcpTool: "browser_batch",
+      args: { steps: [{ action: "click", selector: "#save" }] },
+    }]);
+  });
+
+  it("translates browser_type into a single-step batch call", () => {
+    const calls = MANAGED_BROWSER_TOOL_SPECS.browser_type.translate.build({
+      selector: "#name",
+      text: "hello",
+      clearFirst: true,
+      submit: true,
+    });
+    assert.deepEqual(calls, [{
+      mcpTool: "browser_batch",
+      args: { steps: [{ action: "type", selector: "#name", text: "hello", clearFirst: true, submit: true }] },
+    }]);
+  });
+
+  it("normalizes batch options and step keys to the daemon's snake_case", () => {
+    const normalized = normalizeManagedArgs("browser_batch", {
+      steps: [{ action: "type", selector: "#name", text: "hi", clearFirst: true }],
+      stopOnFailure: false,
+      finalSummaryOnly: true,
+    });
+    assert.deepEqual(normalized, {
+      steps: [{ action: "type", selector: "#name", text: "hi", clear_first: true }],
+      stop_on_failure: false,
+      summary_only: true,
+    });
+  });
+
+  it("translates browser_verify into navigate, assert, and screenshot calls", () => {
+    const calls = MANAGED_BROWSER_TOOL_SPECS.browser_verify.translate.build({
+      url: "http://localhost:3000",
+      timeout: 5000,
+      checks: [
+        { description: "heading shows", selector: "h1", expectedText: "Welcome" },
+        { description: "spinner gone", selector: ".spinner", expectedVisible: false },
+        { description: "evidence", selector: "main", expectedVisible: true, screenshot: true },
+      ],
+    });
+    assert.deepEqual(calls, [
+      { mcpTool: "browser_navigate", args: { url: "http://localhost:3000", timeout: 5000 } },
+      {
+        mcpTool: "browser_assert",
+        args: {
+          checks: [
+            { kind: "text_visible", text: "Welcome" },
+            { kind: "selector_hidden", selector: ".spinner" },
+            { kind: "selector_visible", selector: "main" },
+          ],
+        },
+      },
+      { mcpTool: "browser_screenshot", args: {}, optional: true },
+    ]);
+  });
+
+  it("declares every tool a translation can emit in its coverage requirements", () => {
+    for (const [name, spec] of Object.entries(MANAGED_BROWSER_TOOL_SPECS)) {
+      if (!spec.translate) continue;
+      const maximalArgs = {
+        url: "http://localhost:3000",
+        timeout: 5000,
+        selector: "#el",
+        text: "hi",
+        clearFirst: true,
+        checks: [{ description: "d", selector: "#el", expectedText: "hi", expectedVisible: true, screenshot: true }],
+      };
+      const emitted = spec.translate.build(maximalArgs).map((call) => call.mcpTool);
+      for (const mcpTool of emitted) {
+        assert.ok(
+          spec.translate.requires.includes(mcpTool),
+          `${name} translation emits ${mcpTool} but does not require it for coverage`,
+        );
+      }
+    }
+  });
+
+  it("translates browser_verify without checks into navigation only", () => {
+    const calls = MANAGED_BROWSER_TOOL_SPECS.browser_verify.translate.build({ url: "http://localhost:3000", checks: [] });
+    assert.deepEqual(calls, [{ mcpTool: "browser_navigate", args: { url: "http://localhost:3000" } }]);
+  });
+
+  it("translates browser_reload into evaluate plus best-effort network-idle wait", () => {
+    const calls = MANAGED_BROWSER_TOOL_SPECS.browser_reload.translate.build({});
+    assert.deepEqual(calls, [
+      { mcpTool: "browser_evaluate", args: { expression: "location.reload()" } },
+      { mcpTool: "browser_wait_for", args: { condition: "network_idle", timeout: 3_000 }, optional: true },
+    ]);
+  });
+});

package/src/resources/extensions/claude-code-cli/stream-adapter.ts

@@ -60,6 +60,7 @@ import {
 } 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, type Question, type RoundResult } from "../shared/tui.js";
 import type {
 	SDKAssistantMessage,
@@ -1591,7 +1592,7 @@ function browserMcpServerNameFromAllowedTools(allowedTools: unknown): string | u
 		if (typeof toolName !== "string") continue;
 		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;
 		}
 	}
@@ -1604,7 +1605,7 @@ function workflowMcpServerNameFromAllowedTools(allowedTools: unknown): string |
 	for (const toolName of allowedTools) {
 		if (typeof toolName !== "string") continue;
 		const parsed = parseAllowedMcpToolName(toolName);
-		if (!parsed || parsed.server === browserServerName || parsed.tool.startsWith("browser_")) continue;
+		if (!parsed || parsed.server === browserServerName || hasBrowserContractPrefix(parsed.tool)) continue;
 		return parsed.server;
 	}
 	return undefined;

package/src/resources/extensions/gsd/bootstrap/register-extension.ts

@@ -17,6 +17,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
@@ -37,6 +38,12 @@ 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: string): void {
@@ -133,6 +140,21 @@ export function installEpipeGuard(): void {
   }
 }
 
+function assertCriticalGsdWorkflowToolsRegistered(pi: ExtensionAPI): void {
+  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: ExtensionAPI): void {
   // Note: registerGSDCommand is called by index.ts before this function,
   // so we intentionally skip it here to avoid double-registration.
@@ -214,4 +236,6 @@ export function registerGsdExtension(pi: ExtensionAPI): void {
       );
     }
   }
+
+  assertCriticalGsdWorkflowToolsRegistered(pi);
 }