@bridge_gpt/mcp-server 0.2.38 → 0.2.39

package/README.md

@@ -32,8 +32,9 @@ account — it will ask.
 **Prerequisites**
 
 - **Node.js 18 or newer** (`node --version`), which is what provides `npx`.
-- **A project directory** — run the command from the folder your editor opens, the
-  one containing `package.json` or your repository root.
+- **A project directory** — run the command from the folder your editor opens: your
+  repository root, the one containing `.git`. No `package.json` is required — SFCC
+  cartridge repos, Python, Go, Rust, and other non-Node projects work the same way.
 - **An MCP-capable editor**: Claude Code, GitHub Copilot, Cursor, Windsurf, or
   OpenAI Codex.
 - **No Bridge account needed.** The installer can create one for you from just an
@@ -254,7 +255,7 @@ created or spent.
 | `--repo <name>` | Name the registered repository instead of resolving or asking for it |
 | `--tools <list>` | Configure specific MCP hosts without the picker (e.g. `claude-code,cursor`) |
 | `--agent claude\|cursor-agent` | Which agent to open for the final configuration step (default `claude`) |
-| `--dry-run` | Preview every step without writing, contacting Bridge, or opening anything |
+| `--dry-run` | Preview every step without writing, contacting Bridge, resolving or prompting for a credential, or opening anything. Genuinely inert: it returns before the project-root prompt, before the repository is resolved, and before any tool-selection prompt, so a value it cannot know locally (an unresolved repository name, an unselected tool) is shown as **not yet known** rather than guessed |
 | `--force` | Overwrite an existing stored key without asking |
 | `-h`, `--help` | Full usage |
 
@@ -269,7 +270,9 @@ different way to arrive, and the installer will not guess between them.
 The installer configures your editors for you. Do this only if you would rather
 write the config yourself, or if you use a host it cannot write automatically.
 
-Scaffold the project files without configuring anything:
+Scaffold the project files without configuring anything. Run it from the same
+project root `install` uses — your repository root, the one containing `.git`.
+No `package.json` is required:
 
 ```bash
 npx -y @bridge_gpt/mcp-server --init
@@ -753,9 +756,11 @@ Behind-the-scenes capabilities an agent gains from the MCP tools — mostly invo
 
 ## Salesforce B2C Commerce (SFCC) Tools
 
-Salesforce's official MCP server, `@salesforce/b2c-dx-mcp`, covers developer-experience tasks — cartridge deploy, step debugging, docs search, logs/MRT, and SCAPI Custom API scaffolding. As of its current toolset it has no way to *read* the platform's object model, custom objects, or site configuration — exactly the context an AI coding agent needs to write correct Commerce code and to inspect a sandbox before touching it. Bridge's SFCC tools install side-by-side with `b2c-dx-mcp` (they don't duplicate its surface) and close that gap with **read-only OCAPI Data API introspection** of system objects, custom object definitions, and site preferences.
+Salesforce's official MCP server, `@salesforce/b2c-dx-mcp`, covers developer-experience tasks — cartridge deploy, step debugging, docs search, logs/MRT, and SCAPI Custom API scaffolding. As of its current toolset it has no way to *read* the platform's object model, custom objects, or site configuration — exactly the context an AI coding agent needs to write correct Commerce code and to inspect a sandbox before touching it. Bridge's SFCC tools install side-by-side with `b2c-dx-mcp` (they don't duplicate its surface) and close that gap with **OCAPI Data API introspection** of system objects, custom object definitions, and site preferences — plus, behind a separate opt-in, a small set of sandbox-bounded writes.
 
-**v1 is read-only and developer-sandbox-only** — no writes, and non-sandbox instances are rejected. Credentials stay local (in `dw.json` or `SFCC_*` env vars) and are never sent to Bridge.
+**Every SFCC tool is restricted to a developer sandbox, and the restriction is checked at invocation time against the hostname your credentials actually resolve to** — not against anything the caller passes in. If `dw.json` or `SFCC_HOSTNAME` names a host Bridge does not recognize as a developer sandbox, every SFCC tool refuses with a `403` before contacting it. See [Sandbox enforcement](#sandbox-enforcement).
+
+**Credentials stay local** — in `dw.json` or `SFCC_*` env vars — and are never sent to Bridge. The `sfcc` profile registers read-only tools; the nine destructive write tools require the separate `sfcc-write` opt-in (see [Read and write profiles](#read-and-write-profiles)).
 
 For a step-by-step OCAPI client setup guide (including the Business Manager permissions grant), see [docs/install/sfcc-integration.md](./docs/install/sfcc-integration.md).
 
@@ -780,40 +785,91 @@ The two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always a
 
 Accepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`, `client-secret`/`clientSecret`/`client_secret`. Prefer a single config — a multi-entry `configs[]` array forces you to pass an explicit `instance` on every call. `dw.json` is auto-added to git exclude and must never be committed. Alternatively, export `SFCC_HOSTNAME` / `SFCC_CLIENT_ID` / `SFCC_CLIENT_SECRET` in the MCP server environment.
 
-**3. Enable the read tools.** Add `sfcc` to `BRIDGE_MCP_PROFILE` in the MCP server `env` block (it is comma-separated; `full` also works), then **restart the MCP client**:
+**3. Enable the tools you want.** Add the groups to `BRIDGE_MCP_PROFILE` in the MCP server `env` block (it is comma-separated), then **restart the MCP client**:
 
 ```json
 "env": { "BRIDGE_MCP_PROFILE": "sfcc" }
 ```
 
-Without this, only the diagnostic tools are registered.
+`sfcc` gives the eight read tools plus `sfcc_log_query`. For the nine destructive write tools as well, use `"sfcc,sfcc-write"`; `full` expands to every group and is therefore write-capable. Without any of these, only the diagnostic tools are registered.
 
 **4. Verify and grant OCAPI access.** Ask your agent to run `sfcc_setup_status` (expect all checks ✓), then `check_permissions`. If it reports HTTP 401/403, it prints the exact OCAPI Settings JSON to paste in Business Manager (**Administration → Site Development → Open Commerce API Settings → Data API** tab); save it there and re-run. Restart the MCP client after any credential or env change — a running session does not pick them up.
 
 </details>
 
+### Sandbox enforcement
+
+Every SFCC tool — all twenty, reads and writes alike, including the diagnostics —
+passes through one check before its own logic runs: **the hostname your
+credentials actually resolve to must be a recognized developer sandbox.**
+
+- The check reads `credentials.hostname`, the value that goes into the OCAPI
+  URL. It does not read the `instance` tool argument. Omitting `instance`, or
+  passing `instance: "sandbox"`, has no effect on the decision — neither one
+  selects or proves anything about the target. A dotted `instance` still
+  *selects* a host through the documented credential precedence, but the host it
+  selects is then validated like any other, so `check_permissions` cannot be
+  aimed at a named production instance.
+- It **fails closed.** An unrecognized, malformed, or unparseable hostname is
+  refused with HTTP `403`, `error.code: "TARGET_NOT_SANDBOX"`, and
+  `error.details.failure_class: "target-not-sandbox"`, before any request leaves
+  your machine.
+
+The accepted hostname forms are:
+
+| Form | Example |
+|---|---|
+| `<realm>-<nnn>.sandbox.<region>.dx.commercecloud.salesforce.com` | `zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com` |
+| `<realm>-<nnn>.sandbox.dx.commercecloud.salesforce.com` | `zzzz-001.sandbox.dx.commercecloud.salesforce.com` |
+| `<realm>-<nnn>.dx.commercecloud.salesforce.com` | `zyis-001.dx.commercecloud.salesforce.com` |
+
+Anything else is refused. In particular, hosts whose leading label names an
+environment (`production-…`, `staging-…`, `development-…`) are rejected even
+when they otherwise fit a form above, and the legacy `*.demandware.net` domain
+is not accepted at all — sandbox, staging, and production instances share that
+domain with no suffix that separates them.
+
+### Read and write profiles
+
+`sfcc` and `sfcc-write` are **independent** groups. Neither implies the other.
+
+| `BRIDGE_MCP_PROFILE` | SFCC tools registered |
+|---|---|
+| unset / `core` | `sfcc_setup_status`, `check_permissions` only |
+| `sfcc` | the above + 8 OCAPI read tools + `sfcc_log_query` |
+| `sfcc-write` | the above diagnostics + the 9 destructive write tools |
+| `sfcc,sfcc-write` | all 20 |
+| `full` | all 20 — `full` includes `sfcc-write` and is therefore write-capable |
+
+**Migration.** Enabling `sfcc` used to register the nine write tools as well. It
+no longer does. If you were relying on SFCC writes through
+`BRIDGE_MCP_PROFILE=sfcc`, change it to `BRIDGE_MCP_PROFILE=sfcc,sfcc-write`.
+Users of `BRIDGE_MCP_PROFILE=full` keep write access and need no change.
+
 ### Tools
 
-All SFCC tools are read-only and target a developer sandbox. An oversized response is saved in full to `BAPI_DOCS_DIR/sfcc/` and replaced by a parseable JSON descriptor — `truncated: true`, the `saved_path` it was written to, and the `page` metadata (`returned`, `total` when OCAPI supplied one, `has_more`) — so the collection metadata survives even though the data itself is on disk. If that save fails, the complete payload is returned inline instead, still as parseable JSON.
+The `sfcc` profile registers **read-only** tools: eight OCAPI reads plus `sfcc_log_query`. The **nine destructive write tools** are registered only by the separate `sfcc-write` profile — see [Read and write profiles](#read-and-write-profiles). Both surfaces are bounded to a developer sandbox by the same invocation-time check.
+
+An oversized response is saved in full to `BAPI_DOCS_DIR/sfcc/` and replaced by a parseable JSON descriptor — `truncated: true`, the `saved_path` it was written to, and the `page` metadata (`returned`, `total` when OCAPI supplied one, `has_more`) — so the collection metadata survives even though the data itself is on disk. If that save fails, the complete payload is returned inline instead, still as parseable JSON.
 
 Attribute-definition reads and writes can return an attribute's `default_value` at `projection: "full"`, and Bridge withholds it — every key is preserved except that one, whose value becomes `[REDACTED_BY_BRIDGE]` — from the inline response, the saved file, and a successful write echo alike. Attribute defaults are intentionally unavailable through this MCP surface; Business Manager is the supported path to read one.
 
 **Diagnostics** (always available, no profile needed)
 - `sfcc_setup_status` — report on every prerequisite: Bridge API key, repo name, `version` config, `dw.json` presence/uniqueness, AM (OCAPI) token acquisition, and the independent **SFCC Log Query (WebDAV)** capability that gates `sfcc_log_query`.
-- `check_permissions` — probe OCAPI access via `GET /system_object_definitions`; on 401/403, print the exact OCAPI Settings JSON to paste in Business Manager (split read-only vs. write/import grants).
+- `check_permissions` — probe OCAPI access via `GET /system_object_definitions`; on 401/403, print the exact OCAPI Settings JSON to paste in Business Manager (read/search grants for the `sfcc` tools, mutation grants for the `sfcc-write` tools). An explicit `instance` hostname is still subject to the sandbox check below.
 
 **System object model** (needs the `sfcc` profile)
 - `system_object_list` — list system object types (Product, Order, Customer, …).
 - `system_object_get` — fetch one system object type's definition.
 - `system_object_attribute_search` — search a type's attribute definitions; prefer this over a full dump when hunting a specific `c_` custom attribute.
 
-**Custom object definitions** (needs the `sfcc` profile)
+**Custom object definitions** (reads need `sfcc`; the two writes need `sfcc-write`)
 - `custom_object_definition_attributes_get` — fetch attribute definitions for a known custom object type (`default_value` withheld). OCAPI cannot enumerate custom object type *IDs* directly, so `object_type` must be known — but it is discoverable: call `system_object_list` at `projection: "full"` for each custom type's `display_name` and `attribute_definition_count`, derive a candidate id (e.g. strip spaces from `"Product Quality Result"` → `ProductQualityResult`), and confirm it by checking that this tool's returned attribute count matches that row's `attribute_definition_count`.
 - `custom_object_definition_attribute_search` — search attribute definitions within a known custom object type (`default_value` withheld). Read-only — creating a custom object *type* isn't possible via OCAPI; that's a future v2 metadata-import capability. Same discovery path as above applies to `object_type`.
 - `custom_object_definition_attribute_create` — **write** (sandbox only): create an attribute definition on a known custom object type via `PUT /custom_object_definitions/{type}/attribute_definitions/{id}`. TYPE creation is never attempted (the type must pre-exist). Echoes paste-ready OCAPI grant JSON on 403.
 - `custom_object_definition_attribute_update` — **write** (sandbox only): update an attribute definition via an ETag-conditional `PATCH …/attribute_definitions/{id}`; surfaces 409/412 conflicts and echoes grant JSON on 403.
 
-**Site preferences** (needs the `sfcc` profile; sandbox only)
+**Site preferences** (reads need `sfcc`; the write needs `sfcc-write`; sandbox only)
 - `site_preference_get` — read a preference group's effective preferences.
 - `site_preference_search` — search/filter preferences within a group.
 - `site_preference_values_set` — **write** (sandbox only): set custom preference values via `PATCH /site_preferences/preference_groups/{group}/sandbox` with a flat map of `c_`-prefixed ids to string/number/boolean/string[] values. A bad group returns 404 `CustomPreferenceGroupNotFoundException`; echoes grant JSON on 403.
@@ -883,6 +939,12 @@ npx -y @bridge_gpt/mcp-server doctor [--agent <name>]
 
 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
+`~/.claude.json` carries a login marker. This is informational only — it never
+blocks the doctor run and cannot guarantee the next worker spawn will
+authenticate. See
+[Claude login for conductor workers](#claude-login-for-conductor-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.
 
 ### `setup-epic`
@@ -901,6 +963,78 @@ Once the plan is approved, the **server-side reconciler** picks the run up withi
 npx -y @bridge_gpt/mcp-server executor --repo <name>
 ```
 
+### `conduct-epic`
+
+The deterministic half of the `/conduct-epic` loop: it owns the epic branch, a
+versioned local checkpoint, a per-epic lock, and the read-only probes the loop
+decides on. It never creates or mutates an `epic_run` — that is the server-side
+v2 reconciler's job, and `init` refuses to start when one is already active.
+
+```
+npx -y @bridge_gpt/mcp-server conduct-epic <verb> [flags]
+```
+
+**Verbs**
+
+| Verb | Flags |
+| --- | --- |
+| `init <EPIC>` | `--tickets K1,K2,…` (required), `--base-branch <b>`, `--checkpoint-path <p>`, `--dry-run`, `--json` |
+| `status <EPIC>` | `--json` (required), `--checkpoint-path <p>` |
+| `checkpoint set <EPIC>` | `--ticket <KEY>` (required), `--field <name> <value>` (repeatable), `--journal "<line>"`, `--checkpoint-path <p>` |
+| `finish <EPIC>` | `--checkpoint-path <p>`, `--json` |
+| `spawn <EPIC>` | `--ticket <KEY>` and `--prompt-file <path>` (required), `--agent claude\|cursor-agent`, `--checkpoint-path <p>`, `--json` |
+
+**Local state.** Everything lives *outside* the repository, under
+`~/.config/bridge/conduct/<repo>/` (honoring `XDG_CONFIG_HOME`), so it resolves
+identically from the main checkout and from any worktree and can never be
+committed by an agent running `git add`:
+
+| Path | Purpose |
+| --- | --- |
+| `<EPIC>.json` | the version-1 checkpoint (file `0600`, directory `0700`) |
+| `<EPIC>.json.prev` | the previous valid checkpoint, retained on every write |
+| `<EPIC>.lock` | the per-epic lock |
+| `<EPIC>/prompts/<KEY>-<kind>-<n>.md` | prompt files the caller writes for `spawn` |
+
+`status` prints the resolved `checkpoint_path`. To unpark a run a human edits the
+checkpoint (`needs_human` → `null`, plus the ticket's `status`/counters);
+`last_seen_head`, `ci_last_poll`, and `lock` are observational and are never
+hand-edited.
+
+**`init` runs ONE preflight** that reports *every* failure in a single pass and
+writes nothing unless all of them pass: `gh auth status`; Worktrunk resolves
+(honoring `BAPI_WORKTRUNK_BIN`); Bridge credentials resolve; `auto_merge_enabled`
+is on — or is turned on by PUTting the *complete* effective config back with just
+that flag flipped, which prints a line beginning `announced:`; at least one
+required CI check exists (an empty required set would make the done gate pass
+vacuously); no active server-side `epic_run` for the key; the lock is free or its
+owner is provably dead; the base branch exists on `origin` after `git fetch`; and
+the indexed-branch override is either absent or this epic's own — a re-`init`
+after a crash is accepted and its `original_base_branch` becomes the default base,
+while a *foreign* override is refused by name. `resolve-ci-checks` is called
+exactly once either way, because that call is what warms the `poll-ci-checks`
+cache the first `status` depends on. Only then does `init` push
+`epic/<EPIC>` to `origin` at the fetched base tip (no local checkout), repoint the
+index, write the checkpoint, and take the lock. `--dry-run` prints the validated
+plan and mutates nothing. A second `init` refuses with `already initialized`.
+
+**Failure posture is split on purpose.** In `status`, each probe fails *open*: a
+`gh`, CI, review, or parse failure leaves that sub-object `null`, adds an entry to
+`probe_errors`, and the command still exits `0` with a complete object — the loop
+must be able to read its own checkpoint during a GitHub outage. Everything else
+fails *closed*: a corrupt or wrong-version checkpoint makes every verb but `init`
+exit non-zero **without rewriting it**, and `checkpoint set`, `spawn`, and
+`finish` refuse a lock held by another live process. `status` never takes the lock.
+
+**Exit codes.** `0` on success — including a missing checkpoint
+(`checkpoint_exists: false`) and an idempotent second `finish`. Non-zero on any
+other failure, with a one-line reason on stderr. With `--json`, stdout is exactly
+one JSON object carrying `ok`.
+
+**Credentials** resolve only from `BAPI_API_KEY` or the user-scoped
+`bapi:<repo>` credential target, travel only in the `X-API-Key` header, and never
+appear in a command argument, in stdout/stderr, or in a journal line.
+
 ### Conductor (epic & multi-agent orchestration)
 
 Conductor is an **opt-in, off-by-default** layer for epic supervision, inter-agent messaging, done-gate evaluation, local git-hook event producers, and conditional auto-merge. Its full reference — the v2 architecture (server-side reconciler + local executor), `setup-epic`, `conductor install-git-hooks`, the supervisor `done_gate_config` / `auto_merge_enabled` settings, and the observability stream — lives in **[CONDUCTOR.md](./docs/CONDUCTOR.md)**.
@@ -964,7 +1098,7 @@ If a custom pipeline has the same key as a built-in pipeline, the custom version
 | `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 |
 | `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), `conductor` (+ 8 conductor/event/supervisor tools), `pipeline-authoring` (+ 5 pipeline run/admin tools — `get_pipeline_recipe` is NOT gated; it stays in `core` because the recipe-driven slash commands depend on it), `sfcc` (+ the 7 heavy SFCC read tools — see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools); the `sfcc_setup_status`/`check_permissions` diagnostics are always registered regardless), and `full` (shortcut that expands to every group). Example: `sfcc,conductor`. 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. Conductor/epic sessions launched via `start-tickets --conductor` automatically inject `BRIDGE_MCP_PROFILE=conductor` at the spawn boundary; a normal `start-tickets` run stays on `core`. |
+| `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), `conductor` (+ 8 conductor/event/supervisor tools), `pipeline-authoring` (+ 5 pipeline run/admin tools — `get_pipeline_recipe` is NOT gated; it stays in `core` because the recipe-driven slash commands depend on it), `sfcc` (+ the 8 heavy SFCC read tools and `sfcc_log_query` — read-only, see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools); the `sfcc_setup_status`/`check_permissions` diagnostics are always registered regardless), `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 `sfcc-write`**). Example: `sfcc,conductor`; 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. Conductor/epic sessions launched via `start-tickets --conductor` automatically inject `BRIDGE_MCP_PROFILE=conductor` at the spawn boundary; a normal `start-tickets` run stays on `core`. |
 
 ## Dynamic tool-surface gating (capability availability)
 
@@ -1084,6 +1218,47 @@ work. Two supported paths write it for you:
 
   Run it without `--write-credentials` to preview; add the flag to write the store.
 
+### Claude login for conductor workers
+
+Conductor workers are **not** isolated into a private Claude configuration
+directory — they run with the executor host's own `HOME`, so a worker
+authenticates the same way any interactive `claude` invocation on that host
+does. The prerequisite is simple: run
+
+```bash
+claude login
+```
+
+on the executor host, once, the normal way. Bridge never stores, resolves, mints,
+rotates, validates, or diagnoses this credential — it is entirely the operator's
+own Claude CLI state, exactly as if you were running `claude` at the terminal
+yourself.
+
+**Headless hosts.** If the executor host has no interactive login session
+available (a service-launched executor, a CI-style runner), export
+`CLAUDE_CODE_OAUTH_TOKEN` into the **executor process's own environment**
+yourself before starting it:
+
+```bash
+export CLAUDE_CODE_OAUTH_TOKEN="$(claude setup-token)"   # run once, wherever you can browser-login
+```
+
+Bridge forwards that value **unchanged**, byte-for-byte, into the direct worker
+process environment — nothing else. It is never written to disk, never placed in
+a generated launchd/systemd service unit, never placed in project configuration
+(`.mcp.json` / `.cursor/mcp.json`), and never sent to Bridge servers. There is no
+credential store entry for it and no lifecycle tracking: expiry, rotation, and
+validity are entirely the operator's own responsibility, the same as any other
+value you choose to export into a process environment.
+
+**`ANTHROPIC_API_KEY` is never forwarded to a worker**, under any circumstance —
+there is no fallback path for it.
+
+`mcp-server doctor` reports a single advisory **Claude login** line — whether
+`~/.claude.json` on the host it runs on carries a login marker. This is
+informational only: it cannot confirm the next worker spawn will authenticate,
+and it never blocks the doctor run or changes its exit code.
+
 ## Reference
 
 The full surface, for when you need the complete enumeration. Day-to-day, use [Usage Documentation](#usage-documentation) instead — you don't call MCP tools directly; you ask your AI assistant to perform a task, or compose tools into a pipeline.
@@ -1100,7 +1275,7 @@ The authoritative tool catalog covers **92 tools** (enumerated below). What's ac
 - **Other AI** — `second_opinion`, `generate_image`, `generate_decision_page`, `visual_diff` (deterministic pixel diff of a rendered URL vs a design comp)
 - **Ticket lifecycle** — `track_ticket`, `update_ticket_state`, `get_ticket_state`, `get_ticket_state_tree` (live repo-wide lifecycle + dependency tree; read-only, no mutation parameter)
 - **Jira status** — `get_jira_transitions`, `update_jira_status`, `resolve_target_status`
-- **Repository & CI** — `parse_repository`, `get_parse_status`, `regenerate_directory_map`, `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`
+- **Repository & CI** — `parse_repository`, `get_parse_status`, `regenerate_directory_map`, `create_pull_request`, `merge_pull_request`, `resolve_ci_checks`, `poll_ci_checks`
 - **Pipelines & automation** — `list_pipelines`, `get_pipeline_recipe`, `run_pipeline`, `resume_pipeline`, `list_pipeline_runs`, `delete_pipeline_run`, `run_full_automation`, `resume_full_automation`
 - **Config** — `get_project_standards`, `config_field` (operations: `get`, `update`, `list`)
 

package/build/agent-capabilities/probe-context.js

@@ -32,7 +32,8 @@ export function buildHeadlessArgs(agentName, opts) {
     }
     // claude (and any positional-prompt agent without a cwd flag)
     const args = ["-p"];
-    // BAPI-725: exactly ONE permission form, matching `buildClaudeExecutorArgv`.
+    // BAPI-725: exactly ONE permission form, matching the Claude executor
+    // adapter's argv builder (`agent-launchers/claude-executor-adapter.ts`).
     // `permissionMode` wins when both are supplied — emitting both would let the
     // skip flag take effect and the probe would report on a posture it never ran.
     if (opts.permissionMode === "acceptEdits") {