@bridge_gpt/mcp-server 0.1.17 → 0.2.1

package/build/start-tickets.js

@@ -40,8 +40,9 @@
  *     via `; exec $SHELL`); attach with `tmux attach -t <session>`.
  *
  * Any other `process.platform` value fails fast with a clear "unsupported
- * platform" message. `--dry-run` short-circuits before routing so it previews
- * the platform-correct command form on any OS.
+ * platform" message. `--dry-run` creates no worktrees and opens no tabs, but it
+ * DOES resolve model routing read-only (fail-open) so the preview shows the
+ * exact platform-correct command form — including the chosen `--model` — on any OS.
  *
  * The single highest-risk Windows detail is the `wt` name collision: Windows
  * Terminal is `wt.exe` (tab launcher) while Worktrunk installs as `git-wt`
@@ -53,13 +54,19 @@
  * 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 os from "node:os";
 import path from "path";
+import { VERSION } from "./version.generated.js";
+import { resolveBapiCredentials } from "./credential-store.js";
+import { readBridgeConfig } from "./bridge-config.js";
+import { provisionMcpRegistrationsForCreatedWorktrees, } from "./mcp-provisioning.js";
 // 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
 // module imports only TYPES back, so the runtime graph stays acyclic.
 import { WORKTRUNK_BINARY_OVERRIDE_ENV, WINDOWS_TERMINAL_COMMAND, WINDOWS_POWERSHELL_CANDIDATES, DEFAULT_WINDOWS_WORKTRUNK_BINARY, DEFAULT_POSIX_WORKTRUNK_BINARY, TMUX_COMMAND, GIT_FOR_WINDOWS_BASH_HINT, isSupportedStartTicketsPlatform, unsupportedPlatformMessage, resolveWorktrunkBinary, commandSucceeded, getCommandProbe, isCommandOnPath, resolveFirstCommandOnPath, enforcePreflightPrerequisites, appendDoctorHint, } from "./start-tickets-prereqs.js";
-import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
+import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, resolveModelAlias, isValidModelAlias, isModelTier, } from "./agent-registry.js";
 // Re-export the shared prereq surface (constants, platform helpers, command
 // probes) so existing import sites that read them from "./start-tickets.js"
 // keep working unchanged.
@@ -75,6 +82,10 @@ export const DEFAULT_MAX_PARALLEL = 3;
 export const DEFAULT_TMUX_SESSION_PREFIX = "bridge-start-tickets";
 /** Environment variable overriding the tmux session-name prefix. */
 export const TMUX_SESSION_OVERRIDE_ENV = "BAPI_TMUX_SESSION";
+/** Return a copy of `row` with `warning` appended; never mutates the input. */
+export function appendSummaryRowWarning(row, warning) {
+    return { ...row, warnings: [...(row.warnings ?? []), warning] };
+}
 // ---------------------------------------------------------------------------
 // Usage / argument parsing
 // ---------------------------------------------------------------------------
@@ -87,7 +98,7 @@ export function getStartTicketsUsage() {
         "Flags:",
         "  --agent claude|cursor-agent Agent command to launch in each worktree (default: claude)",
         "  --terminal terminal|iterm   Override the macOS terminal app (default: auto-detect via $TERM_PROGRAM); honored on macOS only",
-        "  --dry-run                   Print intended actions; create no worktrees, open no tabs",
+        "  --dry-run                   Print intended actions (incl. resolved model routing); create no worktrees, open no tabs",
         "  --branch KEY=BRANCH         Use BRANCH instead of feature/KEY for that ticket (repeatable)",
         "  --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",
@@ -227,7 +238,7 @@ export function parseStartTicketsArgs(argv) {
             dryRun = true;
             continue;
         }
-        if (arg === "--auto-approve") {
+        if (arg === "--auto") {
             autoApprove = true;
             continue;
         }
@@ -384,7 +395,7 @@ export function resolveStartTicketsPlatformConfig(deps, agent, autoApprove = fal
         config: {
             platform,
             worktrunkBinary: resolveWorktrunkBinary(platform, deps.env),
-            buildAgentShellCommand: (key, worktreePath) => buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove),
+            buildAgentShellCommand: (key, worktreePath, modelAlias) => buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias),
             spawnTerminalTab: deps.spawnTerminalTab,
         },
     };
@@ -458,6 +469,8 @@ export function createDefaultStartTicketsDeps() {
             // Worktrunk JSON / git porcelain output can be large; give it room.
             maxBuffer: 64 * 1024 * 1024,
             encoding: "utf-8",
+            // Optional bounded timeout (e.g. cursor-agent --list-models probes).
+            timeout: options?.timeoutMs,
         }, (error, stdout, stderr) => {
             const exitCode = error && typeof error.code === "number"
                 ? (error.code)
@@ -789,47 +802,71 @@ export async function createWorktrees(deps, options, worktrunkBinary) {
 /**
  * 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-approve`) — used by full-automation chains.
+ * (`/implement-ticket <KEY> --auto`) — used by full-automation chains.
  */
 export function buildAgentPrompt(key, opts = {}) {
-    return `/implement-ticket ${key}${opts.autoApprove ? " --auto-approve" : ""}`;
+    // `modelAlias` is accepted for signature consistency only — the model is
+    // injected as a `--model` flag (see buildAgentInvocationArgv), never embedded
+    // in the prompt text.
+    return `/implement-ticket ${key}${opts.autoApprove ? " --auto" : ""}`;
+}
+/**
+ * Build the ordered argv for an agent invocation:
+ * `[command, (--model, alias)?, prompt]`. The model flag+alias are appended ONLY
+ * when the agent supports a model override AND `modelAlias` is a non-empty valid
+ * alias; otherwise they are omitted entirely (fail-open). The prompt is always
+ * the final argument. Pure and never throws on an invalid alias.
+ */
+export function buildAgentInvocationArgv(agent, prompt, modelAlias) {
+    const argv = [agent.command];
+    if (agent.supportsModelOverride &&
+        typeof modelAlias === "string" &&
+        isValidModelAlias(modelAlias)) {
+        argv.push(agent.modelFlag, modelAlias);
+    }
+    argv.push(prompt);
+    return argv;
 }
 /**
- * Build the agent invocation (`<command> <quotedPrompt>`) for the agent's prompt
- * style. Only `positional` exists today; the `switch` keeps a future flag-style
- * agent a typed extension rather than a silent fall-through. `quote` applies the
- * platform-correct quoting to the prompt.
+ * Build the agent invocation string for the agent's prompt style, from the
+ * validated argv array. The registry-controlled command head stays unquoted
+ * (it is never untrusted input); every following argument (the optional
+ * `--model <alias>` and the prompt) is run through the platform-correct `quote`.
  */
-export function buildAgentInvocation(agent, prompt, quote) {
+export function buildAgentInvocation(agent, prompt, quote, modelAlias) {
     switch (agent.promptArgStyle) {
-        case "positional":
-            return `${agent.command} ${quote(prompt)}`;
+        case "positional": {
+            const [command, ...rest] = buildAgentInvocationArgv(agent, prompt, modelAlias);
+            const quotedRest = rest.map(quote);
+            return [command, ...quotedRest].join(" ");
+        }
         default: {
             const exhaustive = agent.promptArgStyle;
             throw new Error(`Unsupported agent promptArgStyle: ${String(exhaustive)}`);
         }
     }
 }
-/** POSIX agent shell command: `cd '<path>' && <agent> '<prompt>'`. */
-export function buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove = false) {
-    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove }), (p) => `'${shSquoteInner(p)}'`);
+/** 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);
     return `cd '${shSquoteInner(worktreePath)}' && ${invocation}`;
 }
-/** PowerShell agent shell command: `Set-Location -LiteralPath '<path>'; <agent> '<prompt>'`. */
-export function buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove = false) {
-    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove }), powershellSquote);
+/** 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);
     return `Set-Location -LiteralPath ${powershellSquote(worktreePath)}; ${invocation}`;
 }
 /**
  * Build the shell command run inside each spawned tab/session, dispatched by
  * 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.
+ * determines the launched command. An optional validated `modelAlias` is
+ * injected as `--model` at the spawn boundary.
  */
-export function buildAgentShellCommand(agent, key, worktreePath, platform = "darwin", autoApprove = false) {
+export function buildAgentShellCommand(agent, key, worktreePath, platform = "darwin", autoApprove = false, modelAlias) {
     if (platform === "win32")
-        return buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove);
-    return buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove);
+        return buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias);
+    return buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias);
 }
 // ---------------------------------------------------------------------------
 // macOS terminal spawning (behind the injected boundary)
@@ -1074,7 +1111,7 @@ export async function spawnTabsForCreatedWorktrees(deps, rows, terminal, buildSh
             out.push(row);
             continue;
         }
-        const shellCommand = buildShellCommand(row.key, row.path);
+        const shellCommand = buildShellCommand(row.key, row.path, row.modelAlias ?? null);
         const result = await deps.spawnTerminalTab(deps, terminal, shellCommand, {
             key: row.key,
             worktreePath: row.path,
@@ -1108,22 +1145,46 @@ export function buildDryRunResults(keys, overrides) {
 export function getDryRunPlatformDetails(agent, platform = process.platform, env = process.env, autoApprove = false) {
     return {
         worktrunkBinary: resolveWorktrunkBinary(platform, env),
-        buildAgentShellCommand: (key, worktreePath) => buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove),
+        // 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),
     };
 }
+/**
+ * Build the dry-run preview of the secret-free MCP provisioning that
+ * `start-tickets` would perform for a worktree whose `.bridge/config` includes
+ * 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) {
+    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}`;
+    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",
+        "DRY-RUN:   entry per target to",
+        `DRY-RUN:     ${mcpJson}`,
+        `DRY-RUN:     ${cursorJson}`,
+        `DRY-RUN:     ${shim}`,
+    ];
+}
 /**
  * Build the user-facing dry-run detail lines for one ticket, rendering the
- * platform-correct Worktrunk binary and the selected agent's shell command. Pure
- * platform formatting only — no preflight, no routing failures.
+ * platform-correct Worktrunk binary, the selected agent's shell command, and
+ * 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) {
+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);
     const wtArgs = buildWtSwitchArgs(branch, false, baseBranch);
-    const agentInvocation = build(key, "<worktree-path>");
+    const agentInvocation = build(key, "<worktree-path>", modelAlias);
     return [
         `DRY-RUN: ${key} -> branch=${branch}`,
         `DRY-RUN:   ${worktrunkBinary} ${wtArgs.join(" ")}`,
         `DRY-RUN:   ${agentInvocation}`,
+        ...buildDryRunMcpProvisioningLines("<worktree-path>", platform),
     ];
 }
 /**
@@ -1140,13 +1201,30 @@ export function formatSummaryReport(rows) {
             line += `  path=${row.path}`;
         lines.push(line);
     }
-    const failures = rows.filter((r) => r.status === "create-failed" || r.status === "spawn-failed");
-    if (failures.length > 0) {
+    // Warnings section: create/spawn-failed row errors AND any non-fatal
+    // per-row provisioning warnings. Identical error/warning text for the same
+    // row is emitted only once.
+    const warningLines = [];
+    for (const row of rows) {
+        const messages = [];
+        if (row.status === "create-failed" || row.status === "spawn-failed") {
+            messages.push(row.error ?? row.status);
+        }
+        for (const warning of row.warnings ?? []) {
+            messages.push(warning);
+        }
+        const seen = new Set();
+        for (const message of messages) {
+            if (seen.has(message))
+                continue;
+            seen.add(message);
+            warningLines.push(`  ${row.key}: ${message}`);
+        }
+    }
+    if (warningLines.length > 0) {
         lines.push("");
         lines.push("Warnings:");
-        for (const row of failures) {
-            lines.push(`  ${row.key}: ${row.error ?? row.status}`);
-        }
+        lines.push(...warningLines);
     }
     return lines.join("\n");
 }
@@ -1158,7 +1236,403 @@ export function formatSummaryReport(rows) {
  * using the platform-correct shell builder. Global preflight/refresh failures
  * are returned as `{ ok: false }`; per-ticket failures stay in the rows.
  */
-export async function orchestrateStartTickets(deps, options) {
+/**
+ * Build the `mcp-provisioning` filesystem boundary from `StartTicketsDeps`.
+ * Provisioning needs real `fs/promises` ops (not part of the command-runner DI
+ * boundary), but inherits the platform and cwd from the orchestration deps.
+ */
+export function buildMcpProvisioningDeps(deps) {
+    return {
+        readFile: (filePath) => readFile(filePath, "utf-8"),
+        writeFile: (filePath, data) => writeFile(filePath, data, "utf-8"),
+        mkdir: (dirPath, options) => mkdir(dirPath, options),
+        platform: deps.platform,
+        cwd: deps.cwd,
+    };
+}
+/**
+ * Tier-3 file-credential materialization seam.
+ *
+ * The committed `.bridge/config` schema does not (yet) declare file-credential
+ * entries — Tier-3 file materialization is a gated seam (see
+ * `credential-materialization.ts`, whose Windows worktree-visible copy remains
+ * disabled pending the open context-vs-server-only design decision). With no
+ * file-credential configuration there is nothing to materialize, so the default
+ * is a safe pass-through. The seam exists so `orchestrateStartTickets` calls it
+ * in the correct order — AFTER MCP registration provisioning and BEFORE tab
+ * spawning — once the schema and the design decision are resolved. Per-row
+ * failures must mark only the affected row `spawn-failed`; normal symlinks are
+ * never torn down on completion.
+ */
+export async function materializeFileCredentialsForCreatedWorktrees(rows, _deps) {
+    return rows;
+}
+// ---------------------------------------------------------------------------
+// BAPI-365: difficulty-based model routing (fail-open at the spawn boundary)
+// ---------------------------------------------------------------------------
+/** Default Bridge API base URL when BAPI_BASE_URL is unset. */
+export const START_TICKETS_DEFAULT_BASE_URL = "https://bridgegpt-api.com";
+const TICKET_MODEL_TIER_FETCH_TIMEOUT_MS = 75_000;
+const CONFIG_FIELD_FETCH_TIMEOUT_MS = 30_000;
+const CURSOR_MODEL_LIST_TIMEOUT_MS = 15_000;
+/** GET auth headers for the CLI's Bridge API calls. */
+function startTicketsGetHeaders(access) {
+    return {
+        "X-API-Key": access.apiKey,
+        "X-Bridge-MCP-Version": VERSION,
+    };
+}
+/**
+ * Resolve the repo name for routing: prefer `BAPI_REPO_NAME`, then `.bridge/config`.
+ * Returns `null` when neither is available.
+ */
+export async function resolveStartTicketsRepoName(deps) {
+    const fromEnv = deps.env.BAPI_REPO_NAME;
+    if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
+        return fromEnv.trim();
+    }
+    try {
+        const result = await readBridgeConfig(deps.cwd, {
+            readFile: (filePath) => readFile(filePath, "utf-8"),
+        });
+        if (result.ok && result.manifest.repoName) {
+            return result.manifest.repoName;
+        }
+    }
+    catch {
+        // fall through to null
+    }
+    return null;
+}
+/**
+ * Resolve Bridge API access (repo name + API key + base URL). Returns a
+ * structured failure — never throwing and never embedding secret values — so the
+ * caller can degrade to the agent default model.
+ */
+export async function resolveStartTicketsBridgeApiAccess(deps) {
+    const repoName = await resolveStartTicketsRepoName(deps);
+    if (!repoName) {
+        return {
+            ok: false,
+            warning: "model routing: could not resolve repo name (set BAPI_REPO_NAME or .bridge/config); using agent default model",
+        };
+    }
+    let credResult;
+    try {
+        credResult = await resolveBapiCredentials(repoName, {
+            env: deps.env,
+            homedir: os.homedir,
+            platform: deps.platform,
+            readFile: (p) => readFile(p, "utf-8"),
+            stat: (p) => stat(p),
+        });
+    }
+    catch {
+        return { ok: false, warning: "model routing: failed to resolve Bridge API credentials; using agent default model" };
+    }
+    if (!credResult.ok) {
+        return { ok: false, warning: "model routing: Bridge API credentials unavailable; using agent default model" };
+    }
+    const baseUrlRaw = deps.env.BAPI_BASE_URL;
+    const baseUrl = typeof baseUrlRaw === "string" && baseUrlRaw.trim().length > 0
+        ? baseUrlRaw.trim()
+        : START_TICKETS_DEFAULT_BASE_URL;
+    return { ok: true, access: { repoName, apiKey: credResult.credentials.apiKey, baseUrl } };
+}
+/** Build a `${baseUrl}/jira${apiPath}` URL with query params; trims trailing slashes. */
+export function buildStartTicketsJiraUrl(baseUrl, apiPath, params = {}) {
+    const trimmed = baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${trimmed}/jira${apiPath}`);
+    for (const [k, v] of Object.entries(params)) {
+        url.searchParams.set(k, v);
+    }
+    return url.toString();
+}
+/**
+ * GET JSON with an `AbortController` timeout. Throws a generic error (no secret
+ * material) on a non-2xx response; always clears the timeout.
+ */
+export async function fetchJsonWithTimeout(url, headers, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const resp = await fetch(url, { headers, signal: controller.signal });
+        if (!resp.ok) {
+            throw new Error(`request failed with status ${resp.status}`);
+        }
+        return await resp.json();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Normalize an unknown config value into a clean tier->alias override map. */
+export function normalizeDifficultyModelTierOverrides(value) {
+    if (value === null || value === undefined)
+        return {};
+    if (typeof value !== "object" || Array.isArray(value))
+        return {};
+    const out = {};
+    for (const [key, raw] of Object.entries(value)) {
+        if (!isModelTier(key))
+            continue;
+        if (typeof raw !== "string")
+            continue;
+        const trimmed = raw.trim();
+        if (trimmed.length === 0)
+            continue;
+        out[key] = trimmed;
+    }
+    return out;
+}
+/** GET /jira/config-field/{fieldName}; returns the parsed `value` (or undefined). */
+export async function fetchStartTicketsConfigField(access, fieldName) {
+    const url = buildStartTicketsJiraUrl(access.baseUrl, `/config-field/${encodeURIComponent(fieldName)}`, { repo_name: access.repoName });
+    const body = await fetchJsonWithTimeout(url, startTicketsGetHeaders(access), CONFIG_FIELD_FETCH_TIMEOUT_MS);
+    if (body && typeof body === "object" && "value" in body) {
+        return body.value;
+    }
+    return undefined;
+}
+/**
+ * Fetch the repo's routing config once. A missing/null enable value defaults to
+ * enabled (the feature ships ON); an explicit boolean `false` disables routing.
+ * Any fetch failure returns a structured failure so the caller omits `--model`.
+ */
+export async function fetchDifficultyModelRoutingConfig(access) {
+    try {
+        const enabledValue = await fetchStartTicketsConfigField(access, "difficulty_model_routing_enabled");
+        const overridesValue = await fetchStartTicketsConfigField(access, "difficulty_model_tier_overrides");
+        const enabled = enabledValue === false ? false : true;
+        return { ok: true, config: { enabled, overrides: normalizeDifficultyModelTierOverrides(overridesValue) } };
+    }
+    catch {
+        return { ok: false, warning: "model routing: failed to fetch routing config; using agent default model" };
+    }
+}
+/**
+ * Fetch the coarse tier for one ticket with a bounded timeout. Never throws to
+ * the batch orchestrator: failures/timeouts return a structured warning.
+ */
+export async function fetchTicketModelTierForStartTickets(access, ticket) {
+    try {
+        const url = buildStartTicketsJiraUrl(access.baseUrl, `/tickets/${encodeURIComponent(ticket)}/model-tier`, { repo_name: access.repoName });
+        const body = await fetchJsonWithTimeout(url, startTicketsGetHeaders(access), TICKET_MODEL_TIER_FETCH_TIMEOUT_MS);
+        const obj = (body ?? {});
+        const tier = isModelTier(obj.tier) ? obj.tier : null;
+        const difficulty = typeof obj.difficulty === "number" ? obj.difficulty : null;
+        const source = obj.source === "cached" || obj.source === "computed" || obj.source === "fallback"
+            ? obj.source
+            : "fallback";
+        return { ok: true, value: { difficulty, tier, source } };
+    }
+    catch {
+        return { ok: false, warning: `model routing: tier lookup failed for ${ticket}; using agent default model` };
+    }
+}
+/**
+ * Fetch tiers for the still-spawnable rows with bounded parallelism (capped at
+ * 3). One ticket's failure never aborts the others; results are keyed by ticket.
+ */
+export async function fetchTicketModelTiersForRows(access, rows, maxParallel, isEligible = (r) => r.status === "created" && !!r.path) {
+    const eligible = rows.filter(isEligible);
+    const limit = Math.min(maxParallel, 3);
+    const results = await runWithConcurrency(eligible, limit, (row) => fetchTicketModelTierForStartTickets(access, row.key).then((res) => [row.key, res]));
+    return new Map(results);
+}
+/**
+ * Parse a model-list command's stdout into a set of advertised model aliases.
+ * Tokens are split on whitespace/commas, stripped of surrounding bullets and
+ * punctuation, and kept only when they match the alias allowlist pattern.
+ */
+export function parseAdvertisedAgentModels(stdout) {
+    const out = new Set();
+    for (const token of stdout.split(/[\s,]+/)) {
+        const cleaned = token.replace(/^[^A-Za-z0-9._:-]+/, "").replace(/[^A-Za-z0-9._:-]+$/, "");
+        // Require at least one alphanumeric char so bare punctuation (e.g. a "-"
+        // bullet) is not mistaken for an alias even though it matches the pattern.
+        if (cleaned.length > 0 && /[A-Za-z0-9]/.test(cleaned) && isValidModelAlias(cleaned)) {
+            out.add(cleaned);
+        }
+    }
+    return out;
+}
+/**
+ * Discover the cursor-agent advertised model set by running
+ * `cursor-agent --list-models` (then `cursor-agent models` as a fallback)
+ * non-interactively with a bounded timeout. Returns `null` on failure, timeout,
+ * empty output, or parse uncertainty.
+ */
+export async function fetchCursorAgentAdvertisedModels(deps, agent) {
+    const tryCommand = async (args) => {
+        try {
+            const result = await deps.runCommand(agent.command, args, {
+                cwd: deps.cwd,
+                timeoutMs: CURSOR_MODEL_LIST_TIMEOUT_MS,
+            });
+            if (!commandSucceeded(result))
+                return null;
+            const models = parseAdvertisedAgentModels(result.stdout);
+            return models.size > 0 ? models : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const primary = await tryCommand(["--list-models"]);
+    if (primary)
+        return primary;
+    return tryCommand(["models"]);
+}
+/**
+ * Validate a resolved alias for the agent before it reaches shell construction.
+ * For non-cursor agents the candidate is returned unchanged (resolveModelAlias
+ * already statically validated claude aliases). For cursor-agent the candidate
+ * must appear in the live advertised model set; otherwise it is rejected.
+ */
+export async function validateResolvedModelAliasForAgent(deps, agent, candidate) {
+    if (agent.name !== "cursor-agent") {
+        return { ok: true, alias: candidate };
+    }
+    const advertised = await fetchCursorAgentAdvertisedModels(deps, agent);
+    if (!advertised) {
+        return {
+            ok: false,
+            warning: `model routing: could not verify cursor-agent models; omitting --model for '${candidate}'`,
+        };
+    }
+    if (!advertised.has(candidate)) {
+        return {
+            ok: false,
+            warning: `model routing: cursor-agent model '${candidate}' not advertised; omitting --model`,
+        };
+    }
+    return { ok: true, alias: candidate };
+}
+/** Return a copy of `row` with default (no-routing) metadata and a reason. */
+export function applyDefaultModelRoutingMetadata(row, reason) {
+    return {
+        ...row,
+        difficulty: row.difficulty ?? null,
+        modelTier: null,
+        modelAlias: null,
+        modelRoutingSource: row.modelRoutingSource ?? "default",
+        modelRoutingReason: reason,
+    };
+}
+/** Real spawn path: a worktree was created and has a path. */
+const isCreatedRoutingEligible = (r) => r.status === "created" && !!r.path;
+/** Dry-run path: rows have no worktree path yet but are eligible for a preview. */
+const isDryRunRoutingEligible = (r) => r.status === "dry-run";
+/**
+ * Shared fail-open routing resolution. `isEligible` selects which rows get a
+ * resolved tier/alias; every failure mode (unsupported agent, credential/config/
+ * tier fetch failure, backend fallback, invalid/unavailable alias) is converted
+ * to `modelAlias: null` plus a row warning, and never throws. Non-eligible rows
+ * pass through untouched.
+ */
+async function resolveModelRoutingForEligible(deps, rows, options, agent, isEligible) {
+    const eligible = rows.filter(isEligible);
+    if (eligible.length === 0)
+        return rows;
+    if (!agent.supportsModelOverride) {
+        const reason = `model routing: agent '${agent.name}' does not support --model; using agent default`;
+        return rows.map((r) => (isEligible(r) ? applyDefaultModelRoutingMetadata(r, reason) : r));
+    }
+    const accessResult = await resolveStartTicketsBridgeApiAccess(deps);
+    if (!accessResult.ok) {
+        return rows.map((r) => isEligible(r)
+            ? appendSummaryRowWarning(applyDefaultModelRoutingMetadata(r, accessResult.warning), accessResult.warning)
+            : r);
+    }
+    const access = accessResult.access;
+    const configResult = await fetchDifficultyModelRoutingConfig(access);
+    if (!configResult.ok) {
+        return rows.map((r) => isEligible(r)
+            ? appendSummaryRowWarning(applyDefaultModelRoutingMetadata(r, configResult.warning), configResult.warning)
+            : r);
+    }
+    const { enabled, overrides } = configResult.config;
+    if (!enabled) {
+        const reason = "model routing: disabled for this repo; using agent default";
+        return rows.map((r) => (isEligible(r) ? applyDefaultModelRoutingMetadata(r, reason) : r));
+    }
+    const tierMap = await fetchTicketModelTiersForRows(access, eligible, options.maxParallel, isEligible);
+    const out = [];
+    for (const row of rows) {
+        if (!isEligible(row)) {
+            out.push(row);
+            continue;
+        }
+        const tierResult = tierMap.get(row.key);
+        if (!tierResult || !tierResult.ok) {
+            const warning = tierResult && !tierResult.ok
+                ? tierResult.warning
+                : `model routing: no tier resolved for ${row.key}; using agent default`;
+            out.push(appendSummaryRowWarning(applyDefaultModelRoutingMetadata(row, warning), warning));
+            continue;
+        }
+        const { difficulty, tier, source } = tierResult.value;
+        const baseRow = {
+            ...row,
+            difficulty: difficulty ?? null,
+            modelTier: tier ?? null,
+            modelRoutingSource: source,
+        };
+        if (!tier) {
+            const warning = `model routing: ${row.key} resolved no tier (source=${source}); using agent default`;
+            out.push(appendSummaryRowWarning(applyDefaultModelRoutingMetadata(baseRow, warning), warning));
+            continue;
+        }
+        const alias = resolveModelAlias(agent, tier, overrides);
+        if (!alias) {
+            const warning = `model routing: no valid alias for tier=${tier}; using agent default`;
+            out.push(appendSummaryRowWarning({ ...baseRow, modelAlias: null, modelRoutingReason: warning }, warning));
+            continue;
+        }
+        const validation = await validateResolvedModelAliasForAgent(deps, agent, alias);
+        if (!validation.ok) {
+            out.push(appendSummaryRowWarning({ ...baseRow, modelAlias: null, modelRoutingReason: validation.warning }, validation.warning));
+            continue;
+        }
+        out.push({
+            ...baseRow,
+            modelAlias: validation.alias,
+            modelRoutingReason: `tier=${tier} model=${validation.alias} (source=${source})`,
+        });
+    }
+    return out;
+}
+/**
+ * Resolve per-ticket model routing for the spawnable (created) rows. Public
+ * entrypoint for the real spawn path. ALWAYS fail-open (see
+ * {@link resolveModelRoutingForEligible}).
+ */
+export async function resolveModelRoutingForRows(deps, rows, options, agent) {
+    return resolveModelRoutingForEligible(deps, rows, options, agent, isCreatedRoutingEligible);
+}
+/**
+ * Dry-run variant: resolve routing for `dry-run` rows so `--dry-run` can preview
+ * the model each tab would launch with. Identical fail-open resolution; only the
+ * eligibility differs (dry-run rows carry no worktree path). NOTE: this performs
+ * the same read-only tier lookup as a real run, so for a ticket with no cached
+ * difficulty the backend may compute and cache it (one LLM call) — exactly what
+ * the subsequent real run would have done.
+ */
+export async function resolveModelRoutingForDryRun(deps, rows, options, agent) {
+    return resolveModelRoutingForEligible(deps, rows, options, agent, isDryRunRoutingEligible);
+}
+/**
+ * Format one concise routing decision line per ticket:
+ * `KEY difficulty=<n|?> tier=<tier|fallback> agent=<name> model=<alias|default>`.
+ */
+export function formatModelRoutingLine(row, agent) {
+    const difficulty = typeof row.difficulty === "number" ? String(row.difficulty) : "?";
+    const tier = row.modelTier ?? "fallback";
+    const model = row.modelAlias ?? "default";
+    return `${row.key} difficulty=${difficulty} tier=${tier} agent=${agent.name} model=${model}`;
+}
+export async function orchestrateStartTickets(deps, options, overrides = {}) {
     if (options.dryRun) {
         return { ok: true, rows: buildDryRunResults(options.keys, options.branchOverrides) };
     }
@@ -1183,9 +1657,37 @@ export async function orchestrateStartTickets(deps, options) {
     });
     if (!refresh.ok)
         return { ok: false, error: refresh.error };
-    const created = await createWorktrees(deps, options, platformConfig.config.worktrunkBinary);
-    const terminal = detectTerminal(options.terminal, deps.env);
-    const rows = await spawnTabsForCreatedWorktrees(deps, created, terminal, platformConfig.config.buildAgentShellCommand);
+    const createWorktreesFn = overrides.createWorktrees ?? createWorktrees;
+    const provisionFn = overrides.provisionMcpRegistrations ??
+        ((rows, d) => provisionMcpRegistrationsForCreatedWorktrees(rows, buildMcpProvisioningDeps(d)));
+    const materializeFn = overrides.materializeFileCredentials ?? materializeFileCredentialsForCreatedWorktrees;
+    const detectTerminalFn = overrides.detectTerminal ?? detectTerminal;
+    const spawnTabsFn = overrides.spawnTabsForCreatedWorktrees ?? spawnTabsForCreatedWorktrees;
+    const created = 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
+    // spawn step below) — they never abort the whole run.
+    const provisioned = await provisionFn(created, deps);
+    // Materialize any Tier-3 file credentials AFTER MCP registration provisioning
+    // and BEFORE tab spawning (currently a pass-through seam; see
+    // materializeFileCredentialsForCreatedWorktrees).
+    const materialized = await materializeFn(provisioned, deps);
+    // BAPI-365: resolve per-ticket model routing AFTER provisioning/materialization
+    // and BEFORE building the spawn command. Always fail-open: routing never aborts
+    // a spawn — at worst a ticket runs on the agent's default model.
+    const resolveRoutingFn = overrides.resolveModelRoutingForRows ?? resolveModelRoutingForRows;
+    const routed = await resolveRoutingFn(deps, materialized, options, agent);
+    for (const row of routed) {
+        if (row.status !== "created" || !row.path)
+            continue;
+        overrides.modelRoutingLog?.(formatModelRoutingLine(row, agent));
+        if (row.modelAlias == null && row.modelRoutingReason) {
+            overrides.modelRoutingWarningLog?.(`${row.key}: ${row.modelRoutingReason}`);
+        }
+    }
+    const terminal = detectTerminalFn(options.terminal, deps.env);
+    const rows = await spawnTabsFn(deps, routed, terminal, platformConfig.config.buildAgentShellCommand);
     return { ok: true, rows };
 }
 /** Platform-specific guidance printed when one or more tabs fail to spawn. */
@@ -1237,15 +1739,34 @@ export async function runStartTicketsCli(argv, overrides = {}) {
         return 1;
     }
     if (options.dryRun) {
+        // 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.
+        const resolveDryRunRoutingFn = overrides.resolveModelRoutingForDryRun ?? resolveModelRoutingForDryRun;
+        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]));
         for (const key of options.keys) {
             const branch = resolveBranchForTicket(key, options.branchOverrides);
-            for (const line of buildDryRunDetailLines(agent, key, branch, deps.platform, deps.env, options.baseBranch, options.autoApprove)) {
+            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)) {
                 log(line);
             }
+            log(`DRY-RUN:   model routing: ${formatModelRoutingLine(routedRow ?? { key, branch, status: "dry-run" }, agent)}`);
+            if (modelAlias == null && routedRow?.modelRoutingReason) {
+                log(`DRY-RUN:   ${routedRow.modelRoutingReason}`);
+            }
         }
         log("");
     }
-    const result = await orchestrate(deps, options);
+    // Thread the routing decision/warning sinks through to the orchestrator. The
+    // dry-run path short-circuits inside orchestrate before any routing (the
+    // preview above already resolved it), so no backend tiers are fetched twice.
+    const result = await orchestrate(deps, options, {
+        modelRoutingLog: log,
+        modelRoutingWarningLog: errorLog,
+    });
     if (!result.ok) {
         errorLog(`Error: ${result.error}`);
         return 1;