@bridge_gpt/mcp-server 0.2.36 → 0.2.37

package/README.md

@@ -397,7 +397,7 @@ An entry with no trailing `serve` still starts the server — bare invocation me
 <summary><strong>Upgrading Bridge</strong></summary>
 
 ```bash
-npx -y @bridge_gpt/mcp-server upgrade
+npx -y @bridge_gpt/mcp-server@latest --upgrade
 ```
 
 `upgrade` fetches the latest published version, refreshes your scaffolded slash
@@ -405,8 +405,34 @@ commands, agents, and pipelines, updates the version pin in your MCP config, and
 opens a session so you can reconnect. It is also available as the
 `/upgrade-bridge` slash command.
 
-The server checks for updates on startup and notes a newer version in your editor's
-MCP output log. That check is cached for a day and never blocks startup.
+Use the `@latest` form. It applies to the short-lived *upgrader* process: without
+it, npx may reuse a cached older copy of the package and "upgrade" you with the
+build you are trying to replace. The exact `MAJOR.MINOR.PATCH` pin the upgrader
+writes into your MCP config is deliberately different — host configs stay pinned
+to an exact release so a project's server is reproducible.
+
+`upgrade` reports **per config file**, because a project can have several
+(`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`) and they can disagree:
+
+```
+Launcher pins:
+  .mcp.json: 0.2.16 -> 0.2.36
+  .cursor/mcp.json: already 0.2.36
+```
+
+When every applicable launcher pin was already at the target, it prints
+`Already up-to-date.` — that status comes from comparing your configs, not from
+the version of the CLI process. A non-zero exit means the upgrade did **not**
+converge (an unreadable config, a launcher carrying a version range the upgrader
+must not rewrite, a competing local install it could not remove, or a pin that
+failed post-write verification); nothing is reported as complete in that case.
+
+The server checks for updates on startup. The check is cached for a day and never
+blocks startup. When a newer version is known, it surfaces in two places you do
+not have to go looking for: a one-line warning on the server's **stderr**, and a
+short advisory attached to the ordinary `tools/list` response so the agent in the
+session can see that some tools may be missing or renamed in the older build.
+Neither requires calling `ping` or `doctor`.
 
 Re-running `install` on an already-configured project is safe: it refreshes the
 scaffolded files without overwriting your stored credential unless you pass
@@ -559,6 +585,12 @@ Good to know, but not needed every day.
 - **How to use it:** Ask your agent to resume the full-automation chain, naming the run to continue.
 - **Flags:** None.
 
+**15. Update Ticket Description**
+- **What it does:** Rewrites a ticket's description with AI, using the ticket's own content and its reference material. A rewrite that changes more than 60% of the description is held for review instead of applied.
+- **When it's useful:** (Refinement) When a ticket has accumulated comments, attachments, or links and its description no longer reflects them.
+- **How to use it:** Ask your agent — "Update the description for BAPI-123."
+- **Flags:** None. Poll the ticket's state for the outcome; if the update was held for review, read the proposal instead of applying it blind.
+
 ### Now and then
 
 Useful once in a while.
@@ -611,7 +643,13 @@ Useful once in a while.
 - **How to use it:** Ask your agent — "Download the design mockups attached to BAPI-123 into my docs folder," or "Attach build-log.txt to BAPI-123."
 - **Flags:** Choose the direction (download from the ticket, or upload to it) and, for a download, where the files should land.
 
-**9. Estimate Epic**
+**9. Estimate Ticket**
+- **What it does:** Estimates the development effort for one ticket. Use Estimate Epic instead for a whole epic or a named group of tickets.
+- **When it's useful:** (Refinement) When you need a size for a single ticket before committing to it.
+- **How to use it:** Ask your agent — "Estimate BAPI-123."
+- **Flags:** Ask for a fresh estimate to regenerate rather than reuse a stored one.
+
+**10. Estimate Epic**
 - **What it does:** Estimates an epic, or an explicit group of tickets you name.
 - **When it's useful:** (Architecture | Refinement) When you need a sizing pass across an epic, or across a set of tickets you name explicitly.
 - **How to use it:** `/estimate-epic BAPI-123`
@@ -756,7 +794,7 @@ Without this, only the diagnostic tools are registered.
 
 ### Tools
 
-All SFCC tools are read-only and target a developer sandbox. Oversized responses are automatically saved to `BAPI_DOCS_DIR/sfcc/` and previewed inline.
+All SFCC tools are read-only and target a developer sandbox. An oversized response is saved in full to `BAPI_DOCS_DIR/sfcc/` and replaced by a parseable JSON descriptor — `truncated: true`, the `saved_path` it was written to, and the `page` metadata (`returned`, `total` when OCAPI supplied one, `has_more`) — so the collection metadata survives even though the data itself is on disk. If that save fails, the complete payload is returned inline instead, still as parseable JSON.
 
 **Diagnostics** (always available, no profile needed)
 - `sfcc_setup_status` — report on every prerequisite: Bridge API key, repo name, `version` config, `dw.json` presence/uniqueness, AM (OCAPI) token acquisition, and the independent **SFCC Log Query (WebDAV)** capability that gates `sfcc_log_query`.
@@ -764,7 +802,7 @@ All SFCC tools are read-only and target a developer sandbox. Oversized responses
 
 **System object model** (needs the `sfcc` profile)
 - `system_object_list` — list system object types (Product, Order, Customer, …).
-- `system_object_get` — fetch one type's definition, optionally with its full attribute definitions (`expand_attribute_definitions`).
+- `system_object_get` — fetch one system object type's definition.
 - `system_object_attribute_search` — search a type's attribute definitions; prefer this over a full dump when hunting a specific `c_` custom attribute.
 
 **Custom object definitions** (needs the `sfcc` profile)

package/build/base-url.js

@@ -0,0 +1,79 @@
+/**
+ * Pure Bridge API base-URL normalization and validation (BAPI-727).
+ *
+ * Extracted so the executor's credential resolution and the `mcp-invoke` shim can
+ * share ONE definition of "normalized base URL" without `mcp-invoke` importing
+ * executor runtime behavior (`executor/credentials.ts` pulls in the executor deps
+ * types and the credential store, neither of which the shim should depend on).
+ *
+ * Everything here is pure: no filesystem, no process, no network, no environment.
+ * Validation messages name the flag and the reason ONLY — never the supplied URL,
+ * which can carry embedded credentials in its userinfo component.
+ */
+/**
+ * Trim, strip every trailing slash, and treat an empty result as absent.
+ *
+ * This is the executor's long-standing normalization, moved verbatim so the value
+ * a worker registration carries is byte-identical to the one the executor itself
+ * uses for its HTTP calls.
+ */
+export function normalizeBaseUrlCandidate(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const normalized = raw.trim().replace(/\/+$/, "");
+    return normalized.length > 0 ? normalized : null;
+}
+/** Fixed, secret-free explanation for each rejection reason. */
+const REJECTION_TEXT = {
+    empty: "value is empty",
+    "not-absolute-http-url": "value is not an absolute URL",
+    "unsupported-scheme": "only http: and https: URLs are supported",
+    "missing-hostname": "URL has no hostname",
+    "embedded-credentials": "URL must not embed a username or password",
+};
+/**
+ * Human-readable rejection message for a flag. Interpolates only the flag name and
+ * a fixed reason — deliberately NOT the rejected value, so a URL containing
+ * `https://user:secret@host` can never reach an error string, usage text, or log.
+ */
+export function describeBaseUrlRejection(flag, reason) {
+    return `Invalid ${flag}: ${REJECTION_TEXT[reason]}`;
+}
+/**
+ * Strictly validate a base URL supplied on a command line: it must be a non-empty,
+ * absolute `http:`/`https:` URL with a hostname and no embedded user information.
+ * The accepted value is returned normalized by
+ * {@link normalizeBaseUrlCandidate} so it matches the executor's own form.
+ */
+export function validateHttpBaseUrl(raw) {
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        return { ok: false, reason: "empty" };
+    }
+    let parsed;
+    try {
+        parsed = new URL(raw.trim());
+    }
+    catch {
+        // A relative value ("/api", "api.example.test/x") lands here: the WHATWG URL
+        // constructor requires an absolute URL when no base is supplied.
+        return { ok: false, reason: "not-absolute-http-url" };
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return { ok: false, reason: "unsupported-scheme" };
+    }
+    // Defensive: for http/https the WHATWG parser already rejects an empty
+    // authority above (`http://` throws), so this branch is not reachable through
+    // those schemes today. It is kept because "must have a hostname" is the real
+    // invariant, and relying on a parser implementation detail to enforce it would
+    // be fragile.
+    if (parsed.hostname.length === 0) {
+        return { ok: false, reason: "missing-hostname" };
+    }
+    if (parsed.username.length > 0 || parsed.password.length > 0) {
+        return { ok: false, reason: "embedded-credentials" };
+    }
+    const normalized = normalizeBaseUrlCandidate(raw);
+    if (normalized === null)
+        return { ok: false, reason: "empty" };
+    return { ok: true, baseUrl: normalized };
+}

package/build/bridge-api-urls.js

@@ -9,6 +9,15 @@
  *
  * The base URL is supplied by the caller (never hardcoded here) and its
  * trailing slashes are trimmed so no doubled slash is produced.
+ *
+ * The `/jira` segment is the Bridge API's TRANSPORT namespace — the router mount
+ * that serves these routes in BOTH ticket backend modes. It is not, and must not
+ * become, an agent-visible ticket link: a ticket's URL is whatever the server
+ * returns on the create/read response (`https://…` in Jira mode,
+ * `local://tickets/…` in local mode) and is passed through verbatim. Renaming
+ * this mount is explicitly out of scope (no renaming of Jira-shaped surfaces),
+ * and synthesizing a ticket URL from it would produce a link to an API route
+ * rather than to a ticket.
  */
 /**
  * Create the URL builders bound to `baseUrl`. Trailing slashes on the base are

package/build/chain-orchestrator.js

@@ -25,6 +25,8 @@
  */
 import { runPipeline, resumePipeline, peekPipelineRun } from "./pipeline-orchestrator.js";
 import { toStringVariable, substituteChainValue } from "./chain-utils.js";
+import { isValidTicketKey, validateTicketKeys } from "./ticket-key-utils.js";
+import { isUnsupportedInLocalModeEnvelope, parseToolErrorEnvelope, } from "./tool-error-envelope.js";
 const CHAIN_NAME = "full-automation";
 const START_TICKETS_PIPELINE = "start-tickets";
 // Display titles for preambles, keyed by child pipeline name.
@@ -166,13 +168,22 @@ function normalizeAutoApprove(value) {
         return true;
     return false;
 }
-const JIRA_KEY_EXACT = /^[A-Z][A-Z0-9]+-\d+$/;
 /**
- * Extract created Jira ticket keys from a STRUCTURED payload (an object/array
+ * Extract created ticket keys from a STRUCTURED payload (an object/array
  * holding `created_ticket_keys` / `ticket_key` / etc.). Collects values from the
- * preferred key fields in a fixed preference order, validates each against
- * `JIRA_KEY_EXACT`, and de-dupes in encounter order. There is deliberately NO
- * free-text regex fallback: pass the parsed upload-step payload (via
+ * preferred key fields in a fixed preference order, validates each against the
+ * canonical `TICKET_KEY_PATTERN`, and de-dupes in encounter order.
+ *
+ * BAPI-710: the validation used to run against a private `/^[A-Z][A-Z0-9]+-\d+$/`
+ * that rejected keys the server mints (`MY_PROJ-248`, `A-1`), and this helper
+ * DROPPED every non-match silently. Silent dropping is now impossible for the
+ * chain — {@link extractCreatedTicketPayload} rejects the whole payload and names
+ * every offending key. This flat helper still filters (its `string[]` contract
+ * has no failure channel), but it is a non-chain compatibility path only and the
+ * grammar it filters on is now the correct one.
+ *
+ * There is deliberately NO free-text regex fallback: pass the parsed
+ * upload-step payload (via
  * `extractCreatedKeysFromCompletedChild`), never a whole pipeline transcript, so
  * keys merely *mentioned* by an earlier step (e.g. duplicate-detection search
  * hits) can never be mistaken for this run's creations. A string / no-field
@@ -226,7 +237,7 @@ export function extractCreatedTicketKeys(source) {
     const ordered = [];
     for (const key of preferredKeys) {
         for (const candidate of buckets[key]) {
-            if (JIRA_KEY_EXACT.test(candidate))
+            if (isValidTicketKey(candidate))
                 ordered.push(candidate);
         }
     }
@@ -278,7 +289,7 @@ function tryParseJson(raw) {
     }
 }
 function isValidJiraKey(value) {
-    return typeof value === "string" && JIRA_KEY_EXACT.test(value);
+    return isValidTicketKey(value);
 }
 /**
  * Normalize a PARSED, STRUCTURED upload payload into a {@link CreatedTicketPayload}.
@@ -316,7 +327,7 @@ export function extractCreatedTicketPayload(source) {
         if (!isValidJiraKey(parent)) {
             return {
                 ok: false,
-                error: `Epic payload "epic_parent_key" must be a valid Jira key; got ${JSON.stringify(parent)}.`,
+                error: `Epic payload "epic_parent_key" must be a valid ticket key; got ${JSON.stringify(parent)}.`,
             };
         }
         const rawChildren = obj.child_ticket_keys;
@@ -327,14 +338,20 @@ export function extractCreatedTicketPayload(source) {
                     "implementable child ticket key.",
             };
         }
+        // Validate the WHOLE child list first and report every rejected key in one
+        // error (BAPI-710). Failing on the first bad key made a caller fix its
+        // payload one key per round trip, and the previous grammar rejected keys the
+        // server legitimately mints — so a mixed-validity list must fail atomically,
+        // never advance with the valid subset.
+        const childKeyCheck = validateTicketKeys(rawChildren, "child_ticket_keys entry");
+        if (!childKeyCheck.ok) {
+            return {
+                ok: false,
+                error: `Epic payload "child_ticket_keys" must contain only valid implementable ticket keys. ${childKeyCheck.message}`,
+            };
+        }
         const children = [];
         for (const c of rawChildren) {
-            if (!isValidJiraKey(c)) {
-                return {
-                    ok: false,
-                    error: `Epic payload "child_ticket_keys" must contain only valid implementable Jira keys; got ${JSON.stringify(c)}.`,
-                };
-            }
             if (c === parent) {
                 return {
                     ok: false,
@@ -361,7 +378,7 @@ export function extractCreatedTicketPayload(source) {
             return {
                 ok: false,
                 error: 'Single-ticket payload "created_ticket_keys" must contain exactly ' +
-                    "one valid implementable Jira key. A multi-key list is malformed " +
+                    "one valid implementable ticket key. A multi-key list is malformed " +
                     '(the legacy "first key is the Epic parent" convention is not accepted).',
             };
         }
@@ -431,6 +448,36 @@ function failedEnvelopeMentions(env, token) {
     }
     return false;
 }
+/**
+ * Find a recognized ``UNSUPPORTED_IN_LOCAL_MODE`` refusal anywhere in a child
+ * pipeline envelope (BAPI-710).
+ *
+ * Scans the top-level halt error and each step's ``error`` / string ``result``,
+ * matching only the exact ``(error, status)`` pair via the strict parser — never
+ * a substring of prose, so an echoed input or a message that merely mentions the
+ * marker cannot terminate a chain.
+ *
+ * A ``completed`` envelope is scanned too, not just a ``failed`` one: a
+ * ``warn_and_continue`` step in an older persisted run can have swallowed the
+ * refusal into a completed envelope, and treating that as success is exactly the
+ * partial-success outcome this check exists to prevent.
+ */
+function findUnsupportedLocalModeRefusal(env) {
+    const topLevel = parseToolErrorEnvelope(env.error);
+    if (isUnsupportedInLocalModeEnvelope(topLevel))
+        return topLevel;
+    const results = env.results;
+    if (!Array.isArray(results))
+        return null;
+    for (const step of results) {
+        for (const candidate of [step?.error, step?.result]) {
+            const parsed = parseToolErrorEnvelope(candidate);
+            if (isUnsupportedInLocalModeEnvelope(parsed))
+                return parsed;
+        }
+    }
+    return null;
+}
 /**
  * Heuristic, no-LLM one-line stage summary. idea-to-ticket passes a structured
  * {@link CreatedTicketPayload} so the summary distinguishes the Epic parent from
@@ -782,6 +829,37 @@ async function handleChildPipelineEnvelope(persistence, recipe, row, childEnv, o
             }),
         };
     }
+    // BAPI-710 terminal gate. Runs BEFORE the failed-mapping branch, before the
+    // fan-out advance, and before the single-child finalize — i.e. before review
+    // fan-out, worktree preparation, or any start-tickets command can be emitted.
+    // A backend that cannot perform the operation will not start being able to on
+    // the next stage, so continuing would only produce a partial success that
+    // looks like a real one.
+    const refusal = findUnsupportedLocalModeRefusal(childEnv);
+    if (refusal) {
+        const stages = cloneStages(row.stages);
+        if (stages[idx])
+            stages[idx].status = "failed";
+        try {
+            await persistence.patchRun(row.chain_run_id, { stages, status: "failed" });
+        }
+        catch {
+            // best-effort — the terminal failure is what matters
+        }
+        return {
+            kind: "fail",
+            envelope: {
+                ...failedEnvelope("TOOL_ERROR", refusal.message, {
+                    chain_run_id: row.chain_run_id,
+                    chain_stage: stageRecipe.pipeline_name,
+                    chain_step: idx + 1,
+                    chain_total: total,
+                }),
+                backend_error: refusal.error,
+                ...(refusal.supported_in ? { supported_in: refusal.supported_in } : {}),
+            },
+        };
+    }
     if (childEnv.status === "failed") {
         // Stage 0 vagueness or no-keys produced => VALIDATION. Anchor the sentinel
         // check to the failure-text fields (the halt error + per-step error/result

package/build/claude-user-config-doctor.js

@@ -0,0 +1,317 @@
+/**
+ * Read-only inspection of the machine's Claude user configuration
+ * (`~/.claude.json`) for `bridge-api` MCP registrations that can SHADOW the
+ * secret-free registration the conductor provisions into a worker worktree
+ * (BAPI-727).
+ *
+ * EMPIRICALLY ESTABLISHED BEHAVIOR — the only precedence claim this module makes:
+ * a `projects["<main repository path>"].mcpServers["bridge-api"]` entry was
+ * observed to win over a linked worktree's own `.mcp.json`. That is the failure
+ * this inspector exists to detect: the worker silently talks to whatever server
+ * the user-level entry names (in practice, production) instead of the endpoint the
+ * executor provisioned.
+ *
+ * NOT ESTABLISHED, AND MUST NOT BE INFERRED FROM THIS MODULE:
+ *   - user-scope (`mcpServers`) versus project-scope precedence,
+ *   - precedence of a `projects["<worktree path>"]` entry against anything else,
+ *   - symlink equivalence between a configured path and the real path,
+ *   - filesystem case-equivalence on case-insensitive hosts.
+ * The inspector therefore looks in all three places and reports what it finds; it
+ * does not rank them.
+ *
+ * SEPARATE PRIOR ART: the BAPI-451 cold-start "failed to connect" condition is a
+ * launcher/npx-cache TIMING problem, not configuration shadowing. Nothing here
+ * diagnoses or remediates that.
+ *
+ * SECRET SAFETY: this module never retains the parsed document, a registration
+ * entry, a command/argument array, an environment VALUE, a read exception, or
+ * malformed source text. Findings carry only scope labels, the config path, a
+ * fixed shape classification, and sorted environment KEY NAMES.
+ */
+import { isBridgeApiShimEntry, readJsonIfPresent } from "./mcp-registration-doctor.js";
+import { normalizeWorktreePathForRegistration, pathApiForProvisioningPlatform, } from "./mcp-provisioning.js";
+/** The registration key both the provisioner and a user config would use. */
+const BRIDGE_API_SERVER_NAME = "bridge-api";
+/** The Claude user configuration file name, at the home directory root. */
+const CLAUDE_USER_CONFIG_FILENAME = ".claude.json";
+/**
+ * Build the platform-appropriate path to the Claude user configuration from an
+ * explicitly supplied home directory. Shared by executor preflight, per-worktree
+ * enforcement, and doctor so none of them hardcodes its own join, and consults no
+ * global process state.
+ */
+export function resolveClaudeUserConfigPath(homeDirectory, platform) {
+    return pathApiForProvisioningPlatform(platform).join(homeDirectory, CLAUDE_USER_CONFIG_FILENAME);
+}
+/**
+ * Environment override that downgrades a confirmed shadowing collision from a
+ * refusal to a loud warning. Deliberately long and conductor-scoped so it cannot
+ * be set by accident.
+ */
+export const CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING_ENV = "BAPI_CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING";
+/** A plain, non-array object. */
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+/**
+ * Sorted `env` key names, or `[]` when the entry has no `env` object. Only NAMES
+ * are read; the values are never touched.
+ */
+function envKeyNamesOf(entry) {
+    const record = asRecord(entry);
+    if (!record)
+        return [];
+    const env = asRecord(record.env);
+    if (!env)
+        return [];
+    return Object.keys(env).sort();
+}
+/** True when the entry declares an `env` object at all (even an empty one). */
+function hasEnvBlock(entry) {
+    const record = asRecord(entry);
+    if (!record)
+        return false;
+    return asRecord(record.env) !== null;
+}
+/**
+ * Structural shape probe: does this look like the Bridge `mcp-invoke` shim,
+ * ignoring WHICH project root it names? Used only to tell "a shim aimed at
+ * another checkout" apart from "some unrelated command"; acceptance always goes
+ * through {@link isBridgeApiShimEntry} against an expected path.
+ */
+function looksLikeBridgeShimCommand(entry) {
+    const record = asRecord(entry);
+    if (!record)
+        return false;
+    if (typeof record.command !== "string" || record.command.length === 0)
+        return false;
+    if (!Array.isArray(record.args))
+        return false;
+    const args = record.args.filter((a) => typeof a === "string");
+    if (!args.includes("mcp-invoke"))
+        return false;
+    const targetIndex = args.indexOf("--target");
+    return targetIndex >= 0 && args[targetIndex + 1] === "bapi";
+}
+/**
+ * Classify a registration for one scope.
+ *
+ * An entry is an acceptable provisioned shim only when `isBridgeApiShimEntry()`
+ * accepts it for one of the paths this scope may legitimately name AND it stays
+ * secret-free (no `env` block). The provisioner emits exactly `{ command, args }`
+ * — an `env` block therefore proves the entry was not written by it, no matter how
+ * closely the command and arguments otherwise resemble the shim.
+ *
+ * `allowedPaths` is empty when the caller could not resolve the path this scope
+ * compares against; a shim-shaped entry then classifies as inconclusive rather
+ * than as a confirmed collision, so an unresolved path can never manufacture a
+ * false refusal.
+ */
+function classifyEntry(entry, allowedPaths) {
+    if (hasEnvBlock(entry)) {
+        return {
+            verdict: "foreign",
+            shape: looksLikeBridgeShimCommand(entry) ? "shim-with-env-block" : "non-shim-registration",
+        };
+    }
+    for (const allowed of allowedPaths) {
+        if (isBridgeApiShimEntry(entry, allowed))
+            return { verdict: "safe" };
+    }
+    if (looksLikeBridgeShimCommand(entry)) {
+        if (allowedPaths.length === 0)
+            return { verdict: "inconclusive" };
+        return { verdict: "foreign", shape: "shim-for-other-project-root" };
+    }
+    return { verdict: "foreign", shape: "non-shim-registration" };
+}
+/** Resolve a supplied path through the shared registration normalizer, or null. */
+function normalizeOrNull(rawPath, input) {
+    if (typeof rawPath !== "string" || rawPath.trim().length === 0)
+        return null;
+    const normalized = normalizeWorktreePathForRegistration(rawPath, {
+        platform: input.platform,
+        cwd: input.cwd,
+    });
+    return normalized.ok ? normalized.path : null;
+}
+/**
+ * Inspect `~/.claude.json` for a `bridge-api` registration at user, main-project,
+ * and worktree-project scope.
+ *
+ * Healthy states (no finding, no diagnostic): the file is absent, or it contains
+ * no same-named registration in any inspected scope, or every same-named
+ * registration is an acceptable provisioned shim.
+ *
+ * Degraded states (diagnostic, never a confirmed collision): the file could not be
+ * read, its JSON is malformed, or a user-scope shim names a project root that
+ * cannot be checked because no main-repository path was supplied.
+ *
+ * Never throws, never writes, never spawns.
+ */
+export async function inspectClaudeUserConfigForMcpShadowing(input, deps) {
+    const configPath = input.claudeConfigPath;
+    const read = await readJsonIfPresent(configPath, deps);
+    if (read.state === "missing")
+        return { findings: [], diagnostics: [] };
+    if (read.state === "unreadable") {
+        return { findings: [], diagnostics: [{ kind: "unreadable", configPath }] };
+    }
+    if (read.state === "malformed") {
+        return { findings: [], diagnostics: [{ kind: "malformed", configPath }] };
+    }
+    const document = asRecord(read.value);
+    if (!document)
+        return { findings: [], diagnostics: [] };
+    const mainPath = normalizeOrNull(input.mainRepositoryPath, input);
+    const worktreePath = normalizeOrNull(input.worktreePath, input);
+    // A user-scope shim may legitimately target either checkout the executor is
+    // working with; each project scope may only target its own key's path.
+    const userAllowed = [mainPath, worktreePath].filter((p) => p !== null);
+    const lookups = [{ scope: "user", projectKey: null, allowedPaths: userAllowed }];
+    if (mainPath !== null) {
+        lookups.push({ scope: "main-project", projectKey: mainPath, allowedPaths: [mainPath] });
+    }
+    if (worktreePath !== null) {
+        lookups.push({
+            scope: "worktree-project",
+            projectKey: worktreePath,
+            allowedPaths: [worktreePath],
+        });
+    }
+    const projects = asRecord(document.projects);
+    const findings = [];
+    const diagnostics = [];
+    // Identical `projects` keys are ONE registration. Dedupe by key while keeping
+    // every requested scope it satisfies, so a main path and worktree path that
+    // normalize together report once with both scopes rather than twice.
+    const findingByProjectKey = new Map();
+    for (const lookup of lookups) {
+        let servers;
+        if (lookup.projectKey === null) {
+            servers = asRecord(document.mcpServers);
+        }
+        else {
+            const project = projects ? asRecord(projects[lookup.projectKey]) : null;
+            servers = project ? asRecord(project.mcpServers) : null;
+        }
+        if (!servers)
+            continue;
+        if (!Object.prototype.hasOwnProperty.call(servers, BRIDGE_API_SERVER_NAME))
+            continue;
+        const entry = servers[BRIDGE_API_SERVER_NAME];
+        const classification = classifyEntry(entry, lookup.allowedPaths);
+        if (classification.verdict === "safe")
+            continue;
+        if (classification.verdict === "inconclusive") {
+            diagnostics.push({ kind: "inconclusive-user-shim", configPath });
+            continue;
+        }
+        if (lookup.projectKey !== null) {
+            const existing = findingByProjectKey.get(lookup.projectKey);
+            if (existing) {
+                if (!existing.scopes.includes(lookup.scope))
+                    existing.scopes.push(lookup.scope);
+                continue;
+            }
+        }
+        const finding = {
+            scopes: [lookup.scope],
+            configPath,
+            shape: classification.shape,
+            envKeyNames: envKeyNamesOf(entry),
+        };
+        if (lookup.projectKey !== null)
+            findingByProjectKey.set(lookup.projectKey, finding);
+        findings.push(finding);
+    }
+    return { findings, diagnostics };
+}
+// ---------------------------------------------------------------------------
+// Override + shared policy
+// ---------------------------------------------------------------------------
+/** Documented truthy override values (trimmed, case-insensitive). */
+const OVERRIDE_TRUTHY = new Set(["1", "true", "yes", "on"]);
+/**
+ * True only for a trimmed, case-insensitive `1`, `true`, `yes`, or `on`. Absent,
+ * blank, `0`, `false`, `no`, `off`, and anything else are disabled — an override
+ * this consequential must be set deliberately, never by a stray value.
+ */
+export function isClaudeMcpShadowingOverrideEnabled(env) {
+    const raw = env?.[CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING_ENV];
+    if (typeof raw !== "string")
+        return false;
+    return OVERRIDE_TRUTHY.has(raw.trim().toLowerCase());
+}
+/** The exact wording every override path emits, pinned by tests. */
+export const CLAUDE_MCP_SHADOWING_OVERRIDE_WARNING = `Proceeding anyway because ${CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING_ENV} is set`;
+/** Human-readable scope labels (fixed strings, never derived from the config). */
+const SCOPE_LABELS = {
+    user: "user scope (mcpServers)",
+    "main-project": "main-repository project scope (projects[<main repo>])",
+    "worktree-project": "worktree project scope (projects[<worktree>])",
+};
+/** Fixed explanation per shape (never derived from the inspected entry). */
+const SHAPE_LABELS = {
+    "shim-with-env-block": "a shim-shaped entry carrying an env block (the provisioner never writes env)",
+    "shim-for-other-project-root": "an mcp-invoke shim pointed at a different project root",
+    "non-shim-registration": "a registration that is not the provisioned mcp-invoke shim",
+};
+/**
+ * Render ONE finding as a secret-free sentence built exclusively from the
+ * inspector's safe metadata. The registration entry is never serialized.
+ */
+export function formatClaudeMcpShadowFinding(finding) {
+    const scopes = finding.scopes.map((scope) => SCOPE_LABELS[scope]).join(" and ");
+    const envNote = finding.envKeyNames.length > 0
+        ? ` (env keys: ${finding.envKeyNames.join(", ")})`
+        : "";
+    return (`${finding.configPath} registers a '${BRIDGE_API_SERVER_NAME}' MCP server at ${scopes}: ` +
+        `${SHAPE_LABELS[finding.shape]}${envNote}`);
+}
+/** Render one degraded diagnostic as a fixed, path-only sentence. */
+export function formatClaudeUserConfigDiagnostic(diagnostic) {
+    switch (diagnostic.kind) {
+        case "unreadable":
+            return `${diagnostic.configPath} could not be read; Claude MCP shadowing could not be checked`;
+        case "malformed":
+            return `${diagnostic.configPath} contains malformed JSON; Claude MCP shadowing could not be checked`;
+        case "inconclusive-user-shim":
+            return (`${diagnostic.configPath} registers a user-scope '${BRIDGE_API_SERVER_NAME}' shim for an ` +
+                "unverifiable project root (the main repository path could not be resolved)");
+    }
+}
+/**
+ * The SINGLE policy every consumer (executor preflight, per-worktree enforcement,
+ * doctor) applies to an inspection result, so none of them re-derives
+ * classification or override parsing.
+ *
+ * Confirmed findings refuse by DEFAULT. With the override enabled the result is OK
+ * but carries the pinned prominent warning alongside each finding, so an operator
+ * who deliberately opted in still sees exactly what was detected. Degraded
+ * diagnostics are always warnings — they are inconclusive, never a collision.
+ */
+export function evaluateClaudeMcpShadowingPolicy(inspection, env) {
+    const warnings = inspection.diagnostics.map(formatClaudeUserConfigDiagnostic);
+    if (inspection.findings.length === 0)
+        return { ok: true, warnings };
+    const findingMessages = inspection.findings.map(formatClaudeMcpShadowFinding);
+    if (isClaudeMcpShadowingOverrideEnabled(env)) {
+        return {
+            ok: true,
+            warnings: [
+                ...findingMessages.map((m) => `${m}. ${CLAUDE_MCP_SHADOWING_OVERRIDE_WARNING}`),
+                ...warnings,
+            ],
+        };
+    }
+    return {
+        ok: false,
+        refusals: findingMessages.map((m) => `${m}. Refusing to proceed: worktree MCP provisioning may be shadowed. Delete, or ` +
+            `move aside, that registration, or set ` +
+            `${CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING_ENV}=1 to override.`),
+        warnings,
+    };
+}