@bridge_gpt/mcp-server 0.2.6 → 0.2.10

package/build/start-tickets.js

@@ -54,7 +54,7 @@
  * unit-testable on Linux CI without spawning real commands or terminals.
  */
 import { execFile } from "child_process";
-import { readFile, writeFile, mkdir, stat } from "fs/promises";
+import { readFile, writeFile, mkdir, mkdtemp, stat, readdir, rm } from "fs/promises";
 import os from "node:os";
 import path from "path";
 import { VERSION } from "./version.generated.js";
@@ -105,6 +105,7 @@ export function getStartTicketsUsage() {
         "  --base-branch BRANCH        Cut new worktrees from BRANCH and refresh origin/BRANCH (default: main)",
         "  --no-refresh-main           Skip refresh of the configured base branch (default main); historical name retained for backward compatibility",
         "  --max-parallel N            Max worktrees to create concurrently (default: 3)",
+        "  --conductor                 Enable the Conductor system: per-worker hook injection + BAPI_CONDUCTOR_* env, a supervisor peer tab, and check_messages message-relay polling (default: off — a plain run just spawns cd <worktree> && <agent> '/implement-ticket <KEY>')",
         "  -h, --help                  Show this help",
         "",
         "Environment:",
@@ -114,12 +115,14 @@ export function getStartTicketsUsage() {
         "  BAPI_CONDUCTOR_SUPERVISOR_MODE    Conductor supervisor mode (default: auto when --auto, else interactive)",
         "  BAPI_CONDUCTOR_ENABLE_PRE_TOOL_USE  Set 1/true to also register a PreToolUse conductor hook",
         "",
-        "Conductor observability:",
-        "  Real Claude Code workers launched by start-tickets receive per-worktree conductor",
-        "  hook injection (into .claude/settings.local.json) and emit local lifecycle events",
-        "  into the conductor ledger. Each real run mints one run_id and attributes worker",
-        "  events by worker_id, ticket key, and worktree path. Inspect the ledger with the",
-        "  `conductor` CLI.",
+        "Conductor observability (opt-in via --conductor):",
+        "  With --conductor, real Claude Code workers launched by start-tickets receive",
+        "  per-worktree conductor hook injection (into .claude/settings.local.json) and emit",
+        "  local lifecycle events into the conductor ledger. Each such run mints one run_id",
+        "  and attributes worker events by worker_id, ticket key, and worktree path, and a",
+        "  supervisor peer tab is opened. Without --conductor none of this happens. Inspect",
+        "  the ledger with the `conductor` CLI. The BAPI_CONDUCTOR_* env vars above apply",
+        "  only when --conductor is set.",
         "",
         "Prerequisites:",
         "  macOS    wt, git, osascript",
@@ -145,6 +148,7 @@ export function parseStartTicketsArgs(argv) {
     let maxParallelRaw;
     let agentName = DEFAULT_AGENT_NAME;
     let baseBranch = "main";
+    let conductorEnabled = false;
     const branchEntries = [];
     const keys = [];
     for (let i = 0; i < argv.length; i++) {
@@ -254,6 +258,10 @@ export function parseStartTicketsArgs(argv) {
             autoApprove = true;
             continue;
         }
+        if (arg === "--conductor") {
+            conductorEnabled = true;
+            continue;
+        }
         if (arg === "--no-refresh-main") {
             refreshMain = false;
             continue;
@@ -329,7 +337,7 @@ export function parseStartTicketsArgs(argv) {
     }
     return {
         status: "ok",
-        options: { keys, terminal, dryRun, autoApprove, refreshMain, maxParallel, branchOverrides, agentName, baseBranch },
+        options: { keys, terminal, dryRun, autoApprove, refreshMain, maxParallel, branchOverrides, agentName, baseBranch, conductorEnabled },
     };
 }
 /** Returns an error string for an unsafe branch name, or null when valid. */
@@ -397,7 +405,7 @@ export function getDefaultSpawnTerminalTabForPlatform(platform) {
  * are always honored). Returns a structured error for unsupported platforms;
  * never throws.
  */
-export function resolveStartTicketsPlatformConfig(deps, agent, autoApprove = false) {
+export function resolveStartTicketsPlatformConfig(deps, agent, autoApprove = false, conductorEnabled = false, repoName = null) {
     if (!isSupportedStartTicketsPlatform(deps.platform)) {
         return { ok: false, error: unsupportedPlatformMessage(deps.platform) };
     }
@@ -407,7 +415,9 @@ export function resolveStartTicketsPlatformConfig(deps, agent, autoApprove = fal
         config: {
             platform,
             worktrunkBinary: resolveWorktrunkBinary(platform, deps.env),
-            buildAgentShellCommand: (key, worktreePath, modelAlias) => buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias),
+            // 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),
             spawnTerminalTab: deps.spawnTerminalTab,
         },
     };
@@ -415,6 +425,28 @@ export function resolveStartTicketsPlatformConfig(deps, agent, autoApprove = fal
 // ---------------------------------------------------------------------------
 // Pure escaping + slug helpers
 // ---------------------------------------------------------------------------
+/**
+ * Prepend a `BAPI_REPO_NAME` environment assignment to a spawned shell command so
+ * the agent (and any MCP server it launches) resolves the repo identity the SAME
+ * way `start-tickets` did — instead of falling back to `path.basename(cwd)`, which
+ * yields the git/dir name (e.g. `bridge-gpt`) when the server-side project is
+ * registered under a different normalization (e.g. `bridge_gpt`). That mismatch
+ * is the documented cause of sporadic 403 "no API key configured" failures in
+ * freshly-spawned worktrees that lack a `.bridge/config`.
+ *
+ * Fail-open: a null/empty `repoName` returns the command unchanged (the inherited
+ * env / `.mcp.json` provisioning still applies). The assignment is platform
+ * correct — `export VAR='…' && …` on POSIX, `$env:VAR = '…'; …` on PowerShell —
+ * and the value is quoted with the same escaper used for the rest of the command.
+ */
+export function prependRepoNameEnvAssignment(command, repoName, platform = "darwin") {
+    if (!repoName)
+        return command;
+    if (platform === "win32") {
+        return `$env:BAPI_REPO_NAME = ${powershellSquote(repoName)}; ${command}`;
+    }
+    return `export BAPI_REPO_NAME='${shSquoteInner(repoName)}' && ${command}`;
+}
 /**
  * Escape a string for inclusion inside a single-quoted shell context: each
  * embedded single-quote becomes the sequence `'\''`. Returns only the inner
@@ -503,6 +535,10 @@ export function createDefaultStartTicketsDeps() {
         cwd: process.cwd(),
         // The platform router is the single source of truth for spawner selection.
         spawnTerminalTab: getDefaultSpawnTerminalTabForPlatform(process.platform),
+        // Deliver each worker command via a launch-script file rather than embedding
+        // a multi-KB command in the terminal spawn (robust on macOS AppleScript /
+        // Windows wt.exe paths). Tests omit this seam to keep the legacy inline path.
+        writeWorkerLaunchScript: defaultWriteWorkerLaunchScript,
     };
     return deps;
 }
@@ -808,6 +844,47 @@ export async function createWorktreeForTicket(deps, key, branchOverrides, worktr
 export async function createWorktrees(deps, options, worktrunkBinary) {
     return runWithConcurrency(options.keys, options.maxParallel, (key) => createWorktreeForTicket(deps, key, options.branchOverrides, worktrunkBinary, options.baseBranch));
 }
+/**
+ * Resume-mode worktree resolution (BAPI-441). Instead of creating worktrees,
+ * locate each ticket's EXISTING worktree from `git worktree list --porcelain` and
+ * synthesize `created` rows pointing at the found path so the rest of the
+ * orchestration pipeline (MCP provisioning → conductor context → spawn) runs
+ * unchanged. A ticket is matched by exact branch (`resolveBranchForTicket`) first,
+ * then by any worktree branch that contains the ticket key (so an enriched
+ * `feature/<KEY>-<slug>` branch still resolves). Unmatched tickets become
+ * `create-failed` and are skipped downstream. Never throws.
+ */
+export async function resumeWorktrees(deps, options) {
+    const list = await deps.runCommand("git", ["worktree", "list", "--porcelain"], {
+        cwd: deps.cwd,
+    });
+    if (!commandSucceeded(list)) {
+        return options.keys.map((key) => ({
+            key,
+            branch: resolveBranchForTicket(key, options.branchOverrides),
+            status: "create-failed",
+            error: "resume mode: git worktree list --porcelain failed; cannot locate existing worktree.",
+        }));
+    }
+    const entries = parseGitWorktreeList(list.stdout);
+    return options.keys.map((key) => {
+        const branch = resolveBranchForTicket(key, options.branchOverrides);
+        let entry = entries.find((e) => e.branch === branch);
+        if (!entry) {
+            const needle = key.toLowerCase();
+            entry = entries.find((e) => (e.branch ?? "").toLowerCase().includes(needle));
+        }
+        if (entry) {
+            return { key, branch: entry.branch ?? branch, status: "created", path: entry.path };
+        }
+        return {
+            key,
+            branch,
+            status: "create-failed",
+            error: `resume mode: no existing worktree found for ticket ${key} (branch '${branch}').`,
+        };
+    });
+}
 // ---------------------------------------------------------------------------
 // Per-platform shell-command construction
 // ---------------------------------------------------------------------------
@@ -839,16 +916,22 @@ export function buildConductorMessageRelayLaunchInstruction() {
 /**
  * The starter prompt handed to the selected agent. Identical for every agent.
  * When `autoApprove` is set, the implementation agent runs hands-off
- * (`/implement-ticket <KEY> --auto`) — used by full-automation chains. The
- * conductor message-relay polling instruction is appended after the slash command
- * (BAPI-397) so launched workers actually poll `check_messages`.
+ * (`/implement-ticket <KEY> --auto`) — used by full-automation chains.
+ *
+ * The conductor message-relay polling instruction (BAPI-397) is appended after
+ * the slash command ONLY when `conductorEnabled` is set (the `--conductor`
+ * 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.
  */
 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 `${command} ${buildConductorMessageRelayLaunchInstruction()}`;
+    return opts.conductorEnabled
+        ? `${command} ${buildConductorMessageRelayLaunchInstruction()}`
+        : command;
 }
 /**
  * Build the ordered argv for an agent invocation:
@@ -887,13 +970,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) {
-    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove }), (p) => `'${shSquoteInner(p)}'`, modelAlias);
+export function buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false) {
+    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove, conductorEnabled }), (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) {
-    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove }), powershellSquote, modelAlias);
+export function buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false) {
+    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove, conductorEnabled }), powershellSquote, modelAlias);
     return `Set-Location -LiteralPath ${powershellSquote(worktreePath)}; ${invocation}`;
 }
 /**
@@ -901,12 +984,32 @@ export function buildPowerShellAgentShellCommand(agent, key, worktreePath, autoA
  * platform. PowerShell on Windows; POSIX everywhere else (incl. the unsupported
  * dry-run fallback). The selected `agent` (never a module-level constant)
  * determines the launched command. An optional validated `modelAlias` is
- * injected as `--model` at the spawn boundary.
+ * 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) {
+export function buildAgentShellCommand(agent, key, worktreePath, platform = "darwin", autoApprove = false, modelAlias, conductorEnabled = false) {
     if (platform === "win32")
-        return buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias);
-    return buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias);
+        return buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled);
+    return buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled);
+}
+/**
+ * Build the shell command run inside a spawned tab/session for an ARBITRARY
+ * prompt string, dispatched by platform. This is the command-agnostic seam used
+ * by callers other than `start-tickets` (e.g. the `install-bridge` subcommand)
+ * that need to launch the selected agent against a custom prompt rather than the
+ * hard-coded `/implement-ticket <KEY>` prompt. PowerShell on Windows; POSIX
+ * everywhere else. The directory-change and agent invocation are quoted with the
+ * platform-correct quoter (`Set-Location -LiteralPath …;` on Windows, `cd '…' &&`
+ * on POSIX). An optional validated `modelAlias` is injected as `--model` at the
+ * spawn boundary, exactly like `buildAgentShellCommand`.
+ */
+export function buildGenericAgentShellCommand(agent, prompt, cwd, platform = "darwin", modelAlias) {
+    if (platform === "win32") {
+        const invocation = buildAgentInvocation(agent, prompt, powershellSquote, modelAlias);
+        return `Set-Location -LiteralPath ${powershellSquote(cwd)}; ${invocation}`;
+    }
+    const invocation = buildAgentInvocation(agent, prompt, (p) => `'${shSquoteInner(p)}'`, modelAlias);
+    return `cd '${shSquoteInner(cwd)}' && ${invocation}`;
 }
 // ---------------------------------------------------------------------------
 // Spawned-terminal titling (shared across platforms)
@@ -1183,6 +1286,151 @@ export async function spawnUnsupportedPlatformTerminalTab(deps, _terminal, _shel
     return { ok: false, error: unsupportedPlatformMessage(deps.platform) };
 }
 // ---------------------------------------------------------------------------
+// Per-worker launch script (robust spawn delivery)
+// ---------------------------------------------------------------------------
+/*
+ * Why launch via a script file instead of embedding the command in the spawn?
+ *
+ * Each worker command grew from ~100 chars to >1 KB once the conductor identity
+ * env (BAPI-394) and the message-relay launch instruction (BAPI-397) were added.
+ * On macOS that whole string is escaped into an AppleScript literal and injected
+ * via a `keystroke "t"` (Cmd-T) new-tab dance — a delivery path that is
+ * length-, quoting-, and timing-sensitive (a long command racing a not-yet-ready
+ * new-tab shell can land mangled / unexecuted). Windows (`wt.exe`) additionally
+ * has to escape `;` to stop its own arg-splitter from truncating the command.
+ *
+ * Writing the full command to a tiny script and handing the terminal a short
+ * `source <path>` runner sidesteps all of it: the spawned payload is a constant
+ * ~40 chars regardless of how large the underlying command is, and the env +
+ * `cd` + agent invocation live verbatim in the file. The runner is `source`d
+ * (not exec'd) so the tab is left in the worktree after the agent exits, exactly
+ * like the legacy inline path.
+ */
+/** Filesystem-safe per-key launch-script basename fragment. */
+export function sanitizeKeyForLaunchScript(key) {
+    const cleaned = key.replace(/[^A-Za-z0-9._-]/g, "_");
+    return cleaned.length > 0 ? cleaned : "worker";
+}
+/**
+ * Script body for the resolved platform. POSIX scripts carry a `bash` shebang
+ * (harmless when the file is `source`d); Windows scripts are plain PowerShell.
+ * A trailing newline keeps the final statement well-formed.
+ */
+export function buildLaunchScriptContent(platform, fullCommand) {
+    if (platform === "win32")
+        return `${fullCommand}\n`;
+    return `#!/usr/bin/env bash\n${fullCommand}\n`;
+}
+/** The short, escaping-immune runner the terminal executes: `source <path>`. */
+export function buildLaunchScriptRunnerCommand(platform, scriptPath) {
+    // `.` (POSIX) / `.` (PowerShell) dot-source the script into the tab's shell so
+    // `cd` persists and the user is left in the worktree once the agent exits.
+    if (platform === "win32")
+        return `. ${powershellSquote(scriptPath)}`;
+    return `. '${shSquoteInner(scriptPath)}'`;
+}
+/**
+ * Maximum age (ms) a `bridge-start-tickets/w-*` launch-script temp directory may
+ * reach before `pruneStaleLaunchScripts` removes it. 24 hours is a sane ceiling
+ * well past any live `start-tickets` session.
+ */
+export const STALE_LAUNCH_SCRIPT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const defaultPruneStaleLaunchScriptsDeps = {
+    readdir: (dir) => readdir(dir),
+    stat: (p) => stat(p),
+    rm: (p, options) => rm(p, options),
+    now: () => Date.now(),
+};
+/**
+ * IH-2 (PR #552 review): best-effort, age-based prune of stale `w-*` launch-script
+ * temp directories left under `os.tmpdir()/bridge-start-tickets/` by
+ * {@link defaultWriteWorkerLaunchScript}. Nothing else ever removes them, so on a
+ * long-lived dev machine that runs `start-tickets` regularly they accumulate
+ * indefinitely.
+ *
+ * Only directories whose name starts with `"w-"` are considered (the `mkdtemp`
+ * prefix); anything older than {@link STALE_LAUNCH_SCRIPT_MAX_AGE_MS} is removed
+ * recursively. Newer entries and unrelated files/dirs are left untouched.
+ *
+ * Fully fail-open: any error (missing parent dir, unreadable entry, stat/unlink
+ * failure) is swallowed and never blocks or aborts a spawn — the same fail-open
+ * discipline as the launch-script writer fallback in
+ * {@link materializeWorkerLaunchCommand}.
+ */
+export async function pruneStaleLaunchScripts(deps = defaultPruneStaleLaunchScriptsDeps) {
+    try {
+        const parent = path.join(os.tmpdir(), "bridge-start-tickets");
+        let entries;
+        try {
+            entries = await deps.readdir(parent);
+        }
+        catch {
+            // Parent dir missing/unreadable — nothing to prune.
+            return;
+        }
+        const cutoff = deps.now() - STALE_LAUNCH_SCRIPT_MAX_AGE_MS;
+        for (const entry of entries) {
+            if (!entry.startsWith("w-"))
+                continue;
+            const full = path.join(parent, entry);
+            try {
+                const info = await deps.stat(full);
+                if (info.mtimeMs < cutoff) {
+                    await deps.rm(full, { recursive: true, force: true });
+                }
+            }
+            catch {
+                // Per-entry stat/rm failure must never block orchestration.
+            }
+        }
+    }
+    catch {
+        // Absolutely never throw — cleanup is best-effort only.
+    }
+}
+/** Default real-filesystem launch-script writer (used in production). */
+export const defaultWriteWorkerLaunchScript = async ({ platform, key, content, }) => {
+    const parent = path.join(os.tmpdir(), "bridge-start-tickets");
+    await mkdir(parent, { recursive: true });
+    // Atomically allocate a UNIQUE per-write subdirectory. Two workers can share a
+    // sanitized key (a duplicate CLI arg like `BAPI-1 BAPI-1`, or two keys that
+    // collide after sanitization); a fixed `launch-<key>.<ext>` path would let the
+    // second write silently clobber the first before either tab `source`s it,
+    // leaving the first worker running the second's command. `mkdtemp` gives each
+    // write its own directory (collision-proof across workers AND concurrent
+    // processes), so the readable per-key basename can stay for debuggability.
+    const dir = await mkdtemp(path.join(parent, "w-"));
+    const ext = platform === "win32" ? "ps1" : "sh";
+    const file = path.join(dir, `launch-${sanitizeKeyForLaunchScript(key)}.${ext}`);
+    // 0600: the file carries no secrets (conductor env is secret-free) but there is
+    // no reason to make it world-readable; `source` only needs read.
+    await writeFile(file, content, { mode: 0o600 });
+    return file;
+};
+/**
+ * Resolve the command actually handed to the terminal spawner for one worker.
+ * When `deps.writeWorkerLaunchScript` is provided, the full command is persisted
+ * to a script and a short `source <path>` runner is returned; if writing fails
+ * for any reason the original inline command is returned (fail-open — a launch
+ * never aborts because a temp file could not be written). When the seam is
+ * absent, the inline command is returned unchanged (legacy behaviour).
+ */
+export async function materializeWorkerLaunchCommand(deps, key, fullCommand) {
+    if (!deps.writeWorkerLaunchScript)
+        return fullCommand;
+    try {
+        const scriptPath = await deps.writeWorkerLaunchScript({
+            platform: deps.platform,
+            key,
+            content: buildLaunchScriptContent(deps.platform, fullCommand),
+        });
+        return buildLaunchScriptRunnerCommand(deps.platform, scriptPath);
+    }
+    catch {
+        return fullCommand;
+    }
+}
+// ---------------------------------------------------------------------------
 // Tab spawning across created worktrees
 // ---------------------------------------------------------------------------
 /**
@@ -1204,7 +1452,11 @@ export async function spawnTabsForCreatedWorktrees(deps, rows, terminal, buildSh
         // (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 result = await deps.spawnTerminalTab(deps, terminal, shellCommand, {
+        // Deliver the (potentially multi-KB) command via a launch-script file so the
+        // terminal spawn payload stays tiny and escaping-immune. Fail-open / no-op
+        // when no writer seam is configured (see materializeWorkerLaunchCommand).
+        const runnableCommand = await materializeWorkerLaunchCommand(deps, row.key, shellCommand);
+        const result = await deps.spawnTerminalTab(deps, terminal, runnableCommand, {
             key: row.key,
             worktreePath: row.path,
         });
@@ -1234,12 +1486,14 @@ export function buildDryRunResults(keys, overrides) {
  * PowerShell on Windows, `wt` + POSIX on macOS/Linux, and a non-throwing `wt` +
  * POSIX fallback for unsupported platforms.
  */
-export function getDryRunPlatformDetails(agent, platform = process.platform, env = process.env, autoApprove = false) {
+export function getDryRunPlatformDetails(agent, platform = process.platform, env = process.env, autoApprove = false, conductorEnabled = false, repoName = null) {
     return {
         worktrunkBinary: resolveWorktrunkBinary(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.
-        buildAgentShellCommand: (key, worktreePath, modelAlias) => buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias),
+        // The resolved repo name (when known) is injected as a BAPI_REPO_NAME prefix
+        // so the dry-run preview matches the real spawn command exactly.
+        buildAgentShellCommand: (key, worktreePath, modelAlias) => prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled), repoName, platform),
     };
 }
 /**
@@ -1268,8 +1522,8 @@ 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) {
-    const { worktrunkBinary, buildAgentShellCommand: build } = getDryRunPlatformDetails(agent, platform, env, autoApprove);
+export function buildDryRunDetailLines(agent, key, branch, platform = process.platform, env = process.env, baseBranch = "main", autoApprove = false, modelAlias = null, conductorEnabled = false, repoName = null) {
+    const { worktrunkBinary, buildAgentShellCommand: build } = getDryRunPlatformDetails(agent, platform, env, autoApprove, conductorEnabled, repoName);
     const wtArgs = buildWtSwitchArgs(branch, false, baseBranch);
     const agentInvocation = build(key, "<worktree-path>", modelAlias);
     return [
@@ -2155,6 +2409,11 @@ async function defaultClaimEpicDispatch(dispatchKey, runId, deps) {
     });
 }
 export async function orchestrateStartTickets(deps, options, overrides = {}) {
+    // 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
+    // and a real run is never blocked or delayed into failure by I/O latency.
+    await pruneStaleLaunchScripts();
     // Thread dependency-derived base branch from epic identity through the
     // existing --base-branch path (no new branch-cutting or refresh logic).
     if (options.epic?.base_branch) {
@@ -2175,7 +2434,20 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     const preflight = await runPreflight(deps, options);
     if (!preflight.ok)
         return { ok: false, error: preflight.error };
-    const platformConfig = resolveStartTicketsPlatformConfig(deps, agent, options.autoApprove);
+    // Resolve the run-level repo identity ONCE (BAPI_REPO_NAME, else .bridge/config)
+    // and inject it into every spawned session. This stops a freshly-created
+    // worktree from falling back to `path.basename(cwd)` — which yields the git/dir
+    // name (e.g. `bridge-gpt`) and produces sporadic 403s when the server-side
+    // project is registered under a different normalization (e.g. `bridge_gpt`).
+    // Fail-open: an unresolved name is warned about loudly but never aborts the run.
+    const resolveRepoNameFn = overrides.resolveRepoName ?? resolveStartTicketsRepoName;
+    const resolvedRepoName = await resolveRepoNameFn(deps);
+    if (!resolvedRepoName) {
+        overrides.repoNameWarningLog?.("Warning: could not resolve the repo name (set BAPI_REPO_NAME or add a valid " +
+            ".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);
     if (!platformConfig.ok)
         return { ok: false, error: platformConfig.error };
     const refresh = await refreshBaseBranch(deps, {
@@ -2190,7 +2462,14 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     const materializeFn = overrides.materializeFileCredentials ?? materializeFileCredentialsForCreatedWorktrees;
     const detectTerminalFn = overrides.detectTerminal ?? detectTerminal;
     const spawnTabsFn = overrides.spawnTabsForCreatedWorktrees ?? spawnTabsForCreatedWorktrees;
-    const created = await createWorktreesFn(deps, options, platformConfig.config.worktrunkBinary);
+    // BAPI-441: in resume mode, reuse the ticket's existing branch/worktree instead
+    // of creating a new one (the re-dispatched worker continues the original
+    // implementation). The synthesized `created` rows flow through the unchanged
+    // provisioning → conductor → spawn pipeline below.
+    const resumeWorktreesFn = overrides.resumeWorktrees ?? resumeWorktrees;
+    const created = options.resumeMode
+        ? await resumeWorktreesFn(deps, options)
+        : await createWorktreesFn(deps, options, platformConfig.config.worktrunkBinary);
     // 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
@@ -2331,6 +2610,11 @@ export async function runStartTicketsCli(argv, overrides = {}) {
         return 1;
     }
     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
+        // run resolves it independently inside orchestrateStartTickets, so this is
+        // only needed on the dry-run path.
+        const dryRunRepoName = await resolveStartTicketsRepoName(deps);
         // Preview model routing too: resolve tiers read-only (fail-open) so the
         // dry-run shows the exact `--model` each tab would launch with, plus a
         // per-ticket routing decision line.
@@ -2342,7 +2626,7 @@ export async function runStartTicketsCli(argv, overrides = {}) {
             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)) {
+            for (const line of buildDryRunDetailLines(agent, key, branch, deps.platform, deps.env, options.baseBranch, options.autoApprove, modelAlias, options.conductorEnabled ?? false, dryRunRepoName)) {
                 log(line);
             }
             log(`DRY-RUN:   model routing: ${formatModelRoutingLine(routedRow ?? { key, branch, status: "dry-run" }, agent)}`);
@@ -2361,12 +2645,20 @@ export async function runStartTicketsCli(argv, overrides = {}) {
     const result = await orchestrate(deps, options, {
         modelRoutingLog: log,
         modelRoutingWarningLog: errorLog,
-        // BAPI-394: opt the packaged CLI into conductor observability. Supplying the
-        // context seam activates the conductor stage inside orchestrate; the other
-        // two seams fall back to their real module implementations.
-        createConductorContext: createStartTicketsConductorContext,
-        provisionConductorHooksForRows,
-        emitStartTicketsRunStarted,
+        repoNameWarningLog: errorLog,
+        // Conductor is OPT-IN (BAPI-394): the three seams are supplied ONLY when the
+        // user passes `--conductor`. Supplying `createConductorContext` activates the
+        // conductor stage inside orchestrate (env injection + supervisor tab); the
+        // other two seams fall back to their real module implementations. Omitting
+        // them (the default) leaves rows untouched, so a plain run spawns the bare
+        // `cd <worktree> && <agent> '/implement-ticket <KEY>'`.
+        ...(options.conductorEnabled
+            ? {
+                createConductorContext: createStartTicketsConductorContext,
+                provisionConductorHooksForRows,
+                emitStartTicketsRunStarted,
+            }
+            : {}),
     });
     if (!result.ok) {
         errorLog(`Error: ${result.error}`);