@bridge_gpt/mcp-server 0.2.34 → 0.2.37

package/build/claude-review-workflow.js

@@ -0,0 +1,264 @@
+/**
+ * Parameterized `claude-review` workflow scaffold (BAPI-679).
+ *
+ * The Bridge repo's own `.github/workflows/claude-review.yml` carries three
+ * ORGANIZATION-SPECIFIC literals — the allowed bot slug, the OAuth secret name,
+ * and the branch triggers — so it cannot be copied into a consumer repo as-is.
+ * This module renders a structurally equivalent workflow from validated
+ * parameters, with no org value embedded anywhere in the template source.
+ *
+ * The template is a plain TypeScript string constant rather than a generated
+ * asset: the package has no workflow-asset generator, and adding one to ship a
+ * single template would create a `*.generated.ts` that must never be hand-edited
+ * for no benefit. `tsc` ships this module in the published package already.
+ *
+ * INJECTION SAFETY is the module's core constraint. Every interpolated value is
+ * validated against a narrow allowlist BEFORE rendering, so no input can close a
+ * YAML scalar, introduce a key, or inject a `${{ }}` expression. Validation
+ * failures throw before any filesystem collaborator is touched.
+ *
+ * All filesystem access is injected so the module is unit-testable with
+ * in-memory fakes.
+ */
+/** Repo-relative path this module owns. It writes NOTHING else. */
+export const CLAUDE_REVIEW_WORKFLOW_RELPATH = ".github/workflows/claude-review.yml";
+/** Thrown when a parameter fails validation. Carries no rendered YAML. */
+export class ClaudeReviewWorkflowValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ClaudeReviewWorkflowValidationError";
+    }
+}
+// A GitHub App bot login: alphanumerics and hyphens, optionally suffixed `[bot]`.
+// Deliberately rejects whitespace, quotes, newlines, `$`, `{`, and `}`.
+const ALLOWED_BOT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9-]*(\[bot\])?$/;
+// GitHub secret identifiers are uppercase alphanumerics and underscores, not
+// starting with a digit and not using the reserved `GITHUB_` prefix.
+const SECRET_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
+// Branch trigger patterns: git ref characters plus the `*` glob GitHub accepts.
+// Rejects whitespace, quotes, `:`, `$`, `{`, `}`, and leading/trailing slashes.
+const BRANCH_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._\-/*]*$/;
+const MAX_BOT_LENGTH = 100;
+const MAX_SECRET_NAME_LENGTH = 100;
+const MAX_BRANCH_LENGTH = 200;
+const MAX_BRANCHES = 20;
+function validateAllowedBot(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > MAX_BOT_LENGTH) {
+        throw new ClaudeReviewWorkflowValidationError("allowedBot must be a non-empty slug");
+    }
+    if (!ALLOWED_BOT_PATTERN.test(value)) {
+        throw new ClaudeReviewWorkflowValidationError("allowedBot must match a GitHub bot login (alphanumerics/hyphens, optional `[bot]` suffix)");
+    }
+    return value;
+}
+function validateSecretName(value) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MAX_SECRET_NAME_LENGTH) {
+        throw new ClaudeReviewWorkflowValidationError("secretName must be a non-empty identifier");
+    }
+    if (!SECRET_NAME_PATTERN.test(value)) {
+        throw new ClaudeReviewWorkflowValidationError("secretName must be an uppercase GitHub secret identifier (A-Z, 0-9, underscore)");
+    }
+    if (value.startsWith("GITHUB_")) {
+        throw new ClaudeReviewWorkflowValidationError("secretName must not use the reserved GITHUB_ prefix");
+    }
+    return value;
+}
+function validateBranches(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new ClaudeReviewWorkflowValidationError("branches must be a non-empty array");
+    }
+    if (value.length > MAX_BRANCHES) {
+        throw new ClaudeReviewWorkflowValidationError("branches list is too long");
+    }
+    const seen = new Set();
+    const out = [];
+    for (const raw of value) {
+        if (typeof raw !== "string" || raw.length === 0 || raw.length > MAX_BRANCH_LENGTH) {
+            throw new ClaudeReviewWorkflowValidationError("each branch must be a non-empty string");
+        }
+        if (!BRANCH_PATTERN.test(raw)) {
+            throw new ClaudeReviewWorkflowValidationError("each branch must be a valid git ref pattern (no whitespace, quotes, or expressions)");
+        }
+        if (seen.has(raw)) {
+            throw new ClaudeReviewWorkflowValidationError(`duplicate branch: ${raw}`);
+        }
+        seen.add(raw);
+        out.push(raw);
+    }
+    return out;
+}
+/**
+ * Serialize a validated scalar as a single-quoted YAML string.
+ *
+ * Safe because the value already passed an allowlist that excludes `'`, so the
+ * escape below can never be reached with adversarial input — it is kept as
+ * defense in depth rather than as the primary control.
+ */
+function yamlSingleQuoted(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/** Serialize a validated string list as an inline YAML flow sequence. */
+function yamlFlowList(values) {
+    return `[${values.map(yamlSingleQuoted).join(", ")}]`;
+}
+/**
+ * Render the workflow YAML deterministically from validated parameters.
+ *
+ * Structurally mirrors the Bridge repo's own workflow — same triggers,
+ * concurrency, permissions, action, sticky comment, and the verdict/
+ * `Reviewed-SHA`/`run-id` contract the Conductor's merge gate consumes — with
+ * every org-specific literal replaced by a parameter.
+ *
+ * @throws ClaudeReviewWorkflowValidationError before producing any output.
+ */
+export function renderClaudeReviewWorkflow(params) {
+    const allowedBot = validateAllowedBot(params.allowedBot);
+    const secretName = validateSecretName(params.secretName);
+    const branches = validateBranches(params.branches);
+    // `${'$'}{{ ... }}` is avoided by building the expression marker from a constant,
+    // so nothing in this template can be mistaken for a TS template substitution.
+    const gh = (expr) => "${{ " + expr + " }}";
+    return `# Generated by \`install-bridge conductor\` (Bridge API, BAPI-679).
+# Safe to edit: this file is never overwritten without explicit consent.
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, ready_for_review]
+    branches: ${yamlFlowList(branches)}
+
+# A new push to the PR cancels an in-flight review of the stale head, matching the
+# Reviewed-SHA provenance the review emits: the Conductor rejects a verdict whose
+# Reviewed-SHA does not match the current head, so cancelling a superseded review
+# only avoids wasted minutes.
+concurrency:
+  group: claude-review-${gh("github.event.pull_request.number")}
+  cancel-in-progress: true
+
+jobs:
+  claude-review:
+    runs-on: ubuntu-latest
+    if: ${gh("github.event.pull_request.draft == false")}
+    permissions:
+      actions: read
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 1
+
+      - name: Claude Code Review
+        id: review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${gh(`secrets.${secretName}`)}
+          allowed_bots: ${yamlSingleQuoted(allowedBot)}
+          use_sticky_comment: true
+          track_progress: true
+          prompt: |
+            REPO: ${gh("github.repository")}
+            PR NUMBER: ${gh("github.event.pull_request.number")}
+
+            Review this pull request with a focus on:
+            - Bugs, logic errors, and edge cases
+            - Security issues (injection, auth bypasses, sensitive data exposure)
+            - Project conventions and patterns (see CLAUDE.md)
+            - Data-access correctness (parameterized queries, migration safety)
+            - Test coverage gaps for changed code
+
+            Be specific: cite file paths and line numbers.
+
+            Call out significant issues; ignore minor nits with no meaningful impact.
+            If there are no significant issues, just say "Looks good to me!"
+
+            Use \`gh pr comment\` for top-level feedback.
+            Use \`mcp__github_inline_comment__create_inline_comment\` (with \`confirmed: true\`)
+            to highlight specific code issues.
+            Only post GitHub comments - don't submit review text as messages.
+
+            After your feedback, end your top-level \`gh pr comment\` with EXACTLY ONE
+            machine-readable verdict line, on its own line, verbatim — this single line is
+            the source of truth consumed by automation (the Conductor merge gate):
+            - \`claude-review-verdict: approved\` — when the PR is safe to merge
+            - \`claude-review-verdict: changes_requested\` — when significant issues remain
+            Emit exactly one such verdict line, and do not use the words \`approved\` or
+            \`changes_requested\` as a verdict anywhere else in the comment.
+
+            Immediately BELOW the verdict line, on its own line, emit this exact
+            head-SHA provenance line verbatim — it binds the verdict to the exact commit
+            you reviewed so the Conductor can reject a stale verdict:
+            \`Reviewed-SHA: ${gh("github.event.pull_request.head.sha")}\`
+
+            Also include the GitHub Actions run id on its own line so overlapping
+            reviews resolve deterministically by run id, verbatim:
+            \`run-id: ${gh("github.run_id")}\`
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(git diff:*),Bash(git log:*),Bash(git show:*),Read,Glob,Grep"
+`;
+}
+function joinCwd(cwd, rel) {
+    const base = cwd.endsWith("/") ? cwd.slice(0, -1) : cwd;
+    return `${base}/${rel}`;
+}
+/** Absolute path of the workflow file for a project. */
+export function claudeReviewWorkflowPath(cwd) {
+    return joinCwd(cwd, CLAUDE_REVIEW_WORKFLOW_RELPATH);
+}
+function isEnoent(err) {
+    return (typeof err === "object" && err !== null && err.code === "ENOENT");
+}
+/**
+ * Classify an existing workflow file against the rendered content.
+ *
+ * Returns a status ONLY — never the existing file's content, and never the read
+ * error's message (which can echo an absolute path or, for a misconfigured
+ * checkout, file content).
+ */
+export async function inspectClaudeReviewWorkflow(cwd, renderedContent, deps) {
+    let existing;
+    try {
+        existing = await deps.readFile(claudeReviewWorkflowPath(cwd));
+    }
+    catch (err) {
+        return isEnoent(err) ? { status: "absent" } : { status: "unreadable" };
+    }
+    return existing === renderedContent ? { status: "identical" } : { status: "different" };
+}
+/**
+ * Write the workflow, read-compare-write, with SEPARATE overwrite consent.
+ *
+ * `overwriteConsent` must be an explicit decision made for THIS file. It is
+ * never inferred from the installer's earlier base-URL or bootstrap consent:
+ * this file governs review automation on every PR, so silently replacing an
+ * operator's version could disable review repo-wide.
+ *
+ * Writes exactly one path — {@link CLAUDE_REVIEW_WORKFLOW_RELPATH} — and nothing else.
+ */
+export async function writeClaudeReviewWorkflow(cwd, renderedContent, deps, options = {}) {
+    const finalPath = claudeReviewWorkflowPath(cwd);
+    const inspection = await inspectClaudeReviewWorkflow(cwd, renderedContent, deps);
+    if (inspection.status === "identical") {
+        return { ok: true, outcome: "unchanged", path: finalPath };
+    }
+    if (inspection.status === "unreadable") {
+        return { ok: false, error: "existing workflow file could not be read" };
+    }
+    if (inspection.status === "different" && options.overwriteConsent !== true) {
+        return { ok: true, outcome: "skipped", path: finalPath };
+    }
+    try {
+        await deps.mkdir(joinCwd(cwd, ".github/workflows"), { recursive: true });
+        await deps.writeFile(finalPath, renderedContent);
+    }
+    catch (err) {
+        // Message is the fs error's own text (path + errno), never file content.
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `failed to write workflow: ${message}` };
+    }
+    return { ok: true, outcome: "written", path: finalPath };
+}

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,
+    };
+}

package/build/cli-release.js

@@ -0,0 +1,53 @@
+/**
+ * Shared npm release resolution for the Bridge CLI (BAPI-714).
+ *
+ * ONE bounded, fail-open lookup of the latest published `@bridge_gpt/mcp-server`
+ * version, shared by `upgrade` (which already re-exec'd from `@latest`) and by
+ * the `install` path's new self-re-exec. Extracted into its own leaf module so
+ * `install-reexec.ts` does not have to import `upgrade-cli.ts` — that module
+ * pulls in `runInit`, the terminal registry, and the agent registry, none of
+ * which the install hand-off needs.
+ *
+ * The contract is deliberately narrow: return a nonblank version string ONLY for
+ * a successful, well-formed registry response, and resolve to `null` for every
+ * other outcome — non-2xx, timeout/abort, network failure, unparseable body,
+ * non-object JSON, missing/blank/non-string `version`. It never throws and never
+ * logs, because both callers treat "no usable version" as "keep using the local
+ * copy" rather than as an error worth reporting to the user.
+ */
+/** The npm registry endpoint carrying the latest published release metadata. */
+export const NPM_LATEST_ENDPOINT = "https://registry.npmjs.org/@bridge_gpt/mcp-server/latest";
+/**
+ * Hard bound on the registry lookup. Owned here rather than duplicated at each
+ * call site: `install` is a first-time user's very first contact with Bridge, so
+ * a hung registry may never stall it past this budget.
+ */
+export const NPM_LATEST_TIMEOUT_MS = 3000;
+/**
+ * Resolve the latest published version of `@bridge_gpt/mcp-server`, or `null`.
+ *
+ * Fail-open by construction: every failure mode collapses to `null` so the
+ * caller proceeds with its local `VERSION`. Emits no output on any path.
+ */
+export async function fetchLatestVersion(deps = {}) {
+    const doFetch = deps.fetch ?? globalThis.fetch;
+    const timeoutSignal = deps.timeoutSignal ?? ((ms) => AbortSignal.timeout(ms));
+    try {
+        const res = await doFetch(NPM_LATEST_ENDPOINT, {
+            signal: timeoutSignal(NPM_LATEST_TIMEOUT_MS),
+        });
+        if (!res || !res.ok)
+            return null;
+        const data = await res.json();
+        if (!data || typeof data !== "object" || Array.isArray(data))
+            return null;
+        const version = data.version;
+        if (typeof version !== "string")
+            return null;
+        const trimmed = version.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}