@bridge_gpt/mcp-server 0.2.16 → 0.2.19

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
@@ -405,7 +400,10 @@ export function getDefaultSpawnTerminalTabForPlatform(platform) {
  * are always honored). Returns a structured error for unsupported platforms;
  * never throws.
  */
-export function resolveStartTicketsPlatformConfig(deps, agent, autoApprove = false, conductorEnabled = false, repoName = null) {
+export function resolveStartTicketsPlatformConfig(deps, agent, autoApprove = false, conductorEnabled = false, repoName = null, 
+// BAPI-494: a conductor remediation re-dispatch. Appends the full-suite finalize
+// instruction to the resume-mode worker's prompt.
+resumeMode = false) {
     if (!isSupportedStartTicketsPlatform(deps.platform)) {
         return { ok: false, error: unsupportedPlatformMessage(deps.platform) };
     }
@@ -417,7 +415,7 @@ export function resolveStartTicketsPlatformConfig(deps, agent, autoApprove = fal
             worktrunkBinary: resolveWorktrunkBinary(platform, deps.env),
             // Inject the resolved repo identity so the spawned worktree session never
             // falls back to the basename-derived repo name (the 403 root cause).
-            buildAgentShellCommand: (key, worktreePath, modelAlias) => prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled), repoName, platform),
+            buildAgentShellCommand: (key, worktreePath, modelAlias) => prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, resumeMode), repoName, platform),
             spawnTerminalTab: deps.spawnTerminalTab,
         },
     };
@@ -577,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) };
 }
 // ---------------------------------------------------------------------------
@@ -714,6 +725,42 @@ export async function refreshBaseBranch(deps, options) {
 export async function refreshMainBranch(deps, options) {
     return refreshBaseBranch(deps, { refreshMain: options.refreshMain, baseBranch: "main" });
 }
+/**
+ * Non-mutating counterpart to {@link refreshBaseBranch}: fetches
+ * `origin/<baseBranch>` and resolves the fetched tip to an immutable commit
+ * SHA, WITHOUT ever fast-forwarding or force-moving any local branch ref (no
+ * `git merge --ff-only`, no `git branch --force`). Used by review-grounding
+ * (BAPI-474), which must read a pinned base tree without touching the user's
+ * working tree, index, stash, or local branch refs.
+ *
+ * Validates `baseBranch` with {@link validateBranchName} first so an
+ * injection-shaped ref name is rejected before any git invocation. Every git
+ * call uses an argv array (never a shell string), consistent with
+ * {@link refreshBaseBranch}.
+ */
+export async function fetchAndResolveBaseSha(deps, baseBranch) {
+    const validationError = validateBranchName(baseBranch);
+    if (validationError) {
+        return { ok: false, error: `Invalid base branch '${baseBranch}': ${validationError}` };
+    }
+    const fetch = await deps.runCommand("git", ["fetch", "origin", baseBranch], {
+        cwd: deps.cwd,
+    });
+    if (!commandSucceeded(fetch)) {
+        return {
+            ok: false,
+            error: `git fetch origin ${baseBranch} failed. Check your network and 'git remote get-url origin', or pass --no-refresh-base to skip.`,
+        };
+    }
+    const resolve = await deps.runCommand("git", ["rev-parse", "--verify", `origin/${baseBranch}^{commit}`], { cwd: deps.cwd });
+    if (!commandSucceeded(resolve)) {
+        return {
+            ok: false,
+            error: `Failed to resolve origin/${baseBranch} to a commit SHA after fetch (git rev-parse --verify failed).`,
+        };
+    }
+    return { ok: true, base_sha: resolve.stdout.trim() };
+}
 // ---------------------------------------------------------------------------
 // Concurrency + worktree creation
 // ---------------------------------------------------------------------------
@@ -742,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,
@@ -956,6 +886,31 @@ export function buildConductorMessageRelayLaunchInstruction() {
         "emits the gate event; it does not merge). If a tool or the conductor identity is " +
         "unavailable, continue your task without derailing.");
 }
+/**
+ * BAPI-494: the resume-mode remediation finalize instruction. A conductor
+ * re-dispatch (start-tickets resume mode) is spawned to fix a `blocked` ticket —
+ * for a `merge.conflict` block the worker rebases + resolves conflicts. Catalog
+ * E1/F3b proved a clean TEXTUAL merge can still hide a SEMANTIC break (branch A
+ * adds a helper; branch B adds a contract test over all helpers), which only the
+ * FULL suite catches — so this instruction requires the worker to run the full
+ * project test suite (the same gate the advisory pre-push hook enforces) and only
+ * push/complete on green, escalating otherwise.
+ *
+ * Single line (no newlines, no `;`, no quotes/apostrophes) so it stays safe when
+ * single-quoted into a shell command and embedded in terminal-launcher args.
+ */
+export function buildResumeModeRemediationFinalizeInstruction() {
+    return ("Resume-mode remediation finalize: you were re-dispatched to fix a blocked ticket " +
+        "(a merge conflict, a CI failure, or requested review changes). First rebase against " +
+        "the current base branch and resolve the merge conflicts. A clean textual merge can " +
+        "still break behavior, so inspect for semantic conflicts even when there are no textual " +
+        "conflict markers. Before you push or mark the ticket complete, run the full test suite " +
+        "for the project (the full unit suite, the same gate enforced by the advisory pre-push " +
+        "hook described in CLAUDE.md under the CI cost model and advisory pre-push hook section) " +
+        "and do not rely on targeted subsets as your only verification. Push and mark the ticket " +
+        "complete only after the full suite is green. If you cannot make the full suite pass, " +
+        "report the ticket blocked and escalate rather than pushing a green-looking but broken merge.");
+}
 /**
  * The starter prompt handed to the selected agent. Identical for every agent.
  * When `autoApprove` is set, the implementation agent runs hands-off
@@ -966,15 +921,23 @@ export function buildConductorMessageRelayLaunchInstruction() {
  * flag). A plain run returns the bare `/implement-ticket <KEY> [--auto]` so the
  * worker is not told to poll `check_messages` for a conductor that is not
  * running.
+ *
+ * BAPI-494: when `resumeMode` is set (a conductor remediation re-dispatch), the
+ * full-suite finalize instruction is appended so the rebase/resolve worker proves
+ * semantic compatibility before pushing. Scoped to resume mode only — a normal
+ * fresh dispatch is unaffected.
  */
 export function buildAgentPrompt(key, opts = {}) {
     // `modelAlias` is accepted for signature consistency only — the model is
     // injected as a `--model` flag (see buildAgentInvocationArgv), never embedded
     // in the prompt text.
     const command = `/implement-ticket ${key}${opts.autoApprove ? " --auto" : ""}`;
-    return opts.conductorEnabled
-        ? `${command} ${buildConductorMessageRelayLaunchInstruction()}`
-        : command;
+    const parts = [command];
+    if (opts.conductorEnabled)
+        parts.push(buildConductorMessageRelayLaunchInstruction());
+    if (opts.resumeMode)
+        parts.push(buildResumeModeRemediationFinalizeInstruction());
+    return parts.join(" ");
 }
 /**
  * Build the ordered argv for an agent invocation:
@@ -1013,13 +976,13 @@ export function buildAgentInvocation(agent, prompt, quote, modelAlias) {
     }
 }
 /** POSIX agent shell command: `cd '<path>' && <agent> [--model '<alias>'] '<prompt>'`. */
-export function buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false) {
-    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove, conductorEnabled }), (p) => `'${shSquoteInner(p)}'`, modelAlias);
+export function buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false) {
+    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove, conductorEnabled, resumeMode }), (p) => `'${shSquoteInner(p)}'`, modelAlias);
     return `cd '${shSquoteInner(worktreePath)}' && ${invocation}`;
 }
 /** PowerShell agent shell command: `Set-Location -LiteralPath '<path>'; <agent> [--model '<alias>'] '<prompt>'`. */
-export function buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false) {
-    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove, conductorEnabled }), powershellSquote, modelAlias);
+export function buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false) {
+    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove, conductorEnabled, resumeMode }), powershellSquote, modelAlias);
     return `Set-Location -LiteralPath ${powershellSquote(worktreePath)}; ${invocation}`;
 }
 /**
@@ -1030,10 +993,10 @@ export function buildPowerShellAgentShellCommand(agent, key, worktreePath, autoA
  * injected as `--model` at the spawn boundary. `conductorEnabled` appends the
  * BAPI-397 message-relay instruction to the prompt (opt-in via `--conductor`).
  */
-export function buildAgentShellCommand(agent, key, worktreePath, platform = "darwin", autoApprove = false, modelAlias, conductorEnabled = false) {
+export function buildAgentShellCommand(agent, key, worktreePath, platform = "darwin", autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false) {
     if (platform === "win32")
-        return buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled);
-    return buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled);
+        return buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode);
+    return buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode);
 }
 /**
  * Build the shell command run inside a spawned tab/session for an ARBITRARY
@@ -1090,15 +1053,36 @@ export function buildTerminalAppleScript(shellCommand, title) {
         "end tell",
     ].join("\n");
 }
+/**
+ * Build the shell command that sets an iTerm2 session **badge** to `badgeText`
+ * via the proprietary `OSC 1337 ; SetBadgeFormat` escape (base64 payload, per
+ * the iTerm2 spec). The badge is a large translucent per-pane label drawn in
+ * the session corner.
+ *
+ * Why a badge and not just the session `name`: iTerm2 lets a running program
+ * overwrite the session name via ordinary title escapes (`OSC 0/1/2`), and
+ * Claude Code re-sets its terminal title continuously while it works — so the
+ * `set name` label is clobbered within a fraction of a second (empirically the
+ * tab ends up reading "claude working", never "<KEY> Implementation"). The
+ * badge lives in a separate namespace those title escapes never touch, so it
+ * sticks for the life of the pane. `printf` emits the escape from inside the
+ * spawned shell, before the agent command runs.
+ */
+export function itermBadgeShellCommand(badgeText) {
+    const b64 = Buffer.from(badgeText, "utf8").toString("base64");
+    return `printf '\\033]1337;SetBadgeFormat=%s\\007' '${b64}'`;
+}
 /**
  * Generate AppleScript that runs `shellCommand` in an iTerm2 tab. We set the
- * session `name` (which drives the tab title) so the label sticks rather than
- * being overwritten by the running agent's program title.
+ * session `name` (labels the tab until the agent starts re-titling) and, when a
+ * `badgeText` is supplied, pin an agent-proof iTerm badge so the pane stays
+ * identifiable even after Claude Code overrides the title — see
+ * {@link itermBadgeShellCommand}.
  */
-export function buildITermAppleScript(shellCommand, title) {
+export function buildITermAppleScript(shellCommand, title, badgeText) {
     const esc = applescriptDquoteInner(shellCommand);
     const titleEsc = applescriptDquoteInner(title);
-    return [
+    const lines = [
         'tell application "iTerm"',
         "    activate",
         "    if (count of windows) = 0 then",
@@ -1108,10 +1092,15 @@ export function buildITermAppleScript(shellCommand, title) {
         "    end if",
         "    tell spawnedSession",
         `        set name to "${titleEsc}"`,
-        `        write text "${esc}"`,
-        "    end tell",
-        "end tell",
-    ].join("\n");
+    ];
+    if (badgeText) {
+        const badgeEsc = applescriptDquoteInner(itermBadgeShellCommand(badgeText));
+        lines.push(`        write text "${badgeEsc}"`);
+    }
+    lines.push(`        write text "${esc}"`);
+    lines.push("    end tell");
+    lines.push("end tell");
+    return lines.join("\n");
 }
 /**
  * Spawn a single macOS terminal tab running `shellCommand`. Selects the
@@ -1123,7 +1112,7 @@ export function buildITermAppleScript(shellCommand, title) {
 export async function spawnMacOSTerminalTab(deps, terminal, shellCommand, context) {
     const title = terminalTitleForTicket(context?.key ?? "");
     const script = terminal === "iterm"
-        ? buildITermAppleScript(shellCommand, title)
+        ? buildITermAppleScript(shellCommand, title, context?.key || undefined)
         : buildTerminalAppleScript(shellCommand, title);
     const result = await deps.runCommand("osascript", ["-e", script]);
     if (commandSucceeded(result))
@@ -1545,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",
@@ -1565,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);
@@ -1573,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),
     ];
 }
 /**
@@ -1602,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
@@ -1651,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,
+        }),
     };
 }
 /**
@@ -2474,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)
@@ -2490,15 +2502,38 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
             ".bridge/config). Spawned worktrees may fall back to the directory name and " +
             "hit 403 'repository not registered' if it differs from the Bridge API project name.");
     }
-    const platformConfig = resolveStartTicketsPlatformConfig(deps, agent, options.autoApprove, options.conductorEnabled ?? false, resolvedRepoName);
+    const platformConfig = resolveStartTicketsPlatformConfig(deps, agent, options.autoApprove, options.conductorEnabled ?? false, resolvedRepoName, 
+    // BAPI-494: resume-mode dispatches get the full-suite remediation finalize prompt.
+    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)));
@@ -2512,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
@@ -2665,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.16";
+export const VERSION = "0.2.19";