@bridge_gpt/mcp-server 0.2.16 → 0.2.19

package/build/install-bridge.js

@@ -65,7 +65,14 @@ export function buildPrewarmCommandPreview() {
     return `npx ${buildPrewarmArgs().join(" ")}`;
 }
 /** The natural-language sequential prompt handed to the spawned agent session. */
-export const INSTALL_BRIDGE_AGENT_PROMPT = "Please execute the /install-bridge command. Once it completes successfully, execute the /learn-repository command.";
+export const INSTALL_BRIDGE_AGENT_PROMPT = "Please execute the /install-bridge command. Once it completes successfully, execute the " +
+    "/learn-repository command. After /learn-repository completes, ask the user for consent to start " +
+    "repository indexing; with consent, call the parse_repository MCP tool once and report that the " +
+    "job was queued (progress is checked with get_parse_status — do not poll it to completion). " +
+    "When you are done, end with an explicit summary line stating how " +
+    "many config fields the apply_install_manifest call applied (e.g. 'Applied 8 of 9 derived " +
+    "fields') and whether indexing was queued — if 0 fields were applied, say so loudly and explain " +
+    "what is still pending.";
 /** Default base URL when `BAPI_BASE_URL` is unset (mirrors index.ts). */
 export const DEFAULT_BAPI_BASE_URL = "https://bridgegpt-api.com";
 /** Default docs dir when `BAPI_DOCS_DIR` is unset (mirrors index.ts). */
@@ -739,15 +746,19 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         }
         else {
             log(`  warning: could not persist the routing credential (${result.kind}). ` +
-                `start-tickets model routing may not resolve the key for ${plan.credentialTarget}; ` +
-                "set BAPI_API_KEY in the shell or re-run install-bridge.");
+                `start-tickets model routing may not resolve the key for ${plan.credentialTarget} ` +
+                "and will fail open to the premium/Opus tier (the most expensive) — " +
+                "set BAPI_API_KEY in the shell or re-run install-bridge, then verify with " +
+                "'npx -y @bridge_gpt/mcp-server doctor'.");
         }
     }
     catch {
         // Fail-open: persistence is best-effort (mirrors Stage 6). The secret is never
         // included in the warning.
         log("  warning: could not persist the routing credential (unexpected error). " +
-            "start-tickets model routing may need BAPI_API_KEY in the shell.");
+            "start-tickets model routing may need BAPI_API_KEY in the shell and will fail open " +
+            "to the premium/Opus tier (the most expensive) until fixed — verify with " +
+            "'npx -y @bridge_gpt/mcp-server doctor'.");
     }
     // ---- Step 5 — spawn a fresh agent session for the agentic remainder ----
     log(`Step 5/5 — opening a ${agent.name} session for /install-bridge + /learn-repository…`);
@@ -759,14 +770,20 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     if (!spawnResult.ok) {
         // Steps 1–4 (scaffold, config, connectivity-verified, credential persist) all
         // succeeded and are durable; only the best-effort Step 5 tab spawn failed. The
-        // install itself is complete, so this is a non-fatal warning (exit 0) — the
+        // deterministic setup is complete, so this is a non-fatal warning (exit 0) — the
         // user can run the agentic remainder by hand. Mirrors start-tickets treating a
         // spawn failure as non-fatal to the run.
-        errorLog(`Warning: setup completed, but the agent session could not be opened (${spawnResult.error}). ` +
-            "Run /install-bridge then /learn-repository manually in this project.");
+        errorLog(`Warning: setup steps completed, but the agent session could not be opened (${spawnResult.error}). ` +
+            "The project is NOT configured yet — run /install-bridge then /learn-repository manually " +
+            "in this project to derive and apply the config fields.");
         return 0;
     }
     log("");
-    log("install-bridge complete. A fresh agent session is running /install-bridge then /learn-repository.");
+    log(`install-bridge setup steps complete. A fresh ${agent.name} session is now running ` +
+        "/install-bridge then /learn-repository.");
+    log("NOTE: the install is not finished until that session's apply reports applied fields — " +
+        "it will pause to ask you to approve the project description. Verify afterwards on the " +
+        "project's Get Started page (install status panel) or via the session's " +
+        "'Applied N of M' summary.");
     return 0;
 }

package/build/install-doctor.js

@@ -0,0 +1,387 @@
+/**
+ * install-doctor — an advisory, strictly read-only "Install status" section for
+ * the `doctor` subcommand, turning the install manifest's prose done-criteria
+ * into an executable checklist.
+ *
+ * Checks (all best-effort, all read-only GETs, none affect the doctor exit code):
+ *   - identity      — can a repo name / base URL be resolved (env, then the
+ *                     project-local MCP config env blocks)?
+ *   - credential    — does the standard resolver (env → user-scoped store) find
+ *                     a Bridge API key? (never reads or prints the key value)
+ *   - connectivity  — GET /jira/ping (distinguishes rejected key vs unknown repo)
+ *   - bootstrap     — GET /jira/config/install-manifest → N/M bootstrap fields set
+ *   - integrations  — the same manifest's presence-only integrations checklist
+ *                     (unconfigured credentials are configured by a human in the
+ *                     setup UI — never through an agent)
+ *   - indexing      — GET /jira/parse-status → parse job running / idle
+ *
+ * The section is advisory by contract: any failure inside it degrades to a
+ * WARN/SKIP line, never a throw, and the doctor exit code stays driven by the
+ * required prerequisites only.
+ */
+import path from "path";
+import { resolveBapiCredentials } from "./credential-store.js";
+/** Default production base URL (mirrors install-bridge's DEFAULT_BAPI_BASE_URL). */
+const DEFAULT_BASE_URL = "https://bridgegpt-api.com";
+/** Project-local MCP configs whose env blocks may carry repo/base-URL values. */
+const MCP_CONFIG_ENV_TARGETS = [
+    { relPath: ".mcp.json", topLevelKey: "mcpServers" },
+    { relPath: ".cursor/mcp.json", topLevelKey: "mcpServers" },
+    { relPath: ".vscode/mcp.json", topLevelKey: "servers" },
+];
+/** Timeout for each read-only probe request. */
+const PROBE_TIMEOUT_MS = 5_000;
+/**
+ * Resolve the repo name and base URL: environment first, then the NON-SECRET
+ * env-block values of the project-local MCP configs (`BAPI_REPO_NAME` /
+ * `BAPI_BASE_URL`). The API key is deliberately NEVER read from config files —
+ * secret resolution goes through the standard credential resolver only.
+ */
+export async function resolveInstallDoctorTarget(deps) {
+    const envRepo = deps.env.BAPI_REPO_NAME?.trim();
+    const envBase = deps.env.BAPI_BASE_URL?.trim();
+    let repoName = envRepo && envRepo.length > 0 ? envRepo : null;
+    let repoSource = repoName ? "env" : null;
+    let baseUrl = envBase && envBase.length > 0 ? envBase : null;
+    if (!repoName || !baseUrl) {
+        for (const { relPath, topLevelKey } of MCP_CONFIG_ENV_TARGETS) {
+            let raw;
+            try {
+                raw = await deps.readFile(path.join(deps.cwd, relPath));
+            }
+            catch {
+                continue; // absent config is not a finding
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                continue;
+            }
+            const envBlock = parsed && typeof parsed === "object"
+                ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    parsed[topLevelKey]?.["bridge-api"]?.env
+                : undefined;
+            if (!envBlock)
+                continue;
+            if (!repoName && typeof envBlock.BAPI_REPO_NAME === "string" && envBlock.BAPI_REPO_NAME.trim()) {
+                repoName = envBlock.BAPI_REPO_NAME.trim();
+                repoSource = "config";
+            }
+            if (!baseUrl && typeof envBlock.BAPI_BASE_URL === "string" && envBlock.BAPI_BASE_URL.trim()) {
+                baseUrl = envBlock.BAPI_BASE_URL.trim();
+            }
+            if (repoName && baseUrl)
+                break;
+        }
+    }
+    return { repoName, repoSource, baseUrl: baseUrl ?? DEFAULT_BASE_URL };
+}
+/** Read-only GET with a bounded timeout. Never throws. */
+async function probeGet(deps, url, apiKey) {
+    try {
+        const resp = await deps.fetch(url, {
+            headers: { "X-API-Key": apiKey },
+            signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+        });
+        let body = null;
+        try {
+            body = await resp.json();
+        }
+        catch {
+            /* non-JSON body — status alone is still useful */
+        }
+        return { ok: true, status: resp.status, body };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+/** Count set/total bootstrap fields from an install-manifest response body. */
+function summarizeManifestGroups(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const groups = body.groups;
+    if (!Array.isArray(groups))
+        return null;
+    let total = 0;
+    const unset = [];
+    for (const group of groups) {
+        const fields = group?.fields;
+        if (!Array.isArray(fields))
+            continue;
+        for (const field of fields) {
+            const name = field?.field_name;
+            if (typeof name !== "string")
+                continue;
+            total += 1;
+            if (!field.is_set)
+                unset.push(name);
+        }
+    }
+    return { total, unset };
+}
+/** Summarize the manifest's integrations checklist (presence booleans only). */
+function summarizeIntegrations(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const integrations = body.integrations;
+    if (!Array.isArray(integrations))
+        return null;
+    let total = 0;
+    const unconfigured = [];
+    for (const item of integrations) {
+        const label = item?.label;
+        if (typeof label !== "string")
+            continue;
+        total += 1;
+        if (!item.is_configured)
+            unconfigured.push(label);
+    }
+    return { total, unconfigured };
+}
+/**
+ * Collect the install-status checklist. Never throws; every failure path becomes
+ * a WARN or SKIP check line. Performs at most three read-only GETs, and only
+ * when both a repo name and a credential resolve.
+ */
+export async function collectInstallStatusChecks(deps) {
+    const checks = [];
+    const target = await resolveInstallDoctorTarget(deps);
+    if (!target.repoName) {
+        checks.push({
+            id: "identity",
+            label: "Repository identity",
+            status: "SKIP",
+            detail: "no BAPI_REPO_NAME in the environment or project-local MCP configs",
+            remediation: "run install-bridge (or set BAPI_REPO_NAME) to configure this project.",
+        });
+        return checks;
+    }
+    checks.push({
+        id: "identity",
+        label: "Repository identity",
+        status: "PASS",
+        detail: `${target.repoName} (from ${target.repoSource}), base URL ${target.baseUrl}`,
+    });
+    const credDeps = {
+        env: deps.env,
+        homedir: deps.homedir,
+        platform: deps.platform,
+        readFile: deps.readFile,
+        stat: deps.stat,
+        stderr: () => { },
+    };
+    const cred = await resolveBapiCredentials(target.repoName, credDeps);
+    if (!cred.ok) {
+        checks.push({
+            id: "credential",
+            label: "Bridge API credential",
+            status: "WARN",
+            detail: `not resolved (${cred.kind})`,
+            remediation: "set BAPI_API_KEY or persist it via /install-bridge / the credentials subcommand; " +
+                "until then the remaining install checks are skipped.",
+        });
+        for (const [id, label] of [
+            ["connectivity", "Server connectivity"],
+            ["bootstrap", "Bootstrap config fields"],
+            ["indexing", "Repository indexing"],
+        ]) {
+            checks.push({ id, label, status: "SKIP", detail: "no credential resolved" });
+        }
+        return checks;
+    }
+    checks.push({
+        id: "credential",
+        label: "Bridge API credential",
+        status: "PASS",
+        detail: `resolved from ${cred.credentials.source} (value never read into the report)`,
+    });
+    const apiKey = cred.credentials.apiKey;
+    const repoQuery = `repo_name=${encodeURIComponent(target.repoName)}`;
+    // --- connectivity ---
+    const ping = await probeGet(deps, `${target.baseUrl}/jira/ping?${repoQuery}`, apiKey);
+    if (!ping.ok) {
+        checks.push({
+            id: "connectivity",
+            label: "Server connectivity",
+            status: "WARN",
+            detail: `unreachable (${ping.error})`,
+            remediation: `check ${target.baseUrl} and your network, then re-run doctor.`,
+        });
+    }
+    else if (ping.status === 200) {
+        checks.push({ id: "connectivity", label: "Server connectivity", status: "PASS", detail: "ping OK" });
+    }
+    else if (ping.status === 401 || ping.status === 403) {
+        checks.push({
+            id: "connectivity",
+            label: "Server connectivity",
+            status: "WARN",
+            detail: `the server rejected the resolved key (HTTP ${ping.status})`,
+            remediation: "the key may have been rotated — re-run install-bridge with a current key.",
+        });
+    }
+    else if (ping.status === 404) {
+        checks.push({
+            id: "connectivity",
+            label: "Server connectivity",
+            status: "WARN",
+            detail: `the server does not know repo '${target.repoName}' (HTTP 404)`,
+            remediation: "create the project in the setup UI (or check BAPI_REPO_NAME spelling).",
+        });
+    }
+    else {
+        checks.push({
+            id: "connectivity",
+            label: "Server connectivity",
+            status: "WARN",
+            detail: `unexpected HTTP ${ping.status} from /jira/ping`,
+        });
+    }
+    // --- bootstrap fields ---
+    const manifest = await probeGet(deps, `${target.baseUrl}/jira/config/install-manifest?${repoQuery}`, apiKey);
+    if (!manifest.ok) {
+        checks.push({
+            id: "bootstrap",
+            label: "Bootstrap config fields",
+            status: "WARN",
+            detail: `manifest unreachable (${manifest.error})`,
+        });
+    }
+    else if (manifest.status === 404) {
+        checks.push({
+            id: "bootstrap",
+            label: "Bootstrap config fields",
+            status: "WARN",
+            detail: "no configuration row found for this repository",
+            remediation: "create the project in the setup UI, then run /install-bridge.",
+        });
+    }
+    else if (manifest.status === 200) {
+        const summary = summarizeManifestGroups(manifest.body);
+        if (!summary) {
+            checks.push({
+                id: "bootstrap",
+                label: "Bootstrap config fields",
+                status: "WARN",
+                detail: "manifest response had an unexpected shape",
+            });
+        }
+        else if (summary.unset.length === 0) {
+            checks.push({
+                id: "bootstrap",
+                label: "Bootstrap config fields",
+                status: "PASS",
+                detail: `${summary.total}/${summary.total} bootstrap fields set`,
+            });
+        }
+        else {
+            checks.push({
+                id: "bootstrap",
+                label: "Bootstrap config fields",
+                status: "WARN",
+                detail: `${summary.total - summary.unset.length}/${summary.total} set; unset: ${summary.unset.join(", ")}`,
+                remediation: "run /install-bridge to derive the unset fields (intentionally-unset fields are fine to leave).",
+            });
+        }
+    }
+    else {
+        checks.push({
+            id: "bootstrap",
+            label: "Bootstrap config fields",
+            status: "WARN",
+            detail: `unexpected HTTP ${manifest.status} from the install manifest`,
+        });
+    }
+    // --- integrations (from the same manifest response; presence booleans only) ---
+    if (manifest.ok && manifest.status === 200) {
+        const integrations = summarizeIntegrations(manifest.body);
+        if (integrations === null) {
+            checks.push({
+                id: "integrations",
+                label: "Integration credentials",
+                status: "SKIP",
+                detail: "the manifest response carried no integrations checklist",
+            });
+        }
+        else if (integrations.unconfigured.length === 0) {
+            checks.push({
+                id: "integrations",
+                label: "Integration credentials",
+                status: "PASS",
+                detail: `${integrations.total}/${integrations.total} configured`,
+            });
+        }
+        else {
+            checks.push({
+                id: "integrations",
+                label: "Integration credentials",
+                status: "WARN",
+                detail: `not configured: ${integrations.unconfigured.join(", ")}`,
+                remediation: "a human configures these in the setup UI (project settings) — Bridge API never accepts " +
+                    "integration secrets through an agent or MCP tool.",
+            });
+        }
+    }
+    else {
+        checks.push({
+            id: "integrations",
+            label: "Integration credentials",
+            status: "SKIP",
+            detail: "manifest unavailable",
+        });
+    }
+    // --- indexing ---
+    const parse = await probeGet(deps, `${target.baseUrl}/jira/parse-status?${repoQuery}`, apiKey);
+    if (!parse.ok || parse.status !== 200) {
+        checks.push({
+            id: "indexing",
+            label: "Repository indexing",
+            status: "SKIP",
+            detail: parse.ok ? `HTTP ${parse.status} from /jira/parse-status` : `unreachable (${parse.error})`,
+        });
+    }
+    else {
+        const status = parse.body?.status;
+        if (status === "in_progress") {
+            const startedAt = parse.body.started_at;
+            checks.push({
+                id: "indexing",
+                label: "Repository indexing",
+                status: "INFO",
+                detail: `parse job in progress${typeof startedAt === "string" ? ` (started ${startedAt})` : ""}`,
+            });
+        }
+        else {
+            checks.push({
+                id: "indexing",
+                label: "Repository indexing",
+                status: "INFO",
+                detail: "no parse job currently running — if this repository has never been indexed, " +
+                    "queue one with /parse-repository (monitor with get_parse_status).",
+            });
+        }
+    }
+    return checks;
+}
+/** Render the install-status section of the doctor report (pure formatting). */
+export function formatInstallStatusReport(checks) {
+    const lines = ["", "Install status (easy-install done criteria — advisory)", ""];
+    const pad = {
+        PASS: "PASS   ",
+        WARN: "WARN   ",
+        INFO: "INFO   ",
+        SKIP: "SKIPPED",
+    };
+    for (const check of checks) {
+        lines.push(`${pad[check.status]} ${check.label}${check.detail ? ` — ${check.detail}` : ""}`);
+        if (check.remediation) {
+            lines.push(`  ${check.remediation}`);
+        }
+    }
+    lines.push("");
+    lines.push("This section is advisory and never changes the doctor exit code. It performs read-only GETs only.");
+    return lines.join("\n");
+}

package/build/mcp-invoke.js

@@ -32,10 +32,15 @@ import { getThirdPartyTargetDefinition, resolveThirdPartyTargetEnv, validateThir
 export function getMcpInvokeUsage() {
     return [
         "Usage:",
-        "  npx -y @bridge_gpt/mcp-server mcp-invoke --target <target> --project-root <ABS_WORKTREE_PATH>",
+        "  node <abs>/mcp_server/build/index.js mcp-invoke --target <target> --project-root <ABS_WORKTREE_PATH>",
+        "",
+        "  (npm-channel fallback may invoke the same shim through a package spec, e.g.",
+        "   npx -y @bridge_gpt/mcp-server@latest mcp-invoke --target <target> --project-root <ABS_WORKTREE_PATH>)",
         "",
         "Internal worktree shim: resolves the target's launch command and credentials",
         "from the given project root, then spawns the real MCP server over stdio.",
+        "Argument parsing is identical regardless of how this process was launched",
+        "(absolute-path node invocation vs npm-channel npx).",
         "",
         "Flags:",
         "  --target <target>            MCP target to launch. 'bapi' launches the Bridge",
@@ -264,11 +269,22 @@ export async function resolveBapiInvocation(projectRoot, deps) {
     if (!credResult.ok) {
         return { ok: false, error: `failed to resolve credentials: ${credResult.error}` };
     }
-    const env = buildChildEnv(deps.env, {
+    const overlay = {
         BAPI_API_KEY: credResult.credentials.apiKey,
         BAPI_PROJECT_ROOT: projectRoot,
         BAPI_REPO_NAME: repoName,
-    });
+    };
+    // BAPI-527: `CONDUCTOR_NODE_PATH` is NON-SECRET operational metadata (the
+    // captured conductor Node path used by the worker-ledger CLI subprocess).
+    // `buildChildEnv` already inherits the full parent env, so this re-affirms the
+    // pass-through explicitly and ONLY when present — it is a non-secret allowlist
+    // entry, never a credential. It is emphatically NOT the MCP server's re-exec
+    // command: the spawned command stays `deps.execPath` + `[scriptPath]` below.
+    const conductorNodePath = deps.env.CONDUCTOR_NODE_PATH;
+    if (typeof conductorNodePath === "string" && conductorNodePath.trim().length > 0) {
+        overlay.CONDUCTOR_NODE_PATH = conductorNodePath;
+    }
+    const env = buildChildEnv(deps.env, overlay);
     return {
         ok: true,
         invocation: { command: deps.execPath, args: [deps.scriptPath], env },

package/build/mcp-provisioning.js

@@ -18,9 +18,9 @@
  * to avoid a runtime import cycle.
  */
 import path from "path";
-import { VERSION } from "./version.generated.js";
 import { readBridgeConfig } from "./bridge-config.js";
 import { getThirdPartyTargetDefinition, validateThirdPartyTargetManifestEntry, } from "./third-party-mcp-targets.js";
+import { buildMcpShimCommand, } from "./mcp-server-invocation.js";
 // ---------------------------------------------------------------------------
 // Pure helpers
 // ---------------------------------------------------------------------------
@@ -55,27 +55,27 @@ export function serverNameForMcpTarget(target) {
     return target === "bapi" ? "bridge-api" : target;
 }
 /**
- * Build a secret-free shim entry for any target. `args` are version-pinned and
- * carry the target name plus the absolute project root; there is intentionally
- * no `env` block.
+ * Build a secret-free shim entry for any target from a structured invocation.
+ * The command/args carry the target name plus the absolute project root; there is
+ * intentionally no `env` block. The absolute-build-path form serializes as
+ * `{ command: "node", args: ["<abs>/build/index.js", "mcp-invoke", …] }` (the
+ * node executable is a single substitutable field), and the npm-channel fallback
+ * as `{ command: "npx", args: ["-y", "<spec>", "mcp-invoke", …] }`.
+ *
+ * BAPI-527: `.mcp.json` remains intentionally ENV-FREE. `CONDUCTOR_NODE_PATH`
+ * (the captured conductor Node path for the worker-ledger CLI subprocess) is NOT
+ * written here — it is inherited at runtime from the worker SHELL env that
+ * `start-tickets` injects at the spawn boundary, never stored as a registration
+ * value. Keeping the shim env-free preserves the credential-safety invariant
+ * (secrets are resolved by the `mcp-invoke` shim at launch, not persisted in the
+ * worktree) and equally avoids persisting non-secret operational metadata here.
  */
-export function buildShimMcpServerEntry(target, absoluteWorktreePath) {
-    return {
-        command: "npx",
-        args: [
-            "-y",
-            `@bridge_gpt/mcp-server@${VERSION}`,
-            "mcp-invoke",
-            "--target",
-            target,
-            "--project-root",
-            absoluteWorktreePath,
-        ],
-    };
+export function buildShimMcpServerEntry(target, absoluteWorktreePath, invocation) {
+    return buildMcpShimCommand(invocation, target, absoluteWorktreePath);
 }
 /** Back-compat wrapper around `buildShimMcpServerEntry("bapi", ...)`. */
-export function buildBridgeApiShimMcpServerEntry(absoluteWorktreePath) {
-    return buildShimMcpServerEntry("bapi", absoluteWorktreePath);
+export function buildBridgeApiShimMcpServerEntry(absoluteWorktreePath, invocation) {
+    return buildShimMcpServerEntry("bapi", absoluteWorktreePath, invocation);
 }
 /**
  * Convert all supported manifest `mcp` entries into a map of server name -> shim
@@ -84,12 +84,12 @@ export function buildBridgeApiShimMcpServerEntry(absoluteWorktreePath) {
  * or incomplete non-`bapi` targets are skipped with a secret-free warning (they
  * never appear in the returned entries).
  */
-export function buildMcpServerEntriesForManifest(manifest, absoluteWorktreePath) {
+export function buildMcpServerEntriesForManifest(manifest, absoluteWorktreePath, invocation) {
     const entries = {};
     const warnings = [];
     for (const mcp of manifest.mcp) {
         if (mcp.target === "bapi") {
-            entries[serverNameForMcpTarget("bapi")] = buildShimMcpServerEntry("bapi", absoluteWorktreePath);
+            entries[serverNameForMcpTarget("bapi")] = buildShimMcpServerEntry("bapi", absoluteWorktreePath, invocation);
             continue;
         }
         const definition = getThirdPartyTargetDefinition(mcp.target);
@@ -102,9 +102,9 @@ export function buildMcpServerEntriesForManifest(manifest, absoluteWorktreePath)
             warnings.push(`MCP target '${mcp.target}' registration skipped: ${validation.error}.`);
             continue;
         }
-        entries[serverNameForMcpTarget(mcp.target)] = buildShimMcpServerEntry(mcp.target, absoluteWorktreePath);
+        entries[serverNameForMcpTarget(mcp.target)] = buildShimMcpServerEntry(mcp.target, absoluteWorktreePath, invocation);
     }
-    return { entries, warnings };
+    return { entries, warnings, registrationForm: invocation.form };
 }
 /** Both registration files written for every provisioned worktree. */
 export function getWorktreeMcpRegistrationTargets(worktreePath, platform) {
@@ -305,7 +305,7 @@ export async function provisionMcpRegistrationForWorktree(row, deps) {
     if (!normalized.ok) {
         return { ...row, status: "spawn-failed", error: `MCP provisioning failed: ${normalized.error}` };
     }
-    const built = buildMcpServerEntriesForManifest(read.manifest, normalized.path);
+    const built = buildMcpServerEntriesForManifest(read.manifest, normalized.path, deps.mcpServerInvocation);
     if (Object.keys(built.entries).length === 0) {
         // Nothing supported to write (e.g. a manifest with no bapi target and no
         // supported Tier-2 targets). Surface any warnings but leave status unchanged.
@@ -318,10 +318,16 @@ export async function provisionMcpRegistrationForWorktree(row, deps) {
             return { ...row, status: "spawn-failed", error: `MCP provisioning failed: ${result.error}` };
         }
     }
+    // Record the resolved registration form for audit (path-free — the form label
+    // only, never the absolute server entry path, which could leak a username).
+    let result = { ...row, mcpRegistrationForm: built.registrationForm };
+    result = withWarnings(result, built.warnings);
+    if (built.registrationForm !== "absolute-build-path") {
+        result = withWarning(result, "MCP registration used npm-channel fallback because an on-disk build entry was not resolvable.");
+    }
     // Pre-approve the just-registered servers so Claude Code does not prompt to
     // trust them in this fresh worktree path. Best-effort: a failure here only
     // loses the convenience of skipping the prompt, so warn and still spawn.
-    let result = withWarnings(row, built.warnings);
     const serverNames = Object.keys(built.entries);
     const trust = await writeClaudeServerTrustSettings(normalized.path, serverNames, deps);
     if (!trust.ok) {

package/build/mcp-registration-doctor.js

@@ -35,22 +35,42 @@ function flagValue(args, flag) {
     return undefined;
 }
 /**
- * True when `entry` is a secret-free Bridge API shim registration that launches
- * `npx -y @bridge_gpt/mcp-server@<version> mcp-invoke --target bapi
- * --project-root <worktreeRoot>`. The `--target` must be `bapi` and the
- * `--project-root` must match the given worktree exactly.
+ * True when `entry` is a secret-free Bridge API shim registration pointing at
+ * THIS worktree. Two forms are accepted (BAPI-526):
+ *
+ *   - Absolute-build-path (PRIMARY): an absolute `node` (or absolute Node-path)
+ *     invocation of the conductor's own compiled server, e.g.
+ *     `{ command: "node", args: ["<abs>/mcp_server/build/index.js", "mcp-invoke",
+ *     "--target", "bapi", "--project-root", "<worktreeRoot>"] }`. `command` may be
+ *     any non-empty string ("node" or a future absolute Node path); `args[0]` is a
+ *     non-empty server entry path.
+ *   - npm-channel (LEGACY/FALLBACK): `{ command: "npx", args: ["-y",
+ *     "@bridge_gpt/mcp-server@<spec>", "mcp-invoke", "--target", "bapi",
+ *     "--project-root", "<worktreeRoot>"] }`.
+ *
+ * In both forms `--target` must be `bapi` and `--project-root` must match the
+ * given worktree exactly. The server entry path is NOT required to sit under any
+ * particular username/path prefix.
  */
 export function isBridgeApiShimEntry(entry, worktreeRoot) {
     if (!entry || typeof entry !== "object" || Array.isArray(entry))
         return false;
     const candidate = entry;
-    if (candidate.command !== "npx")
+    if (typeof candidate.command !== "string" || candidate.command.length === 0)
         return false;
     if (!Array.isArray(candidate.args))
         return false;
     const args = candidate.args.filter((a) => typeof a === "string");
-    if (!args.some((a) => a.startsWith("@bridge_gpt/mcp-server")))
-        return false;
+    if (candidate.command === "npx") {
+        // npm-channel fallback: must reference the package spec.
+        if (!args.some((a) => a.startsWith("@bridge_gpt/mcp-server")))
+            return false;
+    }
+    else {
+        // Absolute-build-path: first arg must be a non-empty server entry path.
+        if (typeof args[0] !== "string" || args[0].length === 0)
+            return false;
+    }
     if (!args.includes("mcp-invoke"))
         return false;
     if (flagValue(args, "--target") !== "bapi")