@bridge_gpt/mcp-server 0.2.69 → 0.2.70

package/README.md

@@ -410,7 +410,7 @@ later boot.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.69", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.70", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -432,7 +432,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.69", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.70", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -454,7 +454,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.69", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.70", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -477,7 +477,7 @@ Windsurf only supports global MCP configuration.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.69", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.70", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -496,7 +496,7 @@ Windsurf only supports global MCP configuration.
 ```toml
 [mcp_servers.bridge]
 command = "npx"
-args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.69", "serve"]
+args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.70", "serve"]
 
 [mcp_servers.bridge.env]
 BAPI_BASE_URL = "https://bridgegpt-api.com"
@@ -1099,74 +1099,26 @@ Attribute-definition reads and writes can return an attribute's `default_value`
 
 ## Epic Implementer
 
-The Epic Implementer drives a whole epic, several related tickets, from an
-approved plan to merged pull requests. It hands each child ticket to an agent on
-your machine, waits for CI and code review, and merges each child PR into an
-`epic/<KEY>` branch. A person merges the final pull request into your default
-branch.
+The Epic Implementer drives a whole epic, several related tickets, from an approved plan to merged pull requests. It hands each child ticket to an agent on your machine, waits for CI and code review, and merges each child PR into an `epic/<KEY>` branch. A person merges the final pull request into your default branch.
 
-By default a run with two or more tickets is **unattended**: it merges child
-PRs on its own. `--attended` opts out.
+This is the one starting point. The same four steps work with Bridge's own ticket storage and with Jira:
 
-**What it requires**
+1. **Install.** `npx -y @bridge_gpt/mcp-server install` (skip it when Bridge is already installed).
+2. **Set up.** `npx -y @bridge_gpt/mcp-server install conductor` checks everything, fixes what is missing, checks again, and ends with one verdict: "Ready for your first epic" or "Not ready: N steps left".
+3. **Define the epic.** `/define-tickets` writes real child ticket keys, `epic-plan.dag.json`, and `epic-plan.meta.json`.
+4. **Launch.** `/drive-epic-run <EPIC> [<plan path>]` previews, asks you once, creates the run through `drive-epic`, and drives it. From a shell, run `npx -y @bridge_gpt/mcp-server drive-epic <EPIC>`.
 
-- macOS or Linux, with `git`, the GitHub CLI (`gh`, logged in), the Claude Code
-  CLI (`claude`, logged in), and Worktrunk (`wt`) on your `PATH`.
-- Bridge installed in the repository, and the Bridge GitHub App connected.
-- The repository's Epic Implementer defaults, including the CI check each
-  ticket must pass (`install conductor`). For unattended runs, that check must
-  be a job in one of the two workflow files below, for example
-  `epic-implementer-ci / gate`.
-- `.github/workflows/claude-review.yml` and
-  `.github/workflows/epic-implementer-ci.yml` on your default branch, then the
-  repository indexed (or re-indexed) after they merge. The epic branch is cut
-  from the indexed commit.
-- For unattended runs: an escalation channel (the account email, or a webhook)
-  and a merge credential in `BAPI_LOCAL_MERGE_TOKEN`.
+**Read the guide: [Run your first epic](./docs/epic-implementer/getting-started.md).** It lists every prerequisite with its fix. `install` also copies it into your project at `docs/install/epic-implementer-install.md`, so you can ask your agent:
 
-**How to set it up**
+> Set up the Epic Implementer by following `docs/install/epic-implementer-install.md`. Run `npx -y @bridge_gpt/mcp-server install` to write or refresh that file.
 
-The easy way is to ask your agent:
+Setup needs macOS or Linux, with `git`, the GitHub CLI (`gh`, signed in), the Claude Code CLI (`claude`, signed in), and Worktrunk (`wt`) on your `PATH`. By default a run with two or more tickets is **unattended**: it merges child PRs into the epic branch on its own. `--attended` opts out.
 
-> Set up the Epic Implementer by following `docs/install/epic-implementer-install.md`.
+Merging child PRs needs a GitHub token. Setup can store one for this repository on your computer, under `github-merge:<host>/<owner>/<repo>` in your user credential store. `GITHUB_MERGE_TOKEN` still takes precedence when it is set.
 
-`install` copies that guide into your project. It is also in this package as
-[EPIC-IMPLEMENTER-INSTALL.md](./docs/EPIC-IMPLEMENTER-INSTALL.md). It checks
-each step, asks before anything that writes, and tells you which commands you
-must run yourself.
+`/plan-epic` is the advanced planner. It writes placeholder `TBD-N` keys, so you create the child tickets and run `emit-epic-implementer-bundle finalize` before `/drive-epic-run`. It never creates or approves a run.
 
-By hand, the outline is:
-
-```bash
-npx -y @bridge_gpt/mcp-server install                                   # if Bridge is not installed yet
-npx -y @bridge_gpt/mcp-server connect-github --repo <repo_name>         # connect the GitHub App
-npx -y @bridge_gpt/mcp-server install conductor --required-check "epic-implementer-ci / gate" \
-  --review-policy verdict_protocol \
-  --allowed-bot "<bot>" --secret-name <SECRET_NAME> --branches "<default branch>,epic/**"   # AI review is opt-in; omit all four to skip the claude-review workflow
-export BAPI_LOCAL_MERGE_TOKEN="$(gh auth token)"                        # in the shell that runs drive-epic
-npx -y @bridge_gpt/mcp-server epic-implementer readiness --json         # read-only check of every prerequisite
-```
-
-After `install conductor`, restart your MCP client so the Epic Implementer tools
-appear. Add `epic-implementer-ci.yml` (the guide has a template) and the
-`claude-review.yml` that `install conductor` wrote (only when you opted in to AI review with `--review-policy verdict_protocol`), through a pull request into
-your default branch. Once it merges, index the repository with
-`/parse-repository`.
-
-**How to run an epic**
-
-1. `/plan-epic <EPIC>` splits an existing epic ticket into child tickets and
-   writes a plan (`epic-plan.dag.json`). Its last step creates and approves an
-   unattended run.
-2. `/drive-epic-run <EPIC> [<plan path>]` previews, asks you once, starts the
-   run, and watches it to the end. It takes no flags. For `--attended` or
-   `--policy-file <path>`, use the shell instead:
-   `npx -y @bridge_gpt/mcp-server drive-epic <EPIC> --plan-file <path> [--attended]`.
-3. Monitor with the `get_epic_snapshot` and `explain_run` MCP tools, or
-   `npx -y @bridge_gpt/mcp-server notifications --repo <repo_name> --run <EPIC> --follow`.
-
-See [The Epic Implementer](#the-epic-implementer) for every command, and
-[EPIC-IMPLEMENTER.md](./docs/EPIC-IMPLEMENTER.md) for the full reference.
+See [The Epic Implementer](#the-epic-implementer) for what each command is for, and [EPIC-IMPLEMENTER.md](./docs/EPIC-IMPLEMENTER.md) for the full reference.
 
 ## CLI Subcommands
 
@@ -1276,9 +1228,19 @@ onboarding/API setup, and Windsurf are outside packaged repair.
 The package also ships a strictly **read-only** `doctor` subcommand — titled **`bridge doctor — read-only diagnostics`** — that diagnoses your whole Bridge install without changing anything:
 
 ```
-npx -y @bridge_gpt/mcp-server doctor [--agent <name>]
+npx -y @bridge_gpt/mcp-server doctor [--agent <name>] [--advanced]
 ```
 
+By default `doctor` works on a repository in any language: it makes **no `uv`,
+Alembic, or Python call**. `--advanced` adds the Python and self-host
+diagnostics — the `uv` check and the local plane credential section — for
+bridge-api and self-hosting owners.
+
+Right after `Install status`, a **Getting started** section shows the two
+sign-ins a first epic needs: your Claude sign-in (it reads only `~/.claude.json`)
+and your GitHub CLI sign-in (one `gh auth status`, ten seconds at most). Each one
+that is not ready names its one fix. It never changes the exit code.
+
 The report always leads with the advisory **`Install status`** section (repo identity, credential resolution, server connectivity, bootstrap-field completeness, integration credentials, indexing state) **before** the `start-tickets` prerequisite diagnostics; the launcher-cache and MCP tool-surface sections follow. `Install status` is read-only GETs only and never affects the exit code.
 
 The report also includes a **Claude login** advisory: whether the host's own
@@ -1287,7 +1249,7 @@ blocks the doctor run and cannot guarantee the next worker spawn will
 authenticate. See
 [Claude login for Epic Implementer workers](#claude-login-for-epic-implementer-workers).
 
-It is **read-only**: it never installs anything, modifies your system, adds an npm `postinstall`, spawns a terminal, or starts the MCP server, and there is no `--fix`. For each prerequisite it prints found/missing and, when missing, the exact per-OS install command **as a manual instruction you run yourself**. The checked set is the `start-tickets` preflight prerequisites **plus `uv`** **plus the selected agent's command** (`claude` by default, or `cursor-agent` with `--agent cursor-agent`). The Worktrunk binary is probed via the resolved name (honoring `BAPI_WORKTRUNK_BIN`), not a hard-coded one. **Exit code:** `0` when all required prerequisites are present, non-zero when any is missing or the platform is unsupported. A failing `start-tickets` preflight now hints you to run `doctor` for an actionable diagnostics report.
+It is **read-only**: it never installs anything, modifies your system, adds an npm `postinstall`, spawns a terminal, or starts the MCP server, and there is no `--fix`. For each prerequisite it prints found/missing and, when missing, the exact per-OS install command **as a manual instruction you run yourself**. The checked set is the `start-tickets` preflight prerequisites **plus the selected agent's command** (and **`uv`** with `--advanced`) (`claude` by default, or `cursor-agent` with `--agent cursor-agent`). The Worktrunk binary is probed via the resolved name (honoring `BAPI_WORKTRUNK_BIN`), not a hard-coded one. **Exit code:** `0` when all required prerequisites are present, non-zero when any is missing or the platform is unsupported. A failing `start-tickets` preflight now hints you to run `doctor` for an actionable diagnostics report.
 
 **`claude-review` workflow lineage (advisory, read-only).** `doctor` also reports
 whether the current branch's `.github/workflows/claude-review.yml` matches the
@@ -1307,210 +1269,50 @@ worker**. Remedy and full diagnosis:
 
 ### The Epic Implementer
 
-The Epic Implementer drives a whole epic — several related tickets — from an
-approved plan to merged pull requests, with little help from you. It was called
-the "conductor" before BAPI-1077..1083 renamed it. A few command, flag, and path
-names still say `conductor`; each is noted where it appears.
+The Epic Implementer drives a whole epic — several related tickets — from an approved plan to merged pull requests, with little help from you. The getting-started guide in [the section above](#epic-implementer) is the one path; this section says what each command is for.
 
 It has two parts:
 
-- **The v2 engine.** A reconciler on the Bridge API server decides every step. An
-  executor on your machine runs the jobs it hands out, one agent session per child
-  ticket. This is what drives an epic.
-- **Observability** (`start-tickets --conductor`). An opt-in local event ledger,
-  supervisor tab, and git hooks. It is off by default, and driving an epic does not
-  need it.
-
-The path from an epic to a finished run:
-
-1. **Plan.** `/plan-epic` splits the epic into child tickets and a plan DAG
-   (`epic-plan.dag.json`). `emit-epic-implementer-bundle finalize` writes the DAG
-   and the meta file that `drive-epic` uses to find it.
-2. **Set up the repository, once.**
-   `npx -y @bridge_gpt/mcp-server install conductor --required-check <check>`
-   (also spelled `install-bridge conductor`; the name predates the rename). It runs
-   a read-only doctor and writes the done gate from your required CI check(s). It
-   can also scaffold the `claude-review` workflow (only with the explicit AI-review opt-in, `--review-policy verdict_protocol`; omitting the flag persists no repository review choice and scaffolds none), write an executor service unit,
-   and save a launch profile. With its own consent, it adds `epic_implementer` to
-   `BRIDGE_MCP_PROFILE` in your host MCP configs. Run `install conductor --help`
-   for every option.
-3. **Launch and drive.** In Claude Code, `/drive-epic-run <EPIC> [<plan path>]`
-   previews the launch, asks you once, creates the run through `drive-epic`, and
-   then watches and recovers it. From a shell, [`drive-epic <EPIC>`](#drive-epic)
-   creates the run and starts its executor. In Claude Code, `/drive-epic-run` first
-   checks whether Bridge's auto-mode sandbox description is in
-   `~/.claude/settings.json`. Only when it is missing, it asks you once, in the
-   session, and writes it only after an explicit yes. You can add it yourself with
-   `npx -y @bridge_gpt/mcp-server bridge-permissions` (run from the project root; it
-   asks first), inspect it with `bridge-permissions --check --json`, and remove it
-   with `install --remove-bridge-permissions`. `install` itself never touches that
-   file.
-4. **Monitor.** The MCP tools `get_epic_snapshot` and `explain_run` (they need the
-   `epic_implementer` profile; see [Environment Variables](#environment-variables)),
-   `notifications <EPIC|run-id> [--follow]`, `epic-implementer epic-status`, and
-   `executor watch <job>`.
-5. **Recover.** `epic-implementer unpark`, `adopt-current-head-and-unpark`,
-   `continue-child`, `resume-run`, `stop-run`, and `abandon-run` (terminal and
-   irreversible). Run `npx -y @bridge_gpt/mcp-server epic-implementer --help` for
-   the full list.
-
-`epic-implementer readiness` is a read-only report of every prerequisite, the
-unattended ones included, each with its state and one named fix. The full
-reference — architecture, the CI gate, supervisor config, observability, and git
-hooks — is in [EPIC-IMPLEMENTER.md](./docs/EPIC-IMPLEMENTER.md).
-
-**Old variable names stop every command (BAPI-1190).** Every `BAPI_CONDUCTOR_*`
-variable was renamed to `BAPI_EPIC_IMPLEMENTER_*`, and the few old `CONDUCTOR_*`
-names without the `BAPI_` prefix (the node path, for one) now start with
-`EPIC_IMPLEMENTER_`. There are no aliases. If any old name is set, every
-entry point — the MCP server included — prints the old names and exits `1`.
-Rename or unset them.
+- **The engine.** A reconciler on the Bridge API server decides every step. An executor on your machine runs the jobs it hands out, one agent session per child ticket. This is what drives an epic.
+- **Observability** (`start-tickets --conductor`). An opt-in local event ledger, supervisor tab, and git hooks. It is off by default, and driving an epic does not need it.
+
+What each command is for:
+
+- **`install conductor`** sets up the repository, once. It checks, fixes what is missing, checks again, and ends with one verdict. It is also spelled `install-bridge conductor`, and `install conductor --help` lists every option.
+- **`/define-tickets`** writes the child tickets and the plan files. **`/plan-epic`** is the advanced planner; it needs `emit-epic-implementer-bundle finalize` and never creates a run.
+- **`/drive-epic-run <EPIC> [<plan path>]`** previews the launch, asks you once, creates the run through [`drive-epic`](#drive-epic), then watches and recovers it. In Claude Code it first checks whether Bridge's auto-mode sandbox description is in `~/.claude/settings.json`. Only when it is missing, it asks you once, in the session, and writes it only after an explicit yes. You can add it yourself with `npx -y @bridge_gpt/mcp-server bridge-permissions` (run from the project root; it asks first), inspect it with `bridge-permissions --check --json`, and remove it with `install --remove-bridge-permissions`. `install` itself never touches that file.
+- **Monitor** with the MCP tools `get_epic_snapshot` and `explain_run` (they need the `epic_implementer` profile; see [Environment Variables](#environment-variables)), `notifications <EPIC|run-id> [--follow]`, `epic-implementer epic-status`, and `executor watch <job>`.
+- **Recover** with `epic-implementer unpark`, `adopt-current-head-and-unpark`, `continue-child`, `resume-run`, `stop-run`, and `abandon-run` (terminal and irreversible). Run `npx -y @bridge_gpt/mcp-server epic-implementer --help` for the full list.
+
+`epic-implementer readiness` is a read-only report of every prerequisite, the unattended ones included, each with its state and one named fix.
+
+**Old variable names stop every command.** Every `BAPI_CONDUCTOR_*` variable was renamed to `BAPI_EPIC_IMPLEMENTER_*`, and the few old `CONDUCTOR_*` names without the `BAPI_` prefix (the node path, for one) now start with `EPIC_IMPLEMENTER_`. There are no aliases. If any old name is set, every entry point — the MCP server included — prints the old names and exits `1`. Rename or unset them.
 
 ### `drive-epic`
 
-The one Epic Implementer entry point every Bridge surface names. Give it an epic
-key and it reads Epic Implementer readiness for your repository and routes to the
-single path your project can actually run:
+The one launch command. Give it an epic key and it reads your repository's readiness and routes to the single path your project can run:
 
 ```
 npx -y @bridge_gpt/mcp-server drive-epic <EPIC>
 ```
 
-You are never asked to choose. `drive-epic` routes to exactly one engine, 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 engine to fall back
-to — and prints no run command. If readiness is **unknown** — unreachable,
-unauthorized, or malformed — it escalates and prints no run command 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.
-
-`drive-epic` owns no branch behavior of its own — it forwards `--feature-branch
-<name>`, `--into-base`, and `--attended` verbatim to `setup-epic`, which decides
-the strategy and the posture (see below). With none of them, a multi-ticket epic
-runs on `epic/<KEY>`, unattended. It also forwards `--repo` and the policy flags:
-`--policy-file <path>` (the complete run policy), `--review-policy <src>` (a
-per-run review policy: `repository_policy`, `verdict_protocol`,
-`native_review_decision`, or `none`; omitted, the server stamps `repository_policy`
-at first approval for a new feature-branch run, and `verdict_protocol` is the
-explicit AI-review opt-in), and `--replace-policy` (allow replacing a live run's
-stored policy).
-
-**Every run gets an executor (BAPI-1279).** Once `drive-epic` creates a run, it
-starts an executor scoped to that run in the background, from this checkout's Git
-top level. The executor claims only that run's jobs, logs to
-`.bridge/executors/<run>.log`, and exits on its own when the run is done or
-abandoned. You do not start one by hand. Run `drive-epic` from a Git work tree
-inside the target repository — it checks this before creating anything. If the
-executor fails to start, the run is left intact and `drive-epic` prints the log
-path and the exact command to start it by hand.
-
-**Choosing the server.** With no flags, `drive-epic` targets production and uses
-the stored `bapi:<repo>` key when there is one. `--base-url <url>` (or
-`BAPI_BASE_URL`) names another server. `--launch-profile <name>` (or
-`BAPI_EPIC_LAUNCH_PROFILE`) selects a host-local profile saved by
-`install conductor --launch-profile <name>`; use one for a local server or a
-durable host. With a profile, `--base-url` must agree with it. A stored key
-approved for a different endpoint is never sent.
-
-**Finding the plan from the epic key (BAPI-1285).** `--plan-file` is optional.
-Without it, `drive-epic` searches `{docs_dir}/epic-plans/*/epic-plan.meta.json` for a
-file whose `epic_key` is exactly this epic (`docs_dir` is `BAPI_DOCS_DIR`, else
-`docs/tmp`, resolved against the Git top level; an absolute `BAPI_DOCS_DIR` is used
-as given). Exactly one match with a sibling `epic-plan.dag.json` is used as if you
-had passed `--plan-file`, and its path is printed before anything is created. Zero
-matches, two or more, or an unusable meta file **stop** with the paths found and
-create nothing, and a folder name, a child ticket key, or
-`sibling-ticket-manifest.json` is never used to guess. A supplied `--plan-file`
-always wins and discovery does not run.
-
-The meta file is `{"epic_key": "<KEY>"}`, written by `emit-epic-implementer-bundle
-finalize` beside the DAG (its own atomic write, reported as `meta_path` in
-`--json`). It is separate from `epic-plan.dag.json` on purpose: the DAG is sent to
-the server, which rejects unknown fields. A plan finalized before this change has no
-meta file, so it is reported as not found — pass its DAG with `--plan-file`.
-
-**A live run with no plan.** If the epic already has a live run and no plan was
-supplied or found, `drive-epic` creates nothing. It makes sure that run has an
-executor: it reuses a verified live one (never starting a second), starts one when
-the old one is gone, starts none for a durable launch profile with a confirmed
-repo-wide executor, and starts none when this checkout's plane is bound to that
-run. An epic with several active runs (`live-run-ambiguous`), or a run that cannot
-be read (`live-run-unknown`), is refused by name.
-
-**Preview with `--dry-run`.** `drive-epic <EPIC> --dry-run` is read-only. It reads
-the target, readiness, the live run, and the plan, runs the bootstrap's own dry-run
-validation when a plan is available, and reports the decision a real invocation
-would make — `create`, `attach`, `refuse`, or `stop` (exit `0` for the first two,
-`1` for the others). It never creates a run, cuts a branch, starts a plane,
-requests a lane, or starts or signals an executor. With `--json` (valid only with
-`--dry-run`) stdout carries exactly one JSON document with `epic_key`, `target`,
-`readiness`, `live_run`, `plan`, `summary`, `decision`, and `refusal`. The
-readiness `reason_id` and `remedy` are the strings the real refusal prints. The
-webhook URL, credentials, and policy contents are never included. The preview
-probes a local plane only when the target is a loopback plane, readiness failed on
-the network, and a plan is available. A refused port plus passing local preflight
-yields a conditional
-`create` with optional `cold_start` (`plane_endpoint`, `will_start_plane: true`,
-`live_run_checked: false`), `live_run: null`, and partial offline setup validation.
-The real launch attempts guarded startup, then rechecks run existence and server
-validation; the preview does not guarantee creation. Remote targets, non-refused
-port probes, and ordinary production previews keep their existing refusal or
-create behavior. `target.source` is optional and appears only for selected
-profiles (`profile` or `profile-env`).
-
-#### Running the server yourself (Bridge API source checkout only)
-
-The rest of this section, and [`plane up`](#plane-up--claim-scope-is-required)
-below, apply only when you run the Bridge API server on your own machine. That
-needs a Bridge API **source checkout**: `plane up` must run from its repository
-root (the directory holding `main.py`, `worker.py`, and `alembic.ini`), and its
-executor lanes run from that checkout's `mcp_server/build/index.js`, never from
-npx. If you target production, skip this part.
-
-**The composed bring-up is two-phase (BAPI-1102).** With `--plan-file` on a
-repository whose readiness is missing only the runtime facts, one invocation runs,
-in order: the **control plane** (Bridge API server + reconciler, each gated on its
-own readiness), then `setup-epic` to create and approve the run, then **executor
-lanes scoped to that run** with `--epic-run-id <run>`, then the **dead-man
-observer** last, then the ready banner. The order is forced: an executor lane must
-carry an explicit claim scope, and the run it is scoped to does not exist until the
-server is up and `setup-epic` has run.
-
-A plane's executor lanes serve **exactly one** run — the run it is bound to. A
-second epic does **not** start a second plane: it attaches to the running plane's
-reconciler and gets its own run-scoped executor. Two planes on one database are
-not supported. If `setup-epic` fails, the control plane is left running and **no
-executor lane is spawned**. If the lanes fail to become ready, the control plane
-and the committed run are both left intact and the observer is not started —
-nothing is rolled back, because a local process that failed to start says nothing
-about whether the run is valid.
-
-"Plane ready" reports **processes**, not dispatchability: if the run cuts an epic
-branch, the reconciler holds ticket dispatch until that branch's index scope
-finishes preparing.
-
-### `plane up` — claim scope is required
-
-`plane up` starts the runtime on its own, from a Bridge API source checkout, and
-every executor lane it starts needs an explicit claim scope:
+You are never asked to choose. If readiness is not green, it names each missing item with its fix and creates nothing. If readiness cannot be read (unreachable, unauthorized, or malformed), it stops and prints no run command, because an unknown state is not the same as a not-ready one.
 
-```
-npx -y @bridge_gpt/mcp-server plane up --epic-run-id <run-id>   # repeatable
-npx -y @bridge_gpt/mcp-server plane up --repo-wide              # or repository-wide
-```
+`drive-epic` owns no branch behavior of its own. It forwards `--feature-branch <name>`, `--into-base`, and `--attended` to `setup-epic`, which decides the strategy and the posture (see [`setup-epic`](#setup-epic)). With none of them, a multi-ticket epic runs on `epic/<KEY>`, unattended. It also forwards `--repo` and the policy flags: `--policy-file <path>` (the complete run policy), `--review-policy <src>` (a per-run review policy: `repository_policy`, `verdict_protocol`, `native_review_decision`, or `none`; omitted, the server stamps `repository_policy` at first approval for a new feature-branch run, and `verdict_protocol` is the explicit AI-review opt-in), and `--replace-policy` (allow replacing a live run's stored policy).
+
+**Every run gets an executor.** Once `drive-epic` creates a run, it starts an executor scoped to that run in the background, from this checkout's Git top level. The executor claims only that run's jobs, logs to `.bridge/executors/<run>.log`, and exits on its own when the run is done or abandoned. You do not start one by hand. Run `drive-epic` from a Git work tree inside the target repository; it checks this before creating anything. If the executor fails to start, the run is left intact and `drive-epic` prints the log path and the exact command to start it by hand.
+
+**Choosing the server.** With no flags, `drive-epic` targets production and uses the stored `bapi:<repo>` key when there is one. `--base-url <url>` (or `BAPI_BASE_URL`) names another server. A stored key approved for a different endpoint is never sent.
+
+**Finding the plan from the epic key.** `--plan-file` is optional. Without it, `drive-epic` searches `{docs_dir}/epic-plans/*/epic-plan.meta.json` for a file whose `epic_key` is exactly this epic (`docs_dir` is `BAPI_DOCS_DIR`, else `docs/tmp`, resolved against the Git top level; an absolute `BAPI_DOCS_DIR` is used as given). Exactly one match with a sibling `epic-plan.dag.json` is used as if you had passed `--plan-file`, and its path is printed before anything is created. Zero matches, two or more, or an unusable meta file **stop** with the paths found and create nothing. A folder name, a child ticket key, or `sibling-ticket-manifest.json` is never used to guess. A supplied `--plan-file` always wins and discovery does not run.
 
-The two are mutually exclusive. Asked to start lanes with neither, `plane up`
-**refuses before spawning anything**, in the executor's own words. That is not a
-new restriction — an executor started with no claim scope has refused to start
-since BAPI-1026 — it is that refusal moved to where it is actionable, instead of
-surfacing as a member crash and a full plane rollback.
+The meta file is `{"epic_key": "<KEY>"}`, written beside the DAG by `/define-tickets` and by `emit-epic-implementer-bundle finalize` (reported as `meta_path` in `--json`). It is separate from `epic-plan.dag.json` on purpose: the DAG is sent to the server, which rejects unknown fields. A plan finalized before the meta file existed has none, so pass its DAG with `--plan-file`.
 
-`plane status` reports the lifecycle phase (control plane starting/ready, lanes
-starting/ready, observer active, plane ready) and the epic run the plane is bound
-to. `plane down` handles every intermediate phase: it stops the bound run first,
-then signals the recorded process group.
+**A live run with no plan.** If the epic already has a live run and no plan was supplied or found, `drive-epic` creates nothing. It makes sure that run has an executor: it reuses a verified live one (never starting a second) and starts one when the old one is gone. An epic with several active runs (`live-run-ambiguous`), or a run that cannot be read (`live-run-unknown`), is refused by name.
+
+**Preview with `--dry-run`.** `drive-epic <EPIC> --dry-run` is read-only. It reads the target, readiness, the live run, and the plan, runs the bootstrap's own dry-run validation when a plan is available, and shows the decision a real invocation would make: `create`, `attach`, `refuse`, or `stop` (exit `0` for the first two, `1` for the others). It never creates a run, cuts a branch, requests a lane, or starts or signals an executor. With `--json` (valid only with `--dry-run`) stdout carries exactly one JSON document with `epic_key`, `target`, `readiness`, `live_run`, `plan`, `summary`, `decision`, and `refusal`. The readiness `reason_id` and `remedy` are the strings the real refusal prints. The webhook URL, credentials, and policy contents are never included.
+
+`drive-epic --help` lists every option. Owners who run their own Bridge server have extra steps: see `drive-epic --help-advanced`.
 
 ### `setup-epic`
 
@@ -1528,20 +1330,20 @@ branch, and one draft integration PR targets the repository base branch. This ho
 every path, CI and `--json` included. A single-node plan keeps the repository base
 branch, matching plain `start-tickets`.
 
-> **Behavior change (BAPI-1009).** The same no-flag command previously ran children
+> **Behavior change.** The same no-flag command previously ran children
 > directly into the repository base branch. **Pass `--into-base` to restore that**, if
 > your automation depends on it. Pass `--feature-branch <name>` to override the derived
 > name, or to force a branch for a single-node plan. Passing both is a parse error,
 > refused before any file read, credential resolution, or network call.
 
-**A run that selects an epic branch is created UNATTENDED (BAPI-1102).** Its
+**A run that selects an epic branch is created UNATTENDED.** Its
 `policy_json` carries `posture: "unattended"` and `v2_auto_merge_enabled: true`, so
 child PRs merge into the epic branch without parking for a human at every gate. The
 **integration PR into the repository base branch stays human-gated.** The run's CI
 gate is stamped **server-side at first approval** — from your repository's declared
 default, or, when it declares none, as an explicit recorded `no_ci_gate` mode.
 
-> **Behavior change (BAPI-1102).** Pass `--attended` to restore the previous
+> **Behavior change.** Pass `--attended` to restore the previous
 > composition: `base_branch` plus an explicitly requested `--review-policy`, with no
 > posture and no auto-merge authorization. `--into-base`, single-node plans, and
 > branch-silent invocations are **unchanged** — they send no `policy_json` at all,
@@ -1552,7 +1354,7 @@ default, or, when it declares none, as an explicit recorded `no_ci_gate` mode.
 An unattended run has two **repository** prerequisites — consent
 (`unattended_epic_implementer_allowed`, ON by default; the repository owner can switch
 "Allow unattended Epic Implementer runs" off and on in the Bridge admin panel's Setup
-page) and an **escalation channel** (BAPI-1274): a verified notify webhook, or,
+page) and an **escalation channel**: a verified notify webhook, or,
 when the policy declares no webhook, an email address on the account — plus
 confirmed default-branch review/CI workflows. Each is refused by name **before any
 run row is created** (`target_not_allowed`, `webhook_unverified`,
@@ -1562,33 +1364,52 @@ to email, and `notify.local_sink` does not count as a channel.
 `epic-implementer readiness` and `drive-epic` both list these prerequisites with
 their current state.
 
-Once the plan is approved, the **server-side reconciler** picks the run up within
-~30s. If you ran `setup-epic` directly, start an executor for the run yourself
-(`drive-epic` does this for you). An executor needs exactly one claim scope, or it
-refuses to start:
+**One switch decides a run's own merges.** A run's child merges into its
+epic branch follow the Setup-page switch "Allow unattended Epic Implementer runs".
+They do not read the legacy repository flags (`auto_merge_enabled`,
+`merge_approval_required`), which still govern merges made outside a run (the plain
+merge route, the approval route, and the `merge_pull_request` tool). The integration
+PR into the base branch is never eligible. If the switch is turned off mid-run, the
+reconciler **holds** each child that reaches merging: `explain_run` shows a pending
+`unattended_posture_off` observation, no job is created, and no attempt is spent.
+Turning the switch back on resumes merging on the next tick with no `unpark`. A hold
+longer than the merging gate's deadline parks through the normal watchdog. A local or
+machine-token merge already handed to the executor before the switch-off may still
+finish.
+
+**Launch capability summary.** An unattended `drive-epic` launch, and its
+`--dry-run`, check three rows before creating a run: the **unattended posture** (the
+Setup switch), **merge credential capability**, and **worktree preparation**. The
+server reports the resolved merge mode and the GitHub `owner/name`. In `local` mode the
+CLI probes `GITHUB_MERGE_TOKEN`, and in `machine_token` mode `BAPI_MACHINE_MERGE_TOKEN`,
+with `gh api --include repos/{owner}/{name}` and one pull-request read. Pass means the
+token has push permission and can read pull requests. `github_actions` mode shows one
+informational row and runs no local probe. The worktree row checks, without writing,
+that the executor clone's git `info/exclude` is present or writable.
+
+Each row carries a `blocking` flag. Only a **proven** problem blocks: the switch is off,
+the token is missing or invalid, a `404` or a `200` without push permission, or an
+exclude that is neither present nor writable. A `401`, `403`, `429`, `5xx`, a network
+error, a timeout, an unresolved repository, a non-local executor clone (a plane lane
+or a durable launch profile), or an older server that does not report the new fields
+is a **"capability not verified"** warning, not a refusal. `--attended` and
+`--into-base` make all three rows informational. The probe does not prove branch
+protection or rulesets; those are still checked at merge time. Upgrade the server
+before the MCP package: an older server simply yields the warning.
+
+Once the plan is approved, the **server-side reconciler** picks the run up within ~30s. If you ran `setup-epic` directly, start an executor for the run yourself (`drive-epic` does this for you). An executor needs exactly one claim scope, or it refuses to start, and it needs `--base-url` or `BAPI_BASE_URL`:
 
 ```
 npx -y @bridge_gpt/mcp-server executor --repo <name> --epic-run-id <run-id> --exit-when-run-terminal
-npx -y @bridge_gpt/mcp-server executor --repo <name> --repo-wide    # every run in the repo
 ```
 
-`executor install-service` generates a launchd/systemd user unit so a durable
-executor survives a reboot. `--base-url` or `BAPI_BASE_URL` is required: the
-executor has no production fallback.
+For durable hosts, see `drive-epic --help-advanced`.
 
 ### Epic Implementer reference
 
-The full reference — the v2 architecture (server-side reconciler + local
-executor), the CI gate, `epic-implementer install-git-hooks`, the supervisor
-`done_gate_config` / `auto_merge_enabled` settings, and the opt-in observability
-stream — lives in **[EPIC-IMPLEMENTER.md](./docs/EPIC-IMPLEMENTER.md)**.
-Auto-merge into the epic branch is **on by default** for unattended runs (see
-[`setup-epic`](#setup-epic)); only the `--conductor` observability layer is off by
-default.
+The full reference — how the engine works, the CI gate, `epic-implementer install-git-hooks`, the supervisor `done_gate_config` / `auto_merge_enabled` settings (which govern merges outside a run; a run's own merges follow the Setup-page switch), and the opt-in observability stream — is in **[EPIC-IMPLEMENTER.md](./docs/EPIC-IMPLEMENTER.md)**. It is a reference, not a second walkthrough: start with the [Epic Implementer](#epic-implementer) section above.
 
-Two retired names remain as failing pointers. The event-ledger CLI was renamed
-from `conductor` to `epic-implementer`, and `emit-conductor-bundle` to
-`emit-epic-implementer-bundle`; the old names now print the new name and exit.
+Two retired names remain as failing pointers: the old event-ledger CLI name and `emit-conductor-bundle`. Both print the new name (`epic-implementer`, `emit-epic-implementer-bundle`) and exit.
 
 > The v1 `epic-implementer epic-tick` command is **frozen** — it throws on every invocation. There is nothing to schedule locally, and `epic-implementer doctor` flags any epic-tick schedule left over from an earlier release so you can cancel it.
 
@@ -1646,23 +1467,26 @@ Optionally set a repository Actions **variable** named `BAPI_BASE_URL` to point
 
 #### Merge credentials (`local` and `machine_token` modes)
 
-No merge path reads an ambient `gh` login. Each mode reads exactly one
-process-launch configuration key, with **no fallback** between them and none to
-an inherited `GH_TOKEN`, `GITHUB_TOKEN`, a `gh auth` session, or the Bridge
-credential store. Bridge never stores either value.
+No merge path reads an ambient `gh` login. The two modes are separate, with **no
+fallback** between them and none to an inherited `GH_TOKEN`, `GITHUB_TOKEN`, or a
+`gh auth` session.
 
 | Mode | Key | Provenance |
 |---|---|---|
-| `local` | `BAPI_LOCAL_MERGE_TOKEN` | A configured local scoped credential. |
-| `machine_token` | `BAPI_MACHINE_MERGE_TOKEN` | Your machine user's credential. |
+| `local` | `GITHUB_MERGE_TOKEN`, then `BAPI_LOCAL_MERGE_TOKEN`, then a stored entry | A scoped GitHub token for this repository. Setup can store one on your computer as `github-merge:<host>/<owner>/<repo>` in `~/.config/bridge/credentials.json`; either environment variable takes precedence over it. |
+| `machine_token` | `BAPI_MACHINE_MERGE_TOKEN` | Your machine user's credential, read from the environment only. A stored `github-merge:` entry does not configure this mode. |
+
+Supply environment keys at process launch, or from an approved external secret manager.
 
-Supply them at process launch, or from an approved external secret manager.
+A probe that passes shows the key has push permission and can read pull requests.
+It does not prove branch protection or repository rules; those are checked at merge time.
 
 | Preflight outcome | Remediation |
 |---|---|
-| `*_credential_missing` | Set the mode's key in the environment this MCP server is launched with. |
+| `*_credential_missing` | Set the mode's key in the environment this MCP server is launched with. For `local` mode, setup can instead store a token for this repository. |
 | `*_credential_invalid` | GitHub rejected the configured credential. Rotate it and relaunch. |
-| `*_credential_unpermitted` | It authenticates but cannot write to this repository. Grant it merge permission. |
+| `*_credential_unpermitted` | GitHub answered `404`, or `200` without push permission, for this repository. Grant it push access. |
+| capability probe unavailable | GitHub answered `401`, `403`, `429`, or `5xx`, or the probe timed out. At launch this is a "capability not verified" warning; at merge time the merge is refused. Retry, then check the token by hand. |
 | `local_gh_unavailable` | Install the GitHub CLI (`gh`) on the machine running this MCP server. |
 
 #### What the workflow does and does not do
@@ -1782,7 +1606,7 @@ If a custom pipeline has the same key as a built-in pipeline, the custom version
 | `BAPI_PLANE_PYTHON` | No | `python` | Executable used for the Python members of `plane up` (Bridge API source checkout only). Point it at a venv interpreter when `python` on `PATH` is not the one you want |
 | `BAPI_PLANE_UVICORN` | No | `uvicorn` | Executable used for the server member of `plane up` |
 | `BAPI_PLANE_PORT` | No | `8000` | Port for the local plane server (`127.0.0.1`). Only for `plane up` and a local `drive-epic` target, from a Bridge API source checkout |
-| `BAPI_EPIC_LAUNCH_PROFILE` | No | _(none)_ | Selects a host-local launch profile (saved by `install conductor --launch-profile`) for `drive-epic`. `--launch-profile` takes precedence. See [`drive-epic`](#drive-epic) |
+| `BAPI_EPIC_LAUNCH_PROFILE` | No | _(none)_ | Selects a host-local launch profile (saved by `install conductor --launch-profile`) for `drive-epic`. `--launch-profile` takes precedence. See `drive-epic --help-advanced` |
 | `BAPI_DOCS_DIR` | No | `docs/tmp` | Local directory for saving plans, critiques, and research reports |
 | `BAPI_PIPELINES_DIR` | No | `.bridge/pipelines` | Directory for user-defined custom pipeline JSON files |
 | `BAPI_WORKTRUNK_BIN` | No | `wt` (`git-wt` on Windows) | Override the Worktrunk executable name/path used by `start-tickets` for nonstandard installs |
@@ -2047,7 +1871,7 @@ The full surface, for when you need the complete enumeration. Day-to-day, use [U
 
 ### MCP tools
 
-The authoritative tool catalog covers **78 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 Epic Implementer (`epic_implementer`), estimation, and 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 **80 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 Epic Implementer (`epic_implementer`), estimation, and 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)
@@ -2056,7 +1880,7 @@ The authoritative tool catalog covers **78 tools** (enumerated below). What's ac
 - **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 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)
+- **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), `get_epic_contract_context` (an epic child's parent requirements and sibling contracts, with explicit coverage; read-only)
 - **Jira status** — `update_jira_status` (pass `status: "auto"` to resolve the configured post-PR status server-side)
 - **Repository & CI** — `parse_repository` (`action`: `start`, `status`), `regenerate_directory_map`, `create_pull_request`, `merge_pull_request`, `resolve_ci_checks`, `poll_ci_checks`, `wait_for_ci_checks` (the last two are hidden until `ci_check_config` resolves, and share one visibility gate)
 - **Epics** — `assess_epic_implementer_eligibility` (core; read-only prediction, before a run, of which epic children change workflow files and so need hand review; the old `assess_epic_conductor_eligibility` name returns `tool_removed`), `estimate_epic` (`estimation` profile), and `get_epic_snapshot` / `explain_run` (`epic_implementer` profile; read-only run state and "why is it stuck"; an unknown run returns `status: "unknown"`)
@@ -2168,9 +1992,33 @@ outcome is unknown, a challenge cannot be recovered, or installation asks for su
 Never delete possibly redeemed proof to restart. Ordinary invite tokens and
 verification codes are not stored.
 
+### Didn't get the code?
+
+The code comes from noreply@bridgegpt-api.com and usually arrives within
+two minutes. Delivery is retried for about two hours, so it can come late.
+
+- Check your spam, junk, and quarantine folders. Search for
+  noreply@bridgegpt-api.com.
+- At the code prompt, type r to send a new code. Earlier codes keep
+  working. You can ask for up to two new codes, a minute apart.
+- Typed the wrong address? Press Ctrl-C and re-run install with the right
+  one. Install offers to start a new signup.
+- A code lasts four hours. If it expires, re-run install from the same
+  folder. Install offers to start a new signup.
+- A teammate on Bridge can send you an invite. Choose "I already have a
+  token", or pass --invite.
+- Still stuck? Email info@bridgegpt.ai.
+
+### Credential storage
+
 Credential storage uses bounded exclusive locking without timeout-based stealing.
-An abandoned lock needs installation support. POSIX systems sync the containing
+An abandoned lock needs help: contact Bridge support at info@bridgegpt.ai and keep
+the recovery proof. POSIX systems sync the containing
 directory; Windows uses file sync plus atomic replacement because portable Node
 directory handles are unavailable. A failure after rename is an uncertain durability
 outcome: the new bytes may already exist. Rerun reloads the actual store under lock;
 there is no guarantee that old pending bytes survive every failure.
+
+### Out of scope
+
+The CLI cannot diagnose non-delivery, a sender mismatch, or incompatible server behavior. It preserves saved attempts, uses the existing neutral guidance and server-enforced resend limits, and still permits the existing teammate-invite route; unresolved cases go to info@bridgegpt.ai, which does not promise a support-issued invite or a verification bypass.