@bridge_gpt/mcp-server 0.2.42 → 0.2.43

package/build/docs.generated.js

@@ -2,5 +2,6 @@
 // This file is produced by scripts/bundle-docs.js
 export const DOCS = {
     "docs/mcp-tool-integrations.md": "# MCP tool integrations — the human \"why\" behind the capability report\n\nThis catalog is **explanatory prose only**. It exists so the `/install-bridge`\ncapability report can cite a human-readable \"why\" for each gate. It is **not** a\nsource of truth for gating: the server computes every `locked_tools` /\n`unlocked_tools` membership decision itself and the agent must never recompute a\ntool's dependencies from this document.\n\n**Authoritative source of gating.** The enforced rules — which tools are blocked,\nwhich are degraded, and what each requires — live in\n`api/library/vcs/vcs_route_operations.py`:\n\n- `VCS_ROUTE_REQUIREMENTS` — routes that **BLOCK** (are unavailable) without a\n  VCS connection.\n- `VCS_ROUTE_WARNINGS` — routes that **DEGRADE** (stay usable, but without\n  codebase context) without a VCS connection.\n- `NEVER_GATED_ROUTE_KEYS` — routes that are never gated on any integration.\n- `INDEX_REQUIRED_ROUTE_KEYS`, `INDEX_REQUIRED_BRAINSTORM_MODES`,\n  `CREATE_DOC_CODEBASE_CONTEXT_DOC_TYPES`, `CREATE_DOC_WARN_DOC_TYPES` — the\n  conditional \"requires a successful code index\" dimension.\n- The resolver helpers `get_required_vcs_operation()`, `get_warn_vcs_operation()`,\n  and `requires_successful_index()` are the authoritative functions that decide a\n  case. The capability report is derived from these; this catalog explains them.\n\n## Reading the capability report\n\nEach tool entry the server returns has the exact shape\n`{tool, effect, missing, semantics}`:\n\n- **`effect`**\n  - **`BLOCK`** — the tool is **unavailable** until every listed dependency is\n    met. It will refuse to run without them.\n  - **`DEGRADE`** — the tool is **usable right now**, but **without codebase\n    context** (it cannot ground its output in your repository). Connecting the\n    listed dependency upgrades it from \"works blind\" to \"works with full context\".\n    A `DEGRADE` tool is never \"failed\".\n- **`missing`** — the server-computed dependency identifiers still needed:\n  integration ids such as `github_app` / `vcs_access_token`, and the synthetic\n  `code_index` (a successful repository index).\n- **`semantics`**\n  - **`all_of`** — every id in `missing` is required.\n  - **`any_of`** — the VCS-provider candidates in `missing` are alternatives:\n    **either** `github_app` **or** `vcs_access_token` satisfies the VCS\n    requirement (this is the \"provider unknown\" case). When `code_index` also\n    appears, it remains separately required — `semantics` describes only the VCS\n    provider candidates, and a code index is always mandatory in addition.\n\nThe three readiness dimensions `configured` / `learned` / `indexed` are reported\nindependently. `indexed` may be `true`, `false`, or `null` — a `null` means the\nindex status could not be confirmed and must **not** be read as \"indexed\".\n\n## The integrations\n\n| Integration id | What it is | What it unlocks |\n| --- | --- | --- |\n| `jira` | Jira API access | Ticket reads/writes, estimation and review automations, status transitions. |\n| `github_app` | GitHub App installation | Pull requests, code review, and private-repo parsing on GitHub projects. |\n| `vcs_access_token` | VCS access token | Pull requests, code review, and private-repo parsing on Bitbucket projects. |\n| `vcs_webhook` | VCS webhook secret | Merge webhooks and CI follow-up triggers. |\n| `code_index` | A successful repository index | Codebase-grounded planning, architecture, reimplementation, and technical/discovery brainstorms. Produced by `/parse-repository`. |\n\nA project's `github_app` **or** `vcs_access_token` provides the VCS connection;\nwhich one applies depends on the project's version-control system. When the\nproject's provider is unknown, either credential satisfies the requirement — the\nreport expresses that as `semantics: any_of`.\n\n## The gates, by capability\n\n### Pull requests and CI (BLOCK on VCS)\n\nTools like `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`, and\n`materialize_fresh_base` are **unavailable** (`BLOCK`) until a VCS connection is\nconfigured. They act directly on the version-control host, so without a\nconnection there is nothing for them to talk to.\n\n### Repository indexing and maps (BLOCK on VCS)\n\n`parse_repository` and `regenerate_directory_map` need a VCS connection to read\nthe repository. They **BLOCK** until VCS is connected.\n\n### Codebase-grounded generation (BLOCK on VCS **and** a code index)\n\nPlanning and architecture tools — `generate_plan_direct`,\n`generate_architecture_direct`, `request_reimplement_context`,\n`code_writer_generate_plan`, `code_writer_generate_architecture`, and\n`create_doc` for **TDD** / **architecture** documents — ground their output in\nyour indexed codebase. They **BLOCK** until BOTH a VCS connection AND a\nsuccessful code index exist (`all_of`, with `code_index` in `missing`).\n\n### Council (BLOCK on a code index, mode-dependent)\n\n`request_council` in **technical** or **discovery** mode searches your indexed\ncodebase, so it **BLOCK**s on `code_index`. **Design**-mode brainstorming never\nqueries the index and is never gated.\n\n### Document generation that DEGRADEs (usable without codebase context)\n\nTools like `generate_prd_direct`, `generate_fsd_direct`,\n`code_writer_generate_fsd`, `generate_clarifying_questions_direct`,\n`generate_ticket_critique_direct`, `generate_ticket_review_direct`, and\n`create_doc` for **PRD** / **FSD** documents **DEGRADE** rather than block: they\nrun today from the ticket alone, and connecting VCS simply lets them ground their\noutput in your codebase. They always appear under \"Tools you can use now\", with a\nreduced-context caveat when the VCS connection is missing.\n\n### Never gated\n\nSetup and bootstrap tools (`ping`, `config_field`, `get_install_manifest`,\n`apply_install_manifest`, `get_my_role`, `persist_routing_credential`,\n`get_docs_dir`, and the bootstrap-invite exchange) are always available — they\nare how you configure everything else.\n",
-    "docs/install/sfcc-integration.md": "# Installing the SFCC Integration (OCAPI)\n\nBridge's Salesforce B2C Commerce (SFCC) tools give an AI coding agent read access to\na sandbox's object model, custom object definitions, and site preferences — plus a\nsmall set of sandbox-only writes — through the **OCAPI Data API**. This guide covers\nsetting up the OCAPI client that those tools authenticate against.\n\n> **Sandbox / local development only.** This integration is intended for a **developer\n> sandbox**, and that restriction is **enforced in code**: before any SFCC tool runs,\n> Bridge validates the hostname your credentials actually resolve to — from `dw.json`\n> or `SFCC_*` — against the sandbox forms listed below. An unrecognized host is refused\n> with a `403` (`error.code: \"TARGET_NOT_SANDBOX\"`) before any request leaves your\n> machine. The check reads the resolved hostname, never the `instance` tool argument,\n> so omitting `instance` or passing `\"sandbox\"` cannot bypass it.\n>\n> Accepted sandbox hostname forms:\n>\n> - `<realm>-<nnn>.sandbox.<region>.dx.commercecloud.salesforce.com`\n> - `<realm>-<nnn>.sandbox.dx.commercecloud.salesforce.com`\n> - `<realm>-<nnn>.dx.commercecloud.salesforce.com`\n>\n> Anything else — a `production-`/`staging-`/`development-` prefixed host, or any\n> `*.demandware.net` host — is rejected.\n>\n> Still do not configure the grants below on an instance that holds real data.\n> Credentials stay local (in `dw.json` or `SFCC_*` env vars) and are never sent to\n> Bridge.\n\nFor the full per-tool list and what each SFCC tool depends on, see\n[MCP Tool Integration Dependencies](./mcp-tool-integrations.md). For the tool reference\nand the `BRIDGE_MCP_PROFILE` gating, see the SFCC section of the\n[package README](../../README.md).\n\n## Prerequisites\n\n- A running SFCC **developer sandbox** and its hostname\n  (e.g. `zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com`).\n- An **Account Manager API client** — a `client-id` and `client-secret`. This is the\n  OCAPI client the tools use to obtain an OAuth token. Create one in Account Manager\n  (**API Client** → *Add API Client*) if you don't already have it, and note its\n  `client_id`.\n- Business Manager access to the sandbox with permission to edit **Open Commerce API\n  Settings**.\n\n## 1. Grant the OCAPI client access in Business Manager\n\nIn Business Manager for the sandbox:\n\n**Administration → Site Development → Open Commerce API Settings → Data API** tab.\n\nAdd the client entry below to the `clients` array of the Data API settings, then\n**Save**. It grants only the resource families and HTTP methods Bridge's SFCC tools\nactually call — not a global `/**` grant. `check_permissions` prints the same JSON on\na 401/403, split into the two blocks.\n\n**READ/SEARCH TOOL GRANTS** — required by the `sfcc` read tools. (`post` is OCAPI's\nconvention for its `*_search` endpoints, not a mutation.)\n\n```json\n{\n  \"client_id\": \"<your-client-id-here>\",\n  \"resources\": [\n    { \"resource_id\": \"/system_object_definitions\",    \"methods\": [\"get\"],         \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n    { \"resource_id\": \"/system_object_definitions/**\", \"methods\": [\"get\", \"post\"], \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n    { \"resource_id\": \"/site_preferences/**\",          \"methods\": [\"get\", \"post\"], \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n    { \"resource_id\": \"/custom_object_definitions/**\", \"methods\": [\"get\", \"post\"], \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" }\n  ]\n}\n```\n\n**MUTATION GRANTS** — required **only if you enable `BRIDGE_MCP_PROFILE=sfcc-write`**,\nwhich registers the nine destructive write tools. These are shipped capabilities, not\nfuture work. No `delete` is granted, because no shipped write tool performs one; the\n`get` entries are needed for the If-Match ETag round trip that precedes each `PATCH`.\n\n```json\n{\n  \"client_id\": \"<your-client-id-here>\",\n  \"resources\": [\n    { \"resource_id\": \"/system_object_definitions\",    \"methods\": [\"get\"],                  \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n    { \"resource_id\": \"/system_object_definitions/**\", \"methods\": [\"get\", \"put\", \"patch\"],  \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n    { \"resource_id\": \"/custom_object_definitions/**\", \"methods\": [\"get\", \"put\", \"patch\"],  \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n    { \"resource_id\": \"/site_preferences/**\",          \"methods\": [\"get\", \"patch\"],         \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" }\n  ]\n}\n```\n\nNotes:\n\n- The `client_id` **must match** the Account Manager API client whose credentials you\n  put in `dw.json` / `SFCC_*` below. Replace the value above with your own client id if\n  it differs.\n- If the Data API settings are empty, wrap the entries in the standard settings\n  envelope. Merge the resource lists from the block(s) above into one `resources`\n  array — do not substitute a global `\"resource_id\": \"/**\"` grant:\n\n  ```json\n  {\n    \"_v\": \"23.2\",\n    \"clients\": [\n      {\n        \"client_id\": \"<your-client-id-here>\",\n        \"resources\": [\n          { \"resource_id\": \"/system_object_definitions\",    \"methods\": [\"get\"],         \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n          { \"resource_id\": \"/system_object_definitions/**\", \"methods\": [\"get\", \"post\"], \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n          { \"resource_id\": \"/site_preferences/**\",          \"methods\": [\"get\", \"post\"], \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n          { \"resource_id\": \"/custom_object_definitions/**\", \"methods\": [\"get\", \"post\"], \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" }\n        ]\n      }\n    ]\n  }\n  ```\n\n- `check_permissions` (below) prints a ready-to-paste grant JSON on a 401/403, so you can\n  also let the tool tell you exactly what to add.\n\n## 2. Provide credentials locally\n\nCreate a `dw.json` in your project root (auto-added to git exclude — never commit it):\n\n```json\n{\n  \"hostname\": \"zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com\",\n  \"client-id\": \"<your-client-id-here>\",\n  \"client-secret\": \"<account-manager-client-secret>\"\n}\n```\n\nAccepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`,\n`client-secret`/`clientSecret`/`client_secret`. Prefer a single config — a multi-entry\n`configs[]` array forces an explicit `instance` on every call. Alternatively, export\n`SFCC_HOSTNAME` / `SFCC_CLIENT_ID` / `SFCC_CLIENT_SECRET` in the MCP server environment.\n\n## 3. Set the repo `version` config field\n\nSet the repo's `version` config to your SFCC project type — one of\n`sfra | pwakit | sitegenesis | storefrontnext | hybrid`. The call-time gate reads this;\na non-SFCC value blocks every SFCC tool except `sfcc_setup_status`. Set it via your\nnormal config path, the `config_field` MCP tool (operation `update`, field `version`),\nor the `/teach-bridge` skill.\n\n## 4. Enable the SFCC tools\n\nThe two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always\nregistered. Everything else is gated, behind **two independent profile groups**:\n\n| Group | Registers |\n|---|---|\n| `sfcc` | the 8 OCAPI read tools + `sfcc_log_query` — read-only |\n| `sfcc-write` | the 9 destructive write tools |\n\nNeither implies the other. Add what you need to `BRIDGE_MCP_PROFILE` in the MCP server\n`env` block (it is comma-separated), then **restart the MCP client**:\n\n```json\n\"env\": { \"BRIDGE_MCP_PROFILE\": \"sfcc\" }\n```\n\nFor reads plus writes, use `\"sfcc,sfcc-write\"`. `full` expands to every group and is\ntherefore write-capable.\n\n> **Migration.** `sfcc` used to register the nine write tools too. It no longer does.\n> If you were relying on SFCC writes through `BRIDGE_MCP_PROFILE=sfcc`, change it to\n> `BRIDGE_MCP_PROFILE=sfcc,sfcc-write`. `full` users keep write access and need no\n> change.\n\n## 5. Verify\n\nAsk your agent to run:\n\n1. `sfcc_setup_status` — expect all prerequisite checks ✓ (Bridge API key, repo name,\n   `version` config, `dw.json` presence/uniqueness, AM/OCAPI token acquisition).\n2. `check_permissions` — probes OCAPI via `GET /system_object_definitions`. A 200 (with\n   the OCAPI version) confirms the grant. On 401/403 it prints the exact grant JSON to\n   paste back in step 1.\n\nRestart the MCP client after any credential, grant, or env change — a running session\ndoes not pick them up.\n\n## Notes\n\n- **WebDAV logs are separate.** `sfcc_log_query` authenticates with a Business Manager\n  username + a 40-character **WebDAV access key** over HTTP Basic auth — *not* the OCAPI\n  OAuth token configured here. `sfcc_setup_status` reports OCAPI (step 5) and WebDAV\n  (step 6) independently; one can be green while the other is not.\n- **Writes are sandbox-only.** The write tools (attribute/preference create/update) target\n  a developer sandbox and echo a paste-ready grant JSON on a 403.\n"
+    "docs/install/sfcc-integration.md": "# Installing the SFCC Integration (OCAPI)\n\nBridge's Salesforce B2C Commerce (SFCC) tools give an AI coding agent read access to\na sandbox's object model, custom object definitions, and site preferences — plus a\nsmall set of sandbox-only writes — through the **OCAPI Data API**. This guide covers\nsetting up the OCAPI client that those tools authenticate against.\n\n> **Sandbox / local development only.** This integration is intended for a **developer\n> sandbox**, and that restriction is **enforced in code**: before any SFCC tool runs,\n> Bridge validates the hostname your credentials actually resolve to — from `dw.json`\n> or `SFCC_*` — against the sandbox forms listed below. An unrecognized host is refused\n> with a `403` (`error.code: \"TARGET_NOT_SANDBOX\"`) before any request leaves your\n> machine. The check reads the resolved hostname, never the `instance` tool argument,\n> so omitting `instance` or passing `\"sandbox\"` cannot bypass it.\n>\n> Accepted sandbox hostname forms:\n>\n> - `<realm>-<nnn>.sandbox.<region>.dx.commercecloud.salesforce.com`\n> - `<realm>-<nnn>.sandbox.dx.commercecloud.salesforce.com`\n> - `<realm>-<nnn>.dx.commercecloud.salesforce.com`\n>\n> Anything else — a `production-`/`staging-`/`development-` prefixed host, or any\n> `*.demandware.net` host — is rejected.\n>\n> Still do not configure the grants below on an instance that holds real data.\n> Credentials stay local (in `dw.json` or `SFCC_*` env vars) and are never sent to\n> Bridge.\n\nFor the full per-tool list and what each SFCC tool depends on, see\n[MCP Tool Integration Dependencies](./mcp-tool-integrations.md). For the tool reference\nand the `BRIDGE_MCP_PROFILE` gating, see the SFCC section of the\n[package README](../../README.md).\n\n## Prerequisites\n\n- A running SFCC **developer sandbox** and its hostname\n  (e.g. `zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com`).\n- An **Account Manager API client** — a `client-id` and `client-secret`. This is the\n  OCAPI client the tools use to obtain an OAuth token. Create one in Account Manager\n  (**API Client** → *Add API Client*) if you don't already have it, and note its\n  `client_id`.\n- Business Manager access to the sandbox with permission to edit **Open Commerce API\n  Settings**.\n\n## 1. Grant the OCAPI client access in Business Manager\n\nIn Business Manager for the sandbox:\n\n**Administration → Site Development → Open Commerce API Settings → Data API** tab.\n\nAdd the client entry below to the `clients` array of the Data API settings, then\n**Save**. It grants only the resource families and HTTP methods Bridge's SFCC tools\nactually call — not a global `/**` grant. `check_permissions` prints the same JSON on\na 401/403, split into the two blocks.\n\n**READ/SEARCH TOOL GRANTS** — required by the `sfcc` read tools. (`post` is OCAPI's\nconvention for its `*_search` endpoints, not a mutation.)\n\n```json\n{\n  \"client_id\": \"<your-client-id-here>\",\n  \"resources\": [\n    { \"resource_id\": \"/system_object_definitions\",    \"methods\": [\"get\"],         \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n    { \"resource_id\": \"/system_object_definitions/**\", \"methods\": [\"get\", \"post\"], \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n    { \"resource_id\": \"/site_preferences/**\",          \"methods\": [\"get\", \"post\"], \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n    { \"resource_id\": \"/custom_object_definitions/**\", \"methods\": [\"get\", \"post\"], \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" }\n  ]\n}\n```\n\n**MUTATION GRANTS** — required **only if you enable `BRIDGE_MCP_PROFILE=sfcc-write`**,\nwhich registers the nine destructive write tools. These are shipped capabilities, not\nfuture work. No `delete` is granted, because no shipped write tool performs one; the\n`get` entries are needed for the If-Match ETag round trip that precedes each `PATCH`.\n\n```json\n{\n  \"client_id\": \"<your-client-id-here>\",\n  \"resources\": [\n    { \"resource_id\": \"/system_object_definitions\",    \"methods\": [\"get\"],                  \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n    { \"resource_id\": \"/system_object_definitions/**\", \"methods\": [\"get\", \"put\", \"patch\"],  \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n    { \"resource_id\": \"/custom_object_definitions/**\", \"methods\": [\"get\", \"put\", \"patch\"],  \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n    { \"resource_id\": \"/site_preferences/**\",          \"methods\": [\"get\", \"patch\"],         \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" }\n  ]\n}\n```\n\nNotes:\n\n- The `client_id` **must match** the Account Manager API client whose credentials you\n  put in `dw.json` / `SFCC_*` below. Replace the value above with your own client id if\n  it differs.\n- If the Data API settings are empty, wrap the entries in the standard settings\n  envelope. Merge the resource lists from the block(s) above into one `resources`\n  array — do not substitute a global `\"resource_id\": \"/**\"` grant:\n\n  ```json\n  {\n    \"_v\": \"23.2\",\n    \"clients\": [\n      {\n        \"client_id\": \"<your-client-id-here>\",\n        \"resources\": [\n          { \"resource_id\": \"/system_object_definitions\",    \"methods\": [\"get\"],         \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n          { \"resource_id\": \"/system_object_definitions/**\", \"methods\": [\"get\", \"post\"], \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n          { \"resource_id\": \"/site_preferences/**\",          \"methods\": [\"get\", \"post\"], \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n          { \"resource_id\": \"/custom_object_definitions/**\", \"methods\": [\"get\", \"post\"], \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" }\n        ]\n      }\n    ]\n  }\n  ```\n\n- `check_permissions` (below) prints a ready-to-paste grant JSON on a 401/403, so you can\n  also let the tool tell you exactly what to add.\n\n## 2. Provide credentials locally\n\nCreate a `dw.json` in your project root (auto-added to git exclude — never commit it):\n\n```json\n{\n  \"hostname\": \"zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com\",\n  \"client-id\": \"<your-client-id-here>\",\n  \"client-secret\": \"<account-manager-client-secret>\"\n}\n```\n\nAccepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`,\n`client-secret`/`clientSecret`/`client_secret`. Prefer a single config — a multi-entry\n`configs[]` array forces an explicit `instance` on every call. Alternatively, export\n`SFCC_HOSTNAME` / `SFCC_CLIENT_ID` / `SFCC_CLIENT_SECRET` in the MCP server environment.\n\n## 3. Set the repo `version` config field\n\nSet the repo's `version` config to your SFCC project type — one of\n`sfra | pwakit | sitegenesis | storefrontnext | hybrid`. The call-time gate reads this;\na non-SFCC value blocks every SFCC tool except `sfcc_setup_status`. Set it via your\nnormal config path, the `config_field` MCP tool (operation `update`, field `version`),\nor the `/teach-bridge` skill.\n\n## 4. Enable the SFCC tools\n\nThe two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always\nregistered. Everything else is gated, behind **two independent profile groups**:\n\n| Group | Registers |\n|---|---|\n| `sfcc` | the 8 OCAPI read tools + `sfcc_log_query` — read-only |\n| `sfcc-write` | the 9 destructive write tools |\n\nNeither implies the other. Add what you need to `BRIDGE_MCP_PROFILE` in the MCP server\n`env` block (it is comma-separated), then **restart the MCP client**:\n\n```json\n\"env\": { \"BRIDGE_MCP_PROFILE\": \"sfcc\" }\n```\n\nFor reads plus writes, use `\"sfcc,sfcc-write\"`. `full` expands to every group and is\ntherefore write-capable.\n\n> **Migration.** `sfcc` used to register the nine write tools too. It no longer does.\n> If you were relying on SFCC writes through `BRIDGE_MCP_PROFILE=sfcc`, change it to\n> `BRIDGE_MCP_PROFILE=sfcc,sfcc-write`. `full` users keep write access and need no\n> change.\n\n## 5. Verify\n\nAsk your agent to run:\n\n1. `sfcc_setup_status` — expect all prerequisite checks ✓ (Bridge API key, repo name,\n   `version` config, `dw.json` presence/uniqueness, AM/OCAPI token acquisition).\n2. `check_permissions` — probes OCAPI via `GET /system_object_definitions`. A 200 (with\n   the OCAPI version) confirms the grant. On 401/403 it prints the exact grant JSON to\n   paste back in step 1.\n\nRestart the MCP client after any credential, grant, or env change — a running session\ndoes not pick them up.\n\n## Notes\n\n- **WebDAV logs are separate.** `sfcc_log_query` authenticates with a Business Manager\n  username + a 40-character **WebDAV access key** over HTTP Basic auth — *not* the OCAPI\n  OAuth token configured here. `sfcc_setup_status` reports OCAPI (step 5) and WebDAV\n  (step 6) independently; one can be green while the other is not.\n- **Writes are sandbox-only.** The write tools (attribute/preference create/update) target\n  a developer sandbox and echo a paste-ready grant JSON on a 403.\n",
+    "docs/bridge-ticket-authoring.md": "# Bridge ticket-authoring posture\n\nBridge has several surfaces that can create a ticket. Without a shared posture\neach one behaves differently, and the most-used surface carries none of the\nmaintainer's preferences at all. This document is the deep reference behind the\nshort posture block that every one of those surfaces carries verbatim.\n\nThe block itself is short on purpose — it competes for attention inside prompts\nthat are already long. Everything that explains *why* lives here.\n\n## The canonical block\n\nThis file **is** the canonical source. The marker-delimited block below is\nduplicated byte-identically onto every carrier — every surface that decides\nticket shape holds these exact bytes, so no surface can quietly drift into its\nown house style.\n\nCarriers (all four hold the block verbatim):\n\n- `agents/src/jira-ticket-writer.md` — the writer itself, plus a compressed\n  posture line in its `description:` frontmatter, which is the only coverage a\n  bare-chat session gets with no file read and no `tools/list` cost.\n- `commands/src/explore-ticket.md` — Stage 9, the most-used authoring surface.\n- `mcp_server/instructions/decompose-epic-candidate.md` — the `idea-to-ticket`\n  decomposition step.\n- `mcp_server/instructions/decompose-epic.md` — the `plan-epic` decomposition\n  step.\n\nEdit the block here, copy it verbatim to each carrier, and let\n`tests/pytest/mcp_server/test_ticket_authoring_posture_assets.py` prove it\nlanded. That test permits **no** per-surface variation.\n\n<!-- BEGIN BRIDGE TICKET-AUTHORING POSTURE -->\n<!-- Canonical source: docs/bridge-ticket-authoring.md.\n     This block is duplicated byte-identically onto every carrier. Never edit a\n     copy: edit the canonical source and re-copy it verbatim. A cross-surface\n     byte-equality test fails the build if any copy drifts by a single byte. -->\n\n## Ticket-authoring posture\n\nDeep reference: `docs/bridge-ticket-authoring.md`.\n\n**Draft through the writer.** Every ticket body — an epic parent, an epic child,\nand an ordinary sibling alike — is drafted by the `jira-ticket-writer` agent\nbefore `create_ticket` is called. Do not compose a ticket description inline.\n\n**Size the work.** Size each ticket by file-touch breadth and depth plus rough\nlines of code (LOC) changed:\n\n- `S = 1-2 files / <~80 LOC`\n- `M = ~3-8 files / ~80-400 LOC`\n- `L = ~8-15 files / ~400-900 LOC`\n- `XL = >15 files / >~900 LOC`\n\nTarget size priority: **L (target) -> XL (when the work does not fit in L) -> M\n(third choice) -> S (only when unavoidable)**. This applies equally to a\nstandalone ticket and to an epic child.\n\nAim each slice at L. When one will not fit, grow it to XL rather than splitting\nit — split only when the slice is genuinely two independent pieces of work,\nnever merely to land inside a band. Bridge's grooming and implementation process\nhandles a large vertical slice well and is overkill on small ones: every extra\nticket is another worktree, another PR, another rebase, and another chance for\ntwo workers to touch the same file. Reach for M because the work genuinely is\nthat size, not to avoid an XL.\n\nBeyond roughly 40 files or ~3000 LOC, split anyway. Past that point review\nturnaround and rebase cost dominate the run's budget, and a review that wedges\nholds the gate to its full retry ceiling before anyone notices.\n\n**Group at three.** Three or more implementable tickets is an epic: propose an\nepic parent plus an ordered child manifest, and resolve this surface's own\napproval gate before anything is created. One or two tickets are ordinary\nsiblings — no epic parent, no manifest. The threshold is exactly three.\n\n**Hand off once.** An epic handoff names exactly one conductor entry point,\n`drive-epic`, which selects the runnable path itself. Never present a choice\nbetween conductors.\n\n**Departure is closed-list only.** These three exceptions, and no others, permit\ndeparting from the rules above. Invoking one requires no announcement.\n\n- **E1 External-tracker mirroring** — a recorded upstream identifier exists and\n  its granularity is contractual. Bypasses sizing and the epic threshold.\n- **E2 Discovery-only spike** — no committed production-code deliverable.\n  Bypasses sizing only; does not bypass drafting through the writer.\n- **E3 Authorized incident containment** — tied to an active incident record,\n  not to schedule pressure. Bypasses sizing and the epic threshold.\n\nThe list is closed. Anything outside it is an escalation to the operator, not a\njudgement call. Explicitly refused as grounds for departure: a single-file\ntrivial fix (that is `S` reached through the normal path, not an exception),\ngeneric time pressure, \"already well specified\", \"faster without the writer\",\ndeveloper discretion, minor refactor, unattended mode, context limits, and \"hard\nto decompose\" (XL is the normal overflow, so that is the ordinary path and not a\ndeparture). Writer unavailability escalates; it never silently authorizes inline\ndrafting.\n\n<!-- END BRIDGE TICKET-AUTHORING POSTURE -->\n\nThe rest of this document is the rationale the block is deliberately too short to\ncarry.\n\n\n## The four rules\n\n### 1. Draft through `jira-ticket-writer`\n\nEvery ticket body is drafted by the `jira-ticket-writer` agent before\n`create_ticket` is called — an epic parent, an epic child, and an ordinary\nsibling alike. Nothing composes a ticket description inline.\n\nThe writer is not a formatter. It runs a codebase-research pass first, so its\ntickets cite the files, functions, and extension points a change actually\ntouches. A description written inline skips that pass, and the difference shows\nup two steps later: plan generation and implementation both ground themselves in\nthe ticket body, so a body with no code references produces a plan with no code\nreferences.\n\n\"The ticket is already well specified\" is not a reason to skip the writer. A\nwell-specified *request* is the writer's input, not a substitute for its output.\n\n### 2. Size toward L\n\nSize each ticket by file-touch breadth and depth plus rough lines of code\nchanged:\n\n| Band | Files | LOC |\n| --- | --- | --- |\n| `S` | 1–2 | `<~80` |\n| `M` | ~3–8 | ~80–400 |\n| `L` | ~8–15 | ~400–900 |\n| `XL` | >15 | `>~900` |\n\nPriority: **L (target) → XL (when the work does not fit in L) → M (third choice)\n→ S (only when unavoidable)**.\n\nThe target is L because the Bridge implementation tooling works best on\nindependently implementable vertical slices. What matters as much as the target\nis the **direction you move when a slice misses it**: upward, not downward.\n\nA slice that will not fit in L becomes **one XL ticket**, not two L ones. Split\nonly when the slice is genuinely two independent pieces of work — never merely to\nland inside a band. Fragmenting a coherent slice to fit is the failure this\nladder exists to prevent: every extra ticket is another worktree, another PR,\nanother rebase, and another chance for two workers to touch the same file, and\nBridge's grooming process is overkill on small tickets. Fewer, larger slices\nspend less of the run's budget on coordination.\n\nThis applies equally to a standalone ticket and to an epic child. There is no\nsize ceiling on a child that a lone ticket does not also have.\n\n`M` is where you land when the work genuinely is three to eight files — not\nsomewhere to retreat to in order to avoid an XL. `S` is likewise not forbidden:\nit is simply what you reach when the work genuinely is one or two files. A\nsingle-file trivial fix is `S` arrived at through the normal path. It is not an\nexception to anything, and it does not license skipping the writer.\n\n**Beyond roughly 40 files or ~3000 LOC, split anyway.** XL is the preferred\noverflow, not an unbounded one. Past that point review turnaround and rebase cost\ndominate the run's budget, and a review that wedges holds the gate to its full\nretry ceiling before anyone notices. That is a real bound, not a preference — and\nit is high enough that reaching it means the work really is two things.\n\n### 3. Group at three\n\nThree or more implementable tickets is an epic. The surface proposes an epic\nparent plus an **ordered child manifest**, and resolves its own approval gate\nbefore anything is created.\n\nOne or two tickets are ordinary siblings: no epic parent, no manifest. The\nthreshold is exactly three — not \"several\", not \"a lot\".\n\nThe manifest carries, per child: the boundary of its scope, its size band,\n`depends_on` (hard prerequisites that must land first), `recommended_after` (soft\nsequencing preferences that are not blockers), and a one-line order rationale.\nHard prerequisites and soft sequencing stay strictly separate, because the\nrecommended implementation order is derived from them and conflating the two\nproduces a serialized order where a parallel one was available.\n\nApproval follows each surface's **existing** attended/unattended rule. Nothing\nhere introduces a new gate policy: `/explore-ticket` requires an explicit\naffirmative because creation is irreversible, and the recipe path gates on the\npipeline's own auto-approval variable. What is *not* conditional is the grouping\nitself — an unattended run still produces the epic; only the gate's behavior\nvaries.\n\nDecomposition happens **once**. The pass that decides the split freezes the\nmanifest; body rendering then fans out one writer invocation per entry against\nthat frozen manifest. A rendering invocation may not re-split, merge, reorder,\nrenumber, or rescope. Two independent decisions about the same split disagree,\nand the disagreement surfaces as children that overlap or contradict their\nparent.\n\n### 4. Hand off to exactly one conductor\n\nAn epic handoff names exactly one conductor entry point: `drive-epic`.\n\nBridge currently has two conductors — the v2 server-side engine and the LLM\nconductor pilot — and a standing rule that they must never operate on the same\nepic, because two transition authorities on one epic wedge it permanently. Asking\na model to pick correctly every time is not a control. `drive-epic` makes the\nchoice structural instead: it reads conductor readiness and routes to the one\npath the project can actually run, so no prompt names either underlying conductor\nand no prompt can present both.\n\nTwo conductors is a transitional state. When one is eliminated, `drive-epic` is\nthe only thing that changes — no prompt, bundled doc, command mirror, or posture\ntest moves.\n\n## The closed exception list\n\nExactly three exceptions permit departing from the rules above. Invoking one\nrequires **no announcement** — the departure is silent by design, because a\nmandatory announcement would be one more instruction to drift from, and the cost\nof silence was weighed and accepted.\n\n| Id | Exception | Objective trigger | Bypasses |\n| --- | --- | --- | --- |\n| **E1** | External-tracker mirroring | A recorded upstream identifier exists and its granularity is contractual | Sizing and the epic threshold |\n| **E2** | Discovery-only spike | No committed production-code deliverable | Sizing only — **not** drafting through the writer |\n| **E3** | Authorized incident containment | Tied to an active incident record, not to schedule pressure | Sizing and the epic threshold |\n\nEach trigger is objective: an identifier that exists, a deliverable that is\nabsent, an incident record that is open. None of them is a judgement about how\nthe work feels.\n\n### The list is closed\n\nAnything outside the three rows above is an **escalation to the operator**, not a\njudgement call. The following are explicitly refused as grounds for departure:\n\n- a single-file trivial fix — that is `S` reached through the normal path;\n- generic time pressure;\n- \"the request is already well specified\";\n- \"it would be faster without the writer\";\n- developer discretion;\n- \"it's just a minor refactor\";\n- running unattended;\n- context limits;\n- \"this is hard to decompose\" — XL is the normal overflow, so that is the\n  ordinary path and not a departure.\n\n**Writer unavailability escalates.** It never silently authorizes inline\ndrafting. A surface that cannot reach `jira-ticket-writer` stops and says so.\n\n## Accepted trade-off: silent departure is unobservable\n\nObservability was deliberately dropped when this posture was ratified. A model\nmay invoke E1, E2, or E3 without recording that it did, so posture drift is only\ndetectable through ticket quality — not through a log, a counter, or a report.\n\nThis is known and accepted. The alternative was another mandatory instruction on\nevery surface, and an instruction that is skipped silently is worse than one that\ndoes not exist: it reads as coverage while providing none.\n\n## Why duplication, not a shared include\n\nCommands, agents, instructions, and docs have four separate build paths in this\nrepository and no shared compiler. Introducing a generated include step to share\none block would mean a fifth build path, a placeholder that can go unresolved,\nand a failure mode where a carrier ships with the placeholder text still in it.\n\nMarker-delimited duplication plus one byte-equality test is the right mechanism\nat this scale. The test reads the canonical sources directly — never the\ngenerated command mirrors, whose byte-identity the command tests already cover —\nand permits **no** per-surface variation. Any drift, down to a single byte, fails.\n\n## A fresh install inherits this\n\nNo configuration step, no server call. The posture reaches a new project through\nthe packaged bundles that `--init` scaffolds:\n\n- `COMMANDS` (`mcp_server/src/commands.generated.ts`) — carries\n  `commands/src/explore-ticket.md`;\n- `AGENTS` (`mcp_server/src/agents.generated.ts`) — carries\n  `agents/src/jira-ticket-writer.md`, including the compressed posture line in\n  its `description:` frontmatter;\n- `INSTRUCTIONS` (`mcp_server/src/pipelines.generated.ts`) — carries the\n  canonical source and both decomposition instructions;\n- `DOCS` (`mcp_server/src/docs.generated.ts`) — carries this document.\n\nThe compressed frontmatter line matters more than its size suggests: agent\ndescriptions land in every session's system prompt with no file read and no\n`tools/list` cost, so it is the entire bare-chat coverage story.\n\n## Worked examples\n\n**One ticket.** \"Add a `--json` flag to `doctor`.\" Two files and a test, ~90 LOC.\nThat is `M`. One ticket, drafted by the writer, no epic, no manifest, no\nconductor handoff.\n\n**Two tickets.** \"Add rate limiting to the LLM client, and surface the limit in\nthe config UI.\" Backend and frontend are independently implementable and land\nseparately: two ordinary siblings. Still no epic — the threshold is three.\n\n**Four tickets → an epic.** \"Make local ticket mode a first-class system.\"\nDecomposition freezes a parent plus four children, each `L`, with `depends_on`\nnaming the one child that must land first. The full manifest goes to the approval\ngate; on approval, four writer invocations render four bodies against their\nfrozen entries; creation follows `upload-epic-hierarchy.md`; the handoff names\n`drive-epic` and nothing else.\n\n**A child that outgrows `L`.** A proposed child comes out at 19 files. It ships\nas one `XL` child. Do not split it into two `L` children to make it fit — the\nslice is one coherent piece of work, and halving it buys a second worktree, a\nsecond PR, and a rebase between them in exchange for nothing. Split only if the\n19 files really are two independent deliverables.\n\n**Past the ceiling.** A proposed ticket comes out at 60 files and ~5000 LOC.\nThat is over the bound, so it splits — but into the largest coherent pieces\navailable, not into a swarm. Two `XL` tickets is the right answer here; six `M`\nones is not.\n"
 };

package/build/doctor.js

@@ -19,7 +19,7 @@ import { spawn } from "child_process";
 import os from "os";
 import path from "path";
 import { createDefaultStartTicketsDeps } from "./start-tickets.js";
-import { VERSION } from "./version.generated.js";
+import { VERSION, BUILD_COMMIT } from "./version.generated.js";
 import { collectInstallStatusChecks, formatInstallStatusReport, formatInstallStatusFallbackReport, resolveInstallDoctorTarget, } from "./install-doctor.js";
 import { inspectExecutorAgentAdapter, inspectionForFailedResolution, } from "./agent-launchers/executor-adapter-inspection.js";
 import { resolveExecutorAgentAdapter } from "./agent-launchers/executor-adapter-registry.js";
@@ -224,6 +224,14 @@ export function buildDoctorReportHeader(platform, agent) {
     const activeGroups = Array.from(resolveProfiles(process.env.BRIDGE_MCP_PROFILE)).join(", ");
     return [
         DOCTOR_REPORT_TITLE,
+        // BAPI-873: doctor now names the build it is diagnosing. Both values are
+        // GENERATED constants — doctor runs no git subprocess and reads no
+        // repository state to report them, which keeps it read-only. `Build commit`
+        // renders the literal `unknown` when the build had no git metadata; it is
+        // never blank and never omitted. Neither line feeds launcher-pin drift,
+        // which stays a `VERSION`-only comparison.
+        `Package version: ${VERSION}`,
+        `Build commit: ${BUILD_COMMIT}`,
         `Platform: ${platform}`,
         `Selected agent: ${agent.name} (command: ${agent.command})`,
         `Active MCP Groups: \`${activeGroups}\``,
@@ -597,8 +605,10 @@ export function formatLauncherCacheReport(inspections) {
 // `BAPI_MCP_CLI` lets a packaged command shell out to a LOCAL build instead of
 // `npx -y @bridge_gpt/mcp-server`, so an executor or CLI change can be verified
 // before an npm publish. That is useful precisely because it is invisible: the
-// override lives in one environment variable, and `ping` cannot tell a published
-// 0.2.x from a local build at the same version. This section makes it visible.
+// override lives in one environment variable. Since BAPI-873 the build commit
+// reported above does distinguish a published 0.2.x from a local build at the
+// same version — but it identifies THIS process, not the launcher a packaged
+// command would shell out to, so an override still needs naming here.
 //
 // The probe is deliberately narrow. It runs the configured launcher ONCE with a
 // single appended `--version` argument, through the injected array-based command

package/build/drive-epic.js

@@ -0,0 +1,375 @@
+/**
+ * `drive-epic` — the one universal conductor entry point (BAPI-887).
+ *
+ * Bridge 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.
+ *
+ *   - **v2 engine** — bootstrapped by `setup-epic`, which creates a durable
+ *     `epic_run` row, stores a plan DAG, and approves it.
+ *   - **LLM-conductor pilot** — `/loop 5m /conduct-epic <EPIC>`, which creates no
+ *     run row and keeps its whole memory in a local checkpoint plus GitHub.
+ *
+ * Asking a prompt to pick correctly every time is not a control. This subcommand
+ * makes the choice STRUCTURAL: it reads server-side conductor readiness and
+ * routes to exactly one path, so no prompt names either underlying conductor and
+ * no prompt can present both. Every ticket-authoring surface hands off to
+ * `drive-epic` and to nothing else.
+ *
+ * ## The output invariant
+ *
+ * Every branch — including every error path — emits **at most one** conductor
+ * invocation. An escalation carries NO alternative conductor command: "v2 failed,
+ * try the pilot instead" is precisely the dual-authority hazard this subcommand
+ * exists to remove. {@link assertSingleConductorInvocation} enforces this on the
+ * way out rather than trusting each branch to have got it right.
+ *
+ * ## Three-state routing, fail-closed
+ *
+ *   - readiness green            -> delegate to the `setup-epic` (v2) flow
+ *   - readiness read, not green  -> print the pilot instruction
+ *   - readiness UNKNOWN          -> escalate to the operator, print no conductor
+ *
+ * Unknown is never treated as not-ready, and selection never happens by
+ * exception handling. An unreachable, unauthorized, or malformed readiness
+ * response means we do not know which authority owns this epic, and guessing is
+ * the failure mode.
+ *
+ * ## Consolidation day
+ *
+ * Two conductors is a transitional state; one is to be eliminated at the end of
+ * the current evaluation period. Consolidation is:
+ *
+ *   1. set {@link DRIVE_EPIC_PREFERRED_CONDUCTOR} to the surviving conductor;
+ *   2. delete the losing branch in {@link renderConductorHandoff}.
+ *
+ * No prompt, bundled doc, command mirror, or posture test changes as a result —
+ * that is the whole reason the duality is confined to this one subcommand and
+ * this one constant. Epics already assigned to the eliminated conductor must be
+ * drained first; that drain is a conductor-lifecycle concern outside this file.
+ *
+ * No MCP tool is registered here. The `tools/list` token budget is deliberately
+ * ratcheted down, and a tool would be useless in a bare-chat session anyway,
+ * where the model has no tool call to make.
+ */
+import { resolveConductorBridgeApiAccess, fetchConductorReadiness, safeDiagnosticMessage, } from "./conductor/bridge-api-client.js";
+import { runSetupEpicCli } from "./setup-epic.js";
+// BAPI-806: mcp-identity.ts is the SOLE source of the package-name literal, so
+// the printed invocation interpolates it rather than repeating it.
+import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
+/** Jira epic key shape. Matches `conduct-epic`'s positional rule exactly. */
+const EPIC_KEY_PATTERN = /^[A-Z]+-[0-9]+$/;
+/** The two conductor paths. Derived types below come from this constant. */
+export const DRIVE_EPIC_CONDUCTORS = ["v2", "pilot"];
+/**
+ * THE consolidation-day edit point.
+ *
+ * When readiness is green, v2 is preferred and the pilot is the fallback for
+ * projects that cannot run it. This is expressed as one named constant rather
+ * than as branching scattered through the routing logic precisely so that
+ * eliminating a conductor is a one-line change plus one deleted branch.
+ */
+export const DRIVE_EPIC_PREFERRED_CONDUCTOR = "v2";
+/**
+ * The v2 readiness predicate, as a list so a failure can name what is missing.
+ *
+ * These are the facts v2 actually needs to drive an epic: a stored supervisor
+ * posture, a reconciler that is ticking, a provisioned and live executor, and
+ * complete GitHub App credentials. Each is read from the SERVER's report and
+ * never re-derived locally — two implementations of one classification drift,
+ * and a CLI that disagreed with the server about whether v2 can run would be
+ * worse than no check at all.
+ */
+export const V2_READINESS_REQUIREMENTS = [
+    {
+        id: "supervisor_setup",
+        describe: "supervisor setup stored for this repository",
+        satisfied: (r) => r.supervisor.setup_present,
+    },
+    {
+        id: "supervisor_config",
+        describe: "supervisor configuration stored for this repository",
+        satisfied: (r) => r.supervisor.config_present,
+    },
+    {
+        id: "github_credentials",
+        describe: "GitHub App credentials that resolve completely",
+        satisfied: (r) => r.github.credentials_complete,
+    },
+    {
+        id: "reconciler_live",
+        describe: "a reconciler that is ticking and not stale",
+        satisfied: (r) => r.reconciler.liveness_readable && !r.reconciler.stale,
+    },
+    {
+        id: "executor_live",
+        describe: "an executor provisioned and reporting ready",
+        satisfied: (r) => r.executor.liveness_readable && r.executor.ready === true,
+    },
+];
+export function getDriveEpicUsage() {
+    return [
+        "Usage: mcp-server drive-epic [options] <EPIC>",
+        "",
+        "Drives one epic with the conductor this project can actually run. Reads",
+        "conductor readiness from Bridge API and routes to exactly one path — it",
+        "never asks you to choose.",
+        "",
+        "Arguments:",
+        "  <EPIC>                 Jira epic key, matches [A-Z]+-[0-9]+ (e.g. BAPI-885)",
+        "",
+        "Options:",
+        "  --plan-file <path>     Plan DAG sidecar. When supplied and the v2 path is",
+        "                         selected, drive-epic runs that bootstrap directly",
+        "                         instead of printing the command to run.",
+        "  --repo <name>          Repo name (default: BAPI_REPO_NAME or .bridge/config)",
+        "  -h, --help             Show this help",
+    ].join("\n");
+}
+/**
+ * Parse argv. Rejects malformed input BEFORE any side effect — no readiness
+ * read, no credential resolution, no delegation.
+ */
+export function parseDriveEpicArgs(argv) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        return { status: "help", usage: getDriveEpicUsage() };
+    }
+    const positionals = [];
+    let planFile;
+    let repo;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--plan-file" || arg === "--repo") {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("-")) {
+                return { status: "error", message: `${arg} requires a value.` };
+            }
+            if (arg === "--plan-file")
+                planFile = value;
+            else
+                repo = value;
+            i++;
+            continue;
+        }
+        const eq = arg.match(/^(--plan-file|--repo)=(.*)$/);
+        if (eq) {
+            const value = eq[2];
+            if (value.trim().length === 0) {
+                return { status: "error", message: `${eq[1]} requires a value.` };
+            }
+            if (eq[1] === "--plan-file")
+                planFile = value;
+            else
+                repo = value;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            return { status: "error", message: `Unsupported flag: ${arg}` };
+        }
+        positionals.push(arg);
+    }
+    if (positionals.length === 0) {
+        return { status: "error", message: "Missing required epic key." };
+    }
+    if (positionals.length > 1) {
+        // Rejected rather than ignored: a second positional means the caller
+        // believes something we did not parse, and driving the wrong epic is not
+        // recoverable by re-reading the output.
+        return {
+            status: "error",
+            message: `Expected exactly one epic key, got ${positionals.length}: ${positionals.join(", ")}`,
+        };
+    }
+    const epicKey = positionals[0];
+    if (!EPIC_KEY_PATTERN.test(epicKey)) {
+        return { status: "error", message: `Malformed epic key '${epicKey}'. Expected e.g. BAPI-885.` };
+    }
+    const options = { epicKey, ...(planFile ? { planFile } : {}), ...(repo ? { repo } : {}) };
+    return { status: "ok", options };
+}
+/**
+ * Route a readiness report to exactly one conductor.
+ *
+ * Pure and total: it takes the already-read report and always returns a
+ * decision. The unknown case is produced by the caller, which is the only place
+ * that can observe a failed read — selection itself never happens by exception
+ * handling, and so never needs to report that it could not decide.
+ */
+export function selectConductor(readiness) {
+    const missing = V2_READINESS_REQUIREMENTS.filter((req) => !req.satisfied(readiness));
+    if (missing.length === 0) {
+        return {
+            kind: "selected",
+            conductor: DRIVE_EPIC_PREFERRED_CONDUCTOR,
+            reason: "conductor readiness is green",
+        };
+    }
+    return {
+        kind: "selected",
+        conductor: "pilot",
+        reason: `the engine path still needs ${missing.map((m) => m.describe).join("; ")}`,
+    };
+}
+/**
+ * Render the selected path and only the selected path.
+ *
+ * Precondition: the caller has already ruled out delegation. The `v2` branch
+ * reads as "green, but no plan file was supplied", which is only true once
+ * {@link runDriveEpicCli} has declined to delegate — so route first, render
+ * second.
+ *
+ * CONSOLIDATION DAY: delete the branch of the conductor being eliminated and
+ * point {@link DRIVE_EPIC_PREFERRED_CONDUCTOR} at the survivor. Nothing outside
+ * this file moves.
+ */
+export function renderConductorHandoff(selection, epicKey) {
+    if (selection.conductor === "v2") {
+        const invocation = `npx -y ${MCP_PACKAGE_NAME} drive-epic ${epicKey} --plan-file <path>`;
+        return {
+            conductor: "v2",
+            invocation,
+            lines: [
+                `${epicKey}: ${selection.reason}, but no plan file was supplied.`,
+                "",
+                "The engine path needs a plan DAG, and nothing derives one from an epic key:",
+                "the dependency edges and per-ticket touched_files it carries do not exist",
+                "anywhere else. Produce one, then re-run this command with it.",
+                "",
+                `  1. Run /plan-epic ${epicKey} in an interactive session. It writes the`,
+                "     sidecar to {docs_dir}/epic-plans/{epic_slug}/epic-plan.dag.json.",
+                "     If the epic's tickets already exist, run emit-conductor-bundle",
+                "     finalize instead — it resolves the placeholder keys in an existing",
+                "     sidecar and attaches touched_files.",
+                "",
+                `  2. ${invocation}`,
+                "",
+                `That second command bootstraps the run for you; ${SETUP_EPIC_SUBCOMMAND} is not`,
+                "something you invoke directly.",
+            ],
+        };
+    }
+    const invocation = `/loop 5m /conduct-epic ${epicKey}`;
+    return {
+        conductor: "pilot",
+        invocation,
+        lines: [
+            `${epicKey}: ${selection.reason}. Drive it from an interactive session with:`,
+            "",
+            `  ${invocation}`,
+        ],
+    };
+}
+/**
+ * Tokens that identify a conductor path in user-facing output. Used by the
+ * output guard and by its test — one list, so a new spelling cannot be added to
+ * the renderer without the guard seeing it.
+ */
+export const CONDUCTOR_INVOCATION_TOKENS = ["setup-epic", "conduct-epic"];
+/** The v2 token, named once so prose and the guard cannot drift apart. */
+const SETUP_EPIC_SUBCOMMAND = CONDUCTOR_INVOCATION_TOKENS[0];
+/**
+ * Fail closed if a rendered branch names more than one conductor.
+ *
+ * This is a guard, not decoration: the whole value of a single entry point is
+ * that a reader is never handed a choice, and a well-meaning "you could also
+ * try..." line added later would silently reintroduce the dual-authority
+ * hazard. Checking on the way out costs nothing and cannot be forgotten.
+ */
+export function assertSingleConductorInvocation(text) {
+    const named = CONDUCTOR_INVOCATION_TOKENS.filter((token) => text.includes(token));
+    if (named.length > 1) {
+        throw new Error(`drive-epic emitted more than one conductor invocation (${named.join(", ")}). ` +
+            "Exactly one path may ever be presented.");
+    }
+}
+export function createDefaultDriveEpicDeps() {
+    return {
+        resolveAccess: async (repo) => {
+            const result = await resolveConductorBridgeApiAccess(repo ? { repoName: repo } : {});
+            return result.ok ? { ok: true, access: result.access } : { ok: false, error: result.error };
+        },
+        readReadiness: (access) => fetchConductorReadiness(access, globalThis.fetch),
+        runSetupEpic: (argv) => runSetupEpicCli(argv),
+        // stdout is safe here: `drive-epic` is dispatched BEFORE MCP server
+        // construction, so nothing has claimed stdout for the protocol transport.
+        log: (message) => console.log(message),
+        errorLog: (message) => console.error(message),
+    };
+}
+/**
+ * Run the CLI. Returns `0` on a successful handoff and `1` on any validation,
+ * readiness, prerequisite, or execution failure. Never throws: the caller
+ * dispatches this at module top level, where an escaping exception would take
+ * down the process before any diagnostic reached the operator.
+ */
+export async function runDriveEpicCli(argv, overrides = {}) {
+    const deps = { ...createDefaultDriveEpicDeps(), ...overrides };
+    const parsed = parseDriveEpicArgs(argv);
+    if (parsed.status === "help") {
+        deps.log(parsed.usage);
+        return 0;
+    }
+    if (parsed.status === "error") {
+        deps.errorLog(parsed.message);
+        deps.errorLog("");
+        deps.errorLog(getDriveEpicUsage());
+        return 1;
+    }
+    const { epicKey, planFile, repo } = parsed.options;
+    try {
+        // --- Resolve access. A missing credential is UNKNOWN, not not-ready. -----
+        const accessResult = await deps.resolveAccess(repo);
+        if (!accessResult.ok) {
+            return escalate(deps, epicKey, `conductor readiness could not be read: ${accessResult.error}`);
+        }
+        // --- Read readiness. Any failure here is UNKNOWN. ------------------------
+        let readiness;
+        try {
+            readiness = await deps.readReadiness(accessResult.access);
+        }
+        catch (err) {
+            return escalate(deps, epicKey, `conductor readiness could not be read: ${safeDiagnosticMessage(err, "readiness request failed")}`);
+        }
+        // --- Route. Exactly one path from here on. -------------------------------
+        const selection = selectConductor(readiness);
+        // Decide delegation BEFORE rendering. The v2 branch's text is specifically
+        // about a missing plan file, and rendering it on the path that has one
+        // would produce a message contradicting what is about to happen.
+        if (selection.conductor === "v2" && planFile) {
+            // Delegate. `setup-epic` owns branch, run-row, plan, and approval
+            // behavior; drive-epic reimplements none of it and prints nothing of its
+            // own alongside it, so its output remains the only conductor output.
+            const setupArgv = ["--epic-key", epicKey, "--plan-file", planFile, ...(repo ? ["--repo", repo] : [])];
+            return await deps.runSetupEpic(setupArgv);
+        }
+        const handoff = renderConductorHandoff(selection, epicKey);
+        const text = handoff.lines.join("\n");
+        assertSingleConductorInvocation(text);
+        deps.log(text);
+        return 0;
+    }
+    catch (err) {
+        // Last resort. Sanitized, on stderr, converted to an exit code — a
+        // credential must never reach this line, and a stringified unknown is
+        // exactly how one escapes.
+        deps.errorLog(`drive-epic failed: ${safeDiagnosticMessage(err, "unexpected error")}`);
+        return 1;
+    }
+}
+/**
+ * The escalation branch. Prints NO conductor invocation at all — naming a
+ * fallback here is the dual-authority hazard, and an operator who does not know
+ * which authority owns an epic must not be nudged toward either one.
+ */
+function escalate(deps, epicKey, reason) {
+    const lines = [
+        `Cannot determine which conductor owns ${epicKey}: ${reason}`,
+        "",
+        "This is not a not-ready result — it is an unknown one, and starting the wrong",
+        "conductor on an epic wedges it permanently. Restore Bridge API access and run",
+        "drive-epic again, or ask an operator to resolve conductor readiness.",
+    ];
+    const text = lines.join("\n");
+    assertSingleConductorInvocation(text);
+    deps.errorLog(text);
+    return 1;
+}

package/build/executor/http-client.js

@@ -34,6 +34,45 @@ function parseStopRequested(bodyText) {
         return false;
     }
 }
+/**
+ * The claim response header carrying server-derived dispatcher liveness
+ * (BAPI-871). Exported so the client and its tests name it once.
+ */
+export const RECONCILER_LIVENESS_HEADER = "X-BAPI-Reconciler-Liveness";
+/** The only values the server is documented to send. */
+const RECONCILER_LIVENESS_VALUES = [
+    "fresh",
+    "stale",
+    "never_seen",
+    "unknown",
+];
+/**
+ * Read the liveness header off a claim response, admitting ONLY documented
+ * values.
+ *
+ * Absent, blank, or unrecognized all map to `unknown` — the compatibility path.
+ * An executor talking to a backend from before this header existed must keep
+ * claiming exactly as it did, and "I have no verdict" is what `unknown` means.
+ * A value the server never promised is treated the same way rather than being
+ * passed through: an unrecognized string reaching the runner's availability
+ * logic could silently become a fifth state nobody handles.
+ *
+ * Header lookup is case-insensitive via `Headers.get`, which is required by the
+ * spec — HTTP header names are not case-sensitive, and proxies do re-case them.
+ */
+export function parseReconcilerLivenessHeader(headers) {
+    let raw = null;
+    try {
+        raw = headers.get(RECONCILER_LIVENESS_HEADER);
+    }
+    catch {
+        return "unknown";
+    }
+    const value = (raw ?? "").trim().toLowerCase();
+    return RECONCILER_LIVENESS_VALUES.includes(value)
+        ? value
+        : "unknown";
+}
 /**
  * Map a mutation (heartbeat/complete/fail) HTTP response onto the fencing
  * outcome. `allowInvalidResult` maps 422 to `invalid_job_result` (complete only).
@@ -68,7 +107,9 @@ export function createExecutorHttpClient(config) {
             body: JSON.stringify(body),
         });
         const text = await res.text();
-        return { status: res.status, text };
+        // `headers` is surfaced (optional, so the many response fakes that omit it
+        // stay assignable) purely for the claim path's liveness annotation.
+        return { status: res.status, text, headers: res.headers };
     }
     async function mutate(pathSuffix, body, allowInvalidResult, repoName) {
         try {
@@ -85,24 +126,33 @@ export function createExecutorHttpClient(config) {
         async claim(manifest) {
             let status;
             let text;
+            let reconcilerLiveness = "unknown";
             try {
                 const res = await post("/claim", manifest, manifest.repo_name);
                 status = res.status;
                 text = res.text;
+                // Parsed on EVERY response, then attached only to the successful
+                // variants below. A response fake that omits `headers` degrades to
+                // `unknown` rather than throwing.
+                if (res.headers)
+                    reconcilerLiveness = parseReconcilerLivenessHeader(res.headers);
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
                 return { kind: "retryable", error: `claim network error: ${boundedDetail(message)}` };
             }
+            // Both successful outcomes carry the verdict. Nothing about the liveness
+            // value changes the classification below: a 204 is still "no job", and the
+            // retryable/fatal split is untouched.
             if (status === 204)
-                return { kind: "none" };
+                return { kind: "none", reconcilerLiveness };
             if (status === 200) {
                 try {
                     const job = JSON.parse(text);
                     if (!job || typeof job !== "object" || typeof job.claim_token !== "string") {
                         return { kind: "fatal", error: "claim returned a malformed job payload" };
                     }
-                    return { kind: "claimed", job };
+                    return { kind: "claimed", job, reconcilerLiveness };
                 }
                 catch {
                     return { kind: "fatal", error: "claim returned invalid JSON" };
@@ -142,6 +192,24 @@ export function createExecutorHttpClient(config) {
                 result.stop_requested = true;
             return result;
         },
+        /**
+         * Publish per-process liveness (BAPI-871).
+         *
+         * Authenticated with the manifest's PRIMARY repo key. The server verifies
+         * every entry in `repo_names` before writing anything, so a key that does not
+         * hold one of them gets a 4xx — reported here as `failed` and nothing more.
+         * Delivery is non-critical monitoring: it never throws, never classifies a
+         * fencing outcome, and never stops the caller from claiming or running work.
+         */
+        async processHeartbeat(request) {
+            try {
+                const { status, text } = await post("/process-heartbeat", request, request.repo_names[0] ?? "");
+                return status >= 200 && status < 300 && isOkBody(text) ? "delivered" : "failed";
+            }
+            catch {
+                return "failed";
+            }
+        },
         complete(job, completion) {
             return mutate(`/${job.id}/complete`, {
                 repo_name: job.repo_name,

package/build/executor/job-errors.js

@@ -20,6 +20,14 @@
  *    opened a PR whose base branch is not the run base, so `claude-review.yml`
  *    (triggered only on `branches: [main]`) never fires and the `code_review`
  *    gate would hang forever; see `worker-finalization.ts`.
+ *  - `WorkerFinalizationPrNotAttached` — an implementation-style job (BAPI-862)
+ *    exited cleanly and its exact HEAD is durable on origin, but no usable pull
+ *    request exists for that branch: none is visible, its URL is blank, its
+ *    description is blank (BAPI-824 folded in), or it does not yet carry the
+ *    pushed head. The work is COMPLETE and PUSHED — only the attachment is
+ *    missing — so this kind is deliberately distinct from every other
+ *    finalization failure, and its guidance names attachment and warns against
+ *    deleting or rebasing the branch; see `worker-finalization.ts`.
  *  - `WorkerFinalizationSavedButUnfinalized` — an implementation-style job
  *    (BAPI-762) exited cleanly, and an origin branch exists at an authoritative
  *    tip that does NOT match the worker's own HEAD — durable work exists on
@@ -98,6 +106,7 @@ export const WorktreeLostBeforePush = "WorktreeLostBeforePush";
 export const BranchMismatch = "BranchMismatch";
 export const WorkerFinalizationMissingRemoteBranchAndPr = "WorkerFinalizationMissingRemoteBranchAndPr";
 export const WorkerFinalizationPrBaseMismatch = "WorkerFinalizationPrBaseMismatch";
+export const WorkerFinalizationPrNotAttached = "WorkerFinalizationPrNotAttached";
 export const WorkerFinalizationSavedButUnfinalized = "WorkerFinalizationSavedButUnfinalized";
 export const WorkerConfigIsolation = "ContractError.WorkerConfigIsolation";
 export const PreSpawnVerification = "ContractError.PreSpawnVerification";