@bridge_gpt/mcp-server 0.2.67 → 0.2.69

package/README.md

@@ -10,16 +10,35 @@ From your **project root**, run:
 npx -y @bridge_gpt/mcp-server install
 ```
 
-That is the whole setup command. It works whether or not you already have a Bridge
-account — it will ask.
+That command starts guided setup. It works whether or not you already have a Bridge
+account — it will ask; follow the remaining onboarding instructions afterward.
+
+### Already ran `npm i @bridge_gpt/mcp-server`?
+
+> The package and its executable aliases are installed, but your intended project
+> and MCP host still need setup. From your intended project root, run:
+>
+> ```bash
+> npx -y @bridge_gpt/mcp-server install
+> ```
+>
+> You do not need to uninstall the package first. [Continue with the step-by-step
+> setup instructions](#installing-step-by-step) for sign-in, host selection,
+> reload/trust, and agent handoff.
+
+> Package installation is passive: Bridge cannot detect or notify someone who only
+> installs the package and does nothing else. Successful lifecycle output is not a
+> reliable default-install notification because `foreground-scripts` normally
+> defaults to false, and `ignore-scripts` can disable hooks entirely.
 
 > We recommend **the command above** instead of the `npm i @bridge_gpt/mcp-server`
 > one in npm's sidebar, because it **will make set up much easier**.
 
 **What it will do**
 
-- **Bootstraps the Bridge MCP for you** — one command and your editor's agent can
-  use Bridge's tools and slash commands on this project.
+- **Starts guided Bridge MCP setup** — after completing the remaining onboarding
+  instructions, your editor's agent can use Bridge's tools and slash commands on
+  this project.
 - Registers a `bridge` MCP server in your editor's MCP config, leaving any
   other servers you have configured untouched.
 - Creates and updates the files it needs inside your project root: slash commands
@@ -84,27 +103,41 @@ you run it in your home directory, your editor will not find any of it.
 npx -y @bridge_gpt/mcp-server install
 ```
 
-**3. Answer the sign-in question.** On a first run it asks whether you already have
-a token:
+**3. Answer the sign-in question.** On a first run it asks one question:
 
 ```
-1. I need a token
-2. I already have a token
+Email (or press Enter if you already have a token):
 ```
 
-- Choose **1** if you have nothing yet. It asks for your email address and a name
-  for your new Bridge project, then creates both for you.
-- Choose **2** if someone gave you a token — either a Bridge API key or an invite
+- Type your **email address** if you have nothing yet. The installer first shows
+  how your email is used, then sends you a verification code. Your new Bridge
+  project is named after your folder, with no question asked unless the folder
+  name cannot be used. Rename it later on the Setup page.
+- Press **Enter** if someone gave you a token — either a Bridge API key or an invite
   code. Paste it at the hidden prompt; you do not have to say which kind it is,
   because the installer recognizes it. Nothing is echoed as you type.
 
-There is no default answer, so pressing Enter alone selects nothing. If you would
-rather not be asked, pass the answer up front instead — see
+One mistyped answer gets a hint and a second try. If you would rather not be
+asked, pass the answer up front instead — see
 [Choosing how you sign in](#choosing-how-you-sign-in).
 
-**4. Pick which editors to configure.** The installer detects the MCP hosts on your
-machine and asks which ones to set up. Pick every editor you actually use for this
-project; you can re-run the command later to add another.
+**4. Confirm which editors to configure.** The installer detects the MCP hosts on
+your machine and ticks them for you (`[x]`). Press Enter to accept the ticked tools,
+or type the numbers you use (for example `1,3`) to replace them. You can re-run the
+command later to add another.
+
+**Optimization.** The installer then asks how Bridge should balance quality and
+cost: **Quality** (full-depth planning and review), **Speed** (one planning pass,
+one review), or **Token Efficiency** (Speed settings, with simpler tickets handed to
+smaller models, to stretch your Claude Code, Cursor, or Codex subscription). Press
+Enter to keep Quality (or your saved choice). Change it later by running
+`/teach-bridge` in your agent.
+
+When you are done answering, the installer writes Bridge's guidance for your agent
+between `<!-- BEGIN BRIDGE MCP GUIDANCE -->` and `<!-- END BRIDGE MCP GUIDANCE -->`
+without asking. It prints how to remove that region. Then it prints the defaults it
+chose — project name, ticket keys when your project uses local tickets,
+optimization, and guidance — just before offering to open the setup session.
 
 **5. Reload your MCP host.** Editors read their MCP configuration at startup, so a
 freshly written config is not live until you reload. Restart the editor, or use its
@@ -114,7 +147,9 @@ project's `.mcp.json` the first time.
 **6. Finish in the agent session the installer opens — when it opens one.** The
 last thing the installer does is offer to open a fresh agent session running
 `/install-bridge`, which reads your codebase, fills in the remaining project
-settings, and prints a short report of what Bridge can help with. Let it finish.
+settings, and prints a short report of what Bridge can help with. Let it finish. To
+invite teammates later, open the project's Security page from the Setup page and
+create a key.
 
 Three things all have to hold for that session to open: your selection has to
 include a host the installer can launch, the run has to be on an interactive
@@ -155,14 +190,15 @@ committing anything that can hold a credential.
 
 **Prompts you will see.** More than the sign-in question, in three groups:
 
-- *Always on a first bare interactive run:* the sign-in question, a hidden prompt
-  for a token (or a visible one for an email), a project name for a brand-new
-  project, a picker for which editors to configure, and an offer to connect GitHub
-  (`Connect GitHub? [y/N]:`).
+- *Always on a first bare interactive run:* the email-or-token question (a blank
+  answer opens a hidden prompt for a token), the verification code, a picker for
+  which editors to configure (detected ones are pre-ticked), the optimization
+  choice, and an offer to connect GitHub (`Connect GitHub? [y/N]:`).
 - *Conditional on your situation:* a confirmation when the directory has no `.git`
-  (default **No**, and declining aborts); a *"Which tool should open? [1-N]"*
-  chooser when your selection contains more than one launchable tool; and the
-  consent prompt before the final agent session.
+  (default **No**, and declining aborts); a project name when your folder name
+  cannot be used as one; and the consent prompt before the final agent session. With
+  more than one launchable tool selected, the first one is used and the installer
+  says so; pass `--agent` to choose another.
 - *Overwrite confirmations, each default **No** and each skippable with `--force`:*
   a saved key for this project already exists; a host config already contains a
   `BAPI_API_KEY`; a **git-tracked** config would receive your real key; a saved but
@@ -217,8 +253,8 @@ re-run the command from the right directory — if you already had a `.vscode/`,
 (`npx -y @bridge_gpt/mcp-server`) with no subcommand, you started the MCP *server*,
 not the installer. It is waiting for an editor to connect over stdio, which is
 exactly what it should do when your editor launches it — but from a terminal it
-looks like a hang. It prints a line saying so. Press Ctrl-C and run
-`npx -y @bridge_gpt/mcp-server install` instead. The explicit spelling
+looks like a hang. It prints a stderr guidance block explaining this. Press Ctrl-C
+and run `npx -y @bridge_gpt/mcp-server install` instead. The explicit spelling
 `npx -y @bridge_gpt/mcp-server serve` starts the server on purpose.
 
 **"It can't reach Bridge" or "my key was rejected."** The installer checks
@@ -283,7 +319,7 @@ Creates a brand-new Bridge project for that address and your first admin key in
 command. No account, no key, and no invite needed beforehand. The address labels
 your new workspace and may receive a setup message; delivery is best-effort, so
 nothing waits on it. The email is visible as you type (it is not a secret) and is
-never written to a log. This is the same route as answering **1** at the prompt.
+never written to a log. This is the same route as typing an email at the prompt.
 
 **You were sent an invite code.**
 
@@ -374,7 +410,7 @@ later boot.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.67", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.69", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -396,7 +432,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.67", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.69", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -418,7 +454,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.67", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.69", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -441,7 +477,7 @@ Windsurf only supports global MCP configuration.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.67", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.69", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -460,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.67", "serve"]
+args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.69", "serve"]
 
 [mcp_servers.bridge.env]
 BAPI_BASE_URL = "https://bridgegpt-api.com"
@@ -525,12 +561,46 @@ converge, and nothing is reported as complete in that case. The causes:
 - the upgrade finished but left an **unconfigured** MCP entry — one that would
   authenticate as nobody.
 
+#### Upgrade notices
+
 The server checks for updates on startup. The check is cached for a day and never
-blocks startup. When a newer version is known, it surfaces in two places you do
-not have to go looking for: a one-line warning on the server's **stderr**, and a
-short advisory attached to the ordinary `tools/list` response so the agent in the
-session can see that some tools may be missing or renamed in the older build.
-Neither requires calling `ping` or `doctor`.
+blocks startup or a tool call. When a newer version is known, you hear about it
+once, in a place you do not have to go looking for:
+
+- **The first completed tool result.** In an eligible session, the first tool call
+  that finishes carries one extra line naming both versions and `/upgrade-bridge`.
+  It tells the agent to mention the upgrade and to run it only if you say yes.
+  Failed tool calls count too.
+- **Startup instructions.** If the local cache already shows a newer version, the
+  server's instructions to the agent say so from the first message.
+- **A Claude Code `SessionStart` hook.** `install` and `upgrade` add one hook to
+  `.claude/settings.local.json`, pinned to the same version as your project's
+  launcher. It runs `check-update` and shows the notice at the start of a fresh
+  session. The hook is for Claude Code only and is per developer (that file is
+  gitignored). Bridge records the exact command in `.bridge/bridge-permissions.json`,
+  so a changed pin replaces it and removal deletes only that command. Cursor and
+  Codex have no hook; they get the startup instructions and the tool-result line.
+- **`doctor` and `start-tickets`.** `doctor` shows `Bridge MCP version` beside the
+  package version, from a fresh lookup that does not touch the cache. `start-tickets`
+  prints one reminder to stderr when the cache shows a newer version.
+
+The notice is decided without waiting for any lookup. While the latest version is
+unknown, or a result cannot safely carry the extra line, the session keeps its
+chance and tries again on a later call.
+
+It stays **silent** when you are current, when the latest version is unknown, in
+unattended worker sessions (`BAPI_WORKER_BRANCH` or `BAPI_EPIC_IMPLEMENTER_WORKER_ID`
+set), and when `BAPI_MCP_UPDATE_CHECK_ENABLED` is off.
+
+`BAPI_MCP_UPDATE_CHECK_FAKE_LATEST` is a manual-only override for trying the notice.
+It must be a plain `MAJOR.MINOR.PATCH` release; anything else is ignored. It never
+changes what `install` or `upgrade` pin to.
+
+Two limits to know. The startup instructions and the hook read the cache the server
+fills, so a machine that has never run the server may show no notice at session
+start. And a cold, pinned `npx` launch of the hook can take longer than its
+five-second timeout, in which case it stays silent; run `doctor`, or launch the
+pinned CLI once, to warm it.
 
 Re-running `install` on an already-configured project is safe: it refreshes the
 scaffolded files without overwriting your stored credential unless you pass
@@ -570,15 +640,15 @@ The tools worth knowing for most tickets.
 - **Flags:** `--auto` auto-accept findings and skip the approval gates · `--rounds=1` a cheaper single-pass review that still evaluates findings and captures decisions · `--rounds=2` force the full second-opinion review · omit `--rounds` to let the difficulty-adaptive review policy decide.
 
 **2. Start Tickets**
-- **What it does:** Creates one git worktree per ticket and spawns an agent session in each to implement them in parallel.
+- **What it does:** Builds several tickets at once, each in its own copy of the repo (a git worktree) with its own agent.
 - **When it's useful:** (Implementation | Automation) When you're ready to start building one or more refined tickets concurrently.
-- **How to use it:** `/start-tickets BAPI-248 BAPI-250` (see [CLI Subcommands](#cli-subcommands) for the full flag table and cross-platform behavior).
+- **How to use it:** `/start-tickets BAPI-248 BAPI-250`
 - **Flags:** `--auto` skip the approval gates · `--base-branch <branch>` branch off something other than the default · `--workflow implement|review-and-implement` selects which slash command each spawned worktree runs · `--rounds=1|2` forwarded to the review phase, valid only with `--workflow review-and-implement` · `--tier cheap|basic|premium` strict manual model-routing override · `--auto-tier cheap|basic|premium` machine-carried raw tier for chained automation (posture-adjusted; used internally by the `/review-and-implement` handoff), mutually exclusive with `--tier`.
 
 **3. Review and Start**
-- **What it does:** Spawns one worktree per ticket; each session reviews the ticket inline and, after a per-ticket proceed/halt gate, hands off to a **fresh implementation session** that reuses the same worktree — review and implementation run in two separate agent contexts, not one shared session.
+- **What it does:** Like Start Tickets, but each ticket is reviewed first and only built if it passes.
 - **When it's useful:** (Refinement | Implementation | Automation) The **recommended front door** for "review these tickets, then implement the ones that pass," starting from existing ticket keys (unlike `/idea-to-pr`, which only accepts an idea).
-- **How to use it:** `/review-and-start BAPI-248 BAPI-250` (single or multiple keys flow through the identical code path).
+- **How to use it:** `/review-and-start BAPI-248 BAPI-250`
 - **Flags:** `--auto` auto-approves both the review and the implementation phase of every spawned session · `--rounds=1|2` forwarded to the review phase · `--agent`, `--base-branch`, `--max-parallel`, `--dry-run` mirror `/start-tickets`.
 
 **4. Define Tickets**
@@ -610,7 +680,7 @@ Good to know, but not needed every day.
 - **Flags:** Name the issue type (Bug / Story / Task / Epic) and, for a child ticket under an epic, the parent key.
 
 **2. Plan Ticket**
-- **What it does:** Generates a step-by-step implementation plan for a ticket that references real files in your codebase.
+- **What it does:** Writes a step-by-step plan for a ticket that points at the real files to change.
 - **When it's useful:** (Refinement | Implementation) Once a ticket is solid and you want a concrete build plan before — or instead of — auto-implementing it.
 - **How to use it:** `/plan-ticket BAPI-123`
 - **Flags:** `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check the plan with a second provider.
@@ -640,9 +710,9 @@ Good to know, but not needed every day.
 - **Flags:** None.
 
 **7. Drive Epic Run**
-- **What it does:** Launches an Epic Implementer run through `drive-epic` after a preview and an explicit yes — or attaches to the epic's live run — then drives it to a terminal state, applying one sanctioned recovery verb at a time and keeping a written tally.
+- **What it does:** Builds a whole epic for you. Bridge works through the child tickets in order, merges each one into the epic branch, and fixes routine problems along the way, so you only step in when it truly needs you. It shows you a preview and waits for your yes before it starts.
 - **When it's useful:** (Implementation | Automation) When an epic has an approved plan and you want its child tickets built and merged into the epic branch with one session watching the run.
-- **How to use it:** `/drive-epic-run <EPIC> [<plan path>]` — e.g. `/drive-epic-run BAPI-1145`; the plan is found automatically when the path is omitted.
+- **How to use it:** `/drive-epic-run BAPI-1145`
 - **Flags:** None — the epic key and an optional plan path are the only arguments.
 
 ### Now and then
@@ -733,7 +803,7 @@ Useful once in a while.
 Slash commands that drive several tools at once. Start Tickets, Review and Start, and Define Tickets are documented above under [Regularly useful](#regularly-useful); Create Decision Page is documented above under [Occasionally useful](#occasionally-useful); Regression Check and Scan Test Coverage are documented above under [Now and then](#now-and-then) — the rest live here.
 
 **1. Implement Ticket**
-- **What it does:** Full build for one ticket: generate a plan, write the code, commit, open a PR, and monitor CI.
+- **What it does:** Builds one ticket end to end: plans it, writes the code, opens a pull request, and watches CI.
 - **When it's useful:** (Implementation) When a ticket is ready and you want it taken from plan to open PR in one go.
 - **How to use it:** `/implement-ticket BAPI-123` (command only — "implement X" as free text almost always triggers a freehand build instead of the Bridge plan→code→PR→CI pipeline).
 - **Flags:** `--auto` skip the approval gates (e.g. auto-commit/push).
@@ -1071,14 +1141,15 @@ By hand, the outline is:
 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" \
-  --allowed-bot "<bot>" --secret-name <SECRET_NAME> --branches "<default branch>,epic/**"
+  --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, through a pull request into
+`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`.
 
@@ -1151,6 +1222,55 @@ For Codex, `GET /jira/codex-model-catalog?repo_name=...` is the sole tier-to-mod
 
 Per-OS prerequisites: macOS `wt`, `git`, `osascript`; Windows `git-wt`, Git for Windows / Git Bash, Windows Terminal or PowerShell; Linux `wt`, `git`, `tmux`. Set `BAPI_WORKTRUNK_BIN` to override the Worktrunk executable name/path for nonstandard installs (`doctor` honors it too). The read-only `doctor` subcommand (below) additionally surfaces a missing `uv` — Worktrunk's `pre-start` hook runs `uv`, but live preflight does not check it — and the selected agent's command; run `doctor --agent cursor-agent` to also check `cursor-agent` (it prints `cursor-agent login` as an informational auth reminder).
 
+### Missing packaged workflow files
+
+Run read-only `doctor` to distinguish absent, unreadable, unsafe, and uncertain
+workflow files. Healthy discovery adds no recovery prose. Confirmed loss in a
+root-bound initialized installation adds bounded recovery metadata and guidance;
+unknown hosts, fallback roots, legacy inventories, and newer bundle additions do
+not establish historical loss. Readable customized or uncommitted files count as
+present; committing generated files is unnecessary.
+
+```sh
+npx -y '@bridge_gpt/mcp-server@<running-version>' repair-assets --project-root '/path/to/project' --host claude
+```
+
+Replace `<running-version>` with the running package version. Both explicit root and host
+options authorize fill-only provisioning without inventory. Otherwise repair
+requires a matching inventory at the exact selected root; callers in a project
+subdirectory must supply `--project-root`. The canonical selected root is printed
+before writes. Unpinned `npx -y @bridge_gpt/mcp-server repair-assets` intentionally
+selects the latest package, which may introduce new assets.
+
+| Host | Packaged destinations |
+| --- | --- |
+| `claude` | `.claude/commands/`, `.claude/agents/`, shipped documentation |
+| `cursor` | `.cursor/commands/`, shipped documentation; no native agent definitions |
+| `codex` | `.agents/skills/bridge-*/SKILL.md`, shipped documentation |
+| `copilot` | Independent `.github/prompts/`, `.github/skills/`, `.github/agents/`, shipped documentation |
+
+Repair preserves existing bytes and concurrent creation winners. It prepares
+complete temporary files, flushes/closes them, and publishes with exclusive hard
+links. A confined Linux procfs adapter supports writes; macOS/Windows currently
+refuse missing-file writes because a qualified descriptor-relative adapter is
+unavailable. Non-files, permissions, unsafe ancestry, unsupported publication, or
+cleanup failures produce a nonzero exit and distinct diagnostics. Repair does not
+refresh or upgrade existing content.
+
+When a missing host command prevents Bridge invocation, run the terminal command
+from the established root, then refresh/reconnect and run doctor. Hosts may cache
+lists or ignore notifications; healthy files do not guarantee host presentation.
+If the mismatch persists, consult host support.
+
+Plans/reviews/research reports are generated outputs: retrieve identified existing
+results using `get_plan`, `wait_for_ticket_review` for eligible canonical legs,
+`get_deep_research(task_id)`, or `get_council(council_id)`. Never silently rerun paid
+generation. Agent-reviewed rewrites must be recreated and reviewed before
+publication; neither retrieval nor installer repair reconstructs them.
+
+Custom pipelines/instructions, MCP registration/configuration, credentials,
+onboarding/API setup, and Windsurf are outside packaged repair.
+
 ### `doctor`
 
 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:
@@ -1210,14 +1330,21 @@ The path from an epic to a finished run:
    `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, write an executor service unit,
+   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.
+   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
@@ -1264,7 +1391,10 @@ including every error path, ever offers you two paths.
 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), and `--replace-policy` (allow replacing a live run's
+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
@@ -1660,7 +1790,7 @@ If a custom pipeline has the same key as a built-in pipeline, the custom version
 | `BAPI_MCP_UPGRADE_ADVICE_ENABLED` | No | _(enabled)_ | MCP-local opt-out for proactively surfacing upgrade advice in pipeline recipe preambles. Set to `false`/`0`/`no`/`off`/`disabled` to suppress. Disabling it does **not** change the `/jira/ping` response or server-side upgrade computation — it only gates the recipe-preamble convention |
 | `BAPI_MCP_TOOL_SURFACE_GATING_ENABLED` | No | _(enabled)_ | MCP-local kill switch for **dynamic tool-surface capability gating** (see [Dynamic tool-surface gating](#dynamic-tool-surface-gating-capability-availability)). Default-on; set to `false`/`0`/`no`/`off`/`disabled` to skip the startup probe, the recurring poll, and the custom `tools/list` handler entirely, restoring the SDK's previous full profile-derived surface. Fail-open: any probe timeout, unreachable backend, non-2xx, malformed payload, incomplete evaluation, or unsupported schema advertises the full profile |
 | `BAPI_MCP_TOOL_SURFACE_POLL_ENABLED` | No | _(disabled)_ | Opt IN to the recurring tool-surface **poll**. Default-**off**: a session gates once via the startup probe and never re-probes. Set to `true`/`1`/`yes`/`on`/`enabled` to restore the jittered 12–18 s heartbeat that pushes `notifications/tools/list_changed` on mid-session capability changes. No effect when gating itself is disabled |
-| `BAPI_MCP_UPDATE_CHECK_ENABLED` | No | _(enabled)_ | MCP-local kill switch for the cached update check run at startup. Default-on; set to `false`/`0`/`no`/`off`/`disabled` to skip it entirely — no npm registry request, no update-cache read/write, no stderr advice, and no `tools/list` advisory decoration. Any other value is treated as enabled. Useful behind a firewall/registry-restricted network, and used by the payload-measurement harness so a stale local cache can never perturb a capture |
+| `BAPI_MCP_UPDATE_CHECK_ENABLED` | No | _(enabled)_ | MCP-local kill switch for the cached update check run at startup. Default-on; set to `false`/`0`/`no`/`off`/`disabled` to skip it entirely — no npm registry request, no update-cache read/write, and no upgrade notice on any surface (see [Upgrade notices](#upgrade-notices)). Any other value is treated as enabled. Useful behind a firewall/registry-restricted network, and used by the payload-measurement harness so a stale local cache can never perturb a capture |
 | `CURSOR_API_KEY` | No | _(none)_ | API key used to authenticate `cursor-agent` when launching `start-tickets`/scheduled runs with `--agent cursor-agent`. Not needed for the default Claude Code agent |
 | `BRIDGE_MCP_PROFILE` | No | `core` | Startup-time tool registration profile — a **comma-separated** list of groups controlling which tool groups are registered when the server starts. `core` is always implicitly included. Valid groups: `core` (default — normal coding tools only), `epic_implementer` (+ the 2 Epic Implementer tools, `get_epic_snapshot` and `explain_run`), `pipeline-authoring` (adds **no** tools since BAPI-909; still accepted so old configs keep working — `get_pipeline_recipe` stays in `core` because the recipe-driven slash commands depend on it), `estimation` (+ `estimate_epic`, which is **hidden by default** — `/estimate-epic` needs this group), `sfcc` (+ the 8 heavy SFCC read tools, `sfcc_log_query`, and the `sfcc_setup_status`/`check_permissions` diagnostics — read-only, see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools)), `sfcc-write` (+ the 9 destructive SFCC write tools — independent of `sfcc`, which does not enable them; see [Read and write profiles](#read-and-write-profiles)), and `full` (shortcut that expands to every group, **including `estimation` and `sfcc-write`**). Example: `sfcc,epic_implementer`; use `sfcc,sfcc-write` for reads plus writes. Unknown, blank, or malformed tokens are dropped (falling back to `core`). Dynamic mid-session switching via `tools/list_changed` is unsupported — groups are resolved once at process startup, so **changing this variable requires restarting the MCP server**. That is separate from the learn/onboarding tools, which are gated per session and can appear mid-session without a restart (see [Learn/onboarding tool availability](#learnonboarding-tool-availability)). Epic Implementer sessions launched via `start-tickets --conductor` **merge** `epic_implementer` into the parent process's already-resolved groups at the spawn boundary rather than replacing them — a project running on `sfcc` spawns workers on `core,sfcc,epic_implementer`. The retired token `conductor` is no longer valid and is dropped like any unknown token. A normal `start-tickets` run stays on `core`. |
 
@@ -1953,3 +2083,94 @@ plus `total_steps`, `auto_approve`, and `execution_mode`. Each step is either an
 text). `execution_mode` is `inline` — the calling agent executes every step
 itself and keeps its own durable record through `record_phase_result` /
 `record_checkpoint`. There is no server-side orchestrator and no run to resume.
+
+
+## Start Tickets troubleshooting
+
+`start-tickets` reports actual worktree paths and branches in its stable summary,
+then explains successfully spawned sessions. Work from each reported folder: its
+branch is already checked out there and normally cannot also be checked out in
+the original folder. Folder names and locations come from Worktrunk configuration;
+do not infer them from the original checkout.
+
+Monitor the selected agent in the reported Terminal/iTerm tab, Windows Terminal
+tab, PowerShell fallback window, or detached tmux session. Linux output prints
+the exact `tmux attach -t ...` commands. When a destination is not reported, treat
+it as unknown. A spawned session has started; it has not completed implementation
+or review. Review workflows review independently before opening a fresh
+implementation session. Coordinate ownership across multiple independent
+sessions and pause affected work when overlapping changes cause conflicts.
+
+For mixed failures, only `spawned` rows describe running sessions. Retain failed
+row warnings and the CLI exit status. Dry-run and all-failed results open no
+successful sessions. After a failure, read-only diagnostics are allowed:
+
+```bash
+npx -y @bridge_gpt/mcp-server doctor --agent codex
+```
+
+The interactive installer separates **Required for launcher** tools from
+**Recommended diagnostics** (`uv`, selected agent, ast-grep, ripgrep, lizard).
+Missing recommendations and the **Git compatibility advisory** add no install or
+launcher admission gate. Doctor performs no automatic repair, installation, PATH
+mutation, authentication, or terminal launch. The existing launcher still checks
+Git presence and repository work-tree context at launch.
+
+### Worktrunk and Git compatibility evidence
+
+The documented comparison baseline is **Worktrunk v0.80.0**, whose
+[tagged Git-version source](https://github.com/max-sixty/worktrunk/blob/v0.80.0/src/git/version.rs)
+sets the minimum to **Git 2.43.0**. This is the release-specific baseline Bridge
+recommends for this advisory, not a universal rule for every Worktrunk release or
+a requirement to install the latest Git. The onboarding report observed Git
+**2.39.5** being rejected with a **2.43.0** minimum; it did not identify the
+Worktrunk release, so that observation alone is not release verification.
+
+Doctor and the installer report the resolved Git executable and numeric version
+when available, with compatible, incompatible, and unknown advisory states.
+An arbitrary nonempty `BAPI_WORKTRUNK_BIN` override has an unconfirmed release
+requirement and is not assumed compatible with this baseline. On macOS,
+installing another Git does not ensure the launcher resolves it. Verify the
+executable and version selected on PATH before changing your installation:
+
+```bash
+which git
+git --version
+```
+
+### Saved planning work and launch readiness
+
+Successful ticket/plan creation does not establish executor, policy, VCS, or
+indexing readiness. A finalized epic completion may show one bounded read-only
+`drive-epic '<EPIC>' --dry-run --json` preview. Ready means **ready at preview
+time**; a conditional cold start still needs guarded startup/live validation.
+Returned target, refusal reasons, remedies, and `availability_text` remain
+authoritative. An unavailable preview leaves readiness unconfirmed while saved
+work remains successful. Free-form plans or unresolved child keys must be
+finalized first. Actual launch retains its consent and admission checks.
+
+## Backend-owned bootstrap identity (BAPI-1438)
+
+Ordinary new creation uses a friendly display label. Labels may repeat and never
+select credentials. For a scripted operator invite use `install --invite --display-name "My project"`
+and supply the invitation through the existing private input mechanism. In an
+interactive terminal the folder basename is a suggested label. Self-serve signup
+still requires emailed-code verification in an interactive terminal.
+
+Use `--repo <canonical-name>` or `BAPI_REPO_NAME` for existing-key registration
+or explicit legacy creation. Existing keys cannot use `--display-name`; creation
+cannot combine that flag with a canonical selector.
+
+Rerun from the original folder with the same invitation or signup method after
+an interrupted install. The original proof and label are reused; another entered
+label does not rename the recovered project. Preserve recovery storage when an
+outcome is unknown, a challenge cannot be recovered, or installation asks for support.
+Never delete possibly redeemed proof to restart. Ordinary invite tokens and
+verification codes are not stored.
+
+Credential storage uses bounded exclusive locking without timeout-based stealing.
+An abandoned lock needs installation support. 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.

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

@@ -1,6 +1,7 @@
 import { evaluateClaudeMcpShadowingPolicy, inspectClaudeUserConfigForMcpShadowing, resolveClaudeUserConfigPath, } from "../claude-user-config-doctor.js";
 import { createDefaultAgentCapabilitiesDeps } from "../agent-capabilities/default-deps.js";
 import { runDenyEnforcementPreflight, } from "../conductor/deny-enforcement-preflight.js";
+import { CLAUDE_DISABLE_AUTO_MEMORY_ENV } from "../claude-settings.js";
 import { buildExecutorBaseWorkerEnv } from "../executor/env.js";
 import { ExecutorNamedError } from "../executor/job-errors.js";
 import { provisionExecutorDenyLayer } from "../executor/permissions.js";
@@ -267,6 +268,24 @@ export function buildClaudeWatcherNudgeMessage(liveTaskIds) {
         "background log tail), you may stop that watcher. Do not cancel, kill, or abandon any " +
         "required work in order to finish sooner.");
 }
+/**
+ * BAPI-1395 — the nudge sent when the post-result completion window opens and
+ * only the worker's own background Bash is live. The executor cannot tell a
+ * task that merely waits (a polling loop, a `sleep`) from a genuine background
+ * operation, so it must not ask for blanket cancellation: only tasks that are
+ * merely waiting are to be stopped.
+ */
+export function buildClaudeCompletionWindowNudgeMessage(liveTaskIds) {
+    const ids = liveTaskIds
+        .map((id) => boundedIdentifier(id))
+        .filter((id) => id !== null)
+        .slice(0, NUDGE_MAX_TASK_IDS);
+    const named = ids.length > 0 ? ` (task ids: ${ids.join(", ")})` : "";
+    return claudeStdinUserLine(`Your result was received, but background shell tasks you started are still running${named}. ` +
+        "Stop only the tasks of your own that are merely waiting (for example a sleep or a polling " +
+        "loop). Leave any background operation that is doing real work running so it can finish and " +
+        "report its outcome. Do not cancel, kill, or abandon required work in order to finish sooner.");
+}
 // ---------------------------------------------------------------------------
 // Runtime identity probe (BAPI-1301, D4a)
 // ---------------------------------------------------------------------------
@@ -372,6 +391,13 @@ export function buildClaudeWorkerEnv(parentEnv, options = {}) {
     if (typeof token === "string") {
         env[CLAUDE_OAUTH_TOKEN_ENV] = token;
     }
+    // BAPI-1397 (F6) — a worker must never write the OWNER's Claude auto-memory.
+    // The deny-layer provisioning also writes `autoMemoryEnabled: false` into the
+    // worktree's settings; the environment form is set here as well because it
+    // wins over settings and does not depend on that file write succeeding. Set
+    // after the parent environment is filtered, so nothing inherited can turn it
+    // back on.
+    env[CLAUDE_DISABLE_AUTO_MEMORY_ENV] = "1";
     return env;
 }
 /**
@@ -620,6 +646,7 @@ export function createClaudeExecutorAdapter(spec, deps = {}) {
         transport: COMPLETION_EVIDENCE_TRANSPORT,
         probeRuntime: (probeDeps) => probeClaudeCompletionRuntime(spec.command, probeDeps),
         buildWatcherNudge: buildClaudeWatcherNudgeMessage,
+        buildCompletionWindowNudge: buildClaudeCompletionWindowNudgeMessage,
     };
     return {
         identity: {