@bridge_gpt/mcp-server 0.2.18 → 0.2.20

package/build/start-tickets-prereqs.js

@@ -13,6 +13,7 @@
  * the runtime graph stays acyclic — `start-tickets.ts` imports values FROM here,
  * never the reverse.
  */
+import path from "path";
 import { resolveBapiCredentials, getPrimaryCredentialStorePath, } from "./credential-store.js";
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
 import { probeWorktreeMcpRegistration } from "./mcp-registration-doctor.js";
@@ -40,6 +41,29 @@ export const TMUX_COMMAND = "tmux";
 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";
+/**
+ * BAPI-527 live-source checkout guard (conductor durable execution).
+ *
+ * `BAPI_CONDUCTOR_LIVE_SOURCE_PATH` — OPTIONAL operator-set path to the checkout
+ * an operator's live dev server (e.g. `uvicorn main:app --reload`) is running
+ * from. When set, unattended conductor/epic/non-mutating start-tickets dispatch
+ * refuses to run if the conductor base repo it would operate on resolves to the
+ * SAME checkout, because cutting worktrees / touching branches under a live
+ * dev-server checkout risks corrupting the operator's working state. No existing
+ * "live dev-server source path" convention was found in the codebase during
+ * discovery, so this local env contract is introduced here. Read only from the
+ * injected `deps.env` (never global `process.env`) so it stays mockable.
+ *
+ * `BAPI_CONDUCTOR_ALLOW_LIVE_SOURCE_DISPATCH` — explicit escape hatch. When set
+ * to a truthy value (`1`/`true`/`yes`/`on`, case-insensitive) a detected
+ * collision is DOWNGRADED from fatal to a loud warning rather than silently
+ * ignored, so an operator who genuinely wants same-checkout dispatch can opt in
+ * with eyes open.
+ */
+export const CONDUCTOR_LIVE_SOURCE_PATH_ENV = "BAPI_CONDUCTOR_LIVE_SOURCE_PATH";
+export const CONDUCTOR_ALLOW_LIVE_SOURCE_DISPATCH_ENV = "BAPI_CONDUCTOR_ALLOW_LIVE_SOURCE_DISPATCH";
+/** Stable descriptor id for the live-source checkout guard (used in messages + doctor). */
+export const LIVE_SOURCE_GUARD_ID = "conductor-live-source";
 /** True only for the three first-class supported platforms. */
 export function isSupportedStartTicketsPlatform(platform) {
     return platform === "darwin" || platform === "win32" || platform === "linux";
@@ -412,6 +436,107 @@ export function worktreeMcpReachabilityDescriptor() {
         },
     };
 }
+/**
+ * Conservatively normalize a filesystem path for comparison: trim, drop a
+ * trailing separator, and resolve `.`/`..` segments via `path.resolve`. Symlink
+ * canonicalization is handled UPSTREAM by `git rev-parse --show-toplevel` (which
+ * returns the real, absolute repo root); this in-memory step is the fallback for
+ * a path that is not a git work tree. Never touches the filesystem.
+ */
+export function normalizeCheckoutPath(rawPath) {
+    const trimmed = rawPath.trim();
+    const resolved = path.resolve(trimmed);
+    // Strip a redundant trailing separator (path.resolve already removes most, but
+    // a bare root like "/" must be preserved).
+    return resolved.length > 1 ? resolved.replace(/[\\/]+$/, "") : resolved;
+}
+/**
+ * Resolve the repository ROOT for a path using the authoritative, read-only
+ * `git -C <path> rev-parse --show-toplevel`. Falls back to conservative
+ * in-memory normalization when the target is not a git work tree (or git is
+ * unavailable) so the guard still produces a comparable path. Never mutates.
+ */
+export async function resolveRepoRootPath(deps, targetPath) {
+    const result = await deps.runCommand("git", ["-C", targetPath, "rev-parse", "--show-toplevel"], { cwd: deps.cwd });
+    if (commandSucceeded(result)) {
+        const top = result.stdout.trim();
+        if (top.length > 0)
+            return normalizeCheckoutPath(top);
+    }
+    return normalizeCheckoutPath(targetPath);
+}
+/** True when the override env is set to a recognized truthy value (case-insensitive). */
+export function isLiveSourceDispatchOverrideEnabled(env) {
+    const raw = env[CONDUCTOR_ALLOW_LIVE_SOURCE_DISPATCH_ENV];
+    if (raw === undefined)
+        return false;
+    return ["1", "true", "yes", "on"].includes(raw.trim().toLowerCase());
+}
+/**
+ * Evaluate the live-source guard read-only. Resolves the conductor base repo root
+ * (from `deps.cwd`) and the configured live-source root, then compares them after
+ * conservative normalization. Returns one of three states; never throws, never
+ * mutates.
+ */
+export async function evaluateLiveSourceGuard(deps) {
+    const rawLiveSource = deps.env[CONDUCTOR_LIVE_SOURCE_PATH_ENV];
+    if (!rawLiveSource || rawLiveSource.trim().length === 0) {
+        return {
+            state: "not-configured",
+            detail: `no live dev-server source configured (${CONDUCTOR_LIVE_SOURCE_PATH_ENV} unset) — guard inactive`,
+        };
+    }
+    const baseRepoPath = await resolveRepoRootPath(deps, deps.cwd);
+    const liveSourcePath = await resolveRepoRootPath(deps, rawLiveSource);
+    if (baseRepoPath === liveSourcePath) {
+        return {
+            state: "collision",
+            detail: `COLLISION: the conductor base checkout (${baseRepoPath}) is the SAME checkout as the ` +
+                `configured live dev-server source (${CONDUCTOR_LIVE_SOURCE_PATH_ENV}). Unattended dispatch ` +
+                `would create worktrees / touch branches under a running dev server.`,
+            baseRepoPath,
+            liveSourcePath,
+        };
+    }
+    return {
+        state: "safe",
+        detail: `safe: conductor base checkout (${baseRepoPath}) differs from the configured live ` +
+            `dev-server source (${liveSourcePath})`,
+        baseRepoPath,
+        liveSourcePath,
+    };
+}
+/** Per-OS remediation hint for the live-source guard (secret-free). */
+const LIVE_SOURCE_GUARD_HINT = `Point ${CONDUCTOR_LIVE_SOURCE_PATH_ENV} at your live dev server's checkout ONLY when it ` +
+    `differs from this conductor base checkout, or dispatch the conductor from a separate clone. ` +
+    `To override the guard and dispatch anyway (not recommended), set ` +
+    `${CONDUCTOR_ALLOW_LIVE_SOURCE_DISPATCH_ENV}=1.`;
+const LIVE_SOURCE_GUARD_INSTALL_HINTS = {
+    darwin: LIVE_SOURCE_GUARD_HINT,
+    linux: LIVE_SOURCE_GUARD_HINT,
+    win32: LIVE_SOURCE_GUARD_HINT,
+};
+/**
+ * Doctor-only, strictly read-only descriptor that surfaces the three live-source
+ * guard states through the EXISTING doctor render (found + detail / missing +
+ * install hint):
+ *   - not-configured → `found: true`  (guard inactive, neutral)
+ *   - safe           → `found: true`  (different checkouts, safe)
+ *   - collision      → `found: false` (renders as a flagged problem + override hint)
+ * The runtime path specifics ride in `detail` for programmatic consumers.
+ */
+export function liveSourceGuardDescriptor() {
+    return {
+        id: LIVE_SOURCE_GUARD_ID,
+        label: "Conductor live-source checkout guard",
+        installHint: LIVE_SOURCE_GUARD_INSTALL_HINTS,
+        probe: async (deps) => {
+            const outcome = await evaluateLiveSourceGuard(deps);
+            // Only a collision reads as a problem; not-configured and safe are neutral.
+            return { found: outcome.state !== "collision", detail: outcome.detail };
+        },
+    };
+}
 /**
  * The exact existing live-preflight requirement set per platform, plus the git
  * work-tree custom check appended after the command checks. This is the ONLY
@@ -457,6 +582,7 @@ export function getDoctorOnlyPrereqDescriptors(_platform, _env, agent) {
         lizardDescriptor(),
         ripgrepDescriptor(),
         reviewTicketsGitDescriptor(),
+        liveSourceGuardDescriptor(),
     ];
 }
 /**
@@ -497,8 +623,14 @@ export async function probePrerequisite(deps, descriptor) {
  * `runPreflight` behaviour). Iterates the shared preflight descriptors in order
  * and returns on the first missing one. `uv` and the selected agent are NOT
  * enforced here — they are doctor-only. Never throws.
+ *
+ * BAPI-527: when `options.enforceLiveSourceGuard` is set (unattended
+ * conductor/epic/non-mutating dispatch), the live-source checkout guard is
+ * additionally evaluated after the standard loop — a collision is fatal
+ * (`live-source-collision`) unless the override env downgrades it to a returned
+ * `warning`.
  */
-export async function enforcePreflightPrerequisites(deps) {
+export async function enforcePreflightPrerequisites(deps, options = {}) {
     const descriptorsResult = getPreflightPrereqDescriptors(deps.platform, deps.env);
     if (!descriptorsResult.ok) {
         return { ok: false, reason: "unsupported-platform", error: descriptorsResult.error };
@@ -513,5 +645,24 @@ export async function enforcePreflightPrerequisites(deps) {
             return { ok: false, reason: "missing-prerequisite", error };
         }
     }
+    // BAPI-527 live-source checkout guard (unattended dispatch only). Read-only.
+    if (options.enforceLiveSourceGuard) {
+        const guard = await evaluateLiveSourceGuard(deps);
+        if (guard.state === "collision") {
+            const base = `Live-source checkout guard (${LIVE_SOURCE_GUARD_ID}): ${guard.detail}`;
+            if (isLiveSourceDispatchOverrideEnabled(deps.env)) {
+                return {
+                    ok: true,
+                    warning: `${base} Proceeding anyway because ${CONDUCTOR_ALLOW_LIVE_SOURCE_DISPATCH_ENV} is set — ` +
+                        `dispatching under a live dev-server checkout can corrupt the operator's working state.`,
+                };
+            }
+            return {
+                ok: false,
+                reason: "live-source-collision",
+                error: `${base} Refusing unattended dispatch. ${LIVE_SOURCE_GUARD_HINT}`,
+            };
+        }
+    }
     return { ok: true };
 }

package/build/start-tickets.js

@@ -61,6 +61,8 @@ import { VERSION } from "./version.generated.js";
 import { resolveBapiCredentials, getPrimaryCredentialStorePath, } from "./credential-store.js";
 import { resolveStartTicketsRepoName as resolveSharedStartTicketsRepoName, resolveRequiredStartTicketsRepoName, } from "./start-tickets-repo.js";
 import { provisionMcpRegistrationsForCreatedWorktrees, } from "./mcp-provisioning.js";
+import { resolveMcpShimInvocationForRuntime, buildMcpShimCommand, } from "./mcp-server-invocation.js";
+import { existsSync } from "node:fs";
 // Per-OS prerequisite knowledge + low-level command probes live in the shared
 // prereqs module so `runPreflight` (enforce) and the read-only `doctor` (render)
 // can never drift. `start-tickets.ts` imports VALUES from there; the prereqs
@@ -358,13 +360,6 @@ export function validateBranchName(branch) {
     }
     return null;
 }
-/** Resolve the branch for a ticket: explicit override, else feature/<KEY>. */
-export function resolveBranchForTicket(key, overrides) {
-    if (Object.prototype.hasOwnProperty.call(overrides, key)) {
-        return overrides[key];
-    }
-    return `feature/${key}`;
-}
 /**
  * Determine which macOS terminal to drive. An explicit choice wins; otherwise
  * auto-detect iTerm from `$TERM_PROGRAM` (case-insensitive), defaulting to
@@ -580,16 +575,29 @@ export async function requireAnyCommandOnPath(deps, candidates, errorMessage) {
  * read-only `doctor`; an unsupported-platform failure is returned as-is (doctor
  * cannot fix it, and orchestration/CLI tests assert the bare message). `uv` and
  * the selected agent are NOT enforced here — they are doctor-only. Never throws.
- */
-export async function runPreflight(deps, options) {
+ *
+ * BAPI-527: for unattended dispatch (`options.nonMutatingBase === true` OR an
+ * `options.epic` identity is present), the live-source checkout guard is ALSO
+ * enforced. A collision is FATAL unless the operator set the override env, in
+ * which case preflight succeeds but emits a loud warning through `warn` (never a
+ * silent pass). Interactive non-conductor runs pass neither flag, so the guard is
+ * never enforced and behavior stays backward compatible.
+ */
+export async function runPreflight(deps, options, warn = (message) => console.warn(message)) {
     if (options.dryRun)
         return { ok: true };
-    const result = await enforcePreflightPrerequisites(deps);
-    if (result.ok)
+    const enforceLiveSourceGuard = options.nonMutatingBase === true || options.epic !== undefined;
+    const result = await enforcePreflightPrerequisites(deps, { enforceLiveSourceGuard });
+    if (result.ok) {
+        // Overridden collision: not silent — surface the warning through the channel.
+        if (result.warning)
+            warn(result.warning);
         return { ok: true };
+    }
     if (result.reason === "unsupported-platform") {
         return { ok: false, error: result.error };
     }
+    // Both missing-prerequisite and live-source-collision are doctor-diagnosable.
     return { ok: false, error: appendDoctorHint(result.error) };
 }
 // ---------------------------------------------------------------------------
@@ -781,146 +789,29 @@ export async function runWithConcurrency(items, limit, worker) {
     await Promise.all(runners);
     return results;
 }
-/** True only when `git show-ref --verify --quiet refs/heads/<branch>` exits 0. */
-export async function branchExists(deps, branch) {
-    const result = await deps.runCommand("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], { cwd: deps.cwd });
-    return commandSucceeded(result);
-}
-/**
- * Build `wt switch` args. Include `--create` only when the branch does not yet
- * exist. Always include `-y` (auto-approve): the CLI runs the Worktrunk binary
- * via `execFile` with no TTY, so without `-y` the `pre-start` / `post-start`
- * hook-approval prompts would have no input source and the call would hang or
- * fail — this mirrors the deleted `scripts/start-tickets.sh`, which ran
- * `wt switch -c -y`. Never includes `-x` — the CLI owns worktree creation and
- * tab spawning separately. The args are platform-agnostic; only the binary
- * differs (`wt` vs `git-wt`).
- */
-export function buildWtSwitchArgs(branch, exists, baseBranch = "main") {
-    if (exists) {
-        return ["switch", "-y", branch, "--format=json"];
-    }
-    return ["switch", "--create", "-y", branch, "-b", baseBranch, "--format=json"];
-}
-/** Return the Node `path` API matching a platform (`win32` vs POSIX). */
-export function pathApiForPlatform(platform) {
-    return platform === "win32" ? path.win32 : path.posix;
-}
-/**
- * Extract a worktree path from Worktrunk JSON stdout. Accepts several common
- * shapes defensively and resolves relative paths against `cwd` using the
- * platform-correct path semantics (so Windows-style paths resolve correctly
- * even when the test/host OS differs). Throws when no usable path can be
- * extracted.
- */
-export function extractWorktreePath(stdout, cwd, platform = process.platform) {
-    let parsed;
-    try {
-        parsed = JSON.parse(stdout);
-    }
-    catch {
-        throw new Error(`Could not parse Worktrunk JSON output: ${stdout.slice(0, 200)}`);
-    }
-    const candidate = pickWorktreePathField(parsed);
-    if (!candidate) {
-        throw new Error(`Worktrunk JSON did not include a worktree path: ${stdout.slice(0, 200)}`);
-    }
-    const pathApi = pathApiForPlatform(platform);
-    return pathApi.isAbsolute(candidate) ? candidate : pathApi.resolve(cwd, candidate);
-}
-function pickWorktreePathField(parsed) {
-    if (!parsed || typeof parsed !== "object")
-        return undefined;
-    const obj = parsed;
-    if (typeof obj.path === "string")
-        return obj.path;
-    if (typeof obj.worktree_path === "string")
-        return obj.worktree_path;
-    if (typeof obj.directory === "string")
-        return obj.directory;
-    if (obj.worktree && typeof obj.worktree === "object") {
-        const nested = obj.worktree;
-        if (typeof nested.path === "string")
-            return nested.path;
-    }
-    return undefined;
-}
-/**
- * F7: decide whether a PRE-EXISTING branch is safe to reuse as a conductor
- * worktree base. A branch whose tip is an ancestor of the resolved base carries
- * no commits beyond base (nothing stale to build on) and is safe. A branch with
- * commits not on base is a leftover from a prior run — refuse it. Prefers the
- * authoritative `origin/<base>` ref when present. Conservative: any inability to
- * prove ancestry refuses (when in doubt, refuse).
- */
-export async function isExistingBranchSafeToReuse(deps, branch, baseBranch) {
-    let baseRef = baseBranch;
-    const originRef = `origin/${baseBranch}`;
-    const originExists = await deps.runCommand("git", ["rev-parse", "--verify", "--quiet", originRef], { cwd: deps.cwd });
-    if (commandSucceeded(originExists))
-        baseRef = originRef;
-    // `merge-base --is-ancestor <branch> <baseRef>` exits 0 iff <branch> is an
-    // ancestor of <baseRef> (a fresh branch at base counts as an ancestor).
-    const ancestor = await deps.runCommand("git", ["merge-base", "--is-ancestor", branch, baseRef], { cwd: deps.cwd });
-    if (commandSucceeded(ancestor))
-        return { safe: true };
-    return {
-        safe: false,
-        reason: `existing branch '${branch}' is not an ancestor of ${baseRef}; it carries commits not on the ` +
-            `resolved base (likely a leftover from a prior run). Refusing to reuse a stale worktree — delete it ` +
-            `(git worktree remove + git branch -D ${branch}) or rebase it onto ${baseRef}, then re-dispatch.`,
-    };
-}
-/**
- * Create / switch the worktree for a single ticket using the resolved Worktrunk
- * binary (`wt` on macOS/Linux, `git-wt` on Windows). Returns a `created` row on
- * success (with key, branch, path) or a `create-failed` row on any expected
- * failure — never throws for per-ticket problems.
- */
-export async function createWorktreeForTicket(deps, key, branchOverrides, worktrunkBinary, baseBranch = "main", guardStaleWorktree = false) {
-    const branch = resolveBranchForTicket(key, branchOverrides);
-    try {
-        const exists = await branchExists(deps, branch);
-        // F7 (conductor dispatch): refuse a stale pre-existing branch rather than
-        // silently building the worker on leftover code.
-        if (exists && guardStaleWorktree) {
-            const safety = await isExistingBranchSafeToReuse(deps, branch, baseBranch);
-            if (!safety.safe) {
-                return {
-                    key,
-                    branch,
-                    status: "create-failed",
-                    error: `stale worktree guard: ${safety.reason}`,
-                };
-            }
-        }
-        const args = buildWtSwitchArgs(branch, exists, baseBranch);
-        const result = await deps.runCommand(worktrunkBinary, args, { cwd: deps.cwd });
-        if (!commandSucceeded(result)) {
-            const reason = (result.stderr || result.stdout || "").trim();
-            return {
-                key,
-                branch,
-                status: "create-failed",
-                error: `${worktrunkBinary} ${args.join(" ")} failed${reason ? `: ${reason}` : ""}`,
-            };
-        }
-        const worktreePath = extractWorktreePath(result.stdout, deps.cwd, deps.platform);
-        return { key, branch, status: "created", path: worktreePath };
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return { key, branch, status: "create-failed", error: message };
-    }
-}
+// BAPI-534: the shared Worktrunk primitives (branch inspection, `wt switch` arg
+// construction, Worktrunk JSON path parsing, per-ticket create/switch) live in
+// `worktree-core.ts` so the Epic Conductor v2 executor reuses ONE implementation
+// instead of duplicating `wt switch` logic. They are imported here for local use
+// (by `createWorktrees` / `resumeWorktrees`) and re-exported so existing pinned
+// imports of these names from `./start-tickets.js` keep resolving to the exact
+// same function references.
+import { resolveBranchForTicket, branchExists, buildWtSwitchArgs, pathApiForPlatform, extractWorktreePath, isExistingBranchSafeToReuse, createWorktreeForTicket, } from "./worktree-core.js";
+export { resolveBranchForTicket, branchExists, buildWtSwitchArgs, pathApiForPlatform, extractWorktreePath, isExistingBranchSafeToReuse, createWorktreeForTicket, };
 /**
  * Create / switch worktrees for every ticket, throttled to `maxParallel`, using
  * the resolved Worktrunk binary. Returns one row per ticket in original key
  * order; per-ticket failures are recorded as `create-failed` rows rather than
  * aborting the run.
+ *
+ * BAPI-527: `baseStartPoint` is the effective ref/commit new worktrees are cut
+ * from — the immutable SHA resolved by the non-mutating conductor path, or the
+ * logical `options.baseBranch` for interactive dispatch. It defaults to
+ * `options.baseBranch` so existing callers/tests that omit it keep the
+ * historical branch-name behavior unchanged.
  */
-export async function createWorktrees(deps, options, worktrunkBinary) {
-    return runWithConcurrency(options.keys, options.maxParallel, (key) => createWorktreeForTicket(deps, key, options.branchOverrides, worktrunkBinary, options.baseBranch, options.guardStaleWorktree === true));
+export async function createWorktrees(deps, options, worktrunkBinary, baseStartPoint = options.baseBranch) {
+    return runWithConcurrency(options.keys, options.maxParallel, (key) => createWorktreeForTicket(deps, key, options.branchOverrides, worktrunkBinary, baseStartPoint, options.guardStaleWorktree === true));
 }
 /**
  * Resume-mode worktree resolution (BAPI-441). Instead of creating worktrees,
@@ -1643,11 +1534,20 @@ export function getDryRunPlatformDetails(agent, platform = process.platform, env
  * the `bapi` target. Lists both registration files and the version-pinned shim
  * command. Pure formatting — implies no credentials and writes no files.
  */
-export function buildDryRunMcpProvisioningLines(worktreePath, platform = process.platform) {
+export function buildDryRunMcpProvisioningLines(worktreePath, platform = process.platform, mcpServerInvocation) {
     const api = platform === "win32" ? path.win32 : path.posix;
     const mcpJson = api.join(worktreePath, ".mcp.json");
     const cursorJson = api.join(worktreePath, ".cursor", "mcp.json");
-    const shim = `npx -y @bridge_gpt/mcp-server@${VERSION} mcp-invoke --target <target> --project-root ${worktreePath}`;
+    // Render the SAME registration form the code would actually write. When no
+    // invocation is supplied (older callers), fall back to the resolvable
+    // npm-channel spec — never an exact generated version pin.
+    const invocation = mcpServerInvocation ?? {
+        form: "npm-channel",
+        command: "npx",
+        packageSpec: "@bridge_gpt/mcp-server@latest",
+    };
+    const built = buildMcpShimCommand(invocation, "<target>", worktreePath);
+    const shim = `${built.command} ${built.args.join(" ")}`;
     return [
         "DRY-RUN:   MCP provisioning (target-driven from .bridge/config — bapi plus any",
         "DRY-RUN:   supported Tier-2 target such as sfcc): would write a secret-free shim",
@@ -1663,7 +1563,7 @@ export function buildDryRunMcpProvisioningLines(worktreePath, platform = process
  * the secret-free MCP provisioning preview. Pure platform formatting only — no
  * preflight, no routing failures.
  */
-export function buildDryRunDetailLines(agent, key, branch, platform = process.platform, env = process.env, baseBranch = "main", autoApprove = false, modelAlias = null, conductorEnabled = false, repoName = null) {
+export function buildDryRunDetailLines(agent, key, branch, platform = process.platform, env = process.env, baseBranch = "main", autoApprove = false, modelAlias = null, conductorEnabled = false, repoName = null, mcpServerInvocation) {
     const { worktrunkBinary, buildAgentShellCommand: build } = getDryRunPlatformDetails(agent, platform, env, autoApprove, conductorEnabled, repoName);
     const wtArgs = buildWtSwitchArgs(branch, false, baseBranch);
     const agentInvocation = build(key, "<worktree-path>", modelAlias);
@@ -1671,7 +1571,7 @@ export function buildDryRunDetailLines(agent, key, branch, platform = process.pl
         `DRY-RUN: ${key} -> branch=${branch}`,
         `DRY-RUN:   ${worktrunkBinary} ${wtArgs.join(" ")}`,
         `DRY-RUN:   ${agentInvocation}`,
-        ...buildDryRunMcpProvisioningLines("<worktree-path>", platform),
+        ...buildDryRunMcpProvisioningLines("<worktree-path>", platform, mcpServerInvocation),
     ];
 }
 /**
@@ -1700,6 +1600,9 @@ export function formatSummaryReport(rows) {
             line += `  path=${row.path}`;
         if (row.workerId)
             line += `  worker_id=${row.workerId}`;
+        // BAPI-526: path-free audit label only (never the absolute server entry path).
+        if (row.mcpRegistrationForm)
+            line += `  mcp_registration=${row.mcpRegistrationForm}`;
         lines.push(line);
     }
     // Warnings section: create/spawn-failed row errors AND any non-fatal
@@ -1749,6 +1652,17 @@ export function buildMcpProvisioningDeps(deps) {
         mkdir: (dirPath, options) => mkdir(dirPath, options),
         platform: deps.platform,
         cwd: deps.cwd,
+        // Resolve how the worker MCP shim launches at dispatch time from the running
+        // conductor's own on-disk build (absolute-build-path primary, npm-channel
+        // fallback) — never from process.cwd(). `nodeExecutable` is kept as "node"
+        // here: Ticket 3 (P2) can later replace this single field with
+        // CONDUCTOR_NODE_PATH without re-plumbing argv construction.
+        mcpServerInvocation: resolveMcpShimInvocationForRuntime({
+            moduleUrl: import.meta.url,
+            nodeExecutable: "node",
+            argv1: process.argv[1],
+            fileExists: existsSync,
+        }),
     };
 }
 /**
@@ -2572,7 +2486,7 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
             error: `Unknown agent: '${options.agentName}'. Valid agents: ${formatValidAgentNames()}.`,
         };
     }
-    const preflight = await runPreflight(deps, options);
+    const preflight = await runPreflight(deps, options, overrides.liveSourceWarningLog);
     if (!preflight.ok)
         return { ok: false, error: preflight.error };
     // Resolve the run-level repo identity ONCE (BAPI_REPO_NAME, else .bridge/config)
@@ -2593,12 +2507,33 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     options.resumeMode ?? false);
     if (!platformConfig.ok)
         return { ok: false, error: platformConfig.error };
-    const refresh = await refreshBaseBranch(deps, {
-        refreshMain: options.refreshMain,
-        baseBranch: options.baseBranch,
-    });
-    if (!refresh.ok)
-        return { ok: false, error: refresh.error };
+    // BAPI-527: resolve the base start point new worktrees are cut from BEFORE any
+    // worktree side effects. Two mutually-exclusive paths:
+    //   - Non-mutating (unattended conductor/epic dispatch): fetch `origin/<base>`
+    //     and pin the returned immutable commit SHA. This NEVER fast-forwards or
+    //     force-moves a local branch ref (no `refreshBaseBranch`, `git merge
+    //     --ff-only`, or `git branch --force`), so it is safe to run against a
+    //     checkout whose local branches an operator's live dev server is editing.
+    //   - Interactive default: keep the historical `refreshBaseBranch` behavior
+    //     (fetch + fast-forward/align the local base branch) and cut worktrees from
+    //     the branch name.
+    // A fetch-only resolution failure aborts the run globally before any worktree
+    // is created (matching the historical refresh-failure contract below).
+    let effectiveBaseStartPoint = options.baseBranch;
+    if (options.nonMutatingBase === true) {
+        const resolved = await fetchAndResolveBaseSha(deps, options.baseBranch);
+        if (!resolved.ok)
+            return { ok: false, error: resolved.error };
+        effectiveBaseStartPoint = resolved.base_sha;
+    }
+    else {
+        const refresh = await refreshBaseBranch(deps, {
+            refreshMain: options.refreshMain,
+            baseBranch: options.baseBranch,
+        });
+        if (!refresh.ok)
+            return { ok: false, error: refresh.error };
+    }
     const createWorktreesFn = overrides.createWorktrees ?? createWorktrees;
     const provisionFn = overrides.provisionMcpRegistrations ??
         ((rows, d) => provisionMcpRegistrationsForCreatedWorktrees(rows, buildMcpProvisioningDeps(d)));
@@ -2612,7 +2547,7 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     const resumeWorktreesFn = overrides.resumeWorktrees ?? resumeWorktrees;
     const created = options.resumeMode
         ? await resumeWorktreesFn(deps, options)
-        : await createWorktreesFn(deps, options, platformConfig.config.worktrunkBinary);
+        : await createWorktreesFn(deps, options, platformConfig.config.worktrunkBinary, effectiveBaseStartPoint);
     // Synchronously provision secret-free worktree MCP registrations after
     // worktree creation and before launching the agent tab. Per-worktree
     // provisioning failures mark only that row `spawn-failed` (skipped by the
@@ -2765,11 +2700,14 @@ export async function runStartTicketsCli(argv, overrides = {}) {
         const dryRunRows = buildDryRunResults(options.keys, options.branchOverrides);
         const routedDryRunRows = await resolveDryRunRoutingFn(deps, dryRunRows, options, agent);
         const routedByKey = new Map(routedDryRunRows.map((r) => [r.key, r]));
+        // Resolve the SAME worker MCP shim invocation the real provisioning would use
+        // so the dry-run preview matches the `.mcp.json` that would actually be written.
+        const dryRunMcpInvocation = buildMcpProvisioningDeps(deps).mcpServerInvocation;
         for (const key of options.keys) {
             const branch = resolveBranchForTicket(key, options.branchOverrides);
             const routedRow = routedByKey.get(key);
             const modelAlias = routedRow?.modelAlias ?? null;
-            for (const line of buildDryRunDetailLines(agent, key, branch, deps.platform, deps.env, options.baseBranch, options.autoApprove, modelAlias, options.conductorEnabled ?? false, dryRunRepoName)) {
+            for (const line of buildDryRunDetailLines(agent, key, branch, deps.platform, deps.env, options.baseBranch, options.autoApprove, modelAlias, options.conductorEnabled ?? false, dryRunRepoName, dryRunMcpInvocation)) {
                 log(line);
             }
             log(`DRY-RUN:   model routing: ${formatModelRoutingLine(routedRow ?? { key, branch, status: "dry-run" }, agent)}`);

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.18";
+export const VERSION = "0.2.20";