@bridge_gpt/mcp-server 0.2.21 → 0.2.24

package/build/worktree-core.js

@@ -145,6 +145,44 @@ export async function isExistingBranchSafeToReuse(deps, branch, baseStartPoint)
  * job-type logic lives here — the caller decides the start point, the stale
  * guard, and the freshen behavior.
  */
+/**
+ * Hard-reset the branch checked out in `worktreePath` onto `ref`. Returns null on
+ * success or a bounded, secret-free `create-failed` error string on failure.
+ * Shared by the recovery freshen path and the BAPI-586 fresh-dispatch alignment.
+ */
+async function hardResetWorktree(deps, worktreePath, ref) {
+    const resetArgs = ["reset", "--hard", ref];
+    const reset = await deps.runCommand("git", resetArgs, { cwd: worktreePath });
+    if (!commandSucceeded(reset)) {
+        const reason = (reset.stderr || reset.stdout || "").trim();
+        return `git ${resetArgs.join(" ")} failed${reason ? `: ${reason}` : ""}`;
+    }
+    return null;
+}
+/**
+ * BAPI-586: resolve the worktree's `HEAD^{commit}` and the `expected` ref/commit
+ * and confirm they are equal. Returns null when they match, or a bounded,
+ * secret-free `create-failed` error string otherwise. Short-SHA fragments in the
+ * message are safe (they are public commit identifiers, not secrets).
+ */
+async function verifyWorktreeHead(deps, worktreePath, expected) {
+    const headRes = await deps.runCommand("git", ["rev-parse", "--verify", "HEAD^{commit}"], { cwd: worktreePath });
+    if (!commandSucceeded(headRes)) {
+        return "failed to resolve worktree HEAD after creation (git rev-parse HEAD^{commit} failed).";
+    }
+    const expectedRes = await deps.runCommand("git", ["rev-parse", "--verify", `${expected}^{commit}`], { cwd: worktreePath });
+    if (!commandSucceeded(expectedRes)) {
+        return "failed to resolve the expected base commit after creation (git rev-parse --verify failed).";
+    }
+    const head = headRes.stdout.trim();
+    const want = expectedRes.stdout.trim();
+    if (head !== want) {
+        return (`worktree head ${head.slice(0, 12)} does not match the pinned base ${want.slice(0, 12)}; ` +
+            `Worktrunk seeded the worktree from an unexpected start point. Refusing to hand a mis-seeded ` +
+            `worktree to a worker.`);
+    }
+    return null;
+}
 export async function createWorktreeForTicket(deps, key, branchOverrides, worktrunkBinary, baseStartPoint = "main", guardStaleWorktree = false, behavior = {}) {
     const branch = resolveBranchForTicket(key, branchOverrides);
     try {
@@ -181,16 +219,30 @@ export async function createWorktreeForTicket(deps, key, branchOverrides, worktr
         // `origin/<branch>`), so this only applies when the local branch pre-existed.
         // Run inside the switched worktree (the branch is checked out there).
         if (exists && behavior.freshenFromOrigin) {
-            const resetArgs = ["reset", "--hard", behavior.freshenFromOrigin];
-            const reset = await deps.runCommand("git", resetArgs, { cwd: worktreePath });
-            if (!commandSucceeded(reset)) {
-                const reason = (reset.stderr || reset.stdout || "").trim();
-                return {
-                    key,
-                    branch,
-                    status: "create-failed",
-                    error: `git ${resetArgs.join(" ")} failed${reason ? `: ${reason}` : ""}`,
-                };
+            const resetError = await hardResetWorktree(deps, worktreePath, behavior.freshenFromOrigin);
+            if (resetError) {
+                return { key, branch, status: "create-failed", error: resetError };
+            }
+        }
+        // BAPI-586 (fresh dispatch): a guard-approved pre-existing branch is an
+        // ancestor of base but may sit at an OLDER tip. Align it EXACTLY to the
+        // pinned base SHA so a fresh implementation starts at base, not at a stale
+        // ancestor. The stale-branch guard above already ran (and refused unsafe
+        // branches) before this destructive reset. Absent branches were created
+        // straight from `baseStartPoint`, so no alignment is needed there.
+        if (exists && behavior.alignExistingBranchTo) {
+            const resetError = await hardResetWorktree(deps, worktreePath, behavior.alignExistingBranchTo);
+            if (resetError) {
+                return { key, branch, status: "create-failed", error: resetError };
+            }
+        }
+        // BAPI-586 (fresh dispatch): verify the worktree actually starts at the
+        // pinned base. If Worktrunk seeded from an unexpected sibling despite
+        // `-b <sha>`, fail CLOSED before the worktree is handed to a worker.
+        if (behavior.verifyHeadMatches) {
+            const verifyError = await verifyWorktreeHead(deps, worktreePath, behavior.verifyHeadMatches);
+            if (verifyError) {
+                return { key, branch, status: "create-failed", error: verifyError };
             }
         }
         return { key, branch, status: "created", path: worktreePath };

package/{CONDUCTOR.md → docs/CONDUCTOR.md}

@@ -3,13 +3,61 @@
 Conductor is the **opt-in, off-by-default** coordination layer for running many
 agent sessions together (epic supervision, inter-agent messaging, done-gate
 evaluation, and conditional auto-merge). A normal `start-tickets` run does **not**
-involve Conductor — you opt in per run with `--conductor`, and epic-tick dispatch
-enables it internally.
+involve Conductor — you opt in per run with `--conductor`.
 
-This document is the reference for Conductor's observability stream, local git
-hooks, and the per-repo done-gate / auto-merge config. For the everyday
-`start-tickets` flags and cross-platform behavior, see
-[README → CLI Subcommands](./README.md#cli-subcommands).
+This document is the reference for Conductor's architecture, epic setup,
+observability stream, local git hooks, and the per-repo done-gate / auto-merge
+config. For the everyday `start-tickets` flags and cross-platform behavior, see
+[README → CLI Subcommands](../README.md#cli-subcommands).
+
+## Epic Conductor v2 — how an epic is actually driven
+
+**The v1 `conductor epic-tick` command is frozen.** It throws
+`EPIC_TICK_V1_FROZEN` on every invocation and advances nothing. There is nothing
+to schedule locally. If you have an epic-tick schedule registered from an earlier
+release, cancel it (`schedule-run cancel --id <id>`) — it is a dead timer.
+`conductor doctor` flags one if it finds it.
+
+v2 splits the old local tick into two halves:
+
+| Half | Where it runs | What it does |
+| --- | --- | --- |
+| **Reconciler** | **Server-side**, on the Bridge API worker dyno, every 30s | Selects every epic run whose status is `active`, evaluates gates, and enqueues executor jobs. Nothing to install or schedule. |
+| **Executor** | **Locally**, on your machine | Polls for jobs, claims them, spawns worker agents, heartbeats. This is the only piece you run. |
+
+```
+npx -y @bridge_gpt/mcp-server executor --repo <name>
+```
+
+The reconciler drives a run purely off `epic_runs.status = 'active'` — there is no
+local schedule, and no per-repo "enable the tick" flag. (An `epic_tick_enabled`
+config field existed briefly and was inert; it has been removed.)
+
+## Setting up an epic
+
+One command creates the run, stores the plan, and approves it:
+
+```
+npx -y @bridge_gpt/mcp-server setup-epic --epic-key BAPI-405 \
+  --plan-file docs/tmp/epic-plans/<slug>/epic-plan.dag.json
+```
+
+The plan sidecar (`epic-plan.dag.json`) is produced by the `decompose-epic`
+pipeline step. `setup-epic` validates it locally (unique ticket keys, resolvable
+`depends_on`/edge references, acyclicity) before sending anything, so a malformed
+plan fails legibly instead of as a bare HTTP 400.
+
+It is **idempotent**: re-running it on an epic that already has a live run reuses
+that run rather than minting a second one. Use `--dry-run` to validate a plan and
+preview the calls without mutating anything.
+
+Once the plan is approved the run becomes `active`, the server-side reconciler
+picks it up within ~30s, and your local `executor` starts claiming jobs.
+
+> **A caveat worth knowing before you plan an epic.** Conductor has no
+> merge-conflict handling, and plan-time file-overlap serialization is currently
+> dark (the planner does not yet emit the `touched_files` metadata it needs). If
+> two sibling tickets touch the same files, do not let them dispatch in parallel.
 
 ## Conductor observability (opt-in via `--conductor`, BAPI-394)
 
@@ -28,12 +76,12 @@ in the env, hook command, or run metadata. Override the gate/supervisor labels w
 `BAPI_CONDUCTOR_GATE_NAME` / `BAPI_CONDUCTOR_SUPERVISOR_MODE`. Inspect the stream
 with `conductor doctor`. Observability is best-effort: a conductor failure never
 blocks or aborts a spawn, and `--dry-run` performs no conductor side effects.
-(Epic-tick dispatch always enables conductor internally, independent of this flag.)
+(Epic dispatch always enables conductor internally, independent of this flag.)
 
 When `--conductor` is set, the spawn boundary also injects
 `BRIDGE_MCP_PROFILE=conductor` so each worker registers the 8 conductor/event/
 supervisor MCP tools (a plain `start-tickets` run stays on the default `core`
-profile). See [README → Environment Variables](./README.md#environment-variables).
+profile). See [README → Environment Variables](../README.md#environment-variables).
 
 ## `conductor install-git-hooks` (BAPI-395)
 
@@ -61,10 +109,28 @@ hook presence and managed-snippet status **read-only** (a new `git hooks` sectio
 MCP tool drives CI polling and gate evaluation regardless of whether hooks are
 installed.
 
-## `conductor_done_gate` config
+## Supervisor config — where the done gate and auto-merge live
+
+> **These are not config fields.** They used to be `conductor_done_gate` and
+> `conductor_auto_merge_enabled` on the generic config-field route; BAPI-438 moved
+> them onto dedicated supervisor endpoints. Setting them via
+> `PUT /jira/config-field/...` returns **HTTP 400 "Invalid config field"** — that
+> rejection is correct, not a bug. Use the endpoints below.
+
+Two scopes exist for each: a per-repo **project default**, and a per-epic override.
 
-The per-repo `conductor_done_gate` config field (read through the existing
-config-field route) defines the v1 done gate. It supports exactly one condition,
+| Setting | Endpoint (project default) |
+| --- | --- |
+| `done_gate_config` | `PUT /jira/epic-runs/supervisor-setup/defaults/?repo_name=<repo>` |
+| `auto_merge_enabled`, `merge_approval_required` | `PUT /jira/epic-runs/supervisor-config/defaults/?repo_name=<repo>` |
+
+Swap `…/defaults/` for `…/runs/{epic_key}/…` to scope a setting to one epic. The
+matching `GET` on each returns the effective value, with a `source` of `epic`,
+`project_default`, or `none` (nothing configured — fails closed).
+
+### `done_gate_config`
+
+Defines the done gate. It supports exactly one condition,
 `required_ci_checks_green`:
 
 ```json
@@ -81,30 +147,23 @@ config`) only when every listed required check is present, complete, and green f
 the bound PR head SHA. The gate **fails closed**: an unset, disabled (`enabled` not
 strictly `true`), malformed, empty, or unsupported config emits no `gate.met`.
 
-## `conductor_auto_merge_enabled` config (C6 conditional auto-merge)
+### `auto_merge_enabled` (C6 conditional auto-merge)
 
 When a worker's PR meets the done gate (`gate.met`), the supervisor can autonomously
-merge it — but **only** when the repo has explicitly opted in. The per-repo
-`conductor_auto_merge_enabled` config field (read through the same config-field route
-as `conductor_done_gate`) is the opt-in switch:
-
-```json
-{ "enabled": true }
-```
+merge it — but **only** when the repo has explicitly opted in.
+`auto_merge_enabled` on the supervisor-config endpoint is the opt-in switch.
 
-A bare JSON boolean (`true`) is also accepted. **Auto-merge is disabled by default.**
-Behavior:
+**Auto-merge is disabled by default.** Behavior:
 
-- **Disabled / unset / malformed → dry-run.** Anything other than `true` or
-  `{"enabled": true}` — including unset, `false`, `{"enabled": false}`, or any
-  malformed value — fails **closed**: the supervisor records a `merge.dry_run` event
-  and **no PR is ever merged**.
+- **Disabled / unset / unconfigured → dry-run.** Anything other than an explicit
+  `true` — including a repo with no supervisor config at all (`source: "none"`) —
+  fails **closed**: the supervisor records a `merge.dry_run` event and **no PR is
+  ever merged**.
 - **Enabled → autonomous merge** when the gate is met and the deterministic guards
   pass.
-- **Kill-switch.** Set `conductor_auto_merge_enabled` to `false` or remove the field
-  to immediately stop autonomous merges. The protected merge endpoint
-  **independently re-enforces** the flag, so even a conductor that calls it cannot
-  merge while the flag is off.
+- **Kill-switch.** Set `auto_merge_enabled` to `false` to immediately stop
+  autonomous merges. The protected merge endpoint **independently re-enforces** the
+  flag, so even a conductor that calls it cannot merge while the flag is off.
 
 Merge authority is **deterministic code, never an LLM**. The deterministic guards,
 all bound to **PR number + expected head SHA (never a branch name)**:

package/docs/install/github-app.md

@@ -0,0 +1,189 @@
+# Installing the Bridge GitHub App
+
+Bridge connects to GitHub through a **GitHub App**, not a personal access token. Once
+the app is installed on your repository and linked to your Bridge project, Bridge can
+open pull requests, run automated code review, read CI check status, and (when enabled)
+auto-merge — all using short-lived, per-call installation tokens. Your code and
+credentials stay on GitHub; Bridge mints a fresh token for each operation and stores no
+long-lived GitHub token.
+
+## The app
+
+| | |
+|---|---|
+| **Name** | Bridge GPT - AI Tools for SFCC |
+| **Owner** | [@Bridge-GPT](https://github.com/Bridge-GPT) |
+| **Public install page** | <https://github.com/apps/bridge-gpt-ai-tools-for-sfcc> |
+| **App ID** | `954077` |
+| **Client ID** | `Iv23liBEyDUeD25W06ix` |
+
+> The App ID and Client ID are **public** identifiers (GitHub shows them on the app's
+> settings page). They are not secrets. Only the app's **private key** and webhook
+> secret are sensitive, and those are held by whoever operates the Bridge deployment —
+> see [Self-hosting / operator setup](#self-hosting--operator-setup) at the end. As an
+> end user you never handle them.
+
+## Prerequisites
+
+- A GitHub repository you want Bridge to work on.
+- Permission to install a GitHub App on the account that owns it:
+  - **Personal repo:** you can install it yourself.
+  - **Organization repo:** you must be an **organization owner**, or a member who can
+    *request* the install for an owner to approve. (GitHub decides which button you see —
+    **Install**, **Install & request**, or **Request** — based on your role.)
+- Your Bridge project already registered (you have a Bridge API key and repo name).
+
+---
+
+## Option A — Connect GitHub button (recommended)
+
+This is the normal path. Bridge captures the installation automatically — you never copy
+an ID by hand.
+
+1. Open your project's **Get Started** page in the Bridge web UI.
+2. Click **Connect GitHub**. Bridge mints a short-lived, single-use link scoped to your
+   project and sends you to GitHub's app-install screen.
+3. On GitHub, choose the **account or organization** that owns the repository.
+4. Under **Repository access**, choose **Only select repositories** and pick the repo(s)
+   you want Bridge to cover (or **All repositories**). See
+   [Choosing repositories](#choosing-repositories) below.
+5. Review the requested permissions and click **Install** (or **Install & request** /
+   **Request** if an org owner must approve).
+6. GitHub redirects you back to Bridge. Bridge verifies the installation directly with
+   GitHub, links it to your project, and stores the installation automatically. If the
+   installation covers exactly one repo — or one repo clearly matches your project —
+   Bridge binds it for you; otherwise it shows a short **repository picker** so you can
+   confirm which repo maps to this project.
+
+That's it — no manual ID entry. If the automatic link fails for any reason, Bridge tells
+you and points you to Option B.
+
+---
+
+## Option B — Manual install + Installation ID (fallback)
+
+Use this if the Connect GitHub button isn't available to you, or automatic linking
+failed.
+
+### 1. Install the app
+
+Go to the public install page and install it on the owning account/organization,
+selecting the repository/repositories you want Bridge to access:
+
+<https://github.com/apps/bridge-gpt-ai-tools-for-sfcc/installations/new>
+
+(Same repository-selection and permissions-review screen as Option A, steps 3–5.)
+
+### 2. Find the Installation ID
+
+The Installation ID is the trailing number in the app's **Configure** URL:
+
+- **Personal account:** open **Settings → Applications → Installed GitHub Apps**, click
+  **Configure** next to *Bridge GPT - AI Tools for SFCC*. The URL is
+  `https://github.com/settings/installations/<INSTALLATION_ID>`.
+- **Organization:** open **Organization Settings → Third-party Access → GitHub Apps**,
+  click **Configure** next to the app. The URL is
+  `https://github.com/organizations/<ORG>/settings/installations/<INSTALLATION_ID>`.
+
+For example, `https://github.com/organizations/Bridge-GPT/settings/installations/61661616`
+has Installation ID **`61661616`**.
+
+### 3. Enter it in Bridge
+
+On your project's **Setup** page, in the GitHub section, paste the **Installation ID**
+into the field provided and save. Make sure the project's **version control system** is
+set to `github`. Bridge fills in the account owner and repository from your project
+settings.
+
+---
+
+## Choosing repositories
+
+When installing (either option), GitHub asks which repositories the app may access:
+
+- **All repositories** — the app can access every current and future repo on the account.
+- **Only select repositories** — pick specific repos from the **Select repositories**
+  dropdown. Recommended: grant only the repo(s) you actually want Bridge to work on.
+
+You can change this later at any time: **Configure** the installation (paths above),
+adjust **Repository access**, and click **Save**. If the app creates a repository, it is
+automatically granted access to that repo.
+
+## What the app can access
+
+At install time GitHub shows the **authoritative** list of permissions the app requests —
+review it there. Functionally, the Bridge integration exercises these GitHub permissions:
+
+| Permission | Why |
+|---|---|
+| **Contents** (read & write) | Read repo files for parsing/review; manage branch refs when opening/cleaning up PRs |
+| **Pull requests** (read & write) | List/read PRs and diffs; post review comments and reviews; merge when auto-merge is enabled |
+| **Checks / Commit statuses** (read) | Poll CI check-run and status results for a commit |
+| **Administration** (read) | Read branch-protection required-status-checks to resolve which checks must pass |
+| **Metadata** (read) | Baseline repo metadata; verify the installation's repository list |
+| **Webhook events** | Receive `pull_request`, `installation`, and review/merge events that drive automated review and merge |
+
+> These are inferred from the GitHub REST endpoints the integration calls. The exact set
+> the app is *registered* with is shown by GitHub on the install screen; treat that
+> screen as the source of truth.
+
+## Verifying the connection
+
+After linking, confirm Bridge can act on the repo:
+
+- The Bridge **Setup / integration status** should show version control as connected.
+- A Bridge operation that needs GitHub — e.g. `create_pull_request`, `resolve_ci_checks`,
+  or `poll_ci_checks` from the MCP — should succeed rather than return a
+  "no VCS connection" refusal. (See
+  [MCP Tool Integration Dependencies](./mcp-tool-integrations.md) for which tools require
+  a VCS connection.)
+
+If a GitHub-dependent tool refuses, the installation isn't linked to that project yet —
+re-run Option A, or set the Installation ID via Option B.
+
+## Managing or removing the app
+
+- **Change repo access / review permissions:** **Configure** the installation (URLs
+  above) → adjust **Repository access** → **Save**.
+- **Uninstall:** on the same Configure page, scroll to **Danger zone → Uninstall**.
+  Uninstalling revokes Bridge's access immediately; existing stored installation IDs stop
+  working.
+
+---
+
+## Self-hosting / operator setup
+
+*Skip this section if you are an end user connecting to a hosted Bridge deployment — it is
+for whoever runs the Bridge API server.*
+
+The GitHub App identity is configured **once per deployment** via environment variables.
+Bridge uses the App private key to mint short-lived installation tokens on demand; it
+persists no long-lived GitHub token.
+
+| Env var | Value / purpose |
+|---|---|
+| `GIT_APP_ID` | The app's numeric App ID — `954077` for *Bridge GPT - AI Tools for SFCC*. |
+| `GIT_PRIVATE_KEY` | **base64-encoded PEM** private key generated for the app (GitHub → app settings → *Generate a private key*). This is the one true secret. |
+| `GITHUB_APP_INSTALL_URL` | The public install URL the **Connect GitHub** button sends users to: `https://github.com/apps/bridge-gpt-ai-tools-for-sfcc/installations/new`. |
+| `GITHUB_WEBHOOK_SECRET` | App-level shared secret validating signed `installation` / merge webhooks. If unset, those webhooks are disabled (the redirect-callback path still works). |
+| `BGPT_ENCRYPTION_KEY` | Fernet key used to encrypt per-repo credentials at rest. |
+
+The app's **Setup URL** (in GitHub app settings) must point at the deployment's
+`GET /setup/github/callback` endpoint so the post-install redirect can auto-link the
+installation. Webhook endpoints used by the integration include the code-review hook
+(e.g. `https://<deployment-host>/github/code-review`); configure these on the app to match
+your deployment host.
+
+> **Note:** an older placeholder app slug (`bridge-gpt-code-reviewer`) still appears as a
+> stale default string in the codebase. The runtime install URL and App ID always come
+> from `GITHUB_APP_INSTALL_URL` / `GIT_APP_ID`, so set those to the `954077` /
+> `bridge-gpt-ai-tools-for-sfcc` values above rather than relying on the code default.
+
+## See also
+
+- [MCP Tool Integration Dependencies](./mcp-tool-integrations.md) — which MCP tools need a
+  VCS connection (BLOCK) vs merely degrade without one.
+- [Installing the SFCC Integration (OCAPI)](./sfcc-integration.md) — the separate
+  Salesforce B2C sandbox integration.
+- GitHub docs: [Installing a GitHub App from a third party](https://docs.github.com/en/apps/using-github-apps/installing-a-github-app-from-a-third-party),
+  [Reviewing and modifying installed GitHub Apps](https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps).