@bridge_gpt/mcp-server 0.2.54 → 0.2.56

package/README.md

@@ -32,8 +32,7 @@ account — it will ask.
   `--api-key` or `BAPI_API_KEY` — the installer writes that store, it does not read
   it back.
 - Writes outside your project root only when you pick a host whose configuration is
-  global: OpenAI Codex (`~/.codex/config.toml`) and GitHub Copilot CLI
-  (`~/.copilot/mcp-config.json`).
+  global: OpenAI Codex (`~/.codex/config.toml`).
 
 **Prerequisites**
 
@@ -41,8 +40,8 @@ account — it will ask.
 - **A project directory** — run the command from the folder your editor opens: your
   repository root, the one containing `.git`. No `package.json` is required — SFCC
   cartridge repos, Python, Go, Rust, and other non-Node projects work the same way.
-- **An MCP-capable editor or CLI**: Claude Code, GitHub Copilot in VS Code, GitHub
-  Copilot CLI, Cursor, Windsurf, or OpenAI Codex.
+- **An MCP-capable editor or CLI**: Claude Code, GitHub Copilot in VS Code, Cursor,
+  Windsurf, or OpenAI Codex.
 - **No Bridge account needed.** The installer can create one for you from just an
   email address.
 
@@ -87,13 +86,13 @@ npx -y @bridge_gpt/mcp-server install
 a token:
 
 ```
-1. Yes, I have received a token
-2. No, I need one
+1. I need a token
+2. I already have a token
 ```
 
-- Choose **2** if you have nothing yet. It asks for your email address and a name
+- Choose **1** if you have nothing yet. It asks for your email address and a name
   for your new Bridge project, then creates both for you.
-- Choose **1** if someone gave you a token — either a Bridge API key or an invite
+- Choose **2** if someone gave you a token — either a Bridge API key or an invite
   code. Paste it at the hidden prompt; you do not have to say which kind it is,
   because the installer recognizes it. Nothing is echoed as you type.
 
@@ -120,8 +119,8 @@ include a host the installer can launch, the run has to be on an interactive
 terminal, and you have to accept the consent prompt (*"Bridge can configure and set
 up this project for you automatically. Open a `<tool>` session to do that now?
 (Y/n)"*). Claude Code is the only selection that launches on its own. A
-Cursor-only, Copilot, Copilot CLI, Codex, or Windsurf selection, a non-interactive
-run, or a declined prompt all print the command to continue by hand instead. Pass
+Cursor-only, Copilot, Codex, or Windsurf selection, a non-interactive run, or a
+declined prompt all print the command to continue by hand instead. Pass
 `--agent claude` or `--agent cursor-agent` to override the decision outright.
 
 **7. Follow the next step the session shows you, if it shows one.** The installer
@@ -143,7 +142,7 @@ Want to see what would happen without changing anything? Add `--dry-run`.
 
 | Path | What it is | Commit it? |
 |---|---|---|
-| `.claude/commands/`, `.cursor/commands/` | The slash commands your editor runs | Yes |
+| `.claude/commands/`, `.cursor/commands/`, `.github/prompts/`, `.github/skills/` | The generated workflow commands for supported agent hosts | Yes |
 | `.claude/agents/` and editor equivalents | Agent definitions used by those commands | Yes |
 | `.bridge/config` | Your project manifest — the repository name and which MCP targets to provision. Deliberately secret-free | Yes |
 | `.bridge/pipelines/`, `.bridge/instructions/` | Editable pipeline definitions | Yes |
@@ -173,8 +172,8 @@ Cursor's agent instead of Claude Code.
 
 **Selecting Windsurf prints instructions instead of writing config.** Windsurf's
 global `mcp_config.json` is never modified automatically; the installer reports the
-entry for you to paste yourself. Codex and Copilot CLI *are* written automatically,
-even though their files are global too.
+entry for you to paste yourself. Codex *is* written automatically, even though its
+file is global too.
 
 **Your key is stored for the tools that read the store.** The MCP server and the
 shell-spawned tooling (`start-tickets` and its model routing) resolve it from
@@ -261,7 +260,7 @@ Creates a brand-new Bridge project for that address and your first admin key in
 command. No account, no key, and no invite needed beforehand. The address labels
 your new workspace and may receive a setup message; delivery is best-effort, so
 nothing waits on it. The email is visible as you type (it is not a secret) and is
-never written to a log. This is the same route as answering **2** at the prompt.
+never written to a log. This is the same route as answering **1** at the prompt.
 
 **You were sent an invite code.**
 
@@ -300,7 +299,7 @@ created or spent.
 | `--invite [code]` | Redeem an invite code. Omit the value for the hidden prompt (recommended) |
 | `--api-key <key>` | Use an existing Bridge API key |
 | `--repo <name>` | Name the registered repository instead of resolving or asking for it |
-| `--tools <list>` | Configure specific MCP hosts without the picker. Accepted IDs are exactly `claude-code`, `cursor`, `copilot-vscode`, `copilot-cli`, `codex`, and `windsurf` (e.g. `claude-code,cursor`); any other value is a parse error |
+| `--tools <list>` | Configure specific MCP hosts without the picker. Accepted IDs are exactly `claude-code`, `cursor`, `copilot-vscode`, `codex`, and `windsurf` (e.g. `claude-code,cursor`); any other value is a parse error |
 | `--agent claude\|cursor-agent` | Which agent to open for the final configuration step. **No default** — without this flag the agent is derived from the hosts you selected, and an explicit value always wins, including for a host you did not select |
 | `--dry-run` | Preview every step without writing, contacting Bridge, resolving or prompting for a credential, or opening anything. Genuinely inert: it returns before the project-root prompt, before the repository is resolved, and before any tool-selection prompt, so a value it cannot know locally (an unresolved repository name, an unselected tool) is shown as **not yet known** rather than guessed |
 | `--force` | Overwrite an existing stored key without asking |
@@ -352,7 +351,7 @@ later boot.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.54", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.56", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -366,7 +365,7 @@ later boot.
 </details>
 
 <details>
-<summary><strong>VS Code / Copilot (.vscode/mcp.json)</strong></summary>
+<summary><strong>GitHub Copilot (.vscode/mcp.json)</strong></summary>
 
 ```json
 {
@@ -374,7 +373,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.54", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.56", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -396,33 +395,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.54", "serve"],
-      "env": {
-        "BAPI_BASE_URL": "https://bridgegpt-api.com",
-        "BAPI_REPO_NAME": "your-repo",
-        "BAPI_API_KEY": "your-api-key",
-        "BAPI_DOCS_DIR": "docs/tmp"
-      }
-    }
-  }
-}
-```
-</details>
-
-<details>
-<summary><strong>GitHub Copilot CLI (~/.copilot/mcp-config.json)</strong></summary>
-
-Copilot CLI reads a single global file. The installer writes this one for you when
-you select `copilot-cli`; the shape below is what it produces.
-
-```json
-{
-  "mcpServers": {
-    "bridge": {
-      "type": "local",
-      "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.54", "serve"],
-      "tools": ["*"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.56", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -445,7 +418,7 @@ Windsurf only supports global MCP configuration.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.54", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.56", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -464,7 +437,7 @@ Windsurf only supports global MCP configuration.
 ```toml
 [mcp_servers.bridge]
 command = "npx"
-args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.54", "serve"]
+args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.56", "serve"]
 
 [mcp_servers.bridge.env]
 BAPI_BASE_URL = "https://bridgegpt-api.com"
@@ -802,7 +775,16 @@ Repository and ticket housekeeping commands, beyond the tiers above. Implementat
 | `/parse-repository` | Queue a background job to index the repository for Bridge AI agents |
 | `/scan-tickets` | Sync recently-updated Jira tickets and backfill workflow timestamps |
 
-> Commands are designed for Claude Code. Other editors may support slash commands differently — check your editor's documentation for how to invoke prompt files.
+> **GitHub Copilot modes.** On VS Code's Local agent, Bridge provisions one
+> `.github/prompts/<command>.prompt.md` prompt per packaged command, including
+> `/explore-ticket`. On VS Code Agent Host, prompt files are not loaded, so the
+> installer provisions the same canonical command as a project skill at
+> `.github/skills/<command>/SKILL.md`; invoke that skill by its slash-command
+> name. Bridge does not claim Copilot CLI or cloud-agent workflow support from
+> this scaffold alone. If either artifact is not discovered, use VS Code's Chat
+> Customizations diagnostics, confirm the workspace is trusted, and invoke the
+> workflow manually with its full instructions rather than assuming the slash
+> command is available.
 
 ### Extra Capabilities
 
@@ -1003,9 +985,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) |
@@ -1015,15 +997,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.
 
@@ -1176,7 +1160,7 @@ default, or, when it declares none, as an explicit recorded `no_ci_gate` mode.
 > refusal rather than a silent winner.
 
 An unattended run has two one-time **repository** prerequisites — consent
-(`unattended_conductor_allowed`) and a verified notify webhook default — plus
+(`unattended_epic_implementer_allowed`) and a verified notify webhook default — plus
 confirmed default-branch review/CI workflows. Each is refused by name **before any
 run row is created** (`target_not_allowed`, `webhook_unverified`,
 `repository_readiness_unconfirmed`), and `drive-epic` readiness and `doctor` both
@@ -1190,7 +1174,7 @@ prerequisite.
 > half alone would 422 every unattended run at `POST /jira/epic-runs/runs`.
 > Deploying only the server half is safe and inert: it narrows two refusals and adds
 > a first-approval stamp, and **rewrites no existing run**. No database migration and
-> no new environment variable is introduced — `config_projects.unattended_conductor_allowed`
+> no new environment variable is introduced — `config_projects.unattended_epic_implementer_allowed`
 > and `epic_supervisor_setup.done_gate_config` already exist and are read as-is.
 
 Once the plan is approved, the **server-side reconciler** picks the run up within ~30s. To execute claimed jobs on your machine, run `executor`:
@@ -1199,15 +1183,17 @@ Once the plan is approved, the **server-side reconciler** picks the run up withi
 npx -y @bridge_gpt/mcp-server executor --repo <name>
 ```
 
-### `conduct-epic`
+### `implement-epic`
 
 The deterministic half of the `/conduct-epic` loop: it owns the epic branch, a
 versioned local checkpoint, a per-epic lock, and the read-only probes the loop
 decides on. It never creates or mutates an `epic_run` — that is the server-side
 v2 reconciler's job, and `init` refuses to start when one is already active.
+This is EPIC-LEVEL orchestration, distinct from the ticket-level
+`implement-ticket` command.
 
 ```
-npx -y @bridge_gpt/mcp-server conduct-epic <verb> [flags]
+npx -y @bridge_gpt/mcp-server implement-epic <verb> [flags]
 ```
 
 **Verbs**
@@ -1273,9 +1259,9 @@ appear in a command argument, in stdout/stderr, or in a journal line.
 
 ### Conductor (epic & multi-agent orchestration)
 
-Conductor is an **opt-in, off-by-default** layer for epic supervision, inter-agent messaging, done-gate evaluation, local git-hook event producers, and conditional auto-merge. Its full reference — the v2 architecture (server-side reconciler + local executor), `setup-epic`, `conductor install-git-hooks`, the supervisor `done_gate_config` / `auto_merge_enabled` settings, and the observability stream — lives in **[CONDUCTOR.md](./docs/CONDUCTOR.md)**.
+Conductor is an **opt-in, off-by-default** layer for epic supervision, inter-agent messaging, done-gate evaluation, local git-hook event producers, and conditional auto-merge. Its full reference — the v2 architecture (server-side reconciler + local executor), `setup-epic`, `epic-implementer install-git-hooks`, the supervisor `done_gate_config` / `auto_merge_enabled` settings, and the observability stream — lives in **[CONDUCTOR.md](./docs/CONDUCTOR.md)**. (The event-ledger CLI was renamed from `conductor` to `epic-implementer`; the retained `conductor` bin name is now a fixed migration pointer.)
 
-> The v1 `conductor epic-tick` command is **frozen** — it throws on every invocation. There is nothing to schedule locally, and `conductor doctor` flags any epic-tick schedule left over from an earlier release so you can cancel it.
+> The v1 `epic-implementer epic-tick` command is **frozen** — it throws on every invocation. There is nothing to schedule locally, and `epic-implementer doctor` flags any epic-tick schedule left over from an earlier release so you can cancel it.
 
 ## Custom Pipelines
 

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-guidance.generated.js

@@ -0,0 +1,3 @@
+// AUTO-GENERATED — do not edit manually. Regenerate with: npm run build
+// This file is produced by scripts/bundle-agent-guidance.js from mcp_server/agent-guidance.md
+export const AGENT_GUIDANCE = "### Get Project Standards (`get_project_standards`)\n\n**When to use it:** (Implementation | Refinement) Before writing or reviewing code, so the agent applies this project's recorded coding standards instead of generic defaults.\n\n**How to use it:** Call the `get_project_standards` MCP tool directly — it takes no required input and returns the project's recorded standards text.\n\n### Second Opinion (`second_opinion`)\n\n**When to use it:** (Architecture | Refinement | Implementation) Any time you want a quick sanity check on a plan, draft, or decision from a fresh perspective.\n\n**How to use it:** Ask your agent — \"Get a second opinion from Gemini on whether the BAPI-123 plan's migration step is safe to run against production.\"\n\n### Council (`request_council`)\n\n**When to use it:** (Architecture | Refinement) Early, when you want a spread of approaches — technical for how to build it, design for how it should look, discovery for what still needs figuring out before a real ticket exists, general for a quick brief-driven pass before the repository is indexed.\n\n**How to use it:** `/council <question>`\n\n### Review Ticket (`request_ticket_review`)\n\n**When to use it:** (Refinement) Right after a ticket is drafted, before anyone starts building — to surface gaps and tighten it.\n\n**How to use it:** `/review-tickets BAPI-123` (command only — \"review\" as free text is easily mistaken for a freehand agent review). A single key reviews inline in the current session — no terminal tab, no worktree. For several tickets at once, `/review-tickets BAPI-123 BAPI-456` opens one terminal tab per ticket and reviews them in parallel with no worktrees; every review flag applies, and `--review KEY=auto,rounds=N` sets per-ticket overrides.";

package/build/agent-launchers/claude-executor-adapter.js

@@ -345,6 +345,9 @@ export function createClaudeExecutorAdapter(spec, deps = {}) {
             if (input.workerBranch !== undefined) {
                 envOptions.workerBranch = input.workerBranch;
             }
+            if (input.declaredTouchedFiles !== undefined) {
+                envOptions.declaredTouchedFiles = input.declaredTouchedFiles;
+            }
             return {
                 executable: spec.command,
                 argv: buildClaudeArgv(input.prompt, input.modelAlias, input.mcpConfigPath, input.posture),

package/build/agent-notes.js

@@ -0,0 +1,178 @@
+/**
+ * Marker-scoped, opt-in cross-platform agent notes writer (BAPI-1207).
+ *
+ * Creates or refreshes a Bridge-owned region inside a consumer project's
+ * `AGENTS.md` (shared by Cursor, Copilot VS Code, Codex, and Claude Code) and,
+ * for Claude Code specifically, a pointer region inside `CLAUDE.md` — so a
+ * Claude-only selection never leaves a dangling `@AGENTS.md` reference. Every
+ * other byte in either file — content a person wrote by hand outside the
+ * marker pair — is preserved exactly.
+ *
+ * This module performs I/O only through the injected `readFile`/`writeFile`/
+ * `mkdir` seams, mirroring the rest of the install-flow dependency-injection
+ * convention (see `InstallBridgeDeps` in `install-bridge.ts`), and does no
+ * platform detection, credential handling, `.gitignore` mutation, or scaffold
+ * bookkeeping of its own — those stay the caller's responsibility.
+ */
+import path from "path";
+/** The runtime marker pair this module owns inside a target notes file. */
+export const BRIDGE_MCP_GUIDANCE_BEGIN_MARKER = "<!-- BEGIN BRIDGE MCP GUIDANCE -->";
+export const BRIDGE_MCP_GUIDANCE_END_MARKER = "<!-- END BRIDGE MCP GUIDANCE -->";
+/** Platforms whose shared notes file is AGENTS.md. Claude Code also gets CLAUDE.md. */
+const AGENTS_MD_PLATFORMS = new Set([
+    "cursor",
+    "copilot-vscode",
+    "codex",
+    "claude-code",
+]);
+/**
+ * Pure projection from a selected-platform set to the physical notes files
+ * that selection implies. Never touches the filesystem or re-detects
+ * platforms — the caller supplies the already-selected set.
+ */
+export function resolveAgentNotesTargets(selectedPlatforms) {
+    const targets = new Set();
+    const unsupported = new Set();
+    for (const platform of selectedPlatforms) {
+        if (platform === "windsurf") {
+            unsupported.add(platform);
+            continue;
+        }
+        if (AGENTS_MD_PLATFORMS.has(platform)) {
+            targets.add("AGENTS.md");
+        }
+        // Claude Code additionally gets a CLAUDE.md pointer — never a substitute
+        // for AGENTS.md, since @AGENTS.md would otherwise dangle.
+        if (platform === "claude-code") {
+            targets.add("CLAUDE.md");
+        }
+    }
+    const ordered = [];
+    if (targets.has("AGENTS.md"))
+        ordered.push("AGENTS.md");
+    if (targets.has("CLAUDE.md"))
+        ordered.push("CLAUDE.md");
+    return { targets: ordered, unsupportedPlatforms: [...unsupported] };
+}
+/** The one-line pointer note CLAUDE.md's owned region carries (BAPI-1207). */
+const CLAUDE_NOTES_POINTER_NOTE = "Bridge MCP usage guidance is maintained in AGENTS.md — see the section above.";
+function buildClaudeOwnedBody() {
+    return `@AGENTS.md\n\n${CLAUDE_NOTES_POINTER_NOTE}`;
+}
+function countOccurrences(text, marker) {
+    return text.split(marker).length - 1;
+}
+/**
+ * Locate the existing owned region in *text*, or classify why it cannot be
+ * located safely. A malformed topology (a missing half, a duplicate, reversed
+ * order, or a marker not on its own line) is reported rather than repaired —
+ * this module never appends a second region next to one it cannot parse.
+ */
+function scanMarkers(text) {
+    const beginCount = countOccurrences(text, BRIDGE_MCP_GUIDANCE_BEGIN_MARKER);
+    const endCount = countOccurrences(text, BRIDGE_MCP_GUIDANCE_END_MARKER);
+    if (beginCount === 0 && endCount === 0)
+        return { kind: "absent" };
+    if (beginCount === 0 || endCount === 0) {
+        return { kind: "malformed", reason: "missing half of the marker pair" };
+    }
+    if (beginCount > 1)
+        return { kind: "malformed", reason: "duplicate BEGIN marker" };
+    if (endCount > 1)
+        return { kind: "malformed", reason: "duplicate END marker" };
+    const beginIndex = text.indexOf(BRIDGE_MCP_GUIDANCE_BEGIN_MARKER);
+    const endIndex = text.indexOf(BRIDGE_MCP_GUIDANCE_END_MARKER);
+    if (endIndex < beginIndex)
+        return { kind: "malformed", reason: "markers are reversed" };
+    const afterBegin = beginIndex + BRIDGE_MCP_GUIDANCE_BEGIN_MARKER.length;
+    if (text[afterBegin] !== "\n") {
+        return { kind: "malformed", reason: "BEGIN marker is not on its own line" };
+    }
+    const contentStart = afterBegin + 1;
+    const lineStart = text.lastIndexOf("\n", endIndex - 1) + 1;
+    if (text.slice(lineStart, endIndex).trim().length > 0) {
+        return { kind: "malformed", reason: "END marker is not on its own line" };
+    }
+    return { kind: "present", contentStart, contentEnd: endIndex };
+}
+/** Replace only the bytes between valid existing markers; preserve everything else. */
+function replaceRegion(text, contentStart, contentEnd, ownedBody) {
+    const normalized = ownedBody.trim() + "\n";
+    return text.slice(0, contentStart) + normalized + text.slice(contentEnd);
+}
+/**
+ * Append one fresh owned region at EOF, using the minimal separator needed
+ * for a clean markdown boundary. The existing prefix is never normalized —
+ * only the amount of new whitespace inserted before the region varies.
+ */
+function appendRegion(existingText, ownedBody) {
+    const region = `${BRIDGE_MCP_GUIDANCE_BEGIN_MARKER}\n${ownedBody.trim()}\n${BRIDGE_MCP_GUIDANCE_END_MARKER}\n`;
+    if (existingText.length === 0)
+        return region;
+    if (existingText.endsWith("\n\n"))
+        return existingText + region;
+    if (existingText.endsWith("\n"))
+        return existingText + "\n" + region;
+    return existingText + "\n\n" + region;
+}
+function isEnoent(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        "code" in err &&
+        err.code === "ENOENT");
+}
+async function writeOneTarget(target, options) {
+    const filePath = path.join(options.cwd, target);
+    let existing;
+    try {
+        existing = await options.readFile(filePath);
+    }
+    catch (err) {
+        if (isEnoent(err)) {
+            existing = "";
+        }
+        else {
+            return { target, status: "failed", reason: "could not read the existing file" };
+        }
+    }
+    const ownedBody = target === "AGENTS.md" ? options.guidance : buildClaudeOwnedBody();
+    const scan = scanMarkers(existing);
+    let merged;
+    if (scan.kind === "malformed") {
+        return {
+            target,
+            status: "failed",
+            reason: `existing marker region is malformed (${scan.reason})`,
+        };
+    }
+    else if (scan.kind === "present") {
+        merged = replaceRegion(existing, scan.contentStart, scan.contentEnd, ownedBody);
+    }
+    else {
+        merged = appendRegion(existing, ownedBody);
+    }
+    if (merged === existing) {
+        return { target, status: "skipped", reason: "content already up to date" };
+    }
+    try {
+        await options.mkdir(path.dirname(filePath), { recursive: true });
+        await options.writeFile(filePath, merged, { encoding: "utf-8" });
+    }
+    catch {
+        return { target, status: "failed", reason: "could not write the file" };
+    }
+    return { target, status: "written" };
+}
+/**
+ * Create or refresh the Bridge-owned notes region in every target the
+ * selected platforms resolve to. Each target is handled independently — a
+ * failure on one never rolls back or blocks a write already made to another.
+ */
+export async function writeAgentNotes(options) {
+    const { targets, unsupportedPlatforms } = resolveAgentNotesTargets(options.selectedPlatforms);
+    const files = [];
+    for (const target of targets) {
+        files.push(await writeOneTarget(target, options));
+    }
+    return { files, unsupportedPlatforms };
+}

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`.
  */
@@ -44,8 +44,11 @@ export const AGENT_REGISTRY = {
         supportsModelOverride: true,
         modelFlag: "--model",
         // Claude family aliases float to the latest release and never drift, so they
-        // can be validated against a static allowlist.
-        tierModels: { cheap: "haiku", basic: "sonnet", premium: "opus" },
+        // can be validated against a static allowlist. The `cheap` tier deliberately
+        // maps to `sonnet` (not `haiku`): even the lowest-difficulty tickets route to
+        // sonnet. `haiku` stays in the allowlist so a per-repo
+        // `difficulty_model_tier_overrides` may still opt back into it.
+        tierModels: { cheap: "sonnet", basic: "sonnet", premium: "opus" },
         staticModelAliasAllowlist: ["haiku", "sonnet", "opus"],
         // BAPI-781: the reference executor adapter. `managedCarriers` is EMPTY and
         // `passthroughs` names only the operator's own OAuth variable — Bridge
@@ -105,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";
@@ -127,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(", ");
 }
@@ -151,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/agent-utils.js

@@ -108,3 +108,61 @@ export function translateAgentToCopilot(frontmatter, body) {
     const yaml = lines.join("\n");
     return `---\n${yaml}\n---\n${body}`;
 }
+/**
+ * Return the first meaningful line as a short, deterministic Copilot summary.
+ * Canonical command files deliberately have no required frontmatter, so their
+ * opening prose is the only source we can use without maintaining a second
+ * command catalog.
+ */
+function commandDescription(source, commandName) {
+    const line = source
+        .split(/\r?\n/)
+        .map((candidate) => candidate.trim())
+        .find((candidate) => candidate.length > 0 && candidate !== "$ARGUMENTS" && !candidate.startsWith("#"));
+    return line ?? `Run the Bridge ${commandName} workflow.`;
+}
+function commandBodyForPrompt(source) {
+    return source.replaceAll("$ARGUMENTS", "${input:task}");
+}
+function commandBodyForSkill(source) {
+    return source.replaceAll("$ARGUMENTS", "the text supplied after this slash command");
+}
+/**
+ * Translate one packaged command into the two Copilot artifact formats Bridge
+ * supports today. Prompt files are for VS Code's Local agent; project skills
+ * are the Agent Host replacement. Both remain derived from the same canonical
+ * command body, never from a hand-maintained Copilot copy.
+ */
+export function translateCommandToCopilot(filename, source) {
+    const commandName = filename.replace(/\.md$/, "");
+    const description = commandDescription(source, commandName);
+    const prompt = [
+        "---",
+        `description: ${quoteYamlValue(description)}`,
+        "argument-hint: \"[task or ticket key]\"",
+        "tools:",
+        "  - bridge/*",
+        "---",
+        "",
+        `# Bridge ${commandName} workflow`,
+        "",
+        "The user input is available as `${input:task}`. Follow the canonical workflow below.",
+        "",
+        commandBodyForPrompt(source),
+    ].join("\n");
+    const skill = [
+        "---",
+        `name: ${commandName}`,
+        `description: ${quoteYamlValue(description)}`,
+        "argument-hint: \"[task or ticket key]\"",
+        "disable-model-invocation: true",
+        "---",
+        "",
+        `# Bridge ${commandName} workflow`,
+        "",
+        "Use the text supplied after this slash command as the workflow input. Follow the canonical workflow below.",
+        "",
+        commandBodyForSkill(source),
+    ].join("\n");
+    return { prompt, skill };
+}