@bridge_gpt/mcp-server 0.2.67 → 0.2.68

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
@@ -217,8 +236,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
@@ -374,7 +393,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.68", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -396,7 +415,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.68", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -418,7 +437,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.68", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -441,7 +460,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.68", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -460,7 +479,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.68", "serve"]
 
 [mcp_servers.bridge.env]
 BAPI_BASE_URL = "https://bridgegpt-api.com"
@@ -1071,14 +1090,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 +1171,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,7 +1279,7 @@ 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.
@@ -1264,7 +1333,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
@@ -1953,3 +2025,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: {