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

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/gsd-browser-launch-config.test.mjs

@@ -1,7 +1,10 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 
-const { resolveGsdBrowserMcpLaunchConfig } = await import("../../shared/gsd-browser-cli.ts");
+const {
+  resolveGsdBrowserDaemonStartInvocation,
+  resolveGsdBrowserMcpLaunchConfig,
+} = await import("../../shared/gsd-browser-cli.ts");
 
 describe("resolveGsdBrowserMcpLaunchConfig identity flags", () => {
   it("emits a non-empty --identity-key alongside --identity-scope", () => {
@@ -34,4 +37,29 @@ describe("resolveGsdBrowserMcpLaunchConfig identity flags", () => {
     });
     assert.equal(args[args.indexOf("--identity-key") + 1], "custom-key");
   });
+
+  it("uses a path-safe identity-project identifier", () => {
+    const { args } = resolveGsdBrowserMcpLaunchConfig("/tmp/example/project", {});
+    const projectId = args[args.indexOf("--identity-project") + 1];
+    assert.equal(typeof projectId, "string");
+    assert.doesNotMatch(projectId, /[\\/]/);
+  });
+});
+
+describe("resolveGsdBrowserDaemonStartInvocation", () => {
+  it("mirrors MCP session and identity flags with daemon start", () => {
+    const launch = resolveGsdBrowserMcpLaunchConfig("/tmp/example-project", {});
+    const daemon = resolveGsdBrowserDaemonStartInvocation("/tmp/example-project", {});
+
+    assert.equal(daemon.command, launch.command);
+    assert.equal(daemon.cwd, launch.cwd);
+    assert.deepEqual(
+      daemon.args.slice(daemon.args.indexOf("--session")),
+      launch.args.slice(launch.args.indexOf("--session")),
+    );
+    assert.deepEqual(
+      daemon.args.slice(0, daemon.args.indexOf("--session")),
+      [...launch.args.slice(0, launch.args.indexOf("mcp")), "daemon", "start"],
+    );
+  });
 });

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

@@ -59,6 +59,8 @@ import {
 	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, type Question, type RoundResult } from "../shared/tui.js";
 import type {
 	SDKAssistantMessage,
@@ -1590,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;
 		}
 	}
@@ -1603,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;
@@ -1998,8 +2000,9 @@ async function pumpSdkMessages(
 					: {}),
 			},
 		);
+		const workflowMcpServerName = workflowMcpServerNameFromAllowedTools(sdkOpts.allowedTools);
 		const prompt = buildPromptFromContext(context, {
-			workflowMcpServerName: workflowMcpServerNameFromAllowedTools(sdkOpts.allowedTools),
+			workflowMcpServerName,
 			browserMcpServerName: browserMcpServerNameFromAllowedTools(sdkOpts.allowedTools),
 		});
 		const queryPrompt = buildSdkQueryPrompt(context, prompt);
@@ -2041,7 +2044,34 @@ async function pumpSdkMessages(
 			switch (msg.type) {
 				// -- Init --
 				case "system": {
-					// Nothing to emit — the stream is already started.
+					// Tool Surface Readiness gate: the init message is the first (and
+					// only) point where the session reports its live tool surface and
+					// MCP server statuses. If the workflow server failed or has not
+					// registered this Unit's required tools, abort before the first
+					// model turn with a transient, recovery-classifiable error
+					// (tool-unavailable → retry) instead of letting the model hit
+					// "No such tool available" mid-Unit and improvise around it.
+					const init = msg as unknown as {
+						subtype?: string;
+						tools?: string[];
+						mcp_servers?: { name: string; status: string }[];
+					};
+					if (init.subtype === "init") {
+						const readinessError = getToolSurfaceReadinessError({
+							unitType: gsdPhase,
+							workflowServerName: workflowMcpServerName,
+							observation: { tools: init.tools ?? [], mcpServers: init.mcp_servers ?? [] },
+						});
+						if (readinessError) {
+							controller.abort();
+							stream.push({
+								type: "error",
+								reason: "error",
+								error: makeErrorMessage(modelId, readinessError),
+							});
+							return;
+						}
+					}
 					break;
 				}
 

package/src/resources/extensions/gsd/auto/orchestrator.ts

@@ -1023,16 +1023,18 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
       // checks coexist: idempotency for the common immediate-repeat case,
       // stuck-loop for the saturated-window case.
       if (this.lastAdvanceKey === nextKey && matchingCount < STUCK_WINDOW_SIZE) {
+        // Unit already active — benign no-op. Return skipped so the loop re-polls
+        // without cancelling the in-flight unit (blocked+pause would force-cancel it).
         this.clearPendingDispatch();
-        const blocked: AutoAdvanceResult = { kind: "blocked", reason: "idempotent advance: unit already active", action: "pause" };
+        const skipped: AutoAdvanceResult = { kind: "skipped", reason: "idempotent advance: unit already active" };
         this.journalTransition({
-          name: "advance-blocked",
-          reason: blocked.reason,
+          name: "advance-skipped",
+          reason: skipped.reason,
           unitType: decision.unitType,
           unitId: decision.unitId,
         });
-        this.postAdvanceRecord(blocked);
-        return blocked;
+        this.postAdvanceRecord(skipped);
+        return skipped;
       }
 
       // Stuck-loop detection: when the ring is saturated with copies of

package/src/resources/extensions/gsd/auto-dispatch.ts

@@ -90,7 +90,9 @@ import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import {
   getWorkflowTransportSupportError,
   getRequiredWorkflowToolsForAutoUnit,
+  resolveWorkflowMcpProjectRoot,
 } from "./workflow-mcp.js";
+import { prepareBrowserDaemonForUat } from "./browser-daemon-auto-prep.js";
 import {
   PROJECT_RESEARCH_INFLIGHT_MARKER,
 } from "./project-research-policy.js";
@@ -772,6 +774,16 @@ export const DISPATCH_RULES: DispatchRule[] = [
       if (browserToolError) {
         return { action: "stop" as const, reason: browserToolError, level: "warning" as const };
       }
+      const browserDaemonError = prepareBrowserDaemonForUat({
+        uatType,
+        sessionProvider,
+        sessionAuthMode,
+        sessionBaseUrl,
+        projectRoot: resolveWorkflowMcpProjectRoot(basePath),
+      });
+      if (browserDaemonError) {
+        return { action: "stop" as const, reason: browserDaemonError, level: "warning" as const };
+      }
 
       // Cap run-uat dispatch attempts to prevent infinite replay (#3624).
       // Check before incrementing so an exhausted counter cannot create a

package/src/resources/extensions/gsd/auto-model-selection.ts

@@ -1041,16 +1041,36 @@ export function resolveModelId<T extends { id: string; provider: string }>(
     if (providerMatch) return providerMatch;
   }
 
-  // Prefer "anthropic" as the canonical provider for Anthropic models.
-  // Transport-specific tiebreaker (ADR-012): intentionally keys on provider,
-  // not api — we want the plain Anthropic transport when multiple are available.
-  const anthropicMatch = candidates.find(m => m.provider === "anthropic");
-  if (anthropicMatch) return anthropicMatch;
+  // Subscription/OAuth routes beat pay-per-token API when the same model ID
+  // exists on multiple providers. Order matters — first match wins.
+  for (const provider of BARE_ID_SUBSCRIPTION_PROVIDER_PRECEDENCE) {
+    const match = candidates.find(m => m.provider === provider);
+    if (match) return match;
+  }
 
   // Fall back to first non-extension candidate, or any candidate
   return candidates.find(m => !EXTENSION_PROVIDERS.has(m.provider)) ?? candidates[0];
 }
 
+/**
+ * When a bare model ID exists on multiple providers, prefer subscription/OAuth
+ * routes over pay-per-token API keys. Matches PROVIDER_ROUTES in doctor-providers
+ * but applies when *both* sides are authenticated.
+ *
+ * Order rationale:
+ * - openai-codex before github-copilot: ChatGPT-native for shared GPT IDs
+ * - google-gemini-cli before github-copilot: first-party Gemini CLI
+ * - anthropic before github-copilot: first-party Claude API/OAuth over Copilot
+ * - github-copilot before openai/google: Copilot OAuth over platform API keys
+ */
+export const BARE_ID_SUBSCRIPTION_PROVIDER_PRECEDENCE = [
+  "openai-codex",
+  "google-gemini-cli",
+  "anthropic",
+  "github-copilot",
+  "google-antigravity",
+] as const;
+
 /**
  * Flat-rate providers charge the same per request regardless of model.
  * Dynamic routing provides no cost benefit — it only degrades quality (#3453).

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -88,7 +88,7 @@ import { writeTurnGitTransaction } from "./uok/gitops.js";
 import { isClosedStatus } from "./status-guards.js";
 import { detectAbandonMilestone } from "./abandon-detect.js";
 import { getPendingGate } from "./bootstrap/write-gate.js";
-import { isDeterministicPolicyError } from "./auto-tool-tracking.js";
+import { isDeterministicPolicyError, isToolUnavailableError } from "./auto-tool-tracking.js";
 import { formatConnectedStepStack, formatPostUnitStatusCard } from "./auto-status-message.js";
 import {
   clearProjectResearchInflightMarker,
@@ -2022,7 +2022,18 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
           "error",
         );
       } else if (!triggerArtifactVerified) {
-        if (s.lastToolInvocationError) {
+        if (s.lastToolInvocationError && isToolUnavailableError(s.lastToolInvocationError)) {
+          // Tool-unavailable is the one transient invocation error: the
+          // workflow MCP server registers its surface asynchronously, so a
+          // Unit's first call can race the registration. Fall through to the
+          // bounded verification retry instead of pausing.
+          debugLog("postUnit", { phase: "tool-unavailable-retry", unitType: s.currentUnit.type, unitId: s.currentUnit.id, error: s.lastToolInvocationError });
+          ctx.ui.notify(
+            `Tool unavailable for ${s.currentUnit.type}: ${s.lastToolInvocationError}. The tool surface may still be registering — retrying.`,
+            "warning",
+          );
+          s.lastToolInvocationError = null;
+        } else if (s.lastToolInvocationError) {
           const isUserSkip = /queued user message/i.test(s.lastToolInvocationError);
           const errMsg = isUserSkip
             ? `Tool skipped for ${s.currentUnit.type}: ${s.lastToolInvocationError}. Queued user message interrupted the turn — pausing auto-mode.`