@browserstack/mcp-server 2.2.0 → 2.2.1-beta.1

package/dist/tools/capability-registry/oauth.js

@@ -0,0 +1,176 @@
+/**
+ * Bearer-JWT auth for products whose API does not accept `Api-Token`.
+ *
+ * The registry was built on "the caller's credentials, forwarded — never a token this server
+ * mints", and this is the first product that cannot work that way. The security property is
+ * unchanged: the exchange uses the caller's own username and access key, the JWT carries
+ * their `user_id`/`group_id` as signed claims, and the scopes narrow it BELOW what the raw
+ * credential could do. What changes is that a token is now minted rather than formatted, so
+ * the sentence to hold onto is "the server grants nothing beyond the caller's own identity",
+ * not "the server mints nothing".
+ *
+ * The mint itself lives in `lib/central-oauth.ts` and is shared with `askBrowserStackAI`.
+ * This module is only the part that is the registry's: where the endpoint and scopes come
+ * from, what a product is allowed to ask for, and how a failure is worded.
+ */
+import appConfig from "../../config.js";
+import logger from "../../logger.js";
+import { CentralAuthError, mintCentralToken, normaliseScopes, } from "../../lib/central-oauth.js";
+import { InvocationError } from "./index-loader.js";
+/**
+ * Where a central-OAuth JWT is minted, when a product does not name its own.
+ *
+ * Staging, for anyone setting the override:
+ *   CAPABILITY_REGISTRY_AUTH_TOKEN_URL = https://auth-preprod.bsstag.com/oauth2/v2/token
+ */
+export const DEFAULT_AUTH_TOKEN_URL = "https://auth.browserstack.com/oauth2/v2/token";
+/**
+ * The default scope set, and why it is a PAIR.
+ *
+ * `ai_agent` is the scope a product's gate matches on. `oauth_user_profile` is not extra
+ * authority — it is what makes the scope obtainable through the username+access_key flow at
+ * all, and this is measured rather than assumed: `ai_agent` alone comes back
+ * `400 invalid_request`, the pair mints, and the granted token's `scopes` claim carries both.
+ *
+ * Deliberately NOT `ask-browserstack`'s `CENTRAL_SCOPE`, which pairs `ai_agent_notify`
+ * instead — Atlas names its own so that changing this one cannot silently change what Atlas
+ * is authorised for.
+ */
+export const DEFAULT_SCOPES = ["ai_agent", "oauth_user_profile"];
+/**
+ * Small, because the registry uses the token for ONE HTTP call.
+ *
+ * Nothing here holds it for the length of a run the way Atlas does, so this only has to
+ * cover clock skew and the flight time of the request it opens.
+ */
+export const REFRESH_SKEW_MS = 60_000;
+/**
+ * Hosts a PRODUCT INDEX may name as its token endpoint.
+ *
+ * The index is a data file that ships to public npm and is read at startup. Letting it name
+ * an arbitrary `token_url` would let a file decide where the caller's username and access key
+ * get POSTed — so the file declares intent and this list bounds it. An operator setting the
+ * environment variable is a deliberate act and is trusted; shipping an index is not.
+ */
+const ALLOWED_TOKEN_HOSTS = [
+    "auth.browserstack.com",
+    "auth-preprod.bsstag.com",
+];
+/** Announced once per distinct resolution, so a wrong endpoint is a log line, not a deduction. */
+const announced = new Set();
+/** For tests, and for anything that legitimately re-resolves. */
+export function resetOAuthAnnouncements() {
+    announced.clear();
+}
+function announce(product, url, source) {
+    const line = `${product}|${url}|${source}`;
+    if (announced.has(line))
+        return;
+    announced.add(line);
+    logger.info("capability registry: %s mints its token at %s (source: %s)", product, url, source);
+}
+function assertMintable(url, product) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new InvocationError(`product '${product}' declares a token_url that is not a URL: ${JSON.stringify(url)}`);
+    }
+    // Same rule as the product call itself: credentials are never attached over plaintext.
+    if (parsed.protocol !== "https:") {
+        throw new InvocationError(`product '${product}' declares a token_url that is not https. The caller's ` +
+            `credentials are sent to it, so plaintext is refused.`);
+    }
+    if (!ALLOWED_TOKEN_HOSTS.includes(parsed.hostname)) {
+        throw new InvocationError(`product '${product}' declares a token_url on an unrecognised host ` +
+            `'${parsed.hostname}'. An index may only mint against ${ALLOWED_TOKEN_HOSTS.join(" or ")}; ` +
+            `set CAPABILITY_REGISTRY_AUTH_TOKEN_URL if this deployment really does mint elsewhere.`);
+    }
+    return url.replace(/\/+$/, "");
+}
+/**
+ * Three rungs: the operator's override, then the product's declaration, then the built-in.
+ *
+ * Matching `base_url`, where config is explicitly "a default, not the last word" — a
+ * deployment pointed at staging must not be overruled by whatever an index happens to carry.
+ */
+export function resolveTokenUrl(product, auth) {
+    const explicit = process.env.CAPABILITY_REGISTRY_AUTH_TOKEN_URL;
+    if (explicit && explicit.trim()) {
+        const url = explicit.trim().replace(/\/+$/, "");
+        announce(product, url, "env");
+        return url;
+    }
+    if (auth?.token_url && auth.token_url.trim()) {
+        const url = assertMintable(auth.token_url.trim(), product);
+        announce(product, url, "index");
+        return url;
+    }
+    announce(product, DEFAULT_AUTH_TOKEN_URL, "default");
+    return DEFAULT_AUTH_TOKEN_URL;
+}
+/** Two rungs. A scope does not vary by deployment the way a host does, so there is no env one. */
+export function resolveScope(auth) {
+    const declared = auth?.scopes;
+    if (Array.isArray(declared) && declared.length > 0)
+        return normaliseScopes(declared);
+    return normaliseScopes([...DEFAULT_SCOPES]);
+}
+/**
+ * A failure to mint is not a failure of the product, and must not read like one.
+ *
+ * Nothing from the token endpoint's body reaches these messages — it can echo the access key
+ * straight back. Only the classification and the status do.
+ */
+function toInvocationError(error, product) {
+    if (!(error instanceof CentralAuthError))
+        return error;
+    const prefix = `token_mint_failed: could not sign in to '${product}'`;
+    switch (error.kind) {
+        case "no_credentials":
+            return new InvocationError(`${prefix}: BrowserStack username and access key are required`);
+        case "unreachable":
+            return new InvocationError(`${prefix}: BrowserStack auth could not be reached. This is a connectivity or ` +
+                `auth-server problem, not a problem with your credentials. Nothing was sent to ` +
+                `'${product}'.`);
+        case "server_error":
+            return new InvocationError(`${prefix}: BrowserStack auth is unavailable (HTTP ${error.status}). YOUR ` +
+                `CREDENTIALS ARE NOT THE PROBLEM — a 5xx is the auth service failing, not a ` +
+                `rejection. Nothing was sent to '${product}'.`);
+        case "refused_scope":
+            return new InvocationError(`${prefix}: BrowserStack auth would not issue a token for the scope ` +
+                `"${error.scope}" (HTTP ${error.status}). YOUR CREDENTIALS ARE NOT THE PROBLEM — ` +
+                `this is a provisioning problem and the scope has to be enabled for this account ` +
+                `or application. This server will NOT retry with a weaker scope. Nothing was ` +
+                `sent to '${product}'.`);
+        case "refused_credentials":
+            return new InvocationError(`${prefix}: your BrowserStack credentials were rejected by BrowserStack auth ` +
+                `(HTTP ${error.status}). Nothing was sent to '${product}'.`);
+        default:
+            return new InvocationError(`${prefix}: BrowserStack auth answered HTTP ${error.status} without issuing a ` +
+                `token. Nothing was sent to '${product}'.`);
+    }
+}
+/**
+ * The Bearer value for one invocation.
+ *
+ * Cached per user for the life of the token when this process serves one caller, and not at
+ * all when it serves many — `mintCentralToken` is handed `cacheEnabled` rather than deciding
+ * for itself, because the rule is about THIS deployment, not about the mint.
+ */
+export async function bearerToken(product, auth, credentials, transport) {
+    try {
+        return await mintCentralToken({
+            url: resolveTokenUrl(product, auth),
+            scope: resolveScope(auth),
+            credentials,
+            transport,
+            refreshSkewMs: REFRESH_SKEW_MS,
+            cacheEnabled: !appConfig.REMOTE_MCP,
+        });
+    }
+    catch (error) {
+        throw toInvocationError(error, product);
+    }
+}

package/dist/tools/capability-registry/register.js

@@ -13,6 +13,7 @@
  * enforced HERE rather than on a client-side hint — which is the one thing a separate
  * read/write tool pair was buying.
  */
+import { signRouting, readRouting } from "./routing-token.js";
 import { z } from "zod";
 import logger from "../../logger.js";
 import { trackMCP } from "../../lib/instrumentation.js";
@@ -21,7 +22,7 @@ import { redact } from "./redact.js";
 import { fetchTransport } from "./egress.js";
 import { CapabilityRegistry, InvocationError, resolveResponses, } from "./index-loader.js";
 import { invoke } from "./resolve.js";
-import { ambiguousProducts, isBrowseQuery, searchCapabilities, singular, terms, vocabularyOf, } from "./search.js";
+import { ambiguousProducts, productAnchors, isBrowseQuery, searchCapabilities, singular, terms, vocabularyOf, } from "./search.js";
 export const PERMISSION_VALUES = ["not_asked", "granted", "denied"];
 /**
  * The search-side twin of `user_permission`: did a human choose the product, or did you?
@@ -155,6 +156,10 @@ export function addCapabilityRegistryTools(server, deps, config) {
         // likeliest refusal of all, and it was landing in the generic bucket.
         if (message.startsWith("capability_disabled:"))
             return "capability_disabled";
+        // Auth failed before the product was ever called, so it is not the product's 401 and
+        // must not be counted as one. oauth.ts prefixes every one of these.
+        if (message.startsWith("token_mint_failed:"))
+            return "token_mint_failed";
         if (message.startsWith("missing required parameter"))
             return "missing_parameter";
         if (/is not a usable path value/.test(message))
@@ -187,15 +192,122 @@ export function addCapabilityRegistryTools(server, deps, config) {
     tools.listProducts = server.tool("listProducts", "List the BrowserStack products this surface can reach: what each one does, the " +
         "entities it models, and a line saying what each entity is. START HERE — " +
         "searchCapability needs a product, and this is what tells you which one. If two " +
-        "products could both fit the task, ask the user rather than choosing for them.", {}, {
+        "products could both fit the task, ask the user rather than choosing for them. " +
+        "ALWAYS pass the user's request, in their own words, as `query`: the answer then " +
+        "says outright whether the products clash over the words in it. WHEN IT REPORTS A " +
+        "CLASH — two products claiming the same word for different things — ASK THE USER " +
+        "WHICH PRODUCT THEY MEAN AND WAIT FOR THEIR ANSWER BEFORE SEARCHING OR INVOKING " +
+        "ANYTHING. The response carries the question to put to them and what the shared " +
+        "word means in each product. Choosing for them, or searching each product in turn " +
+        "and merging the results, is the failure this call exists to prevent.", {
+        query: z
+            .string()
+            .optional()
+            .describe("The user's request, in their own words. With it the response carries a " +
+            "`routing` block saying whether the products share the vocabulary this " +
+            "request uses — and, when they do, the question to put to the user before " +
+            "searching either product."),
+    }, {
         title: "List Capability Products",
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
-    }, async () => {
+    }, async ({ query }) => {
         track("listProducts");
+        // THE CLASH, STATED RATHER THAN LEFT TO BE NOTICED. The entity lists below carry
+        // the evidence — `report` under two products — but reading two lists and spotting
+        // the overlap is work an agent skips when it already has a product in mind. So the
+        // overlap is computed here and put at the top, with the question already written:
+        // the cheap failure is picking one silently, and this is the call that precedes it.
+        const ambiguity = query
+            ? ambiguousProducts(registry.index.products, query)
+            : { products: [], terms: [] };
+        // A CLASH ANNOUNCED HERE BINDS THE NEXT SEARCH. Reporting it and then letting the
+        // very next call through was the gap the measured runs walked through: the agent
+        // read the clash, searched one product and then the other, and asked only
+        // afterwards. The gate downstream judges the caller's paraphrase when no user words
+        // are quoted, and a paraphrase carries none of the shared words that caused this —
+        // so the refusal never fired. Opening a token here makes the question outlive the
+        // call that raised it, and `user_words` is what closes it.
+        // THE VERDICT TRAVELS WITH THE CALLER. Signed here, read back by the search — which
+        // is how the search can know what this call concluded about the whole request
+        // without the server keeping a note between the two.
+        const listingToken = query
+            ? signRouting(ambiguity.products.length > 1
+                ? { verdict: "clash", terms: ambiguity.terms }
+                : ambiguity.unknown
+                    ? { verdict: "blank" }
+                    : { verdict: "settled", product: ambiguity.settled })
+            : undefined;
+        const routing = ambiguity.products.length > 1
+            ? {
+                verdict: "products_clash",
+                note: `These products clash over ${ambiguity.terms.map((t) => `'${t}'`).join(", ")} — ` +
+                    `the same word means something different in ${ambiguity.products.join(" and ")}. ` +
+                    "ASK THE USER which they mean before searching or invoking anything; do not " +
+                    "search each product in turn and merge the results. Searching before you " +
+                    "ask will be refused: send the user's answer in `user_words` with this " +
+                    "`routing_token`.",
+                routing_token: listingToken,
+                shared_terms: ambiguity.terms,
+                products: ambiguity.products,
+                question: `Which product do you mean — ${ambiguity.products.join(" or ")}?`,
+                senses: ambiguity.products.map((name) => ({
+                    product: name,
+                    means: ambiguity.terms
+                        .map((term) => {
+                        const entities = registry.index.products[name]?.entities ?? {};
+                        const key = Object.keys(entities).find((candidate) => [
+                            candidate,
+                            ...(entities[candidate].aliases ?? []),
+                        ].some((word) => terms(word).map(singular).join(" ") === term));
+                        return key
+                            ? {
+                                term,
+                                entity: key,
+                                description: entities[key].description,
+                            }
+                            : undefined;
+                    })
+                        .filter(Boolean),
+                })),
+            }
+            : query && ambiguity.unknown
+                ? {
+                    verdict: "no_vocabulary",
+                    note: "Nothing in this request names a product, or any word that belongs to " +
+                        "one — so there is no evidence here about which product is meant. This " +
+                        "is the LEAST settled a request can be, not the most. ASK THE USER " +
+                        "which product they mean before searching or invoking anything. " +
+                        "Searching before you ask will be refused: send their answer in " +
+                        "`user_words` with this `routing_token`.",
+                    routing_token: listingToken,
+                    question: `Which product do you mean — ${registry
+                        .productNames()
+                        .join(" or ")}?`,
+                }
+                : query
+                    ? {
+                        verdict: "no_clash",
+                        note: ambiguity.settled
+                            ? `This request names words only ${ambiguity.settled} claims` +
+                                (ambiguity.because?.length
+                                    ? ` (${ambiguity.because.map((t) => `'${t}'`).join(", ")})`
+                                    : "") +
+                                `, so it settles on ${ambiguity.settled} without asking. SEARCH ` +
+                                `${ambiguity.settled}; the other products do not answer this request.`
+                            : "No word in this request is claimed by more than one product, so the " +
+                                "entity lists below settle it without asking.",
+                        routing_token: listingToken,
+                        ...(ambiguity.settled ? { product: ambiguity.settled } : {}),
+                        ...(ambiguity.because?.length
+                            ? { deciding_terms: ambiguity.because }
+                            : {}),
+                    }
+                    : undefined;
         return ok({
+            ...(routing ? { routing } : {}),
             products: registry.productNames().map((name) => ({
                 name,
                 summary: registry.index.products[name].summary,
@@ -260,10 +372,11 @@ export function addCapabilityRegistryTools(server, deps, config) {
         return ok({ product, entity, ...doc });
     });
     tools.searchCapability = server.tool("searchCapability", "Find endpoints this surface can call, by plain language, within ONE product. " +
-        `You must say which: ${productList}. If the task does not name it unambiguously, ` +
-        "call listProducts first — it returns what each product does, the entities each " +
-        "models, and what every entity means, which is what settles the choice. Where two " +
-        "products use the same word for different things, ask the user rather than picking. " +
+        "CALL listProducts FIRST, passing the user's request as its `query`: it names the " +
+        "products, says whether they clash over the words in that request, and gives you " +
+        "the question to ask when they do. You need it anyway — `product` here takes a name " +
+        "exactly as listProducts spells it. Where two products use the same word for " +
+        "different things, ask the USER and wait for an answer rather than picking. " +
         "Search matches the product's OWN words, not synonyms. When your words are not the " +
         "product's, the response says so: `weak_match: true` with a `suggested_vocabulary` " +
         "map of the product's entities and their aliases. Results are still returned, but " +
@@ -306,19 +419,44 @@ export function addCapabilityRegistryTools(server, deps, config) {
         // not (run, project, report, result, folder, workspace, execution, history), where
         // the old behaviour was to silently pick whichever product ranked higher. A wasted
         // round trip against a silent wrong-product answer is not a close trade.
-        product: productArg().describe(`Which product to search: ${productList}. Call listProducts if the task does ` +
-            `not make it obvious, and ask the user when two products could both fit.`),
-        // REQUIRED, and self-reported, exactly like `user_permission` on a write. The
-        // server cannot see whether you asked anyone; what it can do is refuse to answer a
-        // question only the user can settle, and make claiming otherwise an explicit act
-        // rather than an omission.
-        product_choice: z
-            .enum(PRODUCT_CHOICE_VALUES)
-            .describe("'user_confirmed' only when the user named the product, or the task names it " +
-            "unmistakably. 'not_asked' otherwise — then a query that could mean either " +
-            "product is refused and told what to ask, instead of being answered for the " +
-            "wrong one. Never search each product in turn and merge the results: that is " +
-            "the guess this argument exists to prevent."),
+        // A FREE STRING, NOT AN ENUM, AND DELIBERATELY SO — this is the only argument on
+        // this surface that is. An enum publishes the product names in the schema, which
+        // every client shows the model before it calls anything, so a model that has never
+        // called listProducts already knows `tm` and `tra` exist and picks one. Measured:
+        // on the requests that still routed silently, listProducts was never called at all
+        // — there was nothing left to learn from it. Withholding the names makes the
+        // discovery call the only way to obtain one, and discovery is where the clash gets
+        // reported. The cost is losing client-side validation of a typo; an unknown name is
+        // refused here instead, by a message that names listProducts.
+        product: z
+            .string()
+            .describe("Which product to search, named exactly as listProducts spells it. Call " +
+            "listProducts with the user's request to get the name — and to find out " +
+            "whether the products clash over it, in which case ask the user first."),
+        // `product_choice` USED TO LIVE HERE, AND WAS ITS OWN DEFEAT.
+        //
+        // A required enum of 'user_confirmed' | 'not_asked' publishes, in the schema every
+        // client shows the model before it calls anything, the exact string that opens the
+        // gate. Measured on the prompts that still routed silently: the caller wrote
+        // `user_confirmed` on every single one, with no user input behind any of them. A
+        // flag the caller fills in about itself can always be filled in; there is no wording
+        // of it that makes it true. What replaced it is a token this server mints and the
+        // caller cannot guess, plus `user_words`, which is a claim the index can test.
+        routing_token: z
+            .string()
+            .optional()
+            .describe("The `routing_token` from the last listProducts call or product_ambiguous " +
+            "refusal — it carries what that step concluded about the user's request, " +
+            "signed. Always pass the most recent one. When it reports a clash, send the " +
+            "user's answer in `user_words` alongside it; neither works alone."),
+        user_words: z
+            .string()
+            .optional()
+            .describe("The USER'S OWN words, verbatim, that settle which product this is — either " +
+            "the product's name or a term only one product uses ('quality gate', 'test " +
+            "plan'). Quote them; do not paraphrase, and do not write words the user did " +
+            "not say. When a query could mean either product this is what lifts the " +
+            "refusal, because it is checked against the index rather than taken on trust."),
         mode: z
             .enum(["read", "write", "destructive"])
             .optional()
@@ -335,7 +473,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
-    }, async ({ query, entity, product, product_choice, mode, limit, offset }) => {
+    }, async ({ query, entity, product, routing_token, user_words, mode, limit, offset, }) => {
         // THE GATE. Nothing here can tell whether a human was asked — same as the write
         // gate, which also takes the caller's word. What it can do is refuse to answer a
         // question that is genuinely the user's, so that answering it anyway takes a
@@ -349,18 +487,106 @@ export function addCapabilityRegistryTools(server, deps, config) {
         // contains no word to be ambiguous about — `*` names nothing — so there is nothing
         // to ask, and asking anyway would block the one query whose whole purpose is to
         // show what a product contains.
-        if (product_choice !== "user_confirmed" &&
-            !entity &&
-            !isBrowseQuery(query)) {
-            const ambiguity = ambiguousProducts(registry.index.products, query);
-            if (ambiguity.products.length > 1) {
-                // EVERYTHING NEEDED TO ASK, IN THE REFUSAL. Telling the agent to go and call
+        // `product_choice` is the caller describing itself, and a caller that wants to
+        // proceed says user_confirmed — measured at 103 of 183 ambiguous prompts with no
+        // user input behind it, which skipped this gate entirely. So under the flag the
+        // ambiguity check runs whatever the flag says, and what lifts it is `user_words`:
+        // the user's own text, checked here against the index. Quoting the conversation is
+        // a claim the server can test; a boolean is not.
+        // `entity` USED TO BYPASS THIS TOO, and had no business doing so. An entity narrows
+        // WITHIN a product; it says nothing about WHICH product, and the four names both
+        // products carry — project, report, test_run, comment — are precisely the ones the
+        // clash is about. `entity: "report"` alongside a guessed product is the silent pick
+        // this gate exists to stop, stated more confidently, so it skipped the check at the
+        // exact moment the check mattered.
+        // `product` is a free string now, so an unknown name reaches the handler. Refuse it
+        // where the caller can act on it: naming listProducts, which is where the real names
+        // come from, rather than returning an empty search that reads as "nothing matched".
+        if (!registry.index.products[product]) {
+            return refuse("searchCapability", "unknown_product", `No product named '${product}'. Call listProducts — passing the user's request ` +
+                "as `query` — for the names, and for whether the products clash over it.", {}, { product });
+        }
+        if (!isBrowseQuery(query)) {
+            // JUDGE THE USER'S WORDS, NOT THE AGENT'S REWRITE.
+            //
+            // `query` is the caller's paraphrase into product vocabulary, so the caller
+            // decides, through its own phrasing, whether this check fires: "what did the last
+            // report say?" became "list saved reports", and `saved report` is tra-only, so the
+            // shared word the user actually said stopped being examined. It is also the escape
+            // from a refusal — reword and try again, which is what the measured runs did. The
+            // user's text is the one input the caller cannot rewrite without quoting something
+            // different, and `productAnchors` checks what it quotes against this index.
+            const subject = user_words?.trim() ? user_words : query;
+            const ambiguity = ambiguousProducts(registry.index.products, subject);
+            // ALWAYS, NOT ONLY UNDER THE FLAG. With the self-reported flag gone, quoting the
+            // user is the only way past a clash, so the check that reads the quote has to run
+            // on both paths — otherwise the default path refuses with no way out at all. The
+            // flag now governs the stricter refusals (a blank request, a clash still open),
+            // not whether the user's own words count.
+            const anchor = productAnchors(registry.index.products, user_words);
+            // WHAT THE ROUTING STEP CONCLUDED, READ BACK OFF THE CALLER. The token is signed
+            // here and verified by recomputation, so the server keeps no note between the two
+            // calls — and the caller cannot write one, edit the product inside it, or hold one
+            // without having made the routing call that issues it.
+            const routed = readRouting(routing_token);
+            // A clash the routing step already reported is only cleared by the user's own
+            // words: the token shows the question was put, `user_words` says what came back.
+            // Neither works alone — a token on its own is just proof of having been refused.
+            const answered = routed?.verdict !== "settled" &&
+                anchor.products.length === 1 &&
+                anchor.products[0] === product;
+            // One product anchored, and it is the one being searched: the user settled it.
+            // A routing step that already settled on this product counts the same way — it
+            // read the user's whole request, which is more than the fragment quoted here.
+            const settled = (anchor.products.length === 1 && anchor.products[0] === product) ||
+                (routed?.verdict === "settled" && routed.product === product);
+            // NOTHING TO ASK WHEN THERE IS NOTHING TO CHOOSE BETWEEN. A registry serving one
+            // product cannot route a request to the wrong one, so every refusal below is a
+            // question with a single possible answer — pure obstruction.
+            const routable = registry.productNames().length > 1;
+            // A CLASH THE CALLER IS CARRYING IS STILL OPEN UNTIL IT IS ANSWERED, whatever this
+            // call's wording looks like. It has to outlive a REWORDING of the request — the
+            // escape it exists to close — while leaving a genuinely different request alone:
+            // "bulk delete test cases" names a thing only one product has, and blocking it
+            // because something earlier was ambiguous is obstruction, not routing.
+            const reopened = routable &&
+                !settled &&
+                !answered &&
+                ambiguity.settled !== product &&
+                (routed?.verdict === "clash" || routed?.verdict === "blank");
+            // THE WORDS POINT SOMEWHERE ELSE, WHICH IS EVIDENCE, NOT NOISE. A request whose
+            // own vocabulary settles on one product, sent as a search of the OTHER one, is the
+            // silent wrong pick this gate exists to catch — and it used to pass, because the
+            // checks above only ask whether the request settles, never whether it settles on
+            // what is being asked for. `product` is the caller's conclusion; the words are the
+            // evidence, and when they disagree the evidence is the thing to go on. The refusal
+            // already had the sentence for it ("the words you quoted point at X, not Y") and
+            // nothing could reach it.
+            const mismatch = routable && !!ambiguity.settled && ambiguity.settled !== product;
+            // NOTHING RECOGNISED IS NOT PERMISSION TO PICK. A request carrying no product's
+            // vocabulary is the least settled kind there is, and it used to pass this gate
+            // untouched because there was no shared word in it to object to.
+            const blank = routable && ambiguity.unknown && !settled;
+            if (routable &&
+                (ambiguity.products.length > 1 || reopened || blank || mismatch) &&
+                !settled &&
+                !answered) {
+                const token = signRouting(ambiguity.products.length > 1
+                    ? { verdict: "clash", terms: ambiguity.terms }
+                    : mismatch
+                        ? { verdict: "settled", product: ambiguity.settled }
+                        : { verdict: "blank" });
+                // WHAT TO ASK, NOT JUST THAT ASKING IS NEEDED. Sending the caller back to
                 // listProducts costs a round trip and still leaves it composing a question out
                 // of nothing — so it tends to guess instead, which is the behaviour being
-                // stopped. What makes the choice answerable is what each product calls the
-                // shared word and what it means THERE: tm's project owns folders and test
-                // cases, Load Testing's does not.
-                const options = ambiguity.products.map((name) => {
+                // stopped. What makes the choice answerable is what each product CALLS the
+                // shared word and what it means there.
+                const choices = ambiguity.products.length
+                    ? ambiguity.products
+                    : mismatch
+                        ? [ambiguity.settled, product]
+                        : registry.productNames();
+                const options = choices.map((name) => {
                     const entities = registry.index.products[name]?.entities ?? {};
                     const senses = ambiguity.terms
                         .map((term) => {
@@ -380,19 +606,41 @@ export function addCapabilityRegistryTools(server, deps, config) {
                         ...(senses.length ? { shared_terms: senses } : {}),
                     };
                 });
-                return refuse("searchCapability", "product_ambiguous", `'${query}' could mean ${ambiguity.products.join(" or ")} — ` +
-                    `${ambiguity.terms.map((t) => `'${t}'`).join(", ")} ` +
-                    `${ambiguity.terms.length === 1 ? "belongs" : "belong"} to both. ` +
-                    "Put the choice in `clarify` to the USER in their own terms, wait for an " +
-                    "answer, then resend with product_choice='user_confirmed'. Do NOT search " +
-                    "each product in turn and merge the results — that answers the question " +
-                    "instead of asking it.", {
+                const named = anchor.products.length > 0;
+                return refuse("searchCapability", "product_ambiguous", (blank
+                    ? `Nothing in '${subject}' names a product, or any word that belongs to ` +
+                        "one, so there is no evidence here about which one is meant — that is " +
+                        "the least settled a request can be, not the most. "
+                    : mismatch
+                        ? `'${subject}' names words only ${ambiguity.settled} claims` +
+                            (ambiguity.because?.length
+                                ? ` (${ambiguity.because.map((t) => `'${t}'`).join(", ")})`
+                                : "") +
+                            `, so the request points at ${ambiguity.settled}, not ${product}. ` +
+                            "Search the product the words name, or — if the user meant " +
+                            `${product} — get them to say so and quote them. `
+                        : `'${subject}' could mean ${ambiguity.products.join(" or ")} — ` +
+                            `${ambiguity.terms.map((t) => `'${t}'`).join(", ")} ` +
+                            `${ambiguity.terms.length === 1 ? "belongs" : "belong"} to both. `) +
+                    (named
+                        ? `The words you quoted (${anchor.terms.map((t) => `'${t}'`).join(", ")}) ` +
+                            `point at ${anchor.products.join(" and ")}, not ${product}. `
+                        : user_words
+                            ? "Nothing in the words you quoted names a product or a term only one " +
+                                "product uses. "
+                            : "Send `user_words` — the user's OWN words naming the product, or a " +
+                                "term only one product uses — or ask them. ") +
+                    "Put the choice to the USER in their own terms, wait for an answer, then " +
+                    "resend with their words in `user_words` AND `routing_token` set to the " +
+                    "token below. Rewording this query will not get past here. Do NOT search " +
+                    "each product in turn and merge the results.", {
+                    routing_token: token,
                     clarify: {
-                        question: `Which product do you mean — ${ambiguity.products.join(" or ")}?`,
+                        question: `Which product do you mean — ${choices.join(" or ")}?`,
                         shared: ambiguity.terms,
                         options,
                     },
-                }, { product: ambiguity.products.join("+") });
+                }, { product: ambiguity.products.join("+") || "none" });
             }
         }
         const { hits, weak, top_matched, ...rest } = searchCapabilities(registry.index.products, query, {
@@ -684,7 +932,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
                     return refuse("invokeCapability", "change_summary_missing", "change_summary is required: state what will change", undefined, identity);
                 }
             }
-            const result = await invoke(capability, args, await deps.baseUrlFor(product), deps.credentialsFor(), transport, registry.index.products[product]?.auth);
+            const result = await invoke(capability, args, await deps.baseUrlFor(product), deps.credentialsFor(), transport, registry.index.products[product]?.auth, product);
             // The one row for a completed invoke. invoke() returns a 4xx/5xx rather than
             // throwing, so `success` keeps its tool-level meaning and these two fields carry
             // whether the product call worked. Status 0 means it could not be reached.

package/dist/tools/capability-registry/resolve.d.ts

@@ -35,4 +35,4 @@ export interface InvokeResult {
         error?: string;
     };
 }
-export declare function invoke(capability: Capability, args: GroupedArguments, baseUrl: string, credentials: Credentials, transport: Transport, auth?: AuthScheme): Promise<InvokeResult>;
+export declare function invoke(capability: Capability, args: GroupedArguments, baseUrl: string, credentials: Credentials, transport: Transport, auth?: AuthScheme, product?: string): Promise<InvokeResult>;