@bridge_gpt/mcp-server 0.2.57 → 0.2.59

package/README.md

@@ -2,6 +2,44 @@
 
 The Bridge MCP is an end-to-end accelerator for shipping code within SFCC, powered by [Bridge API](https://bridgegpt-api.com). Works with Claude Code, Github Copilot, Cursor, Windsurf, and OpenAI Codex.
 
+## Personal model routing preferences
+
+Create `~/.config/bridge/model-routing.json` to choose ordered providers for
+ticket review, Second Opinion, and Council without changing shared project
+configuration. The file is personal and uncommitted, contains no credentials,
+and is reread for every request. The repository key must exactly match Bridge's
+`repo_name`:
+
+```json
+{
+  "version": 1,
+  "defaults": {
+    "review_ticket": ["gemini", "anthropic"],
+    "second_opinion": ["anthropic", "gemini"],
+    "council": ["anthropic", "gemini"]
+  },
+  "repositories": {
+    "my-repo": { "council": ["gemini"] }
+  }
+}
+```
+
+A repository entry replaces the machine entry only for a feature key it
+contains. Remove a key or set it to `[]` to restore automatic selection for
+that feature; an empty repository entry suppresses the machine entry. Delete
+the file to clear every preference. Malformed, unreadable, or unsafe files are
+ignored with a bounded local warning. Keep the file owned by your user and not
+writable by your group or others.
+
+Only the exact initialized MCP client names `codex` and `claude-code`, or their
+installer markers, identify the Codex and Claude Code families. Cursor, GitHub
+Copilot, and unlisted clients remain neutral. Automatic Codex requests prefer
+eligible Anthropic then Gemini; Claude Code requests prefer eligible OpenAI
+then Gemini. Explicit per-call choices override this personal order but must
+still pass model support, project restrictions, and feature entitlement. A
+populated project Allowed Providers list can reduce an automatic request or
+refuse an incompatible explicit request.
+
 ## Install
 
 From your **project root**, run:
@@ -242,13 +280,16 @@ 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
+**Codex approval profile.** When selecting Codex during interactive `install`,
+press Enter to accept the default Yes at the profile prompt, or answer `n`/`no`
+to decline. 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
+decline; the installer leaves any existing profile content intact. On package
+upgrade, the next Bridge-spawned worker refreshes an older, unmodified managed
+profile before launch. 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
@@ -365,7 +406,7 @@ later boot.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.57", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.59", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -387,7 +428,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.57", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.59", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -409,7 +450,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.57", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.59", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -432,7 +473,7 @@ Windsurf only supports global MCP configuration.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.57", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.59", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -451,7 +492,7 @@ Windsurf only supports global MCP configuration.
 ```toml
 [mcp_servers.bridge]
 command = "npx"
-args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.57", "serve"]
+args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.59", "serve"]
 
 [mcp_servers.bridge.env]
 BAPI_BASE_URL = "https://bridgegpt-api.com"
@@ -564,7 +605,7 @@ The tools worth knowing for most tickets.
 - **What it does:** Creates one git worktree per ticket and spawns an agent session in each to implement them in parallel.
 - **When it's useful:** (Implementation | Automation) When you're ready to start building one or more refined tickets concurrently.
 - **How to use it:** `/start-tickets BAPI-248 BAPI-250` (see [CLI Subcommands](#cli-subcommands) for the full flag table and cross-platform behavior).
-- **Flags:** `--auto` skip the approval gates · `--base-branch <branch>` branch off something other than the default · `--workflow implement|review-and-implement` selects which slash command each spawned worktree runs · `--rounds=1|2` forwarded to the review phase, valid only with `--workflow review-and-implement` · `--tier cheap|basic|premium` coarse model-routing override.
+- **Flags:** `--auto` skip the approval gates · `--base-branch <branch>` branch off something other than the default · `--workflow implement|review-and-implement` selects which slash command each spawned worktree runs · `--rounds=1|2` forwarded to the review phase, valid only with `--workflow review-and-implement` · `--tier cheap|basic|premium` strict manual model-routing override · `--auto-tier cheap|basic|premium` machine-carried raw tier for chained automation (posture-adjusted; used internally by the `/review-and-implement` handoff), mutually exclusive with `--tier`.
 
 **3. Review and Start**
 - **What it does:** Spawns one worktree per ticket; each session reviews the ticket inline and, after a per-ticket proceed/halt gate, hands off to a **fresh implementation session** that reuses the same worktree — review and implementation run in two separate agent contexts, not one shared session.
@@ -664,43 +705,49 @@ Useful once in a while.
 - **How to use it:** Ask your agent — "Post a comment on BAPI-123: blocked on the expired Atlassian token — will retry after it is rotated."
 - **Flags:** A long comment can be attached as a file instead of inlined.
 
-**6. Read Comments**
+**6. Report MCP Bug**
+- **What it does:** Reports a Bridge MCP failure; after receipt, a response and apology will follow. Never include secrets, PII, or proprietary code.
+- **When it's useful:** (Support) When a Bridge MCP tool misbehaves and you need to report it.
+- **How to use it:** Ask your agent to report the failed MCP tool, with no secrets, PII, or proprietary code.
+- **Flags:** Critical reports trigger an immediate page; successful reports receive a response and apology follow-up.
+
+**7. Read Comments**
 - **What it does:** Reads the comment thread on a ticket.
 - **When it's useful:** (Refinement | Implementation) When the discussion on a ticket matters and you want the agent to read it before acting.
 - **How to use it:** Ask your agent — "Read the comments on BAPI-123 and summarize what was decided."
 - **Flags:** None.
 
-**7. Ticket Attachments**
+**8. Ticket Attachments**
 - **What it does:** Downloads files from a ticket to your disk, or attaches a local file to a ticket.
 - **When it's useful:** (Refinement | Implementation) When a ticket has design files or logs you need locally, or you want to attach output back to it.
 - **How to use it:** Ask your agent — "Download the design mockups attached to BAPI-123 into my docs folder," or "Attach build-log.txt to BAPI-123."
 - **Flags:** Choose the direction (download from the ticket, or upload to it) and, for a download, where the files should land.
 
-**8. Estimate Epic**
+**9. Estimate Epic**
 - **What it does:** Estimates an epic, or an explicit group of tickets you name.
 - **When it's useful:** (Architecture | Refinement) When you need a sizing pass across an epic, or across a set of tickets you name explicitly.
 - **How to use it:** `/estimate-epic BAPI-123`
 - **Flags:** Pass an epic key, or an explicit list of ticket keys to estimate as one group.
 
-**9. Regression Check**
+**10. Regression Check**
 - **What it does:** Runs the deterministic regression-reviewer (lightweight mode) against a proposed code change and reports its blast radius — which real call-sites, tests, mocks, or config the change does and doesn't account for.
 - **When it's useful:** (Correctness) Before merging a change, to see which real callers, tests, or config it leaves unaccounted for.
 - **How to use it:** `/regression-check` reviews the working tree against `HEAD` by default; `/regression-check --diff main...HEAD` reviews an explicit range.
 - **Flags:** `--diff <range>` review a specific diff/PR range instead of the working tree vs. `HEAD` · `--symbols a,b,c` review a not-yet-diffed planned change by naming its symbols directly.
 
-**10. Scan Test Coverage**
+**11. Scan Test Coverage**
 - **What it does:** Scans recently shipped tickets from git history and reports which features have or could gain integration tests, and which can only be smoke tested.
 - **When it's useful:** (Testing) Periodically, to find recently shipped features still missing integration-test coverage and how each could be smoke tested instead.
 - **How to use it:** `/scan-test-coverage` runs incrementally from the last recorded marker in `docs/test-coverage/STATE.md`.
 - **Flags:** `--since=YYYY-MM-DD` override the window start date · `--full` ignore the marker and use a 6-month lookback · `--limit=N` cap the number of features investigated.
 
-**11. Estimate Ticket**
+**12. Estimate Ticket**
 - **What it does:** One-ticket shortcut over the existing epic estimation capability: estimates a single Jira ticket via the same `estimate_epic` tool.
 - **When it's useful:** (Estimation) When you want one ticket's estimate without typing out an epic key or an explicit ticket list.
 - **How to use it:** `/estimate-ticket BAPI-123`
 - **Flags:** `--allow-partial` the sole optional flag.
 
-**12. Draft Ticket**
+**13. Draft Ticket**
 - **What it does:** Delegates to the Jira Ticket Writer to create only a local Markdown draft — it does not create or update a Jira issue.
 - **When it's useful:** (Refinement) When you want a reviewable local ticket draft before committing to an upload workflow.
 - **How to use it:** `/draft-ticket <description>`
@@ -789,16 +836,37 @@ 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 |
 
-> **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.
+> **GitHub Copilot modes.** Bridge supports Copilot workflow commands in two
+> VS Code chat modes only. The recorded live results live in
+> [`smoke-test/COPILOT-COMMAND-SMOKE.md`](smoke-test/COPILOT-COMMAND-SMOKE.md),
+> which is the authoritative discovery contract.
+>
+> | Copilot mode | Artifact Bridge writes | How you invoke it |
+> |---|---|---|
+> | VS Code Local agent | `.github/prompts/<command>.prompt.md` | `/<command>`, for example `/explore-ticket` |
+> | VS Code Agent Host | `.github/skills/<command>/SKILL.md` (a separately verified project skill; prompt files are not loaded in this mode) | `/<command>` |
+> | Copilot CLI, Copilot cloud coding agent | None | Out of scope |
+>
+> - **When they are written.** `--init` writes both artifacts for every packaged
+>   command whenever the project has a `.vscode/` directory. `.vscode/` is only
+>   Bridge's VS Code project heuristic; it does not prove that GitHub Copilot is
+>   installed or enabled.
+> - **Input.** A prompt file reads its input from `${input:task}`. Text supplied
+>   after the slash command takes precedence when present, and the agent asks
+>   you for the task when both are empty.
+> - **Tools.** Bridge MCP tools come from the generated `.vscode/mcp.json`
+>   registration. Prompt files carry no `tools` frontmatter restriction.
+> - **Reserved names.** `.github/prompts/<packaged-command>.prompt.md` and
+>   `.github/skills/<packaged-command>/SKILL.md` are Bridge-managed. Rerunning
+>   init overwrites a changed file at one of those paths and reports
+>   `Overwritten (content changed)`. Files with any other name are never
+>   modified.
+> - **Agent definitions are separate.** `.github/agents/*.agent.md` holds agent
+>   definitions, not reusable workflow commands.
+> - **If a command is not discovered.** Open VS Code's Chat Customizations
+>   diagnostics and confirm the workspace is trusted. If Agent Host is recorded
+>   as `UNSUPPORTED_DISCOVERY`, switch the chat session to the Local agent and
+>   use the `.github/prompts/` prompt files instead.
 
 ### Extra Capabilities
 
@@ -1001,14 +1069,15 @@ npx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]
 | `--agent claude\|cursor-agent` | `claude` | Agent command to launch in each worktree |
 | `--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; 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. |
+| `--tier cheap\|basic\|premium` | unset (difficulty routing) | Strict manual 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 exactly as supplied, with no per-session posture adjustment; 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. Mutually exclusive with `--auto-tier`. |
+| `--auto-tier cheap\|basic\|premium` | unset | Internal/advanced machine-carried raw backend tier for chained automation (BAPI-1236). Bypasses the per-ticket lookup like `--tier`, but remains subject to the launching session's own `maximize_subscription` downshift. Used by the `/review-and-implement` handoff to reuse the review-time raw tier snapshot without silently skipping that downshift. Mutually exclusive with `--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) |
 | `--base-branch <BRANCH>` | `main` | Cut new worktrees from `<BRANCH>` and refresh `origin/<BRANCH>` instead of `main` |
 | `--no-refresh-main` | off (the configured base branch is refreshed) | Skip refresh of the configured base branch (default `main`). Historical flag name preserved for backward compatibility — despite the name, it now skips refresh of whatever `--base-branch` resolves to. |
 | `--max-parallel N` | `3` | Max worktrees created concurrently |
-| `--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>'`. |
+| `--conductor` | off | Opt into the Conductor system (per-worker `BAPI_EPIC_IMPLEMENTER_*` 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. 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:
@@ -1021,7 +1090,11 @@ npx -y @bridge_gpt/mcp-server start-tickets --agent cursor-agent BAPI-248
 
 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 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.
+**Maximize-subscription posture (BAPI-1224, extended by BAPI-1236).** The per-repository `optimization_posture` config field (`quality` | `speed` | `maximize_subscription`; unset/NULL, malformed, or unreadable all resolve to `quality`) is read once per invocation, isolated from the routing-config fetch above, and applied to a tier resolved by either the automatic per-ticket difficulty lookup **or** a carried `--auto-tier` raw snapshot — both paths share the same posture resolution and downshift call site. Only `maximize_subscription` downshifts that tier one level — `premium -> basic`, `basic -> cheap`, `cheap -> cheap` (the fixed floor) — before alias resolution; `quality`, `speed`, and every degraded posture outcome preserve current (Quality) routing unchanged. Claude and Cursor still resolve the downshifted tier through their unmodified registry aliases, and Codex still indexes the fetched catalog (`catalog.models[effectiveTier]`) — no maximize-specific alias table exists anywhere. An explicit `--tier` override remains an exact manual override (the posture is never even read on that path), and the harness-local premium fallback used when no usable tier is available stays on `premium` regardless of posture. A degraded posture read never fails a spawn; it appends a secret-free `optimization-posture-unavailable` warning to affected rows and stamps at most one de-duplicated diagnostic per invocation (stderr-only, never Sentry). A separate, additive `[model-routing]` stderr line (never stdout) reports the source/baseline/posture/adjustment/effective-tier/alias for every successfully baseline-routed row, across all three routing paths (`--tier`, `--auto-tier`, and the automatic difficulty lookup).
+
+**Coarse `--tier` override.** Passing `--tier cheap|basic|premium` bypasses only the per-ticket difficulty lookup and applies that tier to every ticket exactly as supplied — posture is never read on this path. 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.
+
+**Machine-carried `--auto-tier` handoff (BAPI-1236).** Passing `--auto-tier cheap|basic|premium` also bypasses the per-ticket difficulty lookup, but — unlike `--tier` — the carried tier IS routed through the launching session's own `maximize_subscription` downshift, exactly once. A malformed, empty, or repeated `--auto-tier` value is a hard parser error (no fail-open sentinel), and `--tier`/`--auto-tier` are mutually exclusive regardless of order. `/review-and-implement` uses this flag, never `--tier`, to hand its review-time raw tier snapshot to the fresh implementation session — so a `maximize_subscription` repo still gets the downshift on the chained handoff instead of silently skipping it.
 
 **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.
 
@@ -1077,12 +1150,12 @@ your project can actually run:
 npx -y @bridge_gpt/mcp-server drive-epic <EPIC>
 ```
 
-You are never asked to choose. Bridge currently has two conductors and a standing
-rule that they must never operate on the same epic — two transition authorities on
-one epic wedge it permanently — so the choice is made structurally rather than by
-judgement. Readiness green routes to the v2 bootstrap below (pass `--plan-file`
-and `drive-epic` runs it for you); readiness not green prints the interactive
-pilot instruction instead. If readiness is **unknown** — unreachable,
+You are never asked to choose. `drive-epic` routes to exactly one conductor, the
+v2 engine — one transition authority per epic is what keeps an epic from wedging.
+Readiness green routes to the v2 bootstrap below (pass `--plan-file`
+and `drive-epic` runs it for you); readiness not green reports that the v2 engine
+is not ready to drive this epic — there is no alternative conductor to fall back
+to — and prints no conductor invocation. If readiness is **unknown** — unreachable,
 unauthorized, or malformed — it escalates and prints no conductor invocation at
 all, because an unknown owner is not the same as a not-ready one. No branch,
 including every error path, ever offers you two paths.
@@ -1197,80 +1270,6 @@ Once the plan is approved, the **server-side reconciler** picks the run up withi
 npx -y @bridge_gpt/mcp-server executor --repo <name>
 ```
 
-### `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 implement-epic <verb> [flags]
-```
-
-**Verbs**
-
-| Verb | Flags |
-| --- | --- |
-| `init <EPIC>` | `--tickets K1,K2,…` (required), `--base-branch <b>`, `--checkpoint-path <p>`, `--dry-run`, `--json` |
-| `status <EPIC>` | `--json` (required), `--checkpoint-path <p>` |
-| `checkpoint set <EPIC>` | `--ticket <KEY>` (required), `--field <name> <value>` (repeatable), `--journal "<line>"`, `--checkpoint-path <p>` |
-| `finish <EPIC>` | `--checkpoint-path <p>`, `--json` |
-| `spawn <EPIC>` | `--ticket <KEY>` and `--prompt-file <path>` (required), `--agent claude\|cursor-agent`, `--checkpoint-path <p>`, `--json` |
-
-**Local state.** Everything lives *outside* the repository, under
-`~/.config/bridge/conduct/<repo>/` (honoring `XDG_CONFIG_HOME`), so it resolves
-identically from the main checkout and from any worktree and can never be
-committed by an agent running `git add`:
-
-| Path | Purpose |
-| --- | --- |
-| `<EPIC>.json` | the version-1 checkpoint (file `0600`, directory `0700`) |
-| `<EPIC>.json.prev` | the previous valid checkpoint, retained on every write |
-| `<EPIC>.lock` | the per-epic lock |
-| `<EPIC>/prompts/<KEY>-<kind>-<n>.md` | prompt files the caller writes for `spawn` |
-
-`status` prints the resolved `checkpoint_path`. To unpark a run a human edits the
-checkpoint (`needs_human` → `null`, plus the ticket's `status`/counters);
-`last_seen_head`, `ci_last_poll`, and `lock` are observational and are never
-hand-edited.
-
-**`init` runs ONE preflight** that reports *every* failure in a single pass and
-writes nothing unless all of them pass: `gh auth status`; Worktrunk resolves
-(honoring `BAPI_WORKTRUNK_BIN`); Bridge credentials resolve; `auto_merge_enabled`
-is on — or is turned on by PUTting the *complete* effective config back with just
-that flag flipped, which prints a line beginning `announced:`; at least one
-required CI check exists (an empty required set would make the done gate pass
-vacuously); no active server-side `epic_run` for the key; the lock is free or its
-owner is provably dead; the base branch exists on `origin` after `git fetch`; and
-the indexed-branch override is either absent or this epic's own — a re-`init`
-after a crash is accepted and its `original_base_branch` becomes the default base,
-while a *foreign* override is refused by name. `resolve-ci-checks` is called
-exactly once either way, because that call is what warms the `poll-ci-checks`
-cache the first `status` depends on. Only then does `init` push
-`epic/<EPIC>` to `origin` at the fetched base tip (no local checkout), repoint the
-index, write the checkpoint, and take the lock. `--dry-run` prints the validated
-plan and mutates nothing. A second `init` refuses with `already initialized`.
-
-**Failure posture is split on purpose.** In `status`, each probe fails *open*: a
-`gh`, CI, review, or parse failure leaves that sub-object `null`, adds an entry to
-`probe_errors`, and the command still exits `0` with a complete object — the loop
-must be able to read its own checkpoint during a GitHub outage. Everything else
-fails *closed*: a corrupt or wrong-version checkpoint makes every verb but `init`
-exit non-zero **without rewriting it**, and `checkpoint set`, `spawn`, and
-`finish` refuse a lock held by another live process. `status` never takes the lock.
-
-**Exit codes.** `0` on success — including a missing checkpoint
-(`checkpoint_exists: false`) and an idempotent second `finish`. Non-zero on any
-other failure, with a one-line reason on stderr. With `--json`, stdout is exactly
-one JSON object carrying `ok`.
-
-**Credentials** resolve only from `BAPI_API_KEY` or the user-scoped
-`bapi:<repo>` credential target, travel only in the `X-API-Key` header, and never
-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`, `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.)
@@ -1562,14 +1561,14 @@ The full surface, for when you need the complete enumeration. Day-to-day, use [U
 
 ### MCP tools
 
-The authoritative tool catalog covers **75 tools** (enumerated below). What's actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
+The authoritative tool catalog covers **77 tools** (enumerated below). What's actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
 
 - **Connectivity & identity** — `ping` (its JSON also carries `docs_dir`, `role`, and `customer_type`)
 - **Team & access** — `invite_member` (admin-only; mints a scoped access key for a teammate on an already-configured project — the plaintext key is shown exactly once)
 - **Jira tickets** — `get_tickets`, `get_ticket`, `create_ticket`, `update_ticket_description`, `add_comment`, `get_comments`
-- **Attachments** — `attachment` (operations: `upload`, `download`, `list`)
+- **Attachments** — `attachment` (operations: `upload`, `download`, `list`, `delete`); `publish_reviewed_attachment` appends only a captured review's fixed Markdown copy during auto review, leaving older Jira attachments intact.
 - **AI generation (request/get)** — `request_plan_generation`/`get_plan`, `create_doc`/`get_doc` (design docs by `doc_type`: tdd/architecture/fsd/prd, where `architecture` is an alias of `tdd`), `request_ticket_review` (writes both `get_clarifying_questions` and `get_ticket_critique`), `request_reimplement_context`/`get_reimplement_context`, `request_council`/`get_council`, `request_deep_research`/`get_deep_research`
-- **Bounded waits** — `wait_for_ticket_review`, `wait_for_ci_checks`. Each call waits at most 240 s and returns `state: "ready" | "pending" | "error"`; `pending` is a normal, resumable result you call again on, never a failure. They exist so an agent can wait without a foreground `sleep` and without binding a long server-side operation to the 900 s MCP client deadline. `wait_for_ci_checks` reports only that checks are **terminal** — deciding pass or fail stays with the caller.
+- **Bounded waits** — `wait_for_ticket_review`, `wait_for_ci_checks`. Each returns `state: "ready" | "pending" | "error"`; review waits default to 20 s and CI waits default to 240 s (both accept up to 240 s explicitly). `pending` is a normal, resumable result you call again on, never a failure. They exist so an agent can wait without a foreground `sleep` and without binding a long server-side operation to the 900 s MCP client deadline. `wait_for_ci_checks` reports only that checks are **terminal** — deciding pass or fail stays with the caller.
 - **Other AI** — `second_opinion`, `generate_image`, `generate_decision_page`, `visual_diff` (deterministic pixel diff of a rendered URL vs a design comp)
 - **Ticket lifecycle** — `track_ticket`, `update_ticket_state`, `get_ticket_state`, `get_ticket_state_tree` (live repo-wide lifecycle + dependency tree; read-only, no mutation parameter)
 - **Jira status** — `update_jira_status` (pass `status: "auto"` to resolve the configured post-PR status server-side)
@@ -1584,7 +1583,7 @@ Pipelines are declarative, multi-step workflows your AI agent executes step-by-s
 | Pipeline | Description | Invoke with |
 |---|---|---|
 | `implement-ticket` | Generate a plan, execute the implementation, commit, open a PR, and monitor CI | `/implement-ticket PROJ-123` |
-| `review-ticket` | Full ticket quality review: clarifying questions + critique plus an automatic second-opinion pass, then evaluation and decision capture. The backend owns round orchestration; pass `--rounds=1` for a single-pass review or `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend decide adaptively. Internal atomic pipeline invoked by `/review-tickets` (inline for one key, spawned per tab for several) and by `/review-and-implement`, `/review-and-start`, `/start-tickets`, and `/conduct-epic`. | `/review-tickets PROJ-123` |
+| `review-ticket` | Full ticket quality review: clarifying questions + critique plus an automatic second-opinion pass, then evaluation and decision capture. The backend owns round orchestration; pass `--rounds=1` for a single-pass review or `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend decide adaptively. Internal atomic pipeline invoked by `/review-tickets` (inline for one key, spawned per tab for several) and by `/review-and-implement`, `/review-and-start`, and `/start-tickets`. | `/review-tickets PROJ-123` |
 | `idea-to-ticket` | Turn an idea into a Jira Task/Spike (or Epic + children) with research, dedup, and critique | `/idea-to-ticket "<idea>"` |
 | `plan-epic` | Decompose an epic into sub-tasks with a structured exploration doc for each | `/plan-epic "<epic>"` |
 | `full-automation` | Client-side wrapper: runs the `idea-to-ticket` recipe, then hands the created keys to `/review-and-start --auto` | `/idea-to-pr "<idea>"` |

package/build/agent-registry.js

@@ -24,6 +24,21 @@ export function isValidModelAlias(value) {
 export function isModelTier(value) {
     return value === "cheap" || value === "basic" || value === "premium";
 }
+/**
+ * BAPI-1224 — downshift one model tier: `premium -> basic`, `basic -> cheap`,
+ * `cheap -> cheap` (the fixed floor). Total and exhaustive: no permissive
+ * default branch, so extending `ModelTier` forces an explicit decision here.
+ */
+export function downshiftModelTier(tier) {
+    switch (tier) {
+        case "premium":
+            return "basic";
+        case "basic":
+            return "cheap";
+        case "cheap":
+            return "cheap";
+    }
+}
 /**
  * The registry: the ONLY place mapping an agent name to its command/spec. Seeded
  * with `claude` (default), `cursor-agent`, and `codex`. `as const satisfies` keeps

package/build/agent-utils.js

@@ -115,10 +115,18 @@ export function translateAgentToCopilot(frontmatter, body) {
  * 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("#"));
+    const lines = source.split(/\r?\n/).map((candidate) => candidate.trim());
+    // Some commands open with host-parsed YAML frontmatter; its delimiters and
+    // keys are metadata, not a summary, so drop the block before scanning.
+    if (lines[0] === "---") {
+        const close = lines.indexOf("---", 1);
+        if (close > 0)
+            lines.splice(0, close + 1);
+    }
+    const line = lines.find((candidate) => candidate.length > 0 &&
+        candidate !== "$ARGUMENTS" &&
+        !candidate.startsWith("#") &&
+        !/^[-*_\s]+$/.test(candidate));
     return line ?? `Run the Bridge ${commandName} workflow.`;
 }
 function commandBodyForPrompt(source) {
@@ -136,17 +144,17 @@ function commandBodyForSkill(source) {
 export function translateCommandToCopilot(filename, source) {
     const commandName = filename.replace(/\.md$/, "");
     const description = commandDescription(source, commandName);
+    // No `tools:` frontmatter: Bridge MCP tools reach Copilot through the
+    // generated `.vscode/mcp.json` registration, not a prompt-level restriction.
     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.",
+        "The workflow input is `${input:task}`. When text is supplied after the slash command, that text takes precedence; if neither contains input, ask the user for the task before continuing. Follow the canonical workflow below.",
         "",
         commandBodyForPrompt(source),
     ].join("\n");
@@ -160,7 +168,7 @@ export function translateCommandToCopilot(filename, source) {
         "",
         `# Bridge ${commandName} workflow`,
         "",
-        "Use the text supplied after this slash command as the workflow input. Follow the canonical workflow below.",
+        "Use the text supplied after this slash command as the workflow input; if no text was supplied, ask the user for the task before continuing. Follow the canonical workflow below.",
         "",
         commandBodyForSkill(source),
     ].join("\n");

package/build/claude-user-config-doctor.js

@@ -52,21 +52,6 @@ const CLAUDE_USER_CONFIG_FILENAME = ".claude.json";
 export function resolveClaudeUserConfigPath(homeDirectory, platform) {
     return pathApiForProvisioningPlatform(platform).join(homeDirectory, CLAUDE_USER_CONFIG_FILENAME);
 }
-/**
- * RETIRED (BAPI-790) — this override is now behaviorally inert.
- *
- * It used to downgrade a confirmed shadowing collision from a refusal to a loud
- * warning. There is no refusal left to downgrade: strict flag-scoped MCP loading
- * means an operator registration cannot shadow a worker, so the finding is always
- * advisory and setting this variable changes nothing.
- *
- * The constant is kept exported, and {@link isClaudeMcpShadowingOverrideEnabled}
- * with it, so an operator who still has it set in a service unit or shell profile
- * gets no error — and so the name stays greppable to whoever wonders why it stopped
- * mattering. Nothing in the policy consults it. Do not reintroduce a branch on it
- * without re-establishing that shadowing can affect a worker again.
- */
-export const CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING_ENV = "BAPI_CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING";
 /** A plain, non-array object. */
 function asRecord(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
@@ -262,27 +247,8 @@ export async function inspectClaudeUserConfigForMcpShadowing(input, deps) {
     return { findings, diagnostics };
 }
 // ---------------------------------------------------------------------------
-// Override + shared policy
+// Shared policy
 // ---------------------------------------------------------------------------
-/** Documented truthy override values (trimmed, case-insensitive). */
-const OVERRIDE_TRUTHY = new Set(["1", "true", "yes", "on"]);
-/**
- * True only for a trimmed, case-insensitive `1`, `true`, `yes`, or `on`. Absent,
- * blank, `0`, `false`, `no`, `off`, and anything else are disabled.
- *
- * RETIRED (BAPI-790): no policy branches on this any more — see
- * {@link CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING_ENV}. Retained as a pure predicate
- * so the parsing rule stays documented and testable rather than being deleted and
- * re-guessed if the override is ever revived.
- */
-export function isClaudeMcpShadowingOverrideEnabled(env) {
-    const raw = env?.[CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING_ENV];
-    if (typeof raw !== "string")
-        return false;
-    return OVERRIDE_TRUTHY.has(raw.trim().toLowerCase());
-}
-/** The exact wording every override path emits, pinned by tests. */
-export const CLAUDE_MCP_SHADOWING_OVERRIDE_WARNING = `Proceeding anyway because ${CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING_ENV} is set`;
 /** Human-readable scope labels (fixed strings, never derived from the config). */
 const SCOPE_LABELS = {
     user: "user scope (mcpServers)",

package/build/codex-bridge-profile.js

@@ -13,6 +13,7 @@ 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",
+    "attachment", "publish_reviewed_attachment",
     "get_phase_context", "record_phase_result", "create_pull_request",
     "update_jira_status", "config_field", "resolve_ci_checks", "poll_ci_checks",
     "wait_for_ci_checks",
@@ -76,8 +77,11 @@ export async function inspectBridgeCodexProfile(home, readFile) {
         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)
+    if (fingerprint(profile) !== parsed.hash)
         return { status: "conflict", key };
+    if (profile !== renderBridgeCodexProfile(key)) {
+        return { status: profile.startsWith(MARKER) ? "stale" : "conflict", key };
+    }
     return { status: "active", key };
 }
 export async function configureBridgeCodexProfile(home, choice, deps) {

package/build/codex-launch-scope.js

@@ -2,7 +2,7 @@
 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 { codexProfilePaths, configureBridgeCodexProfile, 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. */
@@ -39,7 +39,18 @@ export async function resolveCodexLaunchScope(root, deps, codexConfigPath = code
     }
     const bridgeKey = registeredNames[0] ?? MCP_SERVER_NAME;
     const home = codexHome(deps.env ?? process.env, deps.homedir?.());
-    const profile = await inspectBridgeCodexProfile(home, deps.readFile);
+    let profile = await inspectBridgeCodexProfile(home, deps.readFile);
+    if (profile.status === "stale") {
+        try {
+            profile = await configureBridgeCodexProfile(home, "enable", deps);
+        }
+        catch {
+            return { ok: false, error: "Codex MCP scope unavailable: could not refresh the managed Bridge approval profile." };
+        }
+        if (profile.status !== "active") {
+            return { ok: false, error: "Codex MCP scope unavailable: managed Bridge approval profile refresh failed." };
+        }
+    }
     const argv = ["-C", normalized.path];
     if (profile.status === "active" && profile.key === bridgeKey)
         argv.push("--profile", BRIDGE_CODEX_PROFILE);