@bridge_gpt/mcp-server 0.2.54 → 0.2.56

package/build/start-tickets.js

@@ -56,6 +56,7 @@
 import { execFile } from "child_process";
 import { readFile, writeFile, mkdir, mkdtemp, stat, lstat, symlink, unlink, copyFile, readdir, rm, } from "fs/promises";
 import os from "node:os";
+import { createHash } from "node:crypto";
 import path from "path";
 import { VERSION } from "./version.generated.js";
 import { resolveBapiCredentials, getPrimaryCredentialStorePath, } from "./credential-store.js";
@@ -74,7 +75,10 @@ import { TICKET_KEY_PATTERN as SHARED_TICKET_KEY_PATTERN, TICKET_KEY_USAGE_SUMMA
 // 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, resolveModelAlias, isValidModelAlias, isModelTier, } from "./agent-registry.js";
+import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, resolveModelAlias, isValidModelAlias, isModelTier, } from "./agent-registry.js";
+import { agentForPlatform, getHostTarget, getWorktreeHostTargets, isRunnableHostTarget, isHostPlatformId } from "./mcp-host-targets.js";
+import { resolveCodexLaunchScope } from "./codex-launch-scope.js";
+import { tmpdir } from "node:os";
 import { createStartTicketsConductorContext, provisionConductorHooksForRows, emitStartTicketsRunStarted, injectConductorEnvIntoShellCommand, buildSupervisorTabCommand, isSupervisorLaunchEnabled, supervisorSpawnKey, } from "./start-tickets-conductor.js";
 import { transitionEpicDispatch, resolveConductorBridgeApiAccess, } from "./conductor/bridge-api-client.js";
 import { PR_BASE_BRANCH_ENV_VAR, buildPrBaseContractLaunchInstruction, } from "./pr-base-contract.js";
@@ -125,9 +129,11 @@ export function getStartTicketsUsage() {
         `  npx -y ${MCP_PACKAGE_NAME} start-tickets [flags] KEY [KEY ...]`,
         "",
         "Flags:",
-        "  --agent claude|cursor-agent Agent command to launch in each worktree (default: claude)",
-        "  --workflow implement|review-and-implement  Slash command each spawned worktree runs (default: implement). review-and-implement runs /review-ticket then, after a per-ticket halt gate, /implement-ticket in the same session; --auto applies to the selected workflow.",
-        "  --tier cheap|basic|premium  Coarse model-routing override: bypasses the per-ticket difficulty/tier lookup and applies this tier to every ticket. It is still mapped to a model through the agent registry and any configured difficulty_model_tier_overrides, then validated — it is NOT a raw --model alias, and never carries an API key or credential. A malformed value fails open to premium routing.",
+        "  --agent claude|cursor-agent|codex Agent command to launch in each worktree (overrides --host; default: claude)",
+        "  --host claude-code|cursor|codex|copilot-vscode|windsurf Current host when --agent is omitted; Claude Code, Cursor, and Codex can launch sessions",
+        "  Cursor with --auto launches headlessly after a bounded readiness check; without --auto it stays interactive for the review gate.",
+        "  --workflow implement|review-and-implement  Command each spawned worktree runs (default: implement). review-and-implement runs review-ticket then, after a per-ticket halt gate, hands off to a fresh implement-ticket session; --auto applies to both phases.",
+        "  --tier cheap|basic|premium  Coarse model-routing override: bypasses the per-ticket difficulty/tier lookup and applies this tier to every ticket. Claude/Cursor use registry aliases and repository overrides; Codex uses the authenticated Bridge catalog. It is NOT a raw --model alias and never carries an API key or credential. A malformed value requests premium routing when available.",
         "  --rounds 1|2                Review round count forwarded to the review phase; review-only, valid only with --workflow review-and-implement",
         "  --terminal terminal|iterm   Override the macOS terminal app (default: auto-detect via $TERM_PROGRAM); honored on macOS only",
         "  --dry-run                   Print intended actions; creates no worktrees and opens no tabs, but DOES resolve model routing read-only (may compute+cache a ticket's difficulty) to preview the --model each tab would use",
@@ -163,6 +169,13 @@ export function getStartTicketsUsage() {
         TICKET_KEY_USAGE_SUMMARY,
     ].join("\n");
 }
+/** Agent names backed by a runnable, worktree-scoped host registration. */
+function formatStartTicketsAgentNames() {
+    return getWorktreeHostTargets()
+        .filter(isRunnableHostTarget)
+        .map((target) => target.launchAgent)
+        .join(", ");
+}
 /**
  * Parse argv strictly and without an arg-parser dependency. Returns a
  * discriminated result: help, a validation error, or validated options.
@@ -177,7 +190,8 @@ export function parseStartTicketsArgs(argv) {
     let autoApprove = false;
     let refreshMain = true;
     let maxParallelRaw;
-    let agentName = DEFAULT_AGENT_NAME;
+    let agentName;
+    let hostPlatform;
     let baseBranch = "main";
     let conductorEnabled = false;
     // BAPI-948: `--guard-stale-branch` (and `--conductor`, which implies it) opt the
@@ -217,12 +231,20 @@ export function parseStartTicketsArgs(argv) {
             if (!isAgentName(value)) {
                 return {
                     status: "error",
-                    message: `Invalid --agent value: '${value}' (allowed agents: ${formatValidAgentNames()}).`,
+                    message: `Invalid --agent value: '${value}' (launchable agents: ${formatStartTicketsAgentNames()}).`,
                 };
             }
             agentName = value;
             continue;
         }
+        if (arg === "--host" || arg.startsWith("--host=")) {
+            const value = arg.startsWith("--host=") ? arg.slice("--host=".length) : takeValue();
+            if (!value || !isHostPlatformId(value)) {
+                return { status: "error", message: `Invalid --host value: '${value ?? ""}'.` };
+            }
+            hostPlatform = value;
+            continue;
+        }
         if (arg === "--workflow" || arg.startsWith("--workflow=")) {
             let value;
             if (arg.startsWith("--workflow=")) {
@@ -452,6 +474,14 @@ export function parseStartTicketsArgs(argv) {
         }
         reviewRounds = reviewRoundsRaw === "1" ? 1 : 2;
     }
+    const target = hostPlatform ? getHostTarget(hostPlatform) : undefined;
+    if (!agentName && target && !isRunnableHostTarget(target)) {
+        return {
+            status: "error",
+            message: `${target.label} supports MCP configuration but cannot spawn a Bridge session. Continue the workflow manually or pass an explicit --agent override.`,
+        };
+    }
+    const resolvedAgentName = agentName ?? (hostPlatform ? agentForPlatform(hostPlatform) : DEFAULT_AGENT_NAME);
     return {
         status: "ok",
         options: {
@@ -462,7 +492,7 @@ export function parseStartTicketsArgs(argv) {
             refreshMain,
             maxParallel,
             branchOverrides,
-            agentName,
+            agentName: resolvedAgentName,
             baseBranch,
             conductorEnabled,
             workflow,
@@ -550,7 +580,7 @@ baseBranch) {
             // falls back to the basename-derived repo name (the 403 root cause), and
             // (BAPI-586/BAPI-801) the run base so the spawned worker opens its PR
             // against it. The base assignment stays outermost.
-            buildAgentShellCommand: (key, worktreePath, modelAlias) => prependBaseBranchEnvAssignment(prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch), repoName, platform), prBaseBranch, platform),
+            buildAgentShellCommand: (key, worktreePath, modelAlias, launchArgs) => prependBaseBranchEnvAssignment(prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch, launchArgs), repoName, platform), prBaseBranch, platform),
             spawnTerminalTab: deps.spawnTerminalTab,
         },
     };
@@ -775,6 +805,11 @@ export async function runPreflight(deps, options, warn = (message) => console.wa
     const enforceLiveSourceGuard = options.nonMutatingBase === true || options.epic !== undefined;
     const result = await enforcePreflightPrerequisites(deps, { enforceLiveSourceGuard });
     if (result.ok) {
+        if (options.agentName === "cursor-agent" && options.autoApprove) {
+            const cursorReady = await preflightHeadlessCursor(deps);
+            if (!cursorReady.ok)
+                return cursorReady;
+        }
         // Overridden collision: not silent — surface the warning through the channel.
         if (result.warning)
             warn(result.warning);
@@ -786,6 +821,52 @@ export async function runPreflight(deps, options, warn = (message) => console.wa
     // Both missing-prerequisite and live-source-collision are doctor-diagnosable.
     return { ok: false, error: appendDoctorHint(result.error) };
 }
+/** Validate the actual headless path before creating any ticket worktree. */
+async function preflightHeadlessCursor(deps) {
+    let help;
+    try {
+        help = await deps.runCommand("cursor-agent", ["--help"], { timeoutMs: 5000 });
+    }
+    catch {
+        return { ok: false, error: "Cursor Agent is unavailable. Install cursor-agent and ensure it is on PATH." };
+    }
+    if (help.exitCode !== 0) {
+        return { ok: false, error: "Cursor Agent is unavailable. Install cursor-agent and ensure it is on PATH." };
+    }
+    for (const flag of ["--print", "--output-format", "--trust", "--workspace", "--force", "--approve-mcps"]) {
+        if (!help.stdout.includes(flag)) {
+            return { ok: false, error: `Cursor Agent does not support ${flag}. Update cursor-agent before using --auto.` };
+        }
+    }
+    let probeDir;
+    try {
+        probeDir = await mkdtemp(path.join(tmpdir(), "bridge-cursor-ready-"));
+    }
+    catch {
+        return { ok: false, error: "Could not create a temporary workspace for the Cursor Agent readiness check." };
+    }
+    try {
+        const probe = await deps.runCommand("cursor-agent", [
+            "-p", "--output-format", "text", "--trust", "--workspace", probeDir,
+            "Reply with exactly BAPI_CURSOR_READY. Do not use tools.",
+        ], { cwd: probeDir, timeoutMs: 60000 });
+        if (probe.exitCode !== 0 || !probe.stdout.includes("BAPI_CURSOR_READY")) {
+            return { ok: false, error: "Cursor Agent could not complete a headless authentication check. Run cursor-agent login or configure CURSOR_API_KEY, then retry." };
+        }
+        return { ok: true };
+    }
+    catch {
+        return { ok: false, error: "Cursor Agent headless readiness check failed. Verify authentication and retry." };
+    }
+    finally {
+        try {
+            await rm(probeDir, { recursive: true, force: true });
+        }
+        catch {
+            // Cleanup failure must not turn a bounded readiness result into a raw error.
+        }
+    }
+}
 // ---------------------------------------------------------------------------
 // main refresh + worktree parsing
 // ---------------------------------------------------------------------------
@@ -1192,17 +1273,23 @@ export function buildAgentPrompt(key, opts = {}) {
     // injected as a `--model` flag (see buildAgentInvocationArgv), never embedded
     // in the prompt text.
     const workflow = opts.workflow ?? "implement";
-    const head = workflow === "review-and-implement" ? "/review-and-implement" : "/implement-ticket";
+    const commandName = workflow === "review-and-implement" ? "review-and-implement" : "implement-ticket";
+    // Codex skills use explicit invocation names; Claude and Cursor use commands.
+    const head = opts.agentName === "codex" ? `$bridge-${commandName}` : `/${commandName}`;
     let command = `${head} ${key}${opts.autoApprove ? " --auto" : ""}`;
     // Review-only arguments (`--rounds`, non-default `--base-branch`) must never
     // leak into the legacy `/implement-ticket` prompt.
     if (workflow === "review-and-implement") {
+        if (opts.agentName === "cursor-agent")
+            command += " --agent=cursor-agent";
         if (opts.reviewRounds !== undefined) {
             command += ` --rounds=${opts.reviewRounds}`;
         }
         if (opts.baseBranch !== undefined && opts.baseBranch !== "main") {
             command += ` --base-branch='${shSquoteInner(opts.baseBranch)}'`;
         }
+        if (opts.agentName === "codex")
+            command += " --agent codex --host codex";
     }
     const parts = [command];
     if (opts.conductorEnabled) {
@@ -1224,8 +1311,13 @@ export function buildAgentPrompt(key, opts = {}) {
  * 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) {
+export function buildAgentInvocationArgv(agent, prompt, modelAlias, launchArgsOrCursorWorkspace = []) {
     const argv = [agent.command];
+    if (agent.name === "codex" && Array.isArray(launchArgsOrCursorWorkspace))
+        argv.push(...launchArgsOrCursorWorkspace);
+    if (agent.name === "cursor-agent" && typeof launchArgsOrCursorWorkspace === "string" && launchArgsOrCursorWorkspace) {
+        argv.push("-p", "--output-format", "text", "--trust", "--approve-mcps", "--force", "--workspace", launchArgsOrCursorWorkspace);
+    }
     if (agent.supportsModelOverride &&
         typeof modelAlias === "string" &&
         isValidModelAlias(modelAlias)) {
@@ -1241,10 +1333,10 @@ export function buildAgentInvocationArgv(agent, prompt, modelAlias) {
  * `--model <alias>` pair and the prompt — is run through the platform-correct
  * `quote`.
  */
-export function buildAgentInvocation(agent, prompt, quote, modelAlias) {
+export function buildAgentInvocation(agent, prompt, quote, modelAlias, launchArgsOrCursorWorkspace = []) {
     switch (agent.promptArgStyle) {
         case "positional": {
-            const [command, ...rest] = buildAgentInvocationArgv(agent, prompt, modelAlias);
+            const [command, ...rest] = buildAgentInvocationArgv(agent, prompt, modelAlias, launchArgsOrCursorWorkspace);
             const quotedRest = rest.map(quote);
             return [command, ...quotedRest].join(" ");
         }
@@ -1255,13 +1347,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, resumeMode = false, workflow = "implement", reviewRounds, baseBranch) {
-    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch }), (p) => `'${shSquoteInner(p)}'`, modelAlias);
+export function buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch, launchArgs = []) {
+    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch, agentName: agent.name }), (p) => `'${shSquoteInner(p)}'`, modelAlias, agent.name === "cursor-agent" && autoApprove ? worktreePath : launchArgs);
     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, resumeMode = false, workflow = "implement", reviewRounds, baseBranch) {
-    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch }), powershellSquote, modelAlias);
+export function buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch, launchArgs = []) {
+    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch, agentName: agent.name }), powershellSquote, modelAlias, agent.name === "cursor-agent" && autoApprove ? worktreePath : launchArgs);
     return `Set-Location -LiteralPath ${powershellSquote(worktreePath)}; ${invocation}`;
 }
 /**
@@ -1272,10 +1364,10 @@ export function buildPowerShellAgentShellCommand(agent, key, worktreePath, autoA
  * injected as `--model` at the spawn boundary. `conductorEnabled` appends the
  * BAPI-586 PR-base contract instruction to the prompt (opt-in via `--conductor`).
  */
-export function buildAgentShellCommand(agent, key, worktreePath, platform = "darwin", autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch) {
+export function buildAgentShellCommand(agent, key, worktreePath, platform = "darwin", autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch, launchArgs = []) {
     if (platform === "win32")
-        return buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch);
-    return buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch);
+        return buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch, launchArgs);
+    return buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch, launchArgs);
 }
 /**
  * Build the shell command run inside a spawned tab/session for an ARBITRARY
@@ -1857,7 +1949,7 @@ export async function spawnTabsForCreatedWorktrees(deps, rows, terminal, buildSh
             out.push(row);
             continue;
         }
-        const baseShellCommand = buildShellCommand(row.key, row.path, row.modelAlias ?? null);
+        const baseShellCommand = buildShellCommand(row.key, row.path, row.modelAlias ?? null, row.codexLaunchArgs);
         // Scope the row's conductor identity env to this terminal/tab/session only
         // (BAPI-394). No-op when the row carries no conductorEnv (dry-run, non-Claude
         // agents, or conductor disabled). Never mutates process/global env.
@@ -1912,9 +2004,11 @@ export function getDryRunPlatformDetails(agent, platform = process.platform, env
         // and (BAPI-801/BAPI-847) the PR base as a BAPI_BASE_BRANCH prefix through the
         // SAME resolvePrBaseBranchEnvValue rule — including the ordinary `main` case —
         // and the same outermost ordering the real spawn builder uses; dry-run shares
-        // both environment renderings with real spawning. Reuses the same buildAgentShellCommand/buildAgentPrompt path as a
-        // real spawn — dry-run is never special-cased — so the preview is exact.
-        buildAgentShellCommand: (key, worktreePath, modelAlias) => prependBaseBranchEnvAssignment(prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, false, workflow, reviewRounds, baseBranch), repoName, platform), resolvePrBaseBranchEnvValue(conductorEnabled, baseBranch), platform),
+        // both environment renderings with real spawning. Reuses the same
+        // buildAgentShellCommand/buildAgentPrompt path as a real spawn. A Codex
+        // dry-run has no created worktree to bind, so its preview omits the
+        // process-local -C/-c MCP scope that the real spawn resolves later.
+        buildAgentShellCommand: (key, worktreePath, modelAlias, launchArgs) => prependBaseBranchEnvAssignment(prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, false, workflow, reviewRounds, baseBranch, launchArgs), repoName, platform), resolvePrBaseBranchEnvValue(conductorEnabled, baseBranch), platform),
     };
 }
 /**
@@ -2044,9 +2138,9 @@ export function formatSummaryReport(rows) {
  */
 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),
+        readFile: deps.readFile ?? ((filePath) => readFile(filePath, "utf-8")),
+        writeFile: deps.writeFile ?? ((filePath, data) => writeFile(filePath, data, "utf-8")),
+        mkdir: 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
@@ -2127,7 +2221,9 @@ export function formatModelRoutingDiagnosticLine(d) {
     const repo = d.repoName ?? "<unknown>";
     const target = d.storeTarget ?? (d.repoName ? `bapi:${d.repoName}` : "bapi:<repo>");
     const storePath = d.storePath ?? "~/.config/bridge/credentials.json";
-    const failOpen = "Assuming hard ticket; defaulting to premium/Opus when available.";
+    const failOpen = d.agentName === "codex"
+        ? "Codex continues with its configured default model."
+        : "Assuming hard ticket; defaulting to premium/Opus when available.";
     const ticketSuffix = d.ticketKey ? ` for ${d.ticketKey}` : "";
     const statusSuffix = typeof d.status === "number" ? ` (HTTP ${d.status})` : "";
     switch (d.kind) {
@@ -2165,6 +2261,12 @@ export function formatModelRoutingDiagnosticLine(d) {
         case "no-tier":
             return (`model routing: Bridge API returned no usable tier${ticketSuffix}. Ticket spawning ` +
                 `continues fail-open. ${failOpen}`);
+        case "catalog-unavailable":
+            return `model routing degraded: Codex model catalog unavailable. ${failOpen}`;
+        case "catalog-invalid":
+            return `model routing degraded: Codex model catalog failed validation. ${failOpen}`;
+        case "codex-entitlement-unverified":
+            return "model routing: Bridge permits the selected model; local Codex account entitlement cannot be verified non-interactively.";
         default:
             return `model routing degraded: ${d.message} ${failOpen}`;
     }
@@ -2176,6 +2278,7 @@ export function formatModelRoutingDiagnosticLine(d) {
 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 CODEX_CATALOG_FETCH_TIMEOUT_MS = 15_000;
 const CURSOR_MODEL_LIST_TIMEOUT_MS = 15_000;
 /** GET auth headers for the CLI's Bridge API calls. */
 function startTicketsGetHeaders(access) {
@@ -2388,10 +2491,12 @@ export async function fetchStartTicketsConfigField(access, fieldName) {
  * Any fetch failure returns a structured failure (with a classified diagnostic)
  * so the caller fails open to premium/Opus.
  */
-export async function fetchDifficultyModelRoutingConfig(access) {
+export async function fetchDifficultyModelRoutingConfig(access, includeOverrides = true) {
     try {
         const enabledValue = await fetchStartTicketsConfigField(access, "difficulty_model_routing_enabled");
-        const overridesValue = await fetchStartTicketsConfigField(access, "difficulty_model_tier_overrides");
+        const overridesValue = includeOverrides
+            ? await fetchStartTicketsConfigField(access, "difficulty_model_tier_overrides")
+            : undefined;
         const enabled = enabledValue === false ? false : true;
         return { ok: true, config: { enabled, overrides: normalizeDifficultyModelTierOverrides(overridesValue) } };
     }
@@ -2407,6 +2512,57 @@ export async function fetchDifficultyModelRoutingConfig(access) {
         };
     }
 }
+/** One bounded authenticated fetch; reject partial, unsafe, or stale wire data. */
+export async function fetchCodexModelCatalog(access) {
+    let body;
+    try {
+        const url = buildStartTicketsJiraUrl(access.baseUrl, "/codex-model-catalog", {
+            repo_name: access.repoName,
+        });
+        body = await fetchJsonWithTimeout(url, startTicketsGetHeaders(access), CODEX_CATALOG_FETCH_TIMEOUT_MS);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            warning: "model routing: Codex catalog unavailable; using configured default",
+            diagnostic: {
+                ...diagnosticFromFetchError(err, {
+                    repoName: access.repoName,
+                    fallbackKind: "catalog-unavailable",
+                    message: "Codex model catalog unavailable",
+                }),
+                agentName: "codex",
+            },
+        };
+    }
+    const invalid = () => ({
+        ok: false,
+        warning: "model routing: Codex catalog invalid; using configured default",
+        diagnostic: makeModelRoutingDiagnostic({
+            kind: "catalog-invalid",
+            repoName: access.repoName,
+            agentName: "codex",
+            message: "Codex model catalog failed validation",
+        }),
+    });
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return invalid();
+    const obj = body;
+    if (!obj.models || typeof obj.models !== "object" || Array.isArray(obj.models))
+        return invalid();
+    const models = obj.models;
+    const tiers = ["cheap", "basic", "premium"];
+    if (Object.keys(models).length !== tiers.length)
+        return invalid();
+    if (!tiers.every((tier) => typeof models[tier] === "string" && isValidModelAlias(models[tier]))) {
+        return invalid();
+    }
+    const canonical = tiers.map((tier) => `${tier}=${models[tier]}`).join("\n");
+    const revision = `sha256:${createHash("sha256").update(canonical, "utf8").digest("hex")}`;
+    if (obj.revision !== revision)
+        return invalid();
+    return { ok: true, catalog: { models: models, revision } };
+}
 /**
  * Fetch the coarse tier for one ticket with a bounded timeout. Never throws to
  * the batch orchestrator: failures/timeouts return a structured warning plus a
@@ -2532,6 +2688,24 @@ export function applyDefaultModelRoutingMetadata(row, reason, diagnostic) {
         ...(diagnostic ? { modelRoutingDiagnostic: diagnostic } : {}),
     };
 }
+function resolveRoutingAlias(agent, tier, overrides, catalog) {
+    return agent.name === "codex"
+        ? catalog?.models[tier] ?? null
+        : resolveModelAlias(agent, tier, overrides);
+}
+function codexEntitlementDiagnostic(repoName) {
+    return makeModelRoutingDiagnostic({
+        kind: "codex-entitlement-unverified",
+        agentName: "codex",
+        repoName,
+        message: "Local Codex account entitlement cannot be verified non-interactively",
+    });
+}
+function codexDefaultRows(rows, isEligible, warning, diagnostic) {
+    return rows.map((row) => isEligible(row)
+        ? appendSummaryRowWarning(applyDefaultModelRoutingMetadata(row, warning, diagnostic ? { ...diagnostic, agentName: "codex" } : undefined), warning)
+        : row);
+}
 /**
  * Resolve + validate the premium (Opus) alias ONCE and return a reusable applier.
  *
@@ -2547,12 +2721,14 @@ export function applyDefaultModelRoutingMetadata(row, reason, diagnostic) {
  * (e.g. it doesn't support --model, or verification fails) the applier falls back
  * to the true no-routing default so we never emit an invalid --model.
  */
-async function makePremiumFallbackApplier(deps, agent, overrides) {
-    const alias = resolveModelAlias(agent, "premium", overrides);
+async function makePremiumFallbackApplier(deps, agent, overrides, catalog = null, repoName) {
+    const alias = resolveRoutingAlias(agent, "premium", overrides, catalog);
     const validation = alias ? await validateResolvedModelAliasForAgent(deps, agent, alias) : null;
     return (row, warning, diagnostic) => {
         if (validation && validation.ok) {
-            const reason = `${warning}; defaulting to premium/Opus (model=${validation.alias})`;
+            const reason = agent.name === "codex"
+                ? `${warning}; defaulting to premium (model=${validation.alias})`
+                : `${warning}; defaulting to premium/Opus (model=${validation.alias})`;
             return appendSummaryRowWarning({
                 ...row,
                 difficulty: row.difficulty ?? null,
@@ -2560,7 +2736,11 @@ async function makePremiumFallbackApplier(deps, agent, overrides) {
                 modelAlias: validation.alias,
                 modelRoutingSource: "fallback",
                 modelRoutingReason: reason,
-                ...(diagnostic ? { modelRoutingDiagnostic: diagnostic } : {}),
+                ...(diagnostic
+                    ? { modelRoutingDiagnostic: agent.name === "codex" ? { ...diagnostic, agentName: "codex" } : diagnostic }
+                    : agent.name === "codex" && repoName
+                        ? { modelRoutingDiagnostic: codexEntitlementDiagnostic(repoName) }
+                        : {}),
             }, warning);
         }
         // Premium alias unavailable for this agent — fall back to agent default.
@@ -2591,14 +2771,14 @@ const isDryRunRoutingEligible = (r) => r.status === "dry-run";
  * validated ONCE (identical for every row) so a cursor-agent batch fires at most
  * one advertised-model probe.
  */
-async function applyInjectedTierRoutingToEligibleRows(deps, rows, isEligible, agent, overrides, tier) {
+async function applyInjectedTierRoutingToEligibleRows(deps, rows, isEligible, agent, overrides, tier, catalog = null, repoName) {
     const stampInjected = (row) => ({
         ...row,
         difficulty: null,
         modelTier: tier,
         modelRoutingSource: "injected",
     });
-    const alias = resolveModelAlias(agent, tier, overrides);
+    const alias = resolveRoutingAlias(agent, tier, overrides, catalog);
     if (!alias) {
         const warning = `model routing: no valid alias for injected tier=${tier}; using agent default`;
         return rows.map((r) => isEligible(r)
@@ -2616,15 +2796,17 @@ async function applyInjectedTierRoutingToEligibleRows(deps, rows, isEligible, ag
             ...stampInjected(r),
             modelAlias: validation.alias,
             modelRoutingReason: `injected tier=${tier} model=${validation.alias}`,
+            ...(agent.name === "codex" && repoName
+                ? { modelRoutingDiagnostic: codexEntitlementDiagnostic(repoName) }
+                : {}),
         }
         : r);
 }
 /**
  * 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.
+ * resolved tier/alias. Codex fails open to its configured default with no
+ * `--model`; Claude/Cursor retain their premium fallback. Non-eligible rows
+ * pass through untouched, and routing failures never abort worktree creation.
  */
 async function resolveModelRoutingForEligible(deps, rows, options, agent, isEligible) {
     const eligible = rows.filter(isEligible);
@@ -2636,13 +2818,19 @@ async function resolveModelRoutingForEligible(deps, rows, options, agent, isElig
     }
     const accessResult = await resolveStartTicketsBridgeApiAccess(deps);
     if (!accessResult.ok) {
+        if (agent.name === "codex") {
+            return codexDefaultRows(rows, isEligible, accessResult.warning, accessResult.diagnostic);
+        }
         // Genuine error reaching the backend — default unknown difficulty to premium/Opus,
         // stamping the access diagnostic onto every eligible row.
         return applyPremiumFallbackToEligibleRows(deps, rows, isEligible, agent, null, accessResult.warning, accessResult.diagnostic);
     }
     const access = accessResult.access;
-    const configResult = await fetchDifficultyModelRoutingConfig(access);
+    const configResult = await fetchDifficultyModelRoutingConfig(access, agent.name !== "codex");
     if (!configResult.ok) {
+        if (agent.name === "codex") {
+            return codexDefaultRows(rows, isEligible, configResult.warning, configResult.diagnostic);
+        }
         // Can't read routing config — treat as error and default to premium/Opus.
         return applyPremiumFallbackToEligibleRows(deps, rows, isEligible, agent, null, configResult.warning, configResult.diagnostic);
     }
@@ -2651,6 +2839,14 @@ async function resolveModelRoutingForEligible(deps, rows, options, agent, isElig
         const reason = "model routing: disabled for this repo; using agent default";
         return rows.map((r) => (isEligible(r) ? applyDefaultModelRoutingMetadata(r, reason) : r));
     }
+    let catalog = null;
+    if (agent.name === "codex") {
+        const result = await fetchCodexModelCatalog(access);
+        if (!result.ok) {
+            return codexDefaultRows(rows, isEligible, result.warning, result.diagnostic);
+        }
+        catalog = result.catalog;
+    }
     // BAPI-642: an explicitly injected `--tier` short-circuits the per-ticket
     // difficulty/tier lookup — `fetchTicketModelTiersForRows` is NEVER called for
     // any injected value. A recognized tier is applied to every eligible row; a
@@ -2660,11 +2856,11 @@ async function resolveModelRoutingForEligible(deps, rows, options, agent, isElig
     const injected = options.injectedTier;
     if (injected === INJECTED_TIER_UNRESOLVED) {
         const warning = "model routing: --tier was not one of cheap|basic|premium; defaulting to premium routing";
-        const apply = await makePremiumFallbackApplier(deps, agent, overrides);
+        const apply = await makePremiumFallbackApplier(deps, agent, overrides, catalog, access.repoName);
         return rows.map((r) => (isEligible(r) ? apply(r, warning) : r));
     }
     if (injected) {
-        return applyInjectedTierRoutingToEligibleRows(deps, rows, isEligible, agent, overrides, injected);
+        return applyInjectedTierRoutingToEligibleRows(deps, rows, isEligible, agent, overrides, injected, catalog, access.repoName);
     }
     const tierMap = await fetchTicketModelTiersForRows(access, eligible, options.maxParallel, isEligible);
     // Lazily resolve+validate the premium fallback alias at most once for this run
@@ -2672,7 +2868,7 @@ async function resolveModelRoutingForEligible(deps, rows, options, agent, isElig
     let premiumApplier = null;
     const applyPremiumFallback = async (row, warning, diagnostic) => {
         if (!premiumApplier)
-            premiumApplier = await makePremiumFallbackApplier(deps, agent, overrides);
+            premiumApplier = await makePremiumFallbackApplier(deps, agent, overrides, catalog, access.repoName);
         return premiumApplier(row, warning, diagnostic);
     };
     const out = [];
@@ -2697,6 +2893,10 @@ async function resolveModelRoutingForEligible(deps, rows, options, agent, isElig
                     ticketKey: row.key,
                     message: `no tier resolved for ${row.key}`,
                 });
+            if (agent.name === "codex") {
+                out.push(codexDefaultRows([row], () => true, warning, diagnostic)[0]);
+                continue;
+            }
             out.push(await applyPremiumFallback(row, warning, diagnostic));
             continue;
         }
@@ -2718,10 +2918,14 @@ async function resolveModelRoutingForEligible(deps, rows, options, agent, isElig
                 ticketKey: row.key,
                 message: `${row.key} resolved no tier (source=${source})`,
             });
+            if (agent.name === "codex") {
+                out.push(codexDefaultRows([baseRow], () => true, warning, diagnostic)[0]);
+                continue;
+            }
             out.push(await applyPremiumFallback(baseRow, warning, diagnostic));
             continue;
         }
-        const alias = resolveModelAlias(agent, tier, overrides);
+        const alias = resolveRoutingAlias(agent, tier, overrides, catalog);
         if (!alias) {
             const warning = `model routing: no valid alias for tier=${tier}; using agent default`;
             out.push(appendSummaryRowWarning({ ...baseRow, modelAlias: null, modelRoutingReason: warning }, warning));
@@ -2736,6 +2940,9 @@ async function resolveModelRoutingForEligible(deps, rows, options, agent, isElig
             ...baseRow,
             modelAlias: validation.alias,
             modelRoutingReason: `tier=${tier} model=${validation.alias} (source=${source})`,
+            ...(agent.name === "codex"
+                ? { modelRoutingDiagnostic: codexEntitlementDiagnostic(access.repoName) }
+                : {}),
         });
     }
     return out;
@@ -2978,7 +3185,7 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     if (!agent) {
         return {
             ok: false,
-            error: `Unknown agent: '${options.agentName}'. Valid agents: ${formatValidAgentNames()}.`,
+            error: `Unknown agent: '${options.agentName}'. Launchable agents: ${formatStartTicketsAgentNames()}.`,
         };
     }
     const preflight = await runPreflight(deps, options, overrides.liveSourceWarningLog);
@@ -3052,7 +3259,7 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     await emitClaudeReviewWorkflowDriftAdvisory(deps, options.baseBranch, overrides);
     const createWorktreesFn = overrides.createWorktrees ?? createWorktrees;
     const provisionCommandsFn = overrides.provisionCommands ??
-        ((rows, d) => provisionCommandsForCreatedWorktrees(rows, buildCommandProvisioningDeps(d)));
+        ((rows, d) => provisionCommandsForCreatedWorktrees(rows, buildCommandProvisioningDeps(d), agent.name === "codex"));
     const provisionFn = overrides.provisionMcpRegistrations ??
         ((rows, d) => provisionMcpRegistrationsForCreatedWorktrees(rows, buildMcpProvisioningDeps(d)));
     const materializeFn = overrides.materializeFileCredentials ?? materializeFileCredentialsForCreatedWorktrees;
@@ -3166,7 +3373,18 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     // BAPI-844: stamp the validated scope on the spawnable rows immediately before
     // the spawn, so the value the tab is launched with is the one this run
     // declared. A run with no scope gets the identical `routed` array back.
-    const scoped = stampIndexScopeOnRows(routed, indexScope);
+    let scoped = stampIndexScopeOnRows(routed, indexScope);
+    if (agent.name === "codex") {
+        const mcpDeps = buildMcpProvisioningDeps(deps);
+        scoped = await Promise.all(scoped.map(async (row) => {
+            if (row.status !== "created" || !row.path)
+                return row;
+            const scope = await (overrides.resolveCodexScope ?? resolveCodexLaunchScope)(row.path, mcpDeps);
+            return scope.ok
+                ? { ...row, codexLaunchArgs: scope.argv }
+                : { ...row, status: "spawn-failed", error: scope.error };
+        }));
+    }
     const rows = await spawnTabsFn(deps, scoped, terminal, platformConfig.config.buildAgentShellCommand);
     return { ok: true, rows };
 }
@@ -3215,7 +3433,7 @@ export async function runStartTicketsCli(argv, overrides = {}) {
     // is defensive only.
     const agent = resolveAgentSpec(options.agentName);
     if (!agent) {
-        errorLog(`Error: Unknown agent: '${options.agentName}'. Valid agents: ${formatValidAgentNames()}.`);
+        errorLog(`Error: Unknown agent: '${options.agentName}'. Launchable agents: ${formatStartTicketsAgentNames()}.`);
         return 1;
     }
     // BAPI-642: a malformed `--tier` value is fail-open — emit ONE concise,

package/build/version.generated.js

@@ -1,4 +1,4 @@
 // AUTO-GENERATED — do not edit manually. Regenerate with: npm run build
-export const VERSION = "0.2.54";
-export const BUILD_COMMIT = "7b8210791648";
-export const LAUNCHER_ARGS = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.54", "serve"];
+export const VERSION = "0.2.56";
+export const BUILD_COMMIT = "ba95aad09dd4";
+export const LAUNCHER_ARGS = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.56", "serve"];