@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.72e3af2a

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

@@ -4,7 +4,8 @@ import { existsSync, lstatSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { join, resolve } from "node:path";
 import { normalizeWorktreePathForCompare } from "./worktree-root.js";
-import { listWorktrees } from "./worktree-manager.js";
+import { worktreesDirs } from "./worktree-placement.js";
+import { listWorktrees, removeStaleWorktreeDirectory } from "./worktree-manager.js";
 import { getCurrentBranch } from "./worktree.js";
 const fsOnlyDeps = {
     existsSync,
@@ -24,6 +25,7 @@ const defaultDeps = {
             stdio: "pipe",
         });
     },
+    removeStaleWorktreeDirectory,
     getCurrentBranch,
 };
 function isValidMilestoneId(milestoneId) {
@@ -39,7 +41,6 @@ function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
 export function createWorktreeSafetyModule(deps = defaultDeps) {
-    const unregisteredRecoveryFailed = new Set();
     return {
         validateUnitRoot(input) {
             if (input.writeScope === "planning-only") {
@@ -59,15 +60,17 @@ export function createWorktreeSafetyModule(deps = defaultDeps) {
             const projectRoot = resolve(input.projectRoot);
             const unitRoot = resolve(input.unitRoot);
             const isolationMode = input.isolationMode ?? "worktree";
-            const expectedRoot = isolationMode === "worktree"
-                ? join(projectRoot, ".gsd", "worktrees", milestoneId)
-                : projectRoot;
-            if (!samePath(unitRoot, expectedRoot)) {
+            // A milestone worktree may live in the canonical container or the
+            // legacy one (pre-placement-change worktrees keep their location).
+            const expectedRoots = isolationMode === "worktree"
+                ? worktreesDirs(projectRoot).map((dir) => join(dir, milestoneId))
+                : [projectRoot];
+            if (!expectedRoots.some((expectedRoot) => samePath(unitRoot, expectedRoot))) {
                 return failure("invalid-root", isolationMode === "worktree"
                     ? `Unit root ${unitRoot} is not the expected worktree root for ${milestoneId}.`
                     : `Unit root ${unitRoot} is not the project root while isolation mode is ${isolationMode}.`, isolationMode === "worktree"
                     ? "Prepare the Unit in its canonical milestone worktree before allowing source writes."
-                    : "Run the Unit from the project root when worktree isolation is disabled.", { expectedRoot, unitRoot });
+                    : "Run the Unit from the project root when worktree isolation is disabled.", { expectedRoot: expectedRoots[0], unitRoot });
             }
             if (!deps.existsSync(unitRoot)) {
                 return failure("worktree-missing", `Worktree root ${unitRoot} does not exist.`, "Create or recover the milestone worktree before dispatching the source-writing Unit.", { unitRoot });
@@ -87,38 +90,49 @@ export function createWorktreeSafetyModule(deps = defaultDeps) {
                 return failure("worktree-git-marker-not-file", `Worktree root ${unitRoot} has a .git directory, not a registered worktree .git file.`, "Use a registered GSD worktree instead of a copied or nested repository.", { gitMarker });
             }
             let registered;
-            try {
-                registered = deps.listRegisteredWorktrees?.(projectRoot);
-            }
-            catch (error) {
-                return failure("worktree-git-probe-failed", `Unable to list registered worktrees for project root ${projectRoot}.`, "Recover or recreate the milestone worktree before dispatching the source-writing Unit.", { projectRoot, error: errorMessage(error) });
-            }
-            if (registered && !registered.some((worktree) => samePath(worktree.path, unitRoot))) {
-                const wasPreviouslyTracked = unregisteredRecoveryFailed.has(unitRoot);
-                let attemptedPrune = false;
-                if (!wasPreviouslyTracked && deps.pruneRegisteredWorktrees) {
-                    attemptedPrune = true;
-                    try {
-                        deps.pruneRegisteredWorktrees(projectRoot);
-                        const rechecked = deps.listRegisteredWorktrees?.(projectRoot);
-                        if (rechecked?.some((worktree) => samePath(worktree.path, unitRoot))) {
-                            unregisteredRecoveryFailed.delete(unitRoot);
-                            registered = rechecked;
+            if (isolationMode === "worktree") {
+                try {
+                    registered = deps.listRegisteredWorktrees?.(projectRoot);
+                }
+                catch (error) {
+                    return failure("worktree-git-probe-failed", `Unable to list registered worktrees for project root ${projectRoot}.`, "Recover or recreate the milestone worktree before dispatching the source-writing Unit.", { projectRoot, error: errorMessage(error) });
+                }
+                if (registered && !registered.some((worktree) => samePath(worktree.path, unitRoot))) {
+                    let attemptedPrune = false;
+                    if (deps.pruneRegisteredWorktrees) {
+                        attemptedPrune = true;
+                        try {
+                            deps.pruneRegisteredWorktrees(projectRoot);
+                            const rechecked = deps.listRegisteredWorktrees?.(projectRoot);
+                            if (rechecked?.some((worktree) => samePath(worktree.path, unitRoot))) {
+                                registered = rechecked;
+                            }
                         }
-                        else {
-                            unregisteredRecoveryFailed.add(unitRoot);
+                        catch (error) {
+                            return failure("worktree-git-probe-failed", `Unable to recover unregistered worktree root ${unitRoot}.`, "Run 'git worktree prune', then recreate or re-register the milestone worktree before dispatching the source-writing Unit.", { projectRoot, unitRoot, error: errorMessage(error) });
                         }
                     }
-                    catch (error) {
-                        unregisteredRecoveryFailed.add(unitRoot);
-                        return failure("worktree-git-probe-failed", `Unable to recover unregistered worktree root ${unitRoot}.`, "Run 'git worktree prune', then recreate the milestone worktree before dispatching the source-writing Unit.", { projectRoot, unitRoot, error: errorMessage(error) });
+                    if (!registered?.some((worktree) => samePath(worktree.path, unitRoot))) {
+                        // The directory exists on disk with a .git marker but git no longer
+                        // tracks it as a worktree (e.g. a prior removeWorktree crash left the
+                        // directory while `git worktree prune` cleaned the registry). Remove
+                        // the orphaned directory — the same cleanup createWorktree performs —
+                        // so the next dispatch recreates the milestone worktree from scratch
+                        // instead of looping forever on worktree-unregistered (#803, #590).
+                        if (deps.removeStaleWorktreeDirectory) {
+                            try {
+                                deps.removeStaleWorktreeDirectory(unitRoot, milestoneId);
+                                return failure("worktree-missing", `Worktree root ${unitRoot} was not registered with git; removed the orphaned directory so it can be recreated.`, "Recreate the milestone worktree before dispatching the source-writing Unit. Auto-mode recreates it automatically on the next dispatch.", { unitRoot, attemptedPrune, removedStaleDirectory: true });
+                            }
+                            catch (error) {
+                                return failure("worktree-unregistered", `Worktree root ${unitRoot} is not registered with git worktree list and the orphaned directory could not be removed.`, "Remove the orphaned worktree directory manually (it may be locked by another process), then recreate or re-register the milestone worktree before dispatching the source-writing Unit.", { unitRoot, attemptedPrune, removedStaleDirectory: false, error: errorMessage(error) });
+                            }
+                        }
+                        return failure("worktree-unregistered", `Worktree root ${unitRoot} is not registered with git worktree list.`, attemptedPrune
+                            ? "Worktree recovery was attempted but the root is still unregistered. Recreate or re-register the milestone worktree before dispatching the source-writing Unit."
+                            : "Run 'git worktree prune'. If still unregistered, recreate or re-register the milestone worktree before dispatching the source-writing Unit.", { unitRoot, attemptedPrune });
                     }
                 }
-                if (!registered?.some((worktree) => samePath(worktree.path, unitRoot))) {
-                    return failure("worktree-unregistered", `Worktree root ${unitRoot} is not registered with git worktree list.`, attemptedPrune || wasPreviouslyTracked
-                        ? "Worktree recovery was attempted but the root is still unregistered. Recreate or re-register the milestone worktree before dispatching the source-writing Unit."
-                        : "Run 'git worktree prune'. If still unregistered, recreate or re-register the milestone worktree before dispatching the source-writing Unit.", { unitRoot, attemptedPrune, trackedAsFailed: unregisteredRecoveryFailed.has(unitRoot) });
-                }
             }
             if (input.emptyWorktreeWithProjectContent) {
                 return failure("empty-worktree-with-project-content", `Worktree root ${unitRoot} has no project content, but the project root does.`, "Resolve untracked project-root content or recreate the worktree so source writes stay isolated.", { unitRoot, projectRoot });

package/dist/resources/extensions/gsd/worktree-session-state.js

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

package/dist/resources/extensions/gsd/worktree-shell-guard.js

@@ -0,0 +1,113 @@
+// Project/App: gsd-pi
+// File Purpose: Detect shell commands that reference the project root from a milestone worktree.
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { projectRootFromWorktreePath } from "./worktree-root.js";
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function normalizeScanPath(value) {
+    const normalized = value.replace(/\\/g, "/").replace(/\/+$/, "");
+    return normalized.startsWith("/private/var/")
+        ? normalized.slice("/private".length)
+        : normalized;
+}
+function parseWorktreeBase(baseDir) {
+    const normalizedBase = normalizeScanPath(baseDir);
+    const originalRoot = projectRootFromWorktreePath(normalizedBase);
+    if (!originalRoot)
+        return null;
+    return { originalRoot, worktreeRoot: normalizedBase };
+}
+function pathInside(parent, target) {
+    const parentWithSep = parent.endsWith("/") ? parent : `${parent}/`;
+    return target === parent || target.startsWith(parentWithSep);
+}
+function comparablePathVariants(value) {
+    const variants = new Set();
+    const normalized = normalizeScanPath(path.resolve(value));
+    variants.add(normalized);
+    try {
+        variants.add(normalizeScanPath(realpathSync(normalized)));
+    }
+    catch {
+        // Nonexistent paths are still compared lexically.
+    }
+    if (normalized.startsWith("/private/var/")) {
+        variants.add(normalized.replace(/^\/private\/var\//, "/var/"));
+    }
+    else if (normalized.startsWith("/var/")) {
+        variants.add(`/private${normalized}`);
+    }
+    return [...variants];
+}
+function pathInsideAny(parents, targets) {
+    return targets.some((target) => parents.some((parent) => pathInside(parent, target)));
+}
+function stripWrappingQuotes(value) {
+    const trimmed = value.trim();
+    if (trimmed.length < 2)
+        return trimmed;
+    const first = trimmed[0];
+    const last = trimmed[trimmed.length - 1];
+    if ((first === "'" || first === '"' || first === "`") && last === first) {
+        return trimmed.slice(1, -1).trim();
+    }
+    return trimmed;
+}
+function extractPathLikeValues(script) {
+    const values = [];
+    const push = (candidate) => {
+        const cleaned = stripWrappingQuotes(candidate).trim();
+        if (!cleaned)
+            return;
+        values.push(cleaned);
+    };
+    const pushQuotedLiterals = (source, depth = 0) => {
+        for (const match of source.matchAll(/(["'`])((?:\\.|(?!\1).)*)\1/g)) {
+            push(match[2]);
+            if (depth < 2 && /["'`]/.test(match[2])) {
+                pushQuotedLiterals(match[2], depth + 1);
+            }
+        }
+    };
+    for (const match of script.matchAll(/(?:^|[;\n\r]|\&\&|\|\|)\s*cd\s+([^\n\r;|&]+)/g)) {
+        push(match[1]);
+    }
+    for (const match of script.matchAll(/process\.chdir\(\s*([^\n\r;]+?)\s*\)/g)) {
+        push(match[1]);
+        pushQuotedLiterals(match[1]);
+    }
+    pushQuotedLiterals(script);
+    return values;
+}
+export function resolvesToOriginalRootOutsideWorktree(script, baseDir) {
+    const parsed = parseWorktreeBase(baseDir);
+    if (!parsed)
+        return false;
+    const normalizedWorktree = normalizeScanPath(path.resolve(parsed.worktreeRoot));
+    const normalizedOriginalRoot = normalizeScanPath(path.resolve(parsed.originalRoot));
+    const worktreeRoots = comparablePathVariants(normalizedWorktree);
+    const originalRoots = comparablePathVariants(normalizedOriginalRoot);
+    for (const value of extractPathLikeValues(script)) {
+        const resolved = comparablePathVariants(path.resolve(normalizedWorktree, value));
+        if (pathInsideAny(originalRoots, resolved) && !pathInsideAny(worktreeRoots, resolved)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function scriptReferencesOriginalRootFromWorktree(script, baseDir) {
+    const parsed = parseWorktreeBase(baseDir);
+    if (!parsed)
+        return false;
+    const normalizedScript = script.replace(/\\/g, "/");
+    return comparablePathVariants(parsed.originalRoot).some((originalRoot) => {
+        const originalRootPattern = new RegExp(`${escapeRegExp(originalRoot)}(?=$|[\\s'"\\\`;)&|<>]|/(?!\\.gsd(?:-worktrees|/worktrees)(?:/|$)))`);
+        return originalRootPattern.test(normalizedScript);
+    });
+}
+export function bashReferencesProjectRootOutsideWorktree(script, baseDir) {
+    return resolvesToOriginalRootOutsideWorktree(script, baseDir)
+        || scriptReferencesOriginalRootFromWorktree(script, baseDir);
+}

package/dist/resources/extensions/gsd/worktree-state-projection.js

@@ -60,6 +60,23 @@ const VERDICT_RE = /verdict:\s*[\w-]+/i;
  * Only overwrites when the source has a verdict — never clobbers a
  * worktree ASSESSMENT with a verdictless project-root copy.
  */
+function forceOverwriteValidationWithVerdict(srcMilestoneDir, dstMilestoneDir, milestoneId) {
+    if (!existsSync(srcMilestoneDir) || !milestoneId)
+        return;
+    const srcFile = join(srcMilestoneDir, `${milestoneId}-VALIDATION.md`);
+    if (!existsSync(srcFile))
+        return;
+    try {
+        const srcContent = readFileSync(srcFile, "utf-8");
+        if (!VERDICT_RE.test(srcContent))
+            return;
+        mkdirSync(dstMilestoneDir, { recursive: true });
+        safeCopy(srcFile, join(dstMilestoneDir, `${milestoneId}-VALIDATION.md`), { force: true });
+    }
+    catch (err) {
+        logWarning("worktree", `validation force-copy failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 function forceOverwriteAssessmentsWithVerdict(srcMilestoneDir, dstMilestoneDir) {
     if (!existsSync(srcMilestoneDir))
         return;
@@ -211,7 +228,10 @@ export function _projectRootToWorktreeImpl(projectRoot, worktreePath_, milestone
     // session resume the DB is rebuilt from disk, and if the stale ASSESSMENT
     // persists, checkNeedsRunUat finds no passing verdict → re-dispatches
     // run-uat indefinitely (stuck-loop ×9).
-    forceOverwriteAssessmentsWithVerdict(join(prGsd, "milestones", milestoneId), join(wtGsd, "milestones", milestoneId));
+    const prMilestoneDir = join(prGsd, "milestones", milestoneId);
+    const wtMilestoneDir = join(wtGsd, "milestones", milestoneId);
+    forceOverwriteValidationWithVerdict(prMilestoneDir, wtMilestoneDir, milestoneId);
+    forceOverwriteAssessmentsWithVerdict(prMilestoneDir, wtMilestoneDir);
     // Forward-sync completed-units.json from project root to worktree.
     // Project root is authoritative for completion state after crash recovery;
     // without this, the worktree re-dispatches already-completed units (#1886).
@@ -354,14 +374,20 @@ export class WorktreeStateProjection {
      * any Unit dispatches.
      */
     projectRootToWorktree(scope) {
-        _projectRootToWorktreeImpl(scope.workspace.projectRoot, scope.workspace.worktreeRoot ?? scope.workspace.projectRoot, scope.milestoneId);
+        this.projectRootToWorktreePaths(scope.workspace.projectRoot, scope.workspace.worktreeRoot ?? scope.workspace.projectRoot, scope.milestoneId);
+    }
+    projectRootToWorktreePaths(projectRoot, worktreePath, milestoneId) {
+        _projectRootToWorktreeImpl(projectRoot, worktreePath, milestoneId);
     }
     /**
      * Project state from the auto-worktree back onto the project root for `scope`.
      * Called by the post-unit pipeline between Units.
      */
     projectWorktreeToRoot(scope) {
-        _projectWorktreeToRootImpl(scope.workspace.worktreeRoot ?? scope.workspace.projectRoot, scope.workspace.projectRoot, scope.milestoneId);
+        this.projectWorktreeToRootPaths(scope.workspace.worktreeRoot ?? scope.workspace.projectRoot, scope.workspace.projectRoot, scope.milestoneId);
+    }
+    projectWorktreeToRootPaths(worktreePath, projectRoot, milestoneId) {
+        _projectWorktreeToRootImpl(worktreePath, projectRoot, milestoneId);
     }
     /**
      * Final projection from the auto-worktree to the project root before
@@ -373,6 +399,9 @@ export class WorktreeStateProjection {
      * telemetry on what crossed the boundary.
      */
     finalizeProjectionForMerge(scope) {
-        return _finalizeProjectionForMergeImpl(scope.workspace.projectRoot, scope.workspace.worktreeRoot ?? scope.workspace.projectRoot, scope.milestoneId);
+        return this.finalizeProjectionForMergePaths(scope.workspace.projectRoot, scope.workspace.worktreeRoot ?? scope.workspace.projectRoot, scope.milestoneId);
+    }
+    finalizeProjectionForMergePaths(projectRoot, worktreePath, milestoneId) {
+        return _finalizeProjectionForMergeImpl(projectRoot, worktreePath, milestoneId);
     }
 }

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

@@ -63,6 +63,18 @@ export function normalizeAutoExitReason(rawReason) {
                                                         ? reasonLc
                                                         : "other";
 }
+export function autoExitReasonForTerminalOutcome(outcome) {
+    switch (outcome?.code) {
+        case "all-complete":
+            return "all-complete";
+        case "settlement-blocked":
+            return "blocked";
+        case "no-remaining-units":
+            return "stop";
+        default:
+            return null;
+    }
+}
 // ─── Emitters ────────────────────────────────────────────────────────────
 export function emitWorktreeCreated(projectRoot, milestoneId, meta = {}) {
     emitJournalEvent(projectRoot, baseEntry("worktree-created", {

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

@@ -195,7 +195,14 @@ export function resolveGitHeadPath(dir) {
  */
 export function nudgeGitBranchCache(previousCwd) {
     const now = new Date();
-    for (const dir of [previousCwd, process.cwd()]) {
+    let currentCwd = null;
+    try {
+        currentCwd = process.cwd();
+    }
+    catch {
+        currentCwd = null;
+    }
+    for (const dir of [previousCwd, currentCwd].filter((dir) => Boolean(dir))) {
         try {
             const headPath = resolveGitHeadPath(dir);
             if (headPath)

package/dist/resources/extensions/mcp-client/manager.js

@@ -30,6 +30,8 @@ const CHILD_ENV_ALLOWLIST = new Set([
     "XDG_CACHE_HOME",
 ]);
 const MCP_STDERR_MAX_BYTES = 4096;
+/** Short-lived stdio probes must not register/kill production MCP PIDs (see probe-mode.ts). */
+export const GSD_MCP_PROBE_ENV = "GSD_MCP_PROBE";
 let cachedStatus = null;
 let cachedStatusKey = "";
 export function clearMcpConfigCache() {
@@ -259,7 +261,10 @@ export async function testMcpServerConnection(nameOrConfig, options = {}) {
             transport = new StdioClientTransport({
                 command: config.command ?? "",
                 args: config.args,
-                env: buildMcpChildEnv(config.env),
+                env: {
+                    ...buildMcpChildEnv(config.env),
+                    [GSD_MCP_PROBE_ENV]: "1",
+                },
                 cwd: config.cwd,
                 stderr: "pipe",
             });
@@ -350,14 +355,14 @@ function normalizeRawServerConfig(name, config, source) {
         cwd: typeof config.cwd === "string" ? config.cwd : undefined,
         headers,
         oauth: config.oauth && typeof config.oauth === "object" ? config.oauth : undefined,
-        envWarnings: collectEnvWarnings([
+        envWarnings: collectMcpEnvWarnings([
             ["url", url],
             ...Object.entries(env ?? {}).map(([key, value]) => [`env.${key}`, value]),
             ...Object.entries(headers ?? {}).map(([key, value]) => [`headers.${key}`, value]),
         ]),
     };
 }
-function detectTransport(config) {
+export function detectTransport(config) {
     const type = typeof config.type === "string" ? config.type.toLowerCase() : undefined;
     if (type && type !== "stdio" && type !== "http")
         return "unsupported";
@@ -392,7 +397,7 @@ function serializeServerInput(input) {
         _gsdImportedFrom: input.importedFrom,
     });
 }
-function collectEnvWarnings(values) {
+export function collectMcpEnvWarnings(values) {
     const warnings = [];
     for (const [label, value] of values) {
         if (!value)

package/dist/resources/extensions/search-the-web/index.js

@@ -3,30 +3,62 @@
  *
  * Native Anthropic hooks stay eager. Heavy tool registration is deferred in
  * interactive mode so startup is not blocked on the full search tool stack.
+ *
+ * Provider gating: the Brave/Tavily/Ollama-backed tools (search-the-web,
+ * search_and_read) are only registered when a provider API key is actually
+ * configured (resolveSearchProvider() !== null). Without a key these tools can
+ * only return an auth error, so presenting them to the model is pure confusion
+ * — the agent reaches for a tool that cannot work. fetch_page is always
+ * registered because it works key-free via Jina Reader.
  */
 import { importExtensionModule } from "@gsd/pi-coding-agent";
 import { registerSearchProviderCommand } from "./command-search-provider.js";
 import { registerNativeSearchHooks } from "./native-search.js";
-let toolsPromise = null;
+import { resolveSearchProvider } from "./provider.js";
+// fetch_page registration — always available (key-free via Jina Reader).
+let fetchToolPromise = null;
+// search-the-web + search_and_read registration — gated on provider key.
+let searchToolsPromise = null;
 let resetSearchLoopGuardStateRef = null;
-async function registerSearchTools(pi) {
-    if (!toolsPromise) {
-        toolsPromise = (async () => {
-            const [{ registerSearchTool, resetSearchLoopGuardState }, { registerFetchPageTool }, { registerLLMContextTool },] = await Promise.all([
+async function registerFetchTool(pi) {
+    if (!fetchToolPromise) {
+        fetchToolPromise = (async () => {
+            const { registerFetchPageTool } = await importExtensionModule(import.meta.url, "./tool-fetch-page.js");
+            registerFetchPageTool(pi);
+        })().catch((error) => {
+            fetchToolPromise = null;
+            throw error;
+        });
+    }
+    return fetchToolPromise;
+}
+/**
+ * Register the provider-backed search tools, but only when a search provider
+ * key is configured. Memoized so it registers at most once per process; the
+ * guard is re-evaluated on each session_start so a key added before a later
+ * session is picked up without a restart.
+ */
+async function registerProviderSearchTools(pi) {
+    if (resolveSearchProvider() === null)
+        return;
+    if (!searchToolsPromise) {
+        searchToolsPromise = (async () => {
+            const [{ registerSearchTool, resetSearchLoopGuardState }, { registerLLMContextTool },] = await Promise.all([
                 importExtensionModule(import.meta.url, "./tool-search.js"),
-                importExtensionModule(import.meta.url, "./tool-fetch-page.js"),
                 importExtensionModule(import.meta.url, "./tool-llm-context.js"),
             ]);
             resetSearchLoopGuardStateRef = resetSearchLoopGuardState;
             registerSearchTool(pi);
-            registerFetchPageTool(pi);
             registerLLMContextTool(pi);
         })().catch((error) => {
-            toolsPromise = null;
+            searchToolsPromise = null;
             throw error;
         });
     }
-    return toolsPromise;
+    return searchToolsPromise;
+}
+async function registerSearchTools(pi) {
+    await Promise.all([registerFetchTool(pi), registerProviderSearchTools(pi)]);
 }
 export default function (pi) {
     registerSearchProviderCommand(pi);

package/dist/resources/extensions/search-the-web/native-search.js

@@ -6,6 +6,7 @@
  */
 import { isAnthropicApi } from "@gsd/pi-ai";
 import { resolveSearchProviderFromPreferences } from "../gsd/preferences.js";
+import { resolveSearchProvider } from "./provider.js";
 /** Tool names for the Brave-backed custom search tools */
 export const BRAVE_TOOL_NAMES = ["search-the-web", "search_and_read"];
 /** All custom search tool names that should be disabled when native search is active */
@@ -166,11 +167,24 @@ export function registerNativeSearchHooks(pi) {
             pi.setActiveTools(active.filter((t) => !CUSTOM_SEARCH_TOOL_NAMES.includes(t)));
         }
         else if (!isAnthropicProvider && wasAnthropic) {
-            // Switching away from Anthropic — re-enable custom search tools (they
-            // were disabled while native search was active). If keys are missing,
-            // user sees the error rather than tools silently vanishing.
+            // Switching away from Anthropic — re-enable custom search tools that were
+            // disabled while native search was active. Only re-add the Brave/Tavily/
+            // Ollama-backed tools when a provider key is actually configured: without
+            // a key they can only return an auth error, and re-adding their names
+            // would advertise a tool the model cannot use (and, when unregistered,
+            // leak a schema-less phantom name into the tool surface). google_search
+            // is owned by its own extension (which now gates its registration on
+            // Gemini creds); re-adding its name here is harmless either way — it
+            // activates if registered, or is dropped as a no-op if not.
             const active = pi.getActiveTools();
-            const toAdd = CUSTOM_SEARCH_TOOL_NAMES.filter((t) => !active.includes(t));
+            const providerConfigured = resolveSearchProvider() !== null;
+            const toAdd = CUSTOM_SEARCH_TOOL_NAMES.filter((t) => {
+                if (active.includes(t))
+                    return false;
+                if (BRAVE_TOOL_NAMES.includes(t))
+                    return providerConfigured;
+                return true;
+            });
             if (toAdd.length > 0) {
                 pi.setActiveTools([...active, ...toAdd]);
             }
@@ -214,9 +228,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",
+];