@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

package/src/resources/extensions/bg-shell/tests/lifecycle-and-utilities.test.ts

@@ -1,7 +1,7 @@
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
 import type { BgProcess } from "../types.ts";
-import { detectProcessType } from "../process-manager.ts";
+import { detectProcessType, startProcess, terminateProcess, processes } from "../process-manager.ts";
 import { waitForReady } from "../readiness-detector.ts";
 import {
   formatTimeAgo,
@@ -108,6 +108,18 @@ describe("bg-shell waitForReady", () => {
     assert.match(result.detail, /137/);
   });
 
+  test("a clean exit-0 reads as completion, not a crash, and points at the right tool", async () => {
+    // Regression: a run-to-completion batch command (e.g. terraform apply) put
+    // under wait_for_ready exits 0 on success. It must NOT be framed as a crash;
+    // it should say it completed and steer toward async_bash.
+    const bg = makeBg({ alive: false, exitCode: 0 });
+    const result = await waitForReady(bg, 1000);
+    assert.equal(result.ready, false);
+    assert.match(result.detail, /completed \(exit 0\)/);
+    assert.match(result.detail, /async_bash/);
+    assert.doesNotMatch(result.detail, /exited before becoming ready/);
+  });
+
   test("reports failure when the process entered an error state", async () => {
     const bg = makeBg({ status: "error", readyPort: 5173 });
     const result = await waitForReady(bg, 1000);
@@ -204,3 +216,38 @@ describe("bg-shell resolveBgShellPersistenceCwd", () => {
     assert.equal(result, "/proj/.gsd/worktrees/feature-b");
   });
 });
+
+describe("bg-shell terminateProcess (graceful kill ladder)", () => {
+  test(
+    "force-kills a SIGTERM-immune process via the shared killProcessTree ladder",
+    { skip: process.platform === "win32" ? "Unix-primary graceful semantics" : false, timeout: 15_000 },
+    async (t) => {
+      // A process that ignores SIGTERM must still die — terminateProcess routes
+      // through killProcessTree, which escalates SIGTERM → grace → SIGKILL. A bare
+      // single-signal kill (the old behavior) would have left this running.
+      const bg = startProcess({
+        command: "trap '' TERM; while true; do sleep 1; done",
+        cwd: "/tmp",
+        label: "sigterm-immune",
+        type: "generic",
+      });
+      t.after(() => {
+        try { if (bg.proc.pid) process.kill(-bg.proc.pid, "SIGKILL"); } catch { /* gone */ }
+        processes.delete(bg.id);
+      });
+
+      // Let the trap install.
+      await new Promise((r) => setTimeout(r, 300));
+      assert.equal(bg.alive, true, "process should be alive before terminate");
+
+      terminateProcess(bg.id);
+
+      // SIGKILL fires after the 5s grace; poll up to grace + slack.
+      const deadline = Date.now() + 9_000;
+      while (bg.alive && Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 100));
+      }
+      assert.equal(bg.alive, false, "SIGTERM-immune process must be SIGKILLed via the ladder, not left running");
+    },
+  );
+});

package/src/resources/extensions/bg-shell/utilities.ts

@@ -43,9 +43,12 @@ export function formatTimeAgo(timestamp: number): string {
 	return formatDuration(Date.now() - timestamp) + " ago";
 }
 
+// NOTE: these worktree-layout regexes mirror findWorktreeSegment in
+// src/resources/extensions/gsd/worktree-root.ts (bg-shell does not import the
+// gsd extension). Keep them synchronized when a layout changes.
 function deriveProjectRootFromAutoWorktree(cachedCwd?: string): string | undefined {
 	if (!cachedCwd) return undefined;
-	const match = cachedCwd.match(/^(.*?)[\\/]\.gsd[\\/]worktrees[\\/][^\\/]+(?:[\\/].*)?$/);
+	const match = cachedCwd.match(/^(.*?)[\\/]\.gsd(?:-worktrees|[\\/]worktrees)[\\/][^\\/]+(?:[\\/].*)?$/);
 	return match?.[1];
 }
 
@@ -84,7 +87,7 @@ export function resolveBgShellPersistenceCwd(
 	pathExists: (path: string) => boolean = existsSync,
 ): string {
 	const resolvedLiveCwd = liveCwd ?? getBgShellLiveCwd(cachedCwd, pathExists);
-	const cachedIsAutoWorktree = /(?:^|[\\/])\.gsd[\\/]worktrees[\\/]/.test(cachedCwd);
+	const cachedIsAutoWorktree = /(?:^|[\\/])\.gsd(?:-worktrees|[\\/]worktrees)[\\/]/.test(cachedCwd);
 	if (!cachedIsAutoWorktree) return cachedCwd;
 	if (cachedCwd === resolvedLiveCwd && pathExists(cachedCwd)) return cachedCwd;
 	if (!pathExists(cachedCwd)) return resolvedLiveCwd;

package/src/resources/extensions/browser-tools/engine/managed-gsd-browser.ts

@@ -3,6 +3,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { Type, type TSchema } from "@sinclair/typebox";
 
+import { BROWSER_CONTRACT_TOOL_NAMES, type BrowserContractToolName } from "../../shared/browser-contract.js";
 import { resolveGsdBrowserMcpLaunchConfig, type GsdBrowserMcpLaunchConfig } from "../../shared/gsd-browser-cli.js";
 import { buildMcpChildEnv } from "../../mcp-client/manager.js";
 
@@ -13,6 +14,8 @@ interface ManagedBrowserToolDetails {
   server: string;
   tool: string;
   mcpTool: string;
+  /** All MCP tools invoked, in order, when a translation made multiple calls. */
+  mcpTools?: string[];
   sessionName?: string;
   projectRoot?: string;
   truncated?: boolean;
@@ -37,9 +40,28 @@ interface McpContentItem {
   [key: string]: unknown;
 }
 
+interface ManagedTranslatedCall {
+  mcpTool: string;
+  args: Record<string, unknown>;
+  /** Best-effort call: a failure adds no evidence but does not fail the tool. */
+  optional?: boolean;
+}
+
+interface ManagedToolTranslation {
+  /** Every MCP tool build() can emit; all must be served for contract coverage. */
+  requires: readonly string[];
+  /** Expand the Pi contract args into one or more sequential gsd-browser MCP calls. */
+  build(args: Record<string, unknown>): ManagedTranslatedCall[];
+}
+
 interface ManagedBrowserToolSpec {
-  name: string;
+  /** gsd-browser MCP tool candidates, tried in order. Defaults to the contract name itself. */
   mcpTools?: string[];
+  /**
+   * Param-shape translation for contract tools gsd-browser does not serve
+   * under any name. Takes precedence over mcpTools/name-based dispatch.
+   */
+  translate?: ManagedToolTranslation;
   label: string;
   description: string;
   parameters: TSchema;
@@ -51,6 +73,7 @@ const connections = new Map<string, ManagedConnection>();
 const pendingConnections = new Map<string, Promise<ManagedConnection>>();
 const DEFAULT_MAX_LINES = 2_000;
 const DEFAULT_MAX_BYTES = 50 * 1024;
+const MCP_CALL_TIMEOUT_MS = 60_000;
 
 const AssertionCheck = Type.Object({
   kind: Type.String({ description: "Assertion kind, e.g. url_contains, text_visible, selector_visible, no_console_errors, no_failed_requests." }),
@@ -77,30 +100,16 @@ const BatchStep = Type.Object({
   checks: Type.Optional(Type.Array(AssertionCheck)),
 }, { additionalProperties: true });
 
-export const MANAGED_GSD_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",
-] as const;
-
-const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
-  {
-    name: "browser_navigate",
+/**
+ * The managed adapter serves exactly the Browser Automation Contract
+ * vocabulary. The spec table below is keyed by contract name, so adding a
+ * contract capability fails typecheck here until the adapter declares how the
+ * gsd-browser server satisfies it.
+ */
+export const MANAGED_GSD_BROWSER_TOOL_NAMES = BROWSER_CONTRACT_TOOL_NAMES;
+
+export const MANAGED_BROWSER_TOOL_SPECS: Record<BrowserContractToolName, ManagedBrowserToolSpec> = {
+  browser_navigate: {
     label: "Browser Navigate",
     description: "Navigate the managed gsd-browser session to a URL and return page state. Use for local web app verification and UAT evidence.",
     parameters: Type.Object({
@@ -108,8 +117,14 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       screenshot: Type.Optional(Type.Boolean({ description: "Capture screenshot evidence when supported." })),
     }, { additionalProperties: true }),
   },
-  {
-    name: "browser_click",
+  browser_click: {
+    translate: {
+      requires: ["browser_batch"],
+      build: (args) => [{
+        mcpTool: "browser_batch",
+        args: { steps: [{ action: "click", ...args }] },
+      }],
+    },
     label: "Browser Click",
     description: "Click an element in the managed gsd-browser session by selector or coordinates.",
     parameters: Type.Object({
@@ -118,8 +133,14 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       y: Type.Optional(Type.Number({ description: "Y coordinate to click." })),
     }, { additionalProperties: true }),
   },
-  {
-    name: "browser_type",
+  browser_type: {
+    translate: {
+      requires: ["browser_batch"],
+      build: (args) => [{
+        mcpTool: "browser_batch",
+        args: { steps: [{ action: "type", ...args }] },
+      }],
+    },
     label: "Browser Type",
     description: "Type or fill text into an input in the managed gsd-browser session.",
     parameters: Type.Object({
@@ -130,8 +151,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       slowly: Type.Optional(Type.Boolean({ description: "Type character by character." })),
     }, { additionalProperties: true }),
   },
-  {
-    name: "browser_fill_form",
+  browser_fill_form: {
     label: "Browser Fill Form",
     description: "Fill a form in the managed gsd-browser session using field labels, names, placeholders, or aria labels.",
     parameters: Type.Object({
@@ -140,16 +160,14 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       submit: Type.Optional(Type.Boolean({ description: "Submit the form after filling." })),
     }, { additionalProperties: true }),
   },
-  {
-    name: "browser_click_ref",
+  browser_click_ref: {
     label: "Browser Click Ref",
     description: "Click a versioned ref from the latest gsd-browser snapshot.",
     parameters: Type.Object({
       ref: Type.String({ description: "Versioned ref, e.g. @v3:e2." }),
     }, { additionalProperties: true }),
   },
-  {
-    name: "browser_fill_ref",
+  browser_fill_ref: {
     label: "Browser Fill Ref",
     description: "Fill text into an input-like versioned ref from the latest gsd-browser snapshot.",
     parameters: Type.Object({
@@ -160,8 +178,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       slowly: Type.Optional(Type.Boolean({ description: "Type character by character." })),
     }, { additionalProperties: true }),
   },
-  {
-    name: "browser_wait_for",
+  browser_wait_for: {
     label: "Browser Wait For",
     description: "Wait for a browser condition such as network idle, selector visibility, text visibility, or URL change.",
     parameters: Type.Object({
@@ -171,8 +188,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       timeout: Type.Optional(Type.Number({ description: "Maximum milliseconds to wait." })),
     }, { additionalProperties: true }),
   },
-  {
-    name: "browser_assert",
+  browser_assert: {
     label: "Browser Assert",
     description: "Run explicit browser assertions and return structured PASS/FAIL evidence.",
     promptGuidelines: [
@@ -183,8 +199,39 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       checks: Type.Array(AssertionCheck),
     }, { additionalProperties: true }),
   },
-  {
-    name: "browser_verify",
+  browser_verify: {
+    translate: {
+      requires: ["browser_navigate", "browser_assert", "browser_screenshot"],
+      build: (args) => {
+        const calls: ManagedTranslatedCall[] = [
+          {
+            mcpTool: "browser_navigate",
+            args: { url: args.url, ...(args.timeout === undefined ? {} : { timeout: args.timeout }) },
+          },
+        ];
+        const verifyChecks = Array.isArray(args.checks) ? args.checks as Array<Record<string, unknown>> : [];
+        const assertChecks: Array<Record<string, unknown>> = [];
+        for (const check of verifyChecks) {
+          if (typeof check.expectedText === "string") {
+            assertChecks.push({ kind: "text_visible", text: check.expectedText });
+          }
+          if (typeof check.selector === "string") {
+            if (check.expectedVisible === false) {
+              assertChecks.push({ kind: "selector_hidden", selector: check.selector });
+            } else if (check.expectedVisible === true || check.expectedText === undefined) {
+              assertChecks.push({ kind: "selector_visible", selector: check.selector });
+            }
+          }
+        }
+        if (assertChecks.length > 0) {
+          calls.push({ mcpTool: "browser_assert", args: { checks: assertChecks } });
+        }
+        if (verifyChecks.some((check) => check.screenshot === true)) {
+          calls.push({ mcpTool: "browser_screenshot", args: {}, optional: true });
+        }
+        return calls;
+      },
+    },
     label: "Browser Verify",
     description: "Run a structured browser verification flow and return evidence from the managed gsd-browser session.",
     parameters: Type.Object({
@@ -199,8 +246,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       timeout: Type.Optional(Type.Number({ description: "Navigation timeout in milliseconds." })),
     }, { additionalProperties: true }),
   },
-  {
-    name: "browser_screenshot",
+  browser_screenshot: {
     label: "Browser Screenshot",
     description: "Capture browser screenshot evidence from the managed gsd-browser session.",
     compatibility: { producesImages: true },
@@ -210,8 +256,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       quality: Type.Optional(Type.Number({ description: "JPEG quality when supported." })),
     }, { additionalProperties: true }),
   },
-  {
-    name: "browser_snapshot_refs",
+  browser_snapshot_refs: {
     mcpTools: ["browser_snapshot", "browser_snapshot_refs"],
     label: "Browser Snapshot Refs",
     description: "Capture a compact gsd-browser snapshot with versioned refs for reliable interaction.",
@@ -222,8 +267,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       mode: Type.Optional(Type.String({ description: "Snapshot mode: interactive, form, dialog, navigation, errors, headings, visible_only." })),
     }, { additionalProperties: true }),
   },
-  {
-    name: "browser_find",
+  browser_find: {
     mcpTools: ["browser_find_element", "browser_find"],
     label: "Browser Find",
     description: "Find elements by text, role, or selector in the managed gsd-browser session.",
@@ -234,8 +278,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       limit: Type.Optional(Type.Number({ description: "Maximum results to return." })),
     }, { additionalProperties: true }),
   },
-  {
-    name: "browser_get_console_logs",
+  browser_get_console_logs: {
     mcpTools: ["browser_console", "browser_get_console_logs"],
     label: "Browser Console Logs",
     description: "Return buffered console logs and JavaScript errors from the managed gsd-browser session.",
@@ -243,8 +286,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       clear: Type.Optional(Type.Boolean({ description: "Clear the buffer after reading logs." })),
     }, { additionalProperties: true }),
   },
-  {
-    name: "browser_get_network_logs",
+  browser_get_network_logs: {
     mcpTools: ["browser_network", "browser_get_network_logs"],
     label: "Browser Network Logs",
     description: "Return buffered network requests and responses from the managed gsd-browser session.",
@@ -253,8 +295,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       filter: Type.Optional(Type.String({ description: "Filter, e.g. all, errors, fetch-xhr." })),
     }, { additionalProperties: true }),
   },
-  {
-    name: "browser_evaluate",
+  browser_evaluate: {
     mcpTools: ["browser_eval", "browser_evaluate"],
     label: "Browser Evaluate",
     description: "Evaluate a JavaScript expression in the managed gsd-browser page context.",
@@ -262,14 +303,22 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       expression: Type.String({ description: "JavaScript expression to evaluate." }),
     }, { additionalProperties: true }),
   },
-  {
-    name: "browser_reload",
+  browser_reload: {
+    // gsd-browser's daemon has a reload command but does not expose it over
+    // MCP, so reload rides browser_evaluate. The network-idle settle is
+    // best-effort: pages with persistent connections never go idle.
+    translate: {
+      requires: ["browser_evaluate", "browser_wait_for"],
+      build: () => [
+        { mcpTool: "browser_evaluate", args: { expression: "location.reload()" } },
+        { mcpTool: "browser_wait_for", args: { condition: "network_idle", timeout: 3_000 }, optional: true },
+      ],
+    },
     label: "Browser Reload",
     description: "Reload the current page in the managed gsd-browser session.",
     parameters: Type.Object({}, { additionalProperties: true }),
   },
-  {
-    name: "browser_batch",
+  browser_batch: {
     label: "Browser Batch",
     description: "Execute multiple explicit browser steps through the managed gsd-browser session in one call.",
     promptGuidelines: [
@@ -282,8 +331,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       finalSummaryOnly: Type.Optional(Type.Boolean({ description: "Return only the compact final summary." })),
     }, { additionalProperties: true }),
   },
-  {
-    name: "browser_act",
+  browser_act: {
     label: "Browser Act",
     description: "Execute a semantic browser action through gsd-browser, such as primary_cta, submit_form, or close_dialog.",
     parameters: Type.Object({
@@ -291,7 +339,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       scope: Type.Optional(Type.String({ description: "CSS selector to narrow the search area." })),
     }, { additionalProperties: true }),
   },
-];
+};
 
 function resolveProjectRoot(ctx?: ExtensionContext): string {
   return ctx?.cwd || process.cwd();
@@ -381,11 +429,27 @@ function isUnknownMcpToolError(error: unknown): boolean {
   return /unknown tool|tool .*not found|tool not found|not registered|does not exist/i.test(message);
 }
 
-function normalizeManagedArgs(piToolName: string, args: Record<string, unknown>): Record<string, unknown> {
+function normalizeBatchStep(step: unknown): unknown {
+  if (!step || typeof step !== "object") return step;
+  const { clearFirst, ...rest } = step as Record<string, unknown>;
+  return clearFirst === undefined ? step : { ...rest, clear_first: clearFirst };
+}
+
+export function normalizeManagedArgs(piToolName: string, args: Record<string, unknown>): Record<string, unknown> {
   if (piToolName === "browser_snapshot_refs") {
     const { interactiveOnly: _interactiveOnly, ...snapshotArgs } = args;
     return snapshotArgs;
   }
+  if (piToolName === "browser_batch") {
+    // gsd-browser's MCP batch tool reads snake_case option and step keys.
+    const { stopOnFailure, finalSummaryOnly, steps, ...rest } = args;
+    return {
+      ...rest,
+      ...(Array.isArray(steps) ? { steps: steps.map(normalizeBatchStep) } : {}),
+      ...(stopOnFailure === undefined ? {} : { stop_on_failure: stopOnFailure }),
+      ...(finalSummaryOnly === undefined ? {} : { summary_only: finalSummaryOnly }),
+    };
+  }
   return args;
 }
 
@@ -463,43 +527,104 @@ function truncateHeadText(
   };
 }
 
+type McpToolCallResult = {
+  content?: unknown;
+  structuredContent?: unknown;
+  isError?: boolean;
+};
+
+function callGsdBrowserMcp(
+  connection: ManagedConnection,
+  mcpTool: string,
+  args: Record<string, unknown>,
+  signal?: AbortSignal,
+): Promise<McpToolCallResult> {
+  return connection.client.callTool(
+    { name: mcpTool, arguments: args },
+    undefined,
+    { signal, timeout: MCP_CALL_TIMEOUT_MS },
+  ) as Promise<McpToolCallResult>;
+}
+
+function buildManagedToolResult(
+  connection: ManagedConnection,
+  piToolName: string,
+  mcpToolsUsed: string[],
+  contentItems: McpContentItem[],
+  lastResult: McpToolCallResult,
+): ManagedBrowserToolResult {
+  const serialized = serializeMcpContent(contentItems);
+  return {
+    content: serialized.content,
+    details: {
+      engine: "gsd-browser",
+      server: connection.launch.serverName,
+      tool: piToolName,
+      mcpTool: mcpToolsUsed[mcpToolsUsed.length - 1] ?? piToolName,
+      ...(mcpToolsUsed.length > 1 ? { mcpTools: mcpToolsUsed } : {}),
+      sessionName: connection.launch.sessionName,
+      projectRoot: connection.launch.projectRoot,
+      truncated: serialized.truncated,
+      outputLines: serialized.outputLines,
+      outputBytes: serialized.outputBytes,
+      structuredContent: lastResult.structuredContent,
+      mcpIsError: Boolean(lastResult.isError),
+    },
+    isError: Boolean(lastResult.isError),
+  };
+}
+
+async function callTranslatedGsdBrowserTool(
+  connection: ManagedConnection,
+  piToolName: string,
+  translation: ManagedToolTranslation,
+  args: Record<string, unknown>,
+  options: { signal?: AbortSignal },
+): Promise<ManagedBrowserToolResult> {
+  const calls = translation.build(args);
+  const contentItems: McpContentItem[] = [];
+  const toolsUsed: string[] = [];
+  let lastResult: McpToolCallResult = {};
+
+  for (const call of calls) {
+    let result: McpToolCallResult;
+    try {
+      result = await callGsdBrowserMcp(connection, call.mcpTool, normalizeManagedArgs(call.mcpTool, call.args), options.signal);
+    } catch (error) {
+      if (call.optional) continue;
+      throw error;
+    }
+    if (call.optional && result.isError) continue;
+    toolsUsed.push(call.mcpTool);
+    if (Array.isArray(result.content)) contentItems.push(...result.content as McpContentItem[]);
+    lastResult = result;
+    // Later calls assume the earlier ones took effect (e.g. assert after a
+    // failed navigation would report misleading evidence), so stop here.
+    if (lastResult.isError) break;
+  }
+
+  return buildManagedToolResult(connection, piToolName, toolsUsed, contentItems, lastResult);
+}
+
 async function callManagedGsdBrowserTool(
   piToolName: string,
-  mcpTools: string[],
+  spec: ManagedBrowserToolSpec,
   args: Record<string, unknown>,
   options: { signal?: AbortSignal; ctx?: ExtensionContext },
 ): Promise<ManagedBrowserToolResult> {
   const connection = await getOrConnectManagedGsdBrowser(options.ctx, options.signal);
   const normalizedArgs = normalizeManagedArgs(piToolName, args);
-  let lastError: unknown;
 
-  for (const mcpTool of mcpTools) {
+  if (spec.translate) {
+    return callTranslatedGsdBrowserTool(connection, piToolName, spec.translate, normalizedArgs, options);
+  }
+
+  let lastError: unknown;
+  for (const mcpTool of spec.mcpTools ?? [piToolName]) {
     try {
-      const result = await connection.client.callTool(
-        { name: mcpTool, arguments: normalizedArgs },
-        undefined,
-        { signal: options.signal, timeout: 60000 },
-      );
+      const result = await callGsdBrowserMcp(connection, mcpTool, normalizedArgs, options.signal);
       const contentItems = Array.isArray(result.content) ? result.content as McpContentItem[] : [];
-      const serialized = serializeMcpContent(contentItems);
-
-      return {
-        content: serialized.content,
-        details: {
-          engine: "gsd-browser",
-          server: connection.launch.serverName,
-          tool: piToolName,
-          mcpTool,
-          sessionName: connection.launch.sessionName,
-          projectRoot: connection.launch.projectRoot,
-          truncated: serialized.truncated,
-          outputLines: serialized.outputLines,
-          outputBytes: serialized.outputBytes,
-          structuredContent: (result as { structuredContent?: unknown }).structuredContent,
-          mcpIsError: Boolean((result as { isError?: boolean }).isError),
-        },
-        isError: Boolean((result as { isError?: boolean }).isError),
-      };
+      return buildManagedToolResult(connection, piToolName, [mcpTool], contentItems, result);
     } catch (error) {
       lastError = error;
       if (!isUnknownMcpToolError(error)) break;
@@ -520,6 +645,46 @@ function formatManagedBrowserError(toolName: string, error: unknown): string {
   ].join("\n");
 }
 
+/**
+ * Contract tools the server's advertised tool list cannot satisfy through any
+ * of their declared MCP candidates or translations.
+ */
+export function findMissingContractCoverage(servedToolNames: Iterable<string>): BrowserContractToolName[] {
+  const served = new Set(servedToolNames);
+  return BROWSER_CONTRACT_TOOL_NAMES.filter((name) => {
+    const spec = MANAGED_BROWSER_TOOL_SPECS[name];
+    if (spec.translate) {
+      return !spec.translate.requires.every((required) => served.has(required));
+    }
+    const candidates = spec.mcpTools ?? [name];
+    return !candidates.some((candidate) => served.has(candidate));
+  });
+}
+
+/**
+ * Compare the server's advertised tool list against the Browser Automation
+ * Contract so a server that stops serving a contract tool surfaces at warm-up
+ * instead of as a first-use error. Best-effort: a failed or empty listing
+ * returns no warning (call-time alias fallback still applies).
+ */
+async function verifyContractCoverage(
+  connection: ManagedConnection,
+  signal?: AbortSignal,
+): Promise<string | undefined> {
+  let served: string[];
+  try {
+    const result = await connection.client.listTools(undefined, { signal, timeout: 10000 });
+    served = (result.tools ?? []).map((tool) => tool.name);
+  } catch {
+    return undefined;
+  }
+  if (served.length === 0) return undefined;
+
+  const missing = findMissingContractCoverage(served);
+  if (missing.length === 0) return undefined;
+  return `gsd-browser does not serve ${missing.length} Browser Automation Contract tool(s): ${missing.join(", ")}. These will error on first use; update gsd-browser or check GSD_BROWSER_* overrides.`;
+}
+
 /**
  * Eagerly establish the managed gsd-browser connection so browser tools are
  * ready before first use. Best-effort: returns the error instead of throwing so
@@ -530,19 +695,21 @@ function formatManagedBrowserError(toolName: string, error: unknown): string {
 export async function warmUpManagedGsdBrowser(
   ctx?: ExtensionContext,
   signal?: AbortSignal,
-): Promise<{ ok: true } | { ok: false; error: string }> {
+): Promise<{ ok: true; coverageWarning?: string } | { ok: false; error: string }> {
   try {
-    await getOrConnectManagedGsdBrowser(ctx, signal);
-    return { ok: true };
+    const connection = await getOrConnectManagedGsdBrowser(ctx, signal);
+    const coverageWarning = await verifyContractCoverage(connection, signal);
+    return coverageWarning ? { ok: true, coverageWarning } : { ok: true };
   } catch (error) {
     return { ok: false, error: error instanceof Error ? error.message : String(error) };
   }
 }
 
 export function registerManagedGsdBrowserTools(pi: ExtensionAPI): void {
-  for (const tool of MANAGED_BROWSER_TOOLS) {
+  for (const name of BROWSER_CONTRACT_TOOL_NAMES) {
+    const tool = MANAGED_BROWSER_TOOL_SPECS[name];
     pi.registerTool({
-      name: tool.name,
+      name,
       label: tool.label,
       description: tool.description,
       ...(tool.promptGuidelines ? { promptGuidelines: tool.promptGuidelines } : {}),
@@ -551,20 +718,20 @@ export function registerManagedGsdBrowserTools(pi: ExtensionAPI): void {
       async execute(_toolCallId, params, signal, _onUpdate, ctx) {
         try {
           return await callManagedGsdBrowserTool(
-            tool.name,
-            tool.mcpTools ?? [tool.name],
+            name,
+            tool,
             params as Record<string, unknown>,
             { signal, ctx },
           );
         } catch (error) {
-          const message = formatManagedBrowserError(tool.name, error);
+          const message = formatManagedBrowserError(name, error);
           return {
             content: [{ type: "text", text: message }],
             details: {
               engine: "gsd-browser",
               server: "gsd-browser",
-              tool: tool.name,
-              mcpTool: tool.mcpTools?.[0] ?? tool.name,
+              tool: name,
+              mcpTool: tool.translate?.requires[0] ?? tool.mcpTools?.[0] ?? name,
               error: error instanceof Error ? error.message : String(error),
             },
             isError: true,