@bridge_gpt/mcp-server 0.2.41 → 0.2.42

package/build/sfcc/tool-wrapper.js

@@ -368,6 +368,21 @@ function notConfigured(failureClass, message) {
  */
 export function withSfccGate(deps, handler) {
     return async (args, target) => {
+        // (0) Refuse a handler that was registered WITHOUT the target boundary.
+        //
+        // `withSfccGate` returns a two-arity handler and `register.ts` is the only
+        // thing that supplies the second argument, via `withSfccTargetBoundary`. A
+        // caller that skips that wrapper reaches (c) below with `target` undefined
+        // and throws a bare `TypeError`, which the read-path error formatter then
+        // masks into an opaque, deliberately detail-free INTERNAL_ERROR 500 — a
+        // registration defect wearing the costume of an upstream failure. Refusing
+        // here names it instead, and does so BEFORE the version fetch so a
+        // misregistered tool can never cause a network call.
+        if (target === undefined || target === null) {
+            return notConfigured("target-not-supplied", "This SFCC tool was invoked without a resolved target, which means it was " +
+                "registered without withSfccTargetBoundary. Refusing rather than treating " +
+                "an unresolved target as approved.");
+        }
         // (a) Read /config-field/version
         const version = await getSfccVersionConfig(deps.buildGetUrl, deps.getGetHeaders, deps.repoName);
         if (version === null) {

package/build/start-tickets-prereqs.js

@@ -18,7 +18,8 @@ import { resolveBapiCredentials, getPrimaryCredentialStorePath, } from "./creden
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
 import { probeWorktreeMcpRegistration } from "./mcp-registration-doctor.js";
 import { probeWorktreeCommandAssets } from "./command-assets-doctor.js";
-import { CLAUDE_MCP_SHADOWING_REMEDIATION_COMMAND, formatClaudeMcpShadowFinding, formatClaudeUserConfigDiagnostic, inspectClaudeUserConfigForMcpShadowing, resolveClaudeUserConfigPath, } from "./claude-user-config-doctor.js";
+import { MCP_SERVER_NAME, MCP_PACKAGE_NAME } from "./mcp-identity.js";
+import { CLAUDE_MCP_SHADOWING_REMEDIATION_COMMAND, claudeMcpShadowingRemediationCommand, formatClaudeMcpShadowFinding, formatClaudeUserConfigDiagnostic, inspectClaudeUserConfigForMcpShadowing, resolveClaudeUserConfigPath, } from "./claude-user-config-doctor.js";
 // ---------------------------------------------------------------------------
 // Constants (moved here from start-tickets.ts so both consumers share them)
 // ---------------------------------------------------------------------------
@@ -42,7 +43,7 @@ export const TMUX_COMMAND = "tmux";
 /** Actionable hint emitted when Git Bash is missing on Windows. */
 export const GIT_FOR_WINDOWS_BASH_HINT = "Install Git for Windows / Git Bash — Worktrunk runs its pre-start / post-start hooks via Git Bash.";
 /** The read-only doctor invocation surfaced from preflight failures and elsewhere. */
-export const START_TICKETS_DOCTOR_COMMAND = "npx -y @bridge_gpt/mcp-server doctor";
+export const START_TICKETS_DOCTOR_COMMAND = `npx -y ${MCP_PACKAGE_NAME} doctor`;
 /**
  * BAPI-527 live-source checkout guard (conductor durable execution).
  *
@@ -352,7 +353,7 @@ function ripgrepDescriptor() {
 const CREDENTIAL_RESOLUTION_HINT = "Rerun /install-bridge to persist the routing credential, set BAPI_API_KEY in the " +
     'environment, or add it under "bapi:<repo_name>" in ~/.config/bridge/credentials.json. ' +
     "To migrate a key that only lives in .mcp.json / .cursor/mcp.json, run: " +
-    "npx -y @bridge_gpt/mcp-server credentials migrate-agent-config --write-credentials.";
+    `npx -y ${MCP_PACKAGE_NAME} credentials migrate-agent-config --write-credentials.`;
 const CREDENTIAL_RESOLUTION_INSTALL_HINTS = {
     darwin: CREDENTIAL_RESOLUTION_HINT,
     linux: CREDENTIAL_RESOLUTION_HINT,
@@ -531,7 +532,7 @@ export async function resolveMainWorktreePathForDoctor(deps) {
  * which is why the advice below is phrased as "delete, or move aside". Keep every
  * such identifier out of this file, even inside a comment like this one.
  */
-const CLAUDE_MCP_SHADOWING_HINT = `Run \`${CLAUDE_MCP_SHADOWING_REMEDIATION_COMMAND}\` to clear the 'bridge-api' MCP ` +
+const CLAUDE_MCP_SHADOWING_HINT = `Run \`${CLAUDE_MCP_SHADOWING_REMEDIATION_COMMAND}\` to clear the '${MCP_SERVER_NAME}' MCP ` +
     "registration in ~/.claude.json (use the matching scope if it is registered at user scope, " +
     "or under the projects entry for this repository/worktree). This is ADVISORY: workers load " +
     "MCP servers with --strict-mcp-config from their own worktree registration, so this entry " +
@@ -598,15 +599,19 @@ export function claudeMcpShadowingDescriptor() {
             if (inspection.findings.length > 0) {
                 // Advisory (BAPI-790): reported in full, with the remediation command,
                 // but `found: true` so it never fails the prerequisite or the exit code.
+                // BAPI-807: the remediation names the key this finding was ACTUALLY
+                // found under. A fixed canonical command suggested against a legacy
+                // `bridge-api` registration silently succeeds as a no-op, which reads to
+                // the operator as "the advisory is wrong".
                 const findings = inspection.findings.map((finding) => `advisory: ${formatClaudeMcpShadowFinding(finding)} — not loaded by a worker under ` +
-                    `strict MCP loading; clear it with \`${CLAUDE_MCP_SHADOWING_REMEDIATION_COMMAND}\``);
+                    `strict MCP loading; clear it with \`${claudeMcpShadowingRemediationCommand(finding.registrationKey)}\``);
                 return { found: true, detail: [...findings, ...degraded].join("; ") };
             }
             return {
                 found: true,
                 detail: degraded.length > 0
                     ? degraded.join("; ")
-                    : "no foreign bridge-api registration in the Claude user config",
+                    : `no foreign ${MCP_SERVER_NAME} registration in the Claude user config`,
             };
         },
     };

package/build/start-tickets.js

@@ -59,10 +59,7 @@ import os from "node:os";
 import path from "path";
 import { VERSION } from "./version.generated.js";
 import { resolveBapiCredentials, getPrimaryCredentialStorePath, } from "./credential-store.js";
-// BAPI-814/E1b: the read-only index-branch override probe. `getIndexBranch` is
-// reused from the conduct-epic client rather than re-wrapped, so both conductor
-// paths read the one repository-wide override through the same client.
-import { getIndexBranch } from "./conduct-epic/bridge-client.js";
+import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
 import { resolveStartTicketsRepoName as resolveSharedStartTicketsRepoName, resolveRequiredStartTicketsRepoName, } from "./start-tickets-repo.js";
 import { provisionMcpRegistrationsForCreatedWorktrees, } from "./mcp-provisioning.js";
 import { provisionCommandsForCreatedWorktrees, } from "./command-provisioning.js";
@@ -78,6 +75,7 @@ import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentName
 import { createStartTicketsConductorContext, provisionConductorHooksForRows, emitStartTicketsRunStarted, injectConductorEnvIntoShellCommand, buildSupervisorTabCommand, isSupervisorLaunchEnabled, supervisorSpawnKey, } from "./start-tickets-conductor.js";
 import { transitionEpicDispatch, resolveConductorBridgeApiAccess, } from "./conductor/bridge-api-client.js";
 import { PR_BASE_BRANCH_ENV_VAR, buildPrBaseContractLaunchInstruction, } from "./pr-base-contract.js";
+import { INDEX_SCOPE_CONFIGURATION_ERROR, INDEX_SCOPE_ENV_VAR, validateOptionalIndexScope, } from "./index-scope-contract.js";
 // Re-export the shared prereq surface (constants, platform helpers, command
 // probes) so existing import sites that read them from "./start-tickets.js"
 // keep working unchanged.
@@ -121,7 +119,7 @@ export function appendSummaryRowWarning(row, warning) {
 export function getStartTicketsUsage() {
     return [
         "Usage:",
-        "  npx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]",
+        `  npx -y ${MCP_PACKAGE_NAME} start-tickets [flags] KEY [KEY ...]`,
         "",
         "Flags:",
         "  --agent claude|cursor-agent Agent command to launch in each worktree (default: claude)",
@@ -177,7 +175,6 @@ export function parseStartTicketsArgs(argv) {
     let maxParallelRaw;
     let agentName = DEFAULT_AGENT_NAME;
     let baseBranch = "main";
-    let baseBranchExplicit = false;
     let conductorEnabled = false;
     let workflow = "implement";
     let reviewRoundsRaw;
@@ -347,7 +344,6 @@ export function parseStartTicketsArgs(argv) {
                 return { status: "error", message: `Invalid --base-branch value: ${error}` };
             }
             baseBranch = trimmed;
-            baseBranchExplicit = true;
             continue;
         }
         if (arg === "--dry-run") {
@@ -455,7 +451,6 @@ export function parseStartTicketsArgs(argv) {
             branchOverrides,
             agentName,
             baseBranch,
-            ...(baseBranchExplicit ? { baseBranchExplicit: true } : {}),
             conductorEnabled,
             workflow,
             reviewRounds,
@@ -514,17 +509,19 @@ export function resolveStartTicketsPlatformConfig(deps, agent, autoApprove = fal
 resumeMode = false, workflow = "implement", reviewRounds, 
 // BAPI-586: the effective run base branch (incl. epic.base_branch override).
 // Injected as BAPI_BASE_BRANCH so the spawned worker's PR targets it — for
-// conductor runs always, and (BAPI-801) for plain runs whose base is a
-// non-default branch — and threaded (BAPI-593) into the spawned workflow command.
+// conductor runs always, and (BAPI-801/BAPI-847) for every plain run whose base
+// resolved, `main` included — and threaded (BAPI-593) into the spawned workflow
+// command.
 baseBranch) {
     if (!isSupportedStartTicketsPlatform(deps.platform)) {
         return { ok: false, error: unsupportedPlatformMessage(deps.platform) };
     }
     const platform = deps.platform;
-    // BAPI-801: both conductor and plain dispatch carry the PR-base ENVIRONMENT
-    // contract (see resolvePrBaseBranchEnvValue). Only the conductor launch
-    // INSTRUCTION remains conductor-only — a plain worker's prompt stays bare and
-    // learns the base from the env plus the create-PR instruction files.
+    // BAPI-801/BAPI-847: both conductor and plain dispatch carry the PR-base
+    // ENVIRONMENT contract for EVERY resolved base, `main` included (see
+    // resolvePrBaseBranchEnvValue). Only the conductor launch INSTRUCTION remains
+    // conductor-only — a plain worker's prompt stays bare and learns the base from
+    // the env plus the create-PR instruction files.
     const prBaseBranch = resolvePrBaseBranchEnvValue(conductorEnabled, baseBranch);
     return {
         ok: true,
@@ -566,26 +563,33 @@ export function prependRepoNameEnvAssignment(command, repoName, platform = "darw
     return `export BAPI_REPO_NAME='${shSquoteInner(repoName)}' && ${command}`;
 }
 /**
- * BAPI-801: decide the `BAPI_BASE_BRANCH` value a spawned worker's shell should
- * carry — the single rule shared by the real spawn builder
+ * BAPI-801/BAPI-847: decide the `BAPI_BASE_BRANCH` value a spawned worker's shell
+ * should carry — the single rule shared by the real spawn builder
  * ({@link resolveStartTicketsPlatformConfig}) and the dry-run preview builder
  * ({@link getDryRunPlatformDetails}), so the preview can never drift from what
  * is actually spawned.
  *
  * - Conductor runs export whatever base was resolved, `main` included — BAPI-586
  *   behavior, unchanged.
- * - Plain runs export only a non-empty base other than the CLI default `main`.
- *   This mirrors the `--base-branch` threading rule in {@link buildAgentPrompt},
- *   keeps today's plain spawn strings byte-stable on the default base, and costs
- *   nothing: the create-PR fallback tier is `main` anyway.
+ * - Plain runs export EVERY resolved base, `main` included (BAPI-847).
  *
- * Returns `null` when nothing should be exported;
+ * The plain rule used to omit `main` on the reasoning that "the create-PR
+ * fallback tier is `main` anyway". That reasoning was false, and it is the defect
+ * BAPI-847 removes: create-PR falls back to the `base_branch` CONFIG FIELD before
+ * it falls back to `main`, so a run that exported nothing resolved through
+ * whatever that repository-wide field happened to hold — `epic/<EPIC>` while an
+ * epic held the repository's index. An unrelated ticket's PR was opened against
+ * an epic branch exactly that way. Exporting the real base always makes a
+ * worker's PR target independent of repository-wide configuration.
+ *
+ * Returns `null` only when no base was resolved at all (unset, or blank after
+ * normalization) — a blank value is never converted into an exported branch name.
  * {@link prependBaseBranchEnvAssignment} is fail-open on that value.
  */
 function resolvePrBaseBranchEnvValue(conductorEnabled, baseBranch) {
     if (conductorEnabled)
         return baseBranch ?? null;
-    if (!baseBranch || baseBranch === "main")
+    if (!baseBranch || !baseBranch.trim())
         return null;
     return baseBranch;
 }
@@ -1698,6 +1702,41 @@ export async function materializeWorkerLaunchCommand(deps, key, fullCommand) {
 // ---------------------------------------------------------------------------
 // Tab spawning across created worktrees
 // ---------------------------------------------------------------------------
+/**
+ * Build the per-row environment injected into ONE worker's launch command
+ * (BAPI-394 conductor identity + BAPI-844 index scope).
+ *
+ * Returns `undefined` when the row carries neither, so an ordinary worker's
+ * command passes through {@link injectConductorEnvIntoShellCommand} byte-for-byte
+ * unchanged — the pre-feature bare command, with no empty assignment and no
+ * altered ordering.
+ *
+ * The scope is applied LAST so it is emitted from the row's own value and can
+ * never be supplied by a shared conductor env object. Reuses the existing
+ * injection path rather than adding a second shell-prefix mechanism: one escaper,
+ * one platform rule, one place a quoting bug could live.
+ */
+export function buildRowSpawnEnv(row) {
+    if (!row.conductorEnv && !row.indexScope)
+        return undefined;
+    const env = { ...row.conductorEnv };
+    if (row.indexScope)
+        env[INDEX_SCOPE_ENV_VAR] = row.indexScope;
+    return env;
+}
+/**
+ * Stamp the run's validated index scope onto every SPAWNABLE row (BAPI-844).
+ *
+ * A no-op that returns the input array unchanged when the run declared no scope,
+ * so an ordinary run's rows are the exact objects they were. Non-spawnable rows
+ * (`create-failed`, `dry-run`, `skipped`) are never stamped: nothing launches for
+ * them, and stamping would put a routing token into a summary row.
+ */
+export function stampIndexScopeOnRows(rows, indexScope) {
+    if (!indexScope)
+        return rows;
+    return rows.map((row) => row.status === "created" && row.path ? { ...row, indexScope } : row);
+}
 /**
  * Open one tab/session per successfully-created worktree, building each shell
  * command with the platform-correct `buildShellCommand` and passing per-ticket
@@ -1716,7 +1755,7 @@ export async function spawnTabsForCreatedWorktrees(deps, rows, terminal, buildSh
         // Scope the row's conductor identity env to this terminal/tab/session only
         // (BAPI-394). No-op when the row carries no conductorEnv (dry-run, non-Claude
         // agents, or conductor disabled). Never mutates process/global env.
-        const shellCommand = injectConductorEnvIntoShellCommand(deps.platform, baseShellCommand, row.conductorEnv);
+        const shellCommand = injectConductorEnvIntoShellCommand(deps.platform, baseShellCommand, buildRowSpawnEnv(row));
         // Deliver the (potentially multi-KB) command via a launch-script file so the
         // terminal spawn payload stays tiny and escaping-immune. No-op when no writer
         // seam is configured; a failed write falls back inline only while the command
@@ -1764,10 +1803,10 @@ export function getDryRunPlatformDetails(agent, platform = process.platform, env
         // The builder accepts an optional resolved modelAlias; the dry-run caller
         // now passes the previewed tier's alias so `--model` shows in the preview.
         // The resolved repo name (when known) is injected as a BAPI_REPO_NAME prefix,
-        // and (BAPI-801) the PR base as a BAPI_BASE_BRANCH prefix through the SAME
-        // resolvePrBaseBranchEnvValue rule and the same outermost ordering the real
-        // spawn builder uses — dry-run shares both environment renderings with real
-        // spawning. Reuses the same buildAgentShellCommand/buildAgentPrompt path as a
+        // and (BAPI-801/BAPI-847) the PR base as a BAPI_BASE_BRANCH prefix through the
+        // SAME resolvePrBaseBranchEnvValue rule — including the ordinary `main` case —
+        // and the same outermost ordering the real spawn builder uses; dry-run shares
+        // both environment renderings with real spawning. Reuses the same buildAgentShellCommand/buildAgentPrompt path as a
         // real spawn — dry-run is never special-cased — so the preview is exact.
         buildAgentShellCommand: (key, worktreePath, modelAlias) => prependBaseBranchEnvAssignment(prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, false, workflow, reviewRounds, baseBranch), repoName, platform), resolvePrBaseBranchEnvValue(conductorEnabled, baseBranch), platform),
     };
@@ -1788,7 +1827,7 @@ export function buildDryRunMcpProvisioningLines(worktreePath, platform = process
     const invocation = mcpServerInvocation ?? {
         form: "npm-channel",
         command: "npx",
-        packageSpec: "@bridge_gpt/mcp-server@latest",
+        packageSpec: `${MCP_PACKAGE_NAME}@latest`,
     };
     const built = buildMcpShimCommand(invocation, "<target>", worktreePath);
     const shim = `${built.command} ${built.args.join(" ")}`;
@@ -1811,11 +1850,12 @@ export function buildDryRunDetailLines(agent, key, branch, platform = process.pl
     const { worktrunkBinary, buildAgentShellCommand: build } = getDryRunPlatformDetails(agent, platform, env, autoApprove, conductorEnabled, repoName, workflow, reviewRounds, baseBranch);
     const wtArgs = buildWtSwitchArgs(branch, false, baseBranch);
     const agentInvocation = build(key, "<worktree-path>", modelAlias);
-    // BAPI-801: one concise secondary detail naming the PR base, emitted only when
-    // the shared rule actually exports BAPI_BASE_BRANCH. It sits AFTER the rendered
-    // spawn command so the copyable command stays the primary scan target, and it
-    // is ordinary routing detail — never warning-like. An ordinary plain run on
-    // `main` exports nothing and so keeps its existing output density verbatim.
+    // BAPI-801/BAPI-847: one concise secondary detail naming the PR base, emitted
+    // whenever the shared rule exports BAPI_BASE_BRANCH — which is now every run
+    // with a resolved base, the ordinary `main` case included, because that is what
+    // the real spawn exports. It sits AFTER the rendered spawn command so the
+    // copyable command stays the primary scan target, and it is ordinary routing
+    // detail — never warning-like.
     const prBaseBranch = resolvePrBaseBranchEnvValue(conductorEnabled, baseBranch);
     return [
         `DRY-RUN: ${key} -> branch=${branch}`,
@@ -2800,6 +2840,19 @@ async function defaultClaimEpicDispatch(dispatchKey, runId, deps) {
     });
 }
 export async function orchestrateStartTickets(deps, options, overrides = {}) {
+    // BAPI-844: validate the declared index scope FIRST, before any side effect at
+    // all — including the temp-dir prune below. A malformed declaration is a launch
+    // configuration failure, not something to spawn canonical workers through: the
+    // whole point of declaring a scope is that these workers must not research the
+    // canonical index. The message is the shared fixed text, so the submitted value
+    // never reaches the summary, a warning, or the operator's terminal.
+    let indexScope;
+    try {
+        indexScope = validateOptionalIndexScope(options.epic?.index_scope_id);
+    }
+    catch {
+        return { ok: false, error: INDEX_SCOPE_CONFIGURATION_ERROR };
+    }
     // IH-2 (PR #552 review): best-effort prune of stale launch-script temp dirs
     // before doing anything else. Awaited (to avoid concurrent cleanup races) but
     // fully fail-open — it never throws, so a dry-run also benefits from cleanup
@@ -2988,57 +3041,13 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     if (overrides.modelRoutingWarningLog) {
         emitInvocationModelRoutingDiagnosticForRows(routed, overrides.modelRoutingWarningLog);
     }
-    const rows = await spawnTabsFn(deps, routed, terminal, platformConfig.config.buildAgentShellCommand);
+    // BAPI-844: stamp the validated scope on the spawnable rows immediately before
+    // the spawn, so the value the tab is launched with is the one this run
+    // declared. A run with no scope gets the identical `routed` array back.
+    const scoped = stampIndexScopeOnRows(routed, indexScope);
+    const rows = await spawnTabsFn(deps, scoped, terminal, platformConfig.config.buildAgentShellCommand);
     return { ok: true, rows };
 }
-/**
- * Warn when an implicit base branch could be resolved through an active
- * repository-wide index-branch override (BAPI-814/E1b).
- *
- * Informational only, and deliberately narrow:
- *
- * - **Only for an IMPLICIT base.** An explicit `--base-branch` is the caller's
- *   own decision and is unaffected by the override, so the probe is skipped
- *   entirely — no request is made and no warning is printed.
- * - **Only with resolvable credentials.** `start-tickets` creates worktrees and
- *   opens tabs; it does not require Bridge access to do its job. "No credential"
- *   is therefore an ordinary state for this command, not a diagnostic, and
- *   staying silent keeps an unrelated command from growing a credential
- *   complaint. A lookup that FAILS after credentials resolved is different, and
- *   does produce one bounded, sanitized line.
- * - **Never a refusal.** Nothing here changes the exit code, the base branch, or
- *   any spawn behavior.
- *
- * Warnings go to `errorLog` (stderr), so machine-readable stdout stays clean.
- */
-async function warnOnIndexOverrideForImplicitBase(deps, options, errorLog, fetchImpl) {
-    if (options.baseBranchExplicit)
-        return;
-    const access = await resolveConductorBridgeApiAccess({
-        env: deps.env,
-        cwd: deps.cwd,
-        homedir: os.homedir,
-        platform: deps.platform,
-        readFile: deps.readFile ?? ((filePath) => readFile(filePath, "utf-8")),
-        stat: (filePath) => stat(filePath).then((info) => ({ mode: info.mode })),
-    });
-    if (!access.ok)
-        return;
-    const result = await getIndexBranch(access.access, fetchImpl);
-    if (!result.ok) {
-        errorLog(`Warning: the repository's indexed-branch override could not be read: ${result.error}. ` +
-            "Continuing — ticket startup is unaffected.");
-        return;
-    }
-    const override = result.value.override;
-    if (override === null)
-        return;
-    errorLog(`Warning: ${access.access.repoName} has an ACTIVE index-branch override: ` +
-        `'${override.override_branch}'. No --base-branch was given, so the implicit base — ` +
-        "the base-branch config field and feature-branch provisioning — may resolve through " +
-        "that override rather than the repository's usual base. Ticket startup is ALLOWED and " +
-        "continues; pass --base-branch to choose explicitly.");
-}
 /** Platform-specific guidance printed when one or more tabs fail to spawn. */
 function spawnFailureHintForPlatform(platform) {
     if (platform === "darwin") {
@@ -3094,9 +3103,6 @@ export async function runStartTicketsCli(argv, overrides = {}) {
         errorLog("Warning: --tier value was not one of cheap|basic|premium; ignoring the override and " +
             "using premium model routing for every ticket.");
     }
-    // BAPI-814/E1b: informational only, ahead of the dry-run branch so both a
-    // preview and a real run report the same repository-wide condition.
-    await warnOnIndexOverrideForImplicitBase(deps, options, errorLog, overrides.fetchImpl ?? globalThis.fetch);
     if (options.dryRun) {
         // Resolve the repo identity for the preview so the dry-run command matches
         // what the real spawn injects (see prependRepoNameEnvAssignment). The real

package/build/update-check.js

@@ -6,11 +6,12 @@ import { writeFile, mkdir, readFile } from "fs/promises";
 import path from "path";
 import os from "os";
 import { VERSION } from "./version.generated.js";
+import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
 const CACHE_TTL = 86400000; // 24 hours
 const FETCH_TIMEOUT = 3000;
-const REGISTRY_URL = "https://registry.npmjs.org/@bridge_gpt/mcp-server/latest";
+const REGISTRY_URL = `https://registry.npmjs.org/${MCP_PACKAGE_NAME}/latest`;
 export function getCachePath() {
-    return path.join(os.homedir(), ".config", "@bridge_gpt", "mcp-server", "update-check.json");
+    return path.join(os.homedir(), ".config", ...MCP_PACKAGE_NAME.split("/"), "update-check.json");
 }
 /**
  * Compare two semver strings. Returns true if `latest` is strictly greater.

package/build/upgrade-advice.js

@@ -12,6 +12,7 @@
  * caller can interpolate arbitrary (possibly secret-bearing) text into advice
  * that is surfaced to users and models.
  */
+import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
 /**
  * The canonical, always-fresh upgrade invocation.
  *
@@ -20,7 +21,7 @@
  * pin that upgrader then writes into each host config: the upgrader must be the
  * newest published code, while a project launcher must be reproducible.
  */
-export const CANONICAL_UPGRADE_COMMAND = "npx -y @bridge_gpt/mcp-server@latest --upgrade";
+export const CANONICAL_UPGRADE_COMMAND = `npx -y ${MCP_PACKAGE_NAME}@latest --upgrade`;
 /** Accept only plain release strings into user-facing advice. */
 const SAFE_VERSION_RE = /^[0-9A-Za-z.\-+]{1,64}$/;
 /** Replace anything that is not a plausible version string with a fixed marker. */

package/build/upgrade-cli.js

@@ -43,6 +43,7 @@ import { CANONICAL_UPGRADE_COMMAND } from "./upgrade-advice.js";
 import { describeLauncherReason, inspectLauncherConfigs, isApplicableStandardLauncher, isPrerequisiteFailure, LAUNCHER_CONFIG_TARGETS, } from "./launcher-config-inspection.js";
 import { buildGenericAgentShellCommand, detectTerminal, getDefaultSpawnTerminalTabForPlatform, createDefaultStartTicketsDeps, } from "./start-tickets.js";
 import { AGENT_REGISTRY } from "./agent-registry.js";
+import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
 /** The sentinel this CLI passes to the child it re-execs from `@latest`. */
 const INTERNAL_REEXEC_FLAG = "--internal-reexec";
 // ---------------------------------------------------------------------------
@@ -53,7 +54,7 @@ function defaultReexec(cwd, oldVersion) {
     return new Promise((resolve) => {
         const child = spawn(npxCmd, [
             "-y",
-            "@bridge_gpt/mcp-server@latest",
+            `${MCP_PACKAGE_NAME}@latest`,
             "upgrade",
             INTERNAL_REEXEC_FLAG,
             "--old-version",
@@ -67,7 +68,7 @@ function defaultReexec(cwd, oldVersion) {
     });
 }
 function localInstallPath(cwd) {
-    return path.join(cwd, "node_modules", "@bridge_gpt", "mcp-server");
+    return path.join(cwd, "node_modules", ...MCP_PACKAGE_NAME.split("/"));
 }
 async function defaultHasCompetingLocalInstall(cwd) {
     try {
@@ -81,7 +82,7 @@ async function defaultHasCompetingLocalInstall(cwd) {
 function defaultRemoveCompetingLocalInstall(cwd) {
     const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
     return new Promise((resolve) => {
-        const child = spawn(npmCmd, ["uninstall", "@bridge_gpt/mcp-server"], {
+        const child = spawn(npmCmd, ["uninstall", MCP_PACKAGE_NAME], {
             stdio: "inherit",
             cwd,
         });
@@ -153,20 +154,33 @@ export async function resolveUpgradeTarget(argv, deps) {
 // ---------------------------------------------------------------------------
 // Reporting helpers (pure)
 // ---------------------------------------------------------------------------
-/** Render the dry-run preview line for one inspected target. */
+/**
+ * Render the dry-run preview line for one inspected target.
+ *
+ * BAPI-807: an update against a legacy registration is described AS an update to
+ * that key — never as a rename. `upgrade` moves the package pin; it has no
+ * opinion about the registration name, and a preview implying otherwise would
+ * advertise a migration this command deliberately does not perform.
+ */
 export function formatDryRunLine(found) {
     const { relPath, targetVersion } = found;
+    // Suffix, not a rewrite of the line: the existing pin transitions are pinned
+    // by tests and the key is additional context, not a replacement for them.
+    const keyNote = found.legacyRegistration ? ` [\`${found.registrationKey}\` entry]` : "";
     switch (found.action) {
         case "repin":
-            return `    ${relPath}: ${found.currentVersion} -> ${targetVersion}`;
+            return `    ${relPath}: ${found.currentVersion} -> ${targetVersion}${keyNote}`;
         case "already-current":
-            return `    ${relPath}: already ${targetVersion}`;
+            return `    ${relPath}: already ${targetVersion}${keyNote}`;
         case "normalize-unpinned":
-            return `    ${relPath}: would normalize ${found.spec} -> @bridge_gpt/mcp-server@${targetVersion}`;
+            return `    ${relPath}: would normalize ${found.spec} -> ${MCP_PACKAGE_NAME}@${targetVersion}${keyNote}`;
         case "add":
-            return `    ${relPath}: would add @bridge_gpt/mcp-server@${targetVersion}`;
+            return `    ${relPath}: would add ${MCP_PACKAGE_NAME}@${targetVersion}`;
+        case "duplicate-registration":
+            // Reachable only in the dry-run preview: a real run refuses in preflight.
+            return `    ${relPath}: blocked — ${describeLauncherReason("duplicate-registration")}`;
         case "create":
-            return `    ${relPath}: would create with @bridge_gpt/mcp-server@${targetVersion}`;
+            return `    ${relPath}: would create with ${MCP_PACKAGE_NAME}@${targetVersion}`;
         case "skip-worktree-shim":
             return `    ${relPath}: skipped — worktree mcp-invoke shim (no published-package pin applies)`;
         case "skip-inactive":
@@ -184,11 +198,11 @@ export function formatResultLine(action) {
         case "already-current":
             return `  ${relPath}: already ${action.toVersion}`;
         case "normalized":
-            return `  ${relPath}: normalized ${action.fromSpec} -> @bridge_gpt/mcp-server@${action.toVersion}`;
+            return `  ${relPath}: normalized ${action.fromSpec} -> ${MCP_PACKAGE_NAME}@${action.toVersion}`;
         case "added":
-            return `  ${relPath}: added @bridge_gpt/mcp-server@${action.toVersion}`;
+            return `  ${relPath}: added ${MCP_PACKAGE_NAME}@${action.toVersion}`;
         case "created":
-            return `  ${relPath}: created with @bridge_gpt/mcp-server@${action.toVersion}`;
+            return `  ${relPath}: created with ${MCP_PACKAGE_NAME}@${action.toVersion}`;
         case "skipped-worktree-shim":
             return `  ${relPath}: skipped — worktree mcp-invoke shim preserved`;
         case "skipped-ahead":
@@ -278,8 +292,8 @@ export async function runUpgradeCli(argv, injected) {
             !isInternalReexec) {
             stdout(`- Would re-exec from @latest to upgrade the CLI ${VERSION} -> ${target.version}`);
         }
-        stdout(`- Would detect and remove competing local install in node_modules/@bridge_gpt/mcp-server if present.`);
-        stdout(`- Launcher pins (target @bridge_gpt/mcp-server@${target.version}):`);
+        stdout(`- Would detect and remove competing local install in node_modules/${MCP_PACKAGE_NAME} if present.`);
+        stdout(`- Launcher pins (target ${MCP_PACKAGE_NAME}@${target.version}):`);
         const lines = inspections
             .map(formatDryRunLine)
             .filter((l) => l !== null);
@@ -304,8 +318,8 @@ export async function runUpgradeCli(argv, injected) {
         if (!removed) {
             // Leaving it in place means npx keeps preferring the stale local copy, so
             // the repin below would be cosmetic. That is not a completed upgrade.
-            stderr("Bridge API upgrade failed: could not remove node_modules/@bridge_gpt/mcp-server.");
-            stderr("  Remove it manually (rm -rf node_modules/@bridge_gpt/mcp-server), then re-run the upgrade.");
+            stderr(`Bridge API upgrade failed: could not remove node_modules/${MCP_PACKAGE_NAME}.`);
+            stderr(`  Remove it manually (rm -rf node_modules/${MCP_PACKAGE_NAME}), then re-run the upgrade.`);
             return 1;
         }
         stdout("  Removed competing local install.");
@@ -313,7 +327,7 @@ export async function runUpgradeCli(argv, injected) {
     // ---- Phase 5: reconcile ----
     let initResult;
     try {
-        stdout(`\nReconciling launcher pins to @bridge_gpt/mcp-server@${target.version}...\n`);
+        stdout(`\nReconciling launcher pins to ${MCP_PACKAGE_NAME}@${target.version}...\n`);
         initResult = await deps.runInit(deps.cwd, {
             targetVersion: target.version,
             // Upgrade renders its own truthful per-config report below; the generic
@@ -367,10 +381,28 @@ export async function runUpgradeCli(argv, injected) {
             verificationFailures.push(`${action.relPath}: config disappeared after the write`);
             continue;
         }
+        // BAPI-807: a reconciliation that ADDED a canonical entry beside an existing
+        // legacy one leaves both keys present, which the re-inspection reports as
+        // `duplicate-registration`. Check it before the pin comparison — the pin
+        // question is meaningless once there are two entries, and this is the exact
+        // regression the resolve-then-write rule exists to prevent.
+        if (after.action === "duplicate-registration") {
+            verificationFailures.push(`${action.relPath}: reconciliation left TWO Bridge registrations in this config ` +
+                "(a canonical entry was written beside a legacy one)");
+            continue;
+        }
         if (after.action !== "already-current" || after.currentVersion !== target.version) {
-            verificationFailures.push(`${action.relPath}: expected @bridge_gpt/mcp-server@${target.version} after the write, ` +
+            verificationFailures.push(`${action.relPath}: expected ${MCP_PACKAGE_NAME}@${target.version} after the write, ` +
                 `found ${after.spec ?? "no recognizable package token"}`);
         }
+        // The pin landing is not sufficient: a legacy registration must still be
+        // under the SAME key it started under. `runInit` reports the key it actually
+        // wrote, so this compares two independent observations rather than trusting
+        // either one alone.
+        if (action.registrationKey && after.registrationKey !== action.registrationKey) {
+            verificationFailures.push(`${action.relPath}: expected the Bridge entry to remain under \`${action.registrationKey}\` ` +
+                `after the write, found ${after.registrationKey ? `\`${after.registrationKey}\`` : "no recognized registration"}`);
+        }
     }
     // ---- Phase 7: report what actually happened ----
     const resultLines = initResult.configActions

package/build/version.generated.js

@@ -1,2 +1,2 @@
 // AUTO-GENERATED — do not edit manually. Regenerate with: npm run build
-export const VERSION = "0.2.41";
+export const VERSION = "0.2.42";

package/docs/CONDUCTOR.md

@@ -315,6 +315,28 @@ redeems the approval token and the server returns `merge.succeeded`.
 store uses schema version 5 (BAPI-413) to accommodate the `merge.pending_approval`
 type in the `events.type` CHECK constraint.
 
+**Who performs the write (BAPI-832).** "Never holds VCS write credentials" above
+describes the *credential*, not the *typing*, and it remains true everywhere. Two
+paths now perform the provider write with the operator's local `gh` rather than
+with the GitHub App installation token, because GitHub's merge endpoint requires
+`contents: write` and the Bridge GPT App installation is `contents: read`:
+
+- the executor's `merge` job, via `makeLocalMergeExecutor` — the arrangement
+  BAPI-572 locked in; and
+- the `merge_pull_request` MCP tool, which since BAPI-832 sends
+  `execution: "local"`, receives a non-terminal `approved_for_local_execution`
+  from the route above, merges through that same `conductor/local-merge.ts` seam,
+  and reports the outcome to
+  `POST /vcs/pull-requests/{pr_number}/merge/complete`.
+
+In both, the server still owns every decision — the guards, the lease, and the
+terminal ledger row — and neither path holds a credential of its own; they borrow
+the operator's `gh` session. Mode is `merge_execution` on `epic_supervisor_config`
+(`local` by default, `server` for installations whose App holds
+`contents: write`). A caller that dies mid-merge is recovered by lease expiry, not
+by a new mechanism: the next call re-runs the whole tail, and the provider re-read
+reports `already_merged` if the merge landed.
+
 ## Durable execution environment hardening (BAPI-527)
 
 Worker ledger tools are made **reliable again** — this is a robustness fix for the