@bridge_gpt/mcp-server 0.2.55 → 0.2.57

package/README.md

@@ -242,6 +242,20 @@ npx -y @bridge_gpt/mcp-server doctor
 `doctor` is strictly read-only. It reports what it found — configs, registrations,
 credential availability, prerequisites — and changes nothing.
 
+**Codex approval profile.** When selecting Codex during `install`, opt in at the
+prompt or pass `--tools=codex --codex-profile=on` in a scripted install. Bridge
+creates `$CODEX_HOME/bridge.config.toml` (default `~/.codex/bridge.config.toml`)
+with approval settings for the tools used by its review and implementation
+workflows. Bridge-spawned Codex workers then select it automatically, including
+the fresh implementation session after review. Pass `--codex-profile=off` to
+decline; the installer leaves any existing profile content intact. If a profile
+already contains user-authored or conflicting content, the installer leaves it
+untouched and reports that workers cannot use it. Run `doctor --agent codex` to
+inspect the current status. To use the profile in a Codex session you open
+yourself, run `codex --profile bridge`. Bridge `--auto` controls recipe gates;
+Codex MCP tool approvals are a separate setting. The profile does not change
+global `sandbox_mode` or `approval_policy`.
+
 </details>
 
 <details>
@@ -351,7 +365,7 @@ later boot.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.55", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.57", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -373,7 +387,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.55", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.57", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -395,7 +409,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.55", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.57", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -418,7 +432,7 @@ Windsurf only supports global MCP configuration.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.55", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.57", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -437,7 +451,7 @@ Windsurf only supports global MCP configuration.
 ```toml
 [mcp_servers.bridge]
 command = "npx"
-args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.55", "serve"]
+args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.57", "serve"]
 
 [mcp_servers.bridge.env]
 BAPI_BASE_URL = "https://bridgegpt-api.com"
@@ -985,9 +999,9 @@ npx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]
 | Flag | Default | Meaning |
 |---|---|---|
 | `--agent claude\|cursor-agent` | `claude` | Agent command to launch in each worktree |
-| `--workflow implement\|review-and-implement` | `implement` | Slash command each spawned worktree runs. `implement` is byte-identical to today's `/implement-ticket <KEY> [--auto]`. `review-and-implement` spawns `/review-and-implement <KEY> [--auto] [--rounds=<n>]`, which runs `/review-ticket` then, after a per-ticket halt gate, `/implement-ticket` in the same session. `--auto` applies to the selected workflow as a whole. |
+| `--workflow implement\|review-and-implement` | `implement` | Slash command each spawned worktree runs. `review-and-implement` reviews the ticket, then hands approval to a fresh implementation session in the same worktree. `--auto` applies to both phases. |
 | `--rounds 1\|2` | unset | Review round count forwarded to the review phase. Review-only — valid only with `--workflow review-and-implement`. |
-| `--tier cheap\|basic\|premium` | unset (difficulty routing) | Coarse model-routing override. Bypasses **only** the per-ticket difficulty/tier lookup (`GET /jira/tickets/{KEY}/model-tier`) and applies this one tier to every ticket; the tier is still mapped to a model through the centralized 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. Used by the `/review-and-implement` handoff to reuse the review-time tier. |
+| `--tier cheap\|basic\|premium` | unset (difficulty routing) | Coarse model-routing override. Bypasses **only** the per-ticket difficulty/tier lookup (`GET /jira/tickets/{KEY}/model-tier`) and applies this one tier to every ticket; Claude/Cursor use their registry aliases and repository overrides, while Codex uses the authenticated Bridge catalog. It is **not** a raw `--model` alias and never carries an API key or credential. A malformed value fails open to premium routing when its alias is available. Used by the `/review-and-implement` handoff to reuse the review-time tier. |
 | `--terminal terminal\|iterm` | auto-detect via `$TERM_PROGRAM` | Override the macOS terminal app (honored on macOS only) |
 | `--dry-run` | off | Print intended actions; create no worktrees, open no tabs (any OS) |
 | `--branch KEY=BRANCH` | `feature/<KEY>` | Use a custom branch for that ticket (repeatable) |
@@ -997,15 +1011,17 @@ npx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]
 | `--conductor` | off | Opt into the Conductor system (per-worker `BAPI_CONDUCTOR_*` env + Claude hook injection, lifecycle ledger events, and a supervisor peer tab). **Default off** — a plain run spawns `cd <worktree> && <agent> '/implement-ticket <KEY>'`. |
 | `-h`, `--help` | — | Show usage |
 
-Each `KEY` must match `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). The CLI creates/switches each worktree up front (throttled by `--max-parallel`), then opens one tab/session per successful worktree running the selected agent's `'/implement-ticket <KEY>'` — `claude '/implement-ticket <KEY>'` by default, or `cursor-agent '/implement-ticket <KEY>'` with `--agent cursor-agent`. The `/implement-ticket <KEY>` prompt is unchanged for both agents. To launch Cursor Agent instead of Claude Code:
+Each `KEY` must match `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). The CLI creates/switches each worktree up front (throttled by `--max-parallel`), then opens one tab/session per successful worktree running the selected agent. Claude is the default. Cursor with `--auto` runs headlessly after a bounded authentication/readiness check; manual Cursor runs remain interactive for human review gates. To launch Cursor Agent instead of Claude Code:
 
 ```
 npx -y @bridge_gpt/mcp-server start-tickets --agent cursor-agent BAPI-248
 ```
 
-**Difficulty-based model routing.** Before launching each agent, the CLI selects an implementation **model tier** from the ticket's `difficulty` (1-2 → cheap, 3-6 → basic, 7-10 → premium) and injects it as a `--model` flag at the spawn boundary. The Python backend returns only the coarse tier (`GET /jira/tickets/{KEY}/model-tier`, computing + caching difficulty on demand); this CLI alone maps a tier to the agent-specific alias (`claude`: `haiku`/`sonnet`/`opus`; `cursor-agent`: version-suffixed strings validated against `cursor-agent --list-models`). It is gated per repo by `difficulty_model_routing_enabled` (default **ON**) with an optional `difficulty_model_tier_overrides` JSON map (tier → alias). Routing is **fail-open**: missing credentials, an evaluation failure/timeout, a backend `fallback`, an invalid/unavailable alias, an unadvertised Cursor model, or an agent without `--model` support all default to the **premium** (Opus) model — and when even the premium alias cannot be resolved/validated for the agent, `--model` is omitted (the agent uses its default) — each surfaced as a per-ticket warning rather than failing the spawn. `--dry-run` does **not** create worktrees or open tabs, but it **does** resolve routing read-only to preview the `--model` each tab would use.
+**Difficulty-based model routing.** Before launching each agent, the CLI selects an implementation **model tier** from the ticket's `difficulty` (1-2 → cheap, 3-6 → basic, 7-10 → premium) and may inject `--model` at the spawn boundary. The Python backend returns only the coarse tier (`GET /jira/tickets/{KEY}/model-tier`, computing + caching difficulty on demand). Claude and Cursor map that tier through their agent registry aliases; Cursor validates against `cursor-agent --list-models`. Routing is gated per repo by `difficulty_model_routing_enabled` (default **ON**). Claude/Cursor may use `difficulty_model_tier_overrides` (tier → alias) and retain their premium fallback behavior on an unknown tier or transient failure. When an alias cannot be validated, the CLI omits `--model` and launches the agent default. `--dry-run` resolves routing read-only to preview the command without creating worktrees or opening tabs.
+
+For Codex, `GET /jira/codex-model-catalog?repo_name=...` is the sole tier-to-model authority. Bridge derives its three bare CLI IDs and SHA-256 mapping revision at request time from `MODEL_REGISTRY`; the launcher fetches and validates that catalog once per invocation. Repository `difficulty_model_tier_overrides` do not apply to Codex. A failed access, config, tier, catalog, revision, or alias check omits `--model` and launches the configured Codex default. The catalog expresses **Bridge provider policy only**: it cannot confirm that the local Codex login or subscription can use a model. The CLI has no supported non-interactive entitlement probe, so routing emits that limitation as a diagnostic and never uses Bridge's OpenAI API key as proof of local access.
 
-**Coarse `--tier` override.** Passing `--tier cheap|basic|premium` bypasses **only** the per-ticket difficulty lookup above and applies that one tier to every ticket; the tier is still resolved to an alias through the same agent registry + `difficulty_model_tier_overrides` and validated the same way (including the live `cursor-agent --list-models` check). It is never treated as a raw `--model` alias, and no API key or credential belongs in the spawned command (the CLI resolves credentials itself via `resolveBapiCredentials`). A malformed/unrecognized `--tier` value is **fail-open**: the CLI logs one concise warning and routes every ticket on the premium (Opus) fallback rather than aborting. `/review-and-implement` uses this flag to hand its review-time tier snapshot to the fresh implementation session.
+**Coarse `--tier` override.** Passing `--tier cheap|basic|premium` bypasses only the per-ticket difficulty lookup and applies that tier to every ticket. Claude/Cursor use the same alias resolution as normal routing; Codex uses the fetched catalog. It is never a raw model alias, and no API key or credential belongs in the spawned command. A malformed tier requests the premium fallback when its alias is available; otherwise the agent default launches. `/review-and-implement` uses this flag to hand its review-time tier snapshot to the fresh implementation session.
 
 **Conductor observability (opt-in via `--conductor`, BAPI-394).** Conductor is **off by default**. With `--conductor`, a run mints a conductor `run_id`, emits events into the local ledger (`~/.config/bridge/events.db`), opens a supervisor peer tab, and (for Claude Code) injects a secret-free lifecycle hook into each worktree; it also sets `BRIDGE_MCP_PROFILE=conductor` so workers get the conductor MCP tools. Observability is best-effort — a conductor failure never blocks a spawn, and `--dry-run` performs no conductor side effects. (Epic-tick dispatch always enables conductor internally.) See **[CONDUCTOR.md](./docs/CONDUCTOR.md)** for the full observability, git-hook, done-gate, and auto-merge reference.
 

package/build/agent-capabilities/types.js

@@ -5,6 +5,10 @@ export const AGENT_AUTH = {
         note: "Claude Code authenticates via keychain/OAuth — cannot be verified from the environment.",
     },
     "cursor-agent": { kind: "env", varName: "CURSOR_API_KEY" },
+    codex: {
+        kind: "interactive",
+        note: "Codex authenticates via login/OAuth — cannot be verified from the environment.",
+    },
 };
 /** Default hard timeout per headless probe run (ms). The cursor `-p` hang bug is version-sensitive. */
 export const DEFAULT_PROBE_TIMEOUT_MS = 90_000;

package/build/agent-registry.js

@@ -26,7 +26,7 @@ export function isModelTier(value) {
 }
 /**
  * The registry: the ONLY place mapping an agent name to its command/spec. Seeded
- * with exactly `claude` (default) and `cursor-agent`. `as const satisfies` keeps
+ * with `claude` (default), `cursor-agent`, and `codex`. `as const satisfies` keeps
  * the literal keys (so `AgentName` is a precise union) while type-checking each
  * value against `AgentSpec`.
  */
@@ -108,6 +108,20 @@ export const AGENT_REGISTRY = {
             premium: "claude-opus-4-8-thinking-high",
         },
     },
+    codex: {
+        name: "codex",
+        command: "codex",
+        promptArgStyle: "positional",
+        installHint: {
+            darwin: "npm install -g @openai/codex",
+            linux: "npm install -g @openai/codex",
+            win32: "npm install -g @openai/codex",
+        },
+        authNote: "Codex authenticates interactively on first run — follow its login prompt if asked.",
+        // The launch boundary validates a fresh Bridge catalog before injection.
+        supportsModelOverride: true,
+        modelFlag: "--model",
+    },
 };
 /** The default agent used when `--agent` is omitted. */
 export const DEFAULT_AGENT_NAME = "claude";
@@ -130,7 +144,7 @@ export function resolveAgentSpec(name) {
         return null;
     return AGENT_REGISTRY[resolved];
 }
-/** Comma-delimited valid agent names for CLI validation errors (`claude, cursor-agent`). */
+/** Comma-delimited registry names for CLI validation errors (`claude, cursor-agent, codex`). */
 export function formatValidAgentNames() {
     return listAgentNames().join(", ");
 }
@@ -154,10 +168,13 @@ export function resolveModelAlias(agent, tier, overrides) {
         return null;
     if (!tier)
         return null;
+    // Codex has no static or repository-override model authority.
+    if (agent.name === "codex")
+        return null;
     const override = overrides?.[tier];
     const candidate = typeof override === "string" && override.trim().length > 0
         ? override.trim()
-        : agent.tierModels[tier];
+        : agent.tierModels?.[tier];
     if (typeof candidate !== "string" || !isValidModelAlias(candidate))
         return null;
     if (agent.staticModelAliasAllowlist && !agent.staticModelAliasAllowlist.includes(candidate)) {

package/build/codex-bridge-profile.js

@@ -0,0 +1,151 @@
+/** Secret-free, opt-in approval settings for Bridge-spawned Codex workers. */
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { codexBridgeTableNames } from "./mcp-host-config.js";
+import { MCP_SERVER_NAME } from "./mcp-identity.js";
+export { codexHome } from "./codex-home.js";
+export const BRIDGE_CODEX_PROFILE = "bridge";
+const PROFILE_FILE = "bridge.config.toml";
+const STATE_FILE = "bridge.profile-state.json";
+const MARKER = "# Bridge-managed Codex approval profile (BAPI-1214)";
+/** Tools called by review-and-start, review-and-implement, and implement-ticket. */
+export const BRIDGE_WORKFLOW_TOOLS = [
+    "ping", "get_ticket", "get_pipeline_recipe", "request_ticket_review",
+    "wait_for_ticket_review", "fresh_base", "generate_decision_page",
+    "capture_review_decisions", "request_plan_generation", "get_plan",
+    "get_phase_context", "record_phase_result", "create_pull_request",
+    "update_jira_status", "config_field", "resolve_ci_checks", "poll_ci_checks",
+    "wait_for_ci_checks",
+];
+export function codexProfilePaths(home) {
+    return {
+        profile: path.join(home, PROFILE_FILE),
+        state: path.join(home, STATE_FILE),
+        config: path.join(home, "config.toml"),
+    };
+}
+export function renderBridgeCodexProfile(key) {
+    return [
+        MARKER,
+        `# Applies only when selected with codex --profile ${BRIDGE_CODEX_PROFILE}.`,
+        ...BRIDGE_WORKFLOW_TOOLS.flatMap((tool) => [
+            `[mcp_servers.${key}.tools.${tool}]`,
+            'approval_mode = "auto"',
+            "",
+        ]),
+    ].join("\n") + "\n";
+}
+function fingerprint(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+async function optionalRead(readFile, filePath) {
+    try {
+        return await readFile(filePath);
+    }
+    catch (error) {
+        return error.code === "ENOENT" ? null : undefined;
+    }
+}
+/** Only a matching managed file and explicit enabled state can activate workers. */
+export async function inspectBridgeCodexProfile(home, readFile) {
+    const paths = codexProfilePaths(home);
+    const [config, profile, state] = await Promise.all([
+        optionalRead(readFile, paths.config),
+        optionalRead(readFile, paths.profile),
+        optionalRead(readFile, paths.state),
+    ]);
+    if (config === undefined || profile === undefined || state === undefined)
+        return { status: "unreadable" };
+    const names = codexBridgeTableNames(config ?? "");
+    if (names.length > 1)
+        return { status: "conflict" };
+    const key = names[0] ?? MCP_SERVER_NAME;
+    if (state === null)
+        return { status: profile === null ? "missing" : "conflict", key };
+    let parsed;
+    try {
+        parsed = JSON.parse(state);
+    }
+    catch {
+        return { status: "conflict", key };
+    }
+    if (!parsed || typeof parsed !== "object" || !("enabled" in parsed) || typeof parsed.enabled !== "boolean") {
+        return { status: "conflict", key };
+    }
+    if (!parsed.enabled)
+        return { status: "declined", key };
+    if (profile === null || !("hash" in parsed) || typeof parsed.hash !== "string")
+        return { status: "conflict", key };
+    if (profile !== renderBridgeCodexProfile(key) || fingerprint(profile) !== parsed.hash)
+        return { status: "conflict", key };
+    return { status: "active", key };
+}
+export async function configureBridgeCodexProfile(home, choice, deps) {
+    const paths = codexProfilePaths(home);
+    const current = await inspectBridgeCodexProfile(home, deps.readFile);
+    if (choice === "decline") {
+        const oldState = await optionalRead(deps.readFile, paths.state);
+        if (oldState === undefined)
+            return { status: "unreadable" };
+        let existingHash;
+        if (oldState !== null) {
+            try {
+                const parsed = JSON.parse(oldState);
+                if (!parsed || typeof parsed.enabled !== "boolean")
+                    return { status: "conflict" };
+                if (typeof parsed.hash === "string")
+                    existingHash = parsed.hash;
+            }
+            catch {
+                return { status: "conflict" };
+            }
+        }
+        await deps.mkdir(home, { recursive: true });
+        await deps.writeFile(paths.state, JSON.stringify({ enabled: false, ...(existingHash ? { hash: existingHash } : {}) }) + "\n");
+        return { status: "declined", key: current.key };
+    }
+    if (current.status === "unreadable")
+        return current;
+    const config = await optionalRead(deps.readFile, paths.config);
+    if (config === undefined)
+        return { status: "unreadable" };
+    const names = codexBridgeTableNames(config ?? "");
+    if (names.length > 1)
+        return { status: "conflict" };
+    const key = names[0] ?? MCP_SERVER_NAME;
+    const existing = await optionalRead(deps.readFile, paths.profile);
+    const oldState = await optionalRead(deps.readFile, paths.state);
+    const desired = renderBridgeCodexProfile(key);
+    if (existing === undefined || oldState === undefined)
+        return { status: "unreadable", key };
+    if (oldState !== null) {
+        try {
+            const parsed = JSON.parse(oldState);
+            if (!parsed || typeof parsed.enabled !== "boolean" ||
+                (parsed.enabled && (typeof parsed.hash !== "string" || existing === null || parsed.hash !== fingerprint(existing)))) {
+                return { status: "conflict", key };
+            }
+        }
+        catch {
+            return { status: "conflict", key };
+        }
+    }
+    // Existing user content is never modified or implicitly adopted.
+    if (existing !== null && existing !== desired) {
+        let managed = false;
+        if (oldState !== null && existing.startsWith(MARKER)) {
+            try {
+                const parsed = JSON.parse(oldState);
+                managed = typeof parsed?.enabled === "boolean" && parsed?.hash === fingerprint(existing);
+            }
+            catch { /* malformed state cannot authorize a rewrite */ }
+        }
+        if (!managed)
+            return { status: "conflict", key };
+    }
+    await deps.mkdir(home, { recursive: true });
+    if (existing !== desired)
+        await deps.writeFile(paths.profile, desired);
+    await deps.writeFile(paths.state, JSON.stringify({ enabled: true, hash: fingerprint(desired) }) + "\n");
+    return { status: "active", key };
+}

package/build/codex-home.js

@@ -0,0 +1,7 @@
+import path from "node:path";
+import os from "node:os";
+/** Codex's user config root; only an absolute CODEX_HOME is accepted. */
+export function codexHome(env, homedir = os.homedir()) {
+    const override = env.CODEX_HOME?.trim();
+    return override && path.isAbsolute(override) ? override : path.join(homedir, ".codex");
+}

package/build/codex-launch-scope.js

@@ -0,0 +1,54 @@
+/** Per-process Codex MCP scope, derived from the same manifest and shim as worktree provisioning. */
+import { readBridgeConfig } from "./bridge-config.js";
+import { codexBridgeTableNames } from "./mcp-host-config.js";
+import { codexHome } from "./codex-home.js";
+import { codexProfilePaths, inspectBridgeCodexProfile, BRIDGE_CODEX_PROFILE } from "./codex-bridge-profile.js";
+import { buildMcpServerEntriesForManifest, normalizeWorktreePathForRegistration, } from "./mcp-provisioning.js";
+import { MCP_SERVER_NAME } from "./mcp-identity.js";
+/** A missing Bridge target is a launch failure, never a fallback to user-scoped config. */
+export async function resolveCodexLaunchScope(root, deps, codexConfigPath = codexProfilePaths(codexHome(deps.env ?? process.env, deps.homedir?.())).config) {
+    const normalized = normalizeWorktreePathForRegistration(root, deps);
+    if (!normalized.ok)
+        return { ok: false, error: "Codex MCP scope unavailable: invalid repository path." };
+    let manifest;
+    try {
+        const read = await readBridgeConfig(normalized.path, { readFile: deps.readFile });
+        if (!read.ok)
+            return { ok: false, error: "Codex MCP scope unavailable: .bridge/config is missing or invalid." };
+        manifest = read.manifest;
+    }
+    catch {
+        return { ok: false, error: "Codex MCP scope unavailable: could not read .bridge/config." };
+    }
+    const built = buildMcpServerEntriesForManifest(manifest, normalized.path, deps.mcpServerInvocation, deps.bridgeApiBaseUrl);
+    const bridge = built.entries[MCP_SERVER_NAME];
+    if (!bridge)
+        return { ok: false, error: "Codex MCP scope unavailable: .bridge/config has no Bridge target." };
+    let existingConfig = "";
+    try {
+        existingConfig = await deps.readFile(codexConfigPath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            return { ok: false, error: "Codex MCP scope unavailable: could not inspect Codex host config." };
+        }
+    }
+    const registeredNames = codexBridgeTableNames(existingConfig);
+    if (registeredNames.length > 1) {
+        return { ok: false, error: "Codex MCP scope unavailable: duplicate Bridge registrations in Codex host config." };
+    }
+    const bridgeKey = registeredNames[0] ?? MCP_SERVER_NAME;
+    const home = codexHome(deps.env ?? process.env, deps.homedir?.());
+    const profile = await inspectBridgeCodexProfile(home, deps.readFile);
+    const argv = ["-C", normalized.path];
+    if (profile.status === "active" && profile.key === bridgeKey)
+        argv.push("--profile", BRIDGE_CODEX_PROFILE);
+    for (const [name, entry] of Object.entries(built.entries)) {
+        const key = name === MCP_SERVER_NAME ? bridgeKey : name;
+        // Field-level overrides retain the profile's mcp_servers.<key>.tools policy.
+        argv.push("-c", `mcp_servers.${key}.command=${JSON.stringify(entry.command)}`);
+        argv.push("-c", `mcp_servers.${key}.args=${JSON.stringify(entry.args)}`);
+        argv.push("-c", `mcp_servers.${key}.enabled=true`);
+    }
+    return { ok: true, argv };
+}

package/build/codex-skill-adapter.js

@@ -4,8 +4,8 @@
  * Codex discovers repository-local skills from `.agents/skills/<name>/SKILL.md`.
  * Bridge command sources use a standalone `$ARGUMENTS` marker, which is a
  * Claude/Cursor command convention rather than a Codex input variable. This
- * adapter replaces only that marker with the documented explicit-skill input
- * contract while retaining every other byte of the canonical workflow.
+ * adapter replaces that marker with the explicit-skill input contract and
+ * translates references to shipped slash commands into Codex skill names.
  */
 export const CODEX_SKILLS_DIR = ".agents/skills";
 function commandStem(filename) {
@@ -19,7 +19,7 @@ export function codexSkillNameForCommand(filename) {
     return `bridge-${commandStem(filename)}`;
 }
 /** Render the one Codex-native skill artifact for a canonical command. */
-export function renderCodexSkill(filename, command) {
+export function renderCodexSkill(filename, command, knownCommands = [commandStem(filename)]) {
     const stem = commandStem(filename);
     const skillName = codexSkillNameForCommand(filename);
     const invocation = `$${skillName}`;
@@ -28,10 +28,12 @@ export function renderCodexSkill(filename, command) {
         `Treat the text after \`${invocation}\` in the user's message as this workflow's input.`,
         "If no input follows the invocation, follow the canonical workflow's existing usage/error behavior.",
     ].join("\n");
+    const commandPattern = new RegExp(`(?<![A-Za-z0-9_./-])/(${knownCommands.join("|")})(?=[^A-Za-z0-9-]|$)`, "g");
     const adaptedCommand = command
         .split("\n")
         .map((line) => (line.trim() === "$ARGUMENTS" ? inputContract : line))
-        .join("\n");
+        .join("\n")
+        .replace(commandPattern, (_match, name) => `$bridge-${name}`);
     return {
         skillName,
         relativePath: `${CODEX_SKILLS_DIR}/${skillName}/SKILL.md`,
@@ -49,7 +51,8 @@ export function renderCodexSkill(filename, command) {
 }
 /** Build the complete, deterministically ordered Codex skill bundle. */
 export function codexSkillAssets(commands) {
+    const names = Object.keys(commands).map(commandStem).sort((a, b) => b.length - a.length);
     return Object.entries(commands)
         .sort(([left], [right]) => left.localeCompare(right))
-        .map(([filename, command]) => renderCodexSkill(filename, command));
+        .map(([filename, command]) => renderCodexSkill(filename, command, names));
 }

package/build/command-host.js

@@ -0,0 +1,9 @@
+/** Specialize the shared front-door command for a known installation host. */
+export function renderCommandForHost(filename, content, host) {
+    if (filename !== "review-and-start.md" || host !== "cursor")
+        return content;
+    const marker = "**Command host default: none.**";
+    if (!content.includes(marker))
+        throw new Error("review-and-start host default marker is missing");
+    return content.replace(marker, "**Command host default: cursor.**");
+}

package/build/command-provisioning.js

@@ -26,9 +26,11 @@
  */
 import path from "path";
 import { COMMANDS } from "./commands.generated.js";
+import { codexSkillAssets } from "./codex-skill-adapter.js";
 import { ensureGitInfoExcluded } from "./git-ignore-utils.js";
 /** The exact exclude entry appended for the command directory (POSIX-relative). */
 const COMMAND_DIR_EXCLUDE_ENTRY = ".claude/commands/";
+const CODEX_SKILLS_EXCLUDE_ENTRY = ".agents/skills/";
 /** Bounded, secret-free error surfaced when the packaged bundle is empty. */
 const EMPTY_BUNDLE_ERROR = "Command provisioning failed: the packaged command bundle is empty — reinstall or rebuild the MCP server package.";
 /**
@@ -51,7 +53,7 @@ function isEnoentError(err) {
  * for an expected filesystem/Git failure, and never leaks raw exception text,
  * command output, or file contents.
  */
-export async function provisionCommandsForWorktree(worktreeRoot, deps) {
+export async function provisionCommandsForWorktree(worktreeRoot, deps, includeCodexSkills = false) {
     const api = pathApiForCommandProvisioningPlatform(deps.platform);
     const normalizedRoot = api.isAbsolute(worktreeRoot)
         ? api.normalize(worktreeRoot)
@@ -97,6 +99,26 @@ export async function provisionCommandsForWorktree(worktreeRoot, deps) {
                 "Command provisioning failed: could not write one or more packaged command assets.";
         }
     }
+    // Codex launch requires the full bundle. Fill only, preserving customer assets.
+    if (!fillError && includeCodexSkills) {
+        try {
+            for (const asset of codexSkillAssets(COMMANDS)) {
+                const target = api.join(normalizedRoot, asset.relativePath);
+                try {
+                    await deps.readFile(target);
+                }
+                catch (err) {
+                    if (!isEnoentError(err))
+                        throw err;
+                    await deps.mkdir(api.dirname(target), { recursive: true });
+                    await deps.writeFile(target, asset.content);
+                }
+            }
+        }
+        catch {
+            fillError = "Command provisioning failed: could not write one or more Codex skill assets.";
+        }
+    }
     // Phase 3 — ALWAYS attempt exclusion, even after a partial or failed fill, so
     // partially bootstrapped files are never left visible to Git. The primary fill
     // failure is preserved if both the fill and the exclusion fail.
@@ -109,10 +131,19 @@ export async function provisionCommandsForWorktree(worktreeRoot, deps) {
             runCommand: deps.runCommand,
             platform: deps.platform,
         });
+        if (includeCodexSkills) {
+            await ensureGitInfoExcluded(normalizedRoot, CODEX_SKILLS_EXCLUDE_ENTRY, {
+                readFile: deps.readFile,
+                writeFile: deps.writeFile,
+                mkdir: deps.mkdir,
+                runCommand: deps.runCommand,
+                platform: deps.platform,
+            });
+        }
     }
     catch {
         excludeError =
-            "Command provisioning failed: could not add '.claude/commands/' to the worktree Git exclude file.";
+            "Command provisioning failed: could not add generated command assets to the worktree Git exclude file.";
     }
     if (fillError)
         return { ok: false, error: fillError };
@@ -129,7 +160,7 @@ export async function provisionCommandsForWorktree(worktreeRoot, deps) {
  * proceed. A defensive per-row catch guarantees one unexpected failure cannot
  * abort later rows or reject the overall call.
  */
-export async function provisionCommandsForCreatedWorktrees(rows, deps) {
+export async function provisionCommandsForCreatedWorktrees(rows, deps, includeCodexSkills = false) {
     const out = [];
     for (const row of rows) {
         if (row.status !== "created" || !row.path) {
@@ -137,7 +168,7 @@ export async function provisionCommandsForCreatedWorktrees(rows, deps) {
             continue;
         }
         try {
-            const result = await provisionCommandsForWorktree(row.path, deps);
+            const result = await provisionCommandsForWorktree(row.path, deps, includeCodexSkills);
             if (result.ok) {
                 out.push(row);
             }