@bridge_gpt/mcp-server 0.2.9 → 0.2.10

package/README.md

@@ -6,7 +6,58 @@ MCP server for [Bridge API](https://bridgegpt-api.com) — exposes Jira integrat
 
 ## Getting Started
 
-### 1. Install the Package
+### Quick start (one command)
+
+From your **project root**, run:
+
+```bash
+npx -y @bridge_gpt/mcp-server@latest install-bridge
+```
+
+`install-bridge` collapses the whole setup into a single command. It:
+
+1. **Scaffolds** the project (the same artifacts `--init` writes: slash commands,
+   agents, `.bridge/pipelines/`, and secret-free MCP config placeholders).
+2. **Writes the per-host MCP config** (`.mcp.json` / `.cursor/mcp.json` /
+   `.vscode/mcp.json`) with your real `BAPI_REPO_NAME` / `BAPI_API_KEY` /
+   `BAPI_BASE_URL` / `BAPI_DOCS_DIR`, preserving any unrelated servers. The
+   launcher it writes is pinned to the exact installed version so `npx` never
+   silently reuses a stale local copy. (Windsurf and Codex are global configs it
+   can't safely write — it prints copy-paste instructions for those.)
+3. **Verifies connectivity** against the Bridge API before persisting anything.
+4. **Persists your key** to the user-scoped credential store
+   (`~/.config/bridge/credentials.json`, target `bapi:<repo>`) so shell-spawned
+   tooling (e.g. `start-tickets`) can resolve it.
+5. **Opens a fresh agent session** that runs `/install-bridge` (to derive the
+   remaining config fields from your codebase) and then `/learn-repository`.
+
+The only inputs are an **API key** and a **repo name** (everything else is
+derived). Resolution order:
+
+- **API key:** `--api-key <key>` → `BAPI_API_KEY` env → an interactive (no-echo)
+  prompt. Generate one first on the Bridge API web UI **Security** page (see
+  [Generate an API Key](#2-generate-an-api-key)); the command consumes a key, it
+  never mints one. The key is **never printed or logged**.
+- **Repo name:** `--repo <name>` → `BAPI_REPO_NAME` env → an inferred default you
+  confirm interactively. It MUST match the server-side repository registration.
+
+Useful flags:
+
+- `--dry-run` — preview every step (scaffold targets, config files and keys with
+  the key value **redacted**, the ping target, the credential store target, and
+  the exact agent spawn command) without writing, pinging, or spawning anything.
+- `--force` — overwrite an existing real `BAPI_API_KEY` in a host config without
+  prompting (re-running is otherwise non-destructive).
+- `--agent claude|cursor-agent` — which agent to launch for the agentic remainder
+  (default `claude`).
+
+That's it — once `install-bridge` finishes you're connected. If you prefer to do
+it by hand (or just want to understand each step), the manual flow below does the
+same thing.
+
+### Manual Setup (Alternative)
+
+#### 1. Install the Package
 
 From your **project root**, install the MCP server and scaffold slash commands:
 
@@ -23,7 +74,7 @@ npx -y @bridge_gpt/mcp-server --init
 
 Re-run `--init` after upgrading the package to get updated commands.
 
-### 2. Generate an API Key
+#### 2. Generate an API Key
 
 1. Log in to [Bridge API](https://bridgegpt-api.com) and navigate to your project's **Security** page
 2. Click **Create New Key**
@@ -31,7 +82,7 @@ Re-run `--init` after upgrading the package to get updated commands.
 4. Click **Create Key**
 5. **Copy the key immediately** — it will not be shown again
 
-### 3. Configure the MCP Server
+#### 3. Configure the MCP Server
 
 Add the following to your editor's MCP configuration file, pasting in the API key from step 2:
 
@@ -145,7 +196,7 @@ BAPI_DOCS_DIR = "docs/tmp"
 
 After saving the config, restart your editor or reload the MCP server connection. Verify connectivity by asking your AI assistant to call the `ping` tool.
 
-### 4. First-Time Setup: Teach Bridge Your Codebase
+#### 4. First-Time Setup: Teach Bridge Your Codebase
 
 If you're the first person to install Bridge API on your project, run the `/learn-repository` slash command after completing setup. This analyzes your codebase's architecture, testing patterns, code review standards, and documentation conventions, then uploads the findings to Bridge API. This gives Bridge the context it needs to generate implementation plans, ticket critiques, and code reviews that are consistent with your project's actual architecture and conventions.
 
@@ -540,6 +591,7 @@ Reports are written to `<BAPI_DOCS_DIR>/smoke-test/REPORT-<host>-<timestamp>.md`
 | `BAPI_WORKTRUNK_BIN` | No | `wt` (`git-wt` on Windows) | Override the Worktrunk executable name/path used by `start-tickets` for nonstandard installs |
 | `BAPI_TMUX_SESSION` | No | `bridge-start-tickets` | Override the tmux session-name prefix used by `start-tickets` on Linux |
 | `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 |
+| `BRIDGE_MCP_PROFILE` | No | `core` | Startup-time tool registration profile. Controls which tool groups are registered when the server starts. Valid values: `core` (default — normal coding tools only), `conductor` (core + 8 conductor/event/supervisor tools), `pipeline-authoring` (core + 5 pipeline run/admin tools — `get_pipeline_recipe` is NOT gated; it stays in `core` because the recipe-driven slash commands depend on it), `full` (all tools, equivalent to the legacy unconditional registration). Unknown, blank, or malformed values fail safe to `core`. Dynamic mid-session switching via `tools/list_changed` is unsupported — the profile is resolved once at process startup. **Phase 2b note:** epic/conductor sessions launched via `start-tickets` will automatically inject `BRIDGE_MCP_PROFILE=conductor`; that injection is handled at the spawn boundary and is out of scope for this phase. |
 
 ## Worktree credentials and the `mcp-invoke` shim
 

package/build/conductor/bridge-api-client.js

@@ -13,7 +13,7 @@ import os from "node:os";
 import { readFile, stat } from "node:fs/promises";
 import { resolveBapiCredentials } from "../credential-store.js";
 import { resolveStartTicketsRepoName } from "../start-tickets-repo.js";
-import { DONE_GATE_CONFIG_FIELD, normalizePrNumber, normalizeSha } from "./git-ci-types.js";
+import { normalizePrNumber, normalizeSha } from "./git-ci-types.js";
 import { ConductorValidationError } from "./errors.js";
 /** Default Bridge API base URL when `BAPI_BASE_URL` is unset. */
 export const CONDUCTOR_DEFAULT_BASE_URL = "https://bridgegpt-api.com";
@@ -95,7 +95,7 @@ function conductorGetHeaders(access) {
  * non-2xx response — never including the response body, headers, or API key. The
  * timer is always cleared.
  */
-export async function fetchConductorJsonWithTimeout(url, headers, timeoutMs, fetchImpl = fetch) {
+export async function fetchConductorJsonWithTimeout(url, headers, timeoutMs, fetchImpl = globalThis.fetch) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
@@ -132,7 +132,7 @@ export async function fetchConductorJsonWithTimeout(url, headers, timeoutMs, fet
  * `value` payload (or `undefined` when the envelope lacks a `value`). The field
  * name is URL-encoded; the repo scope is always included.
  */
-export async function fetchConductorConfigField(access, fieldName, fetchImpl = fetch) {
+export async function fetchConductorConfigField(access, fieldName, fetchImpl = globalThis.fetch) {
     const url = buildConductorJiraUrl(access.baseUrl, `/config-field/${encodeURIComponent(fieldName)}`, {
         repo_name: access.repoName,
     });
@@ -142,9 +142,41 @@ export async function fetchConductorConfigField(access, fieldName, fetchImpl = f
     }
     return undefined;
 }
-/** Fetch the per-repo `conductor_done_gate` config value (raw, unparsed). */
-export function fetchDoneGateConfigField(access, fetchImpl = fetch) {
-    return fetchConductorConfigField(access, DONE_GATE_CONFIG_FIELD, fetchImpl);
+/**
+ * Fetch the effective supervisor setup for a repo.
+ *
+ * When ``epicKey`` is provided, hits ``GET /jira/epic-runs/runs/{epicKey}/supervisor-setup/``
+ * (per-epic row with project-default fallback). When omitted, hits
+ * ``GET /jira/epic-runs/supervisor-setup/defaults/`` (project-default only).
+ * Fails closed (throws ``ConductorBridgeApiError``) on any network or server error.
+ */
+export async function fetchEffectiveSupervisorSetup(access, epicKey, fetchImpl = globalThis.fetch) {
+    const apiPath = epicKey
+        ? `${EPIC_RUNS_API_PREFIX}/runs/${encodeURIComponent(epicKey)}/supervisor-setup/`
+        : `${EPIC_RUNS_API_PREFIX}/supervisor-setup/defaults/`;
+    const url = buildConductorJiraUrl(access.baseUrl, apiPath, {
+        repo_name: access.repoName,
+    });
+    const parsed = await fetchConductorJsonWithTimeout(url, conductorGetHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    return parsed;
+}
+/**
+ * Fetch the effective supervisor config for a repo.
+ *
+ * When ``epicKey`` is provided, hits ``GET /jira/epic-runs/runs/{epicKey}/supervisor-config/``
+ * (per-epic row with project-default fallback). When omitted, hits
+ * ``GET /jira/epic-runs/supervisor-config/defaults/`` (project-default only).
+ * Fails closed (throws ``ConductorBridgeApiError``) on any network or server error.
+ */
+export async function fetchEffectiveSupervisorConfig(access, epicKey, fetchImpl = globalThis.fetch) {
+    const apiPath = epicKey
+        ? `${EPIC_RUNS_API_PREFIX}/runs/${encodeURIComponent(epicKey)}/supervisor-config/`
+        : `${EPIC_RUNS_API_PREFIX}/supervisor-config/defaults/`;
+    const url = buildConductorJiraUrl(access.baseUrl, apiPath, {
+        repo_name: access.repoName,
+    });
+    const parsed = await fetchConductorJsonWithTimeout(url, conductorGetHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    return parsed;
 }
 /**
  * Poll CI checks for a commit through the existing `/poll-ci-checks` endpoint.
@@ -152,7 +184,7 @@ export function fetchDoneGateConfigField(access, fetchImpl = fetch) {
  * request when it is not a valid SHA. Returns the endpoint response verbatim —
  * the client never invents `pr_number`/`head_sha` fields.
  */
-export async function pollCiChecksForCommit(access, commitRef, fetchImpl = fetch) {
+export async function pollCiChecksForCommit(access, commitRef, fetchImpl = globalThis.fetch) {
     const sha = normalizeSha(commitRef);
     if (sha === null) {
         throw new ConductorBridgeApiError("invalid-input");
@@ -164,6 +196,26 @@ export async function pollCiChecksForCommit(access, commitRef, fetchImpl = fetch
     return fetchConductorJsonWithTimeout(url, conductorGetHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
 }
 // ---------------------------------------------------------------------------
+// Conductor BAPI-440: PR review status GET client
+// ---------------------------------------------------------------------------
+/**
+ * Fetch the normalized PR review status from the backend-owned review-status
+ * endpoint. Validates `prNumber` with {@link normalizePrNumber} before issuing
+ * the request. Returns the endpoint response verbatim — the client never invents
+ * review fields. Throws a sanitized {@link ConductorBridgeApiError} on any failure
+ * so the producer can fail-closed without leaking body/headers/key.
+ */
+export async function fetchPrReviewStatus(access, prNumber, fetchImpl = globalThis.fetch) {
+    const pr = normalizePrNumber(prNumber);
+    if (pr === null) {
+        throw new ConductorBridgeApiError("invalid-input");
+    }
+    const url = buildConductorVcsUrl(access.baseUrl, `/vcs/pull-requests/${pr}/reviews/status`);
+    const fullUrl = new URL(url);
+    fullUrl.searchParams.set("repo_name", access.repoName);
+    return fetchConductorJsonWithTimeout(fullUrl.toString(), conductorGetHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+}
+// ---------------------------------------------------------------------------
 // Conductor C6 (BAPI-398): protected VCS merge POST client
 // ---------------------------------------------------------------------------
 /**
@@ -181,19 +233,20 @@ function conductorPostHeaders(access) {
     return { "X-API-Key": access.apiKey, "Content-Type": "application/json" };
 }
 /**
- * POST JSON with an `AbortController` timeout, mirroring
- * {@link fetchConductorJsonWithTimeout}. Throws a sanitized
+ * Send a JSON request body with the given HTTP method and an `AbortController`
+ * timeout, mirroring {@link fetchConductorJsonWithTimeout}. Throws a sanitized
  * {@link ConductorBridgeApiError} on abort/timeout, network failure, or any
  * non-2xx response — never including the response body, headers, API key, or
- * request body in the error. The timer is always cleared.
+ * request body in the error. The timer is always cleared. Shared core for the
+ * POST and PATCH wrappers below.
  */
-export async function fetchConductorJsonPostWithTimeout(url, headers, body, timeoutMs, fetchImpl) {
+async function fetchConductorJsonWithMethodAndTimeout(method, url, headers, body, timeoutMs, fetchImpl) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
         let resp;
         try {
-            resp = await fetchImpl(url, { method: "POST", headers, body, signal: controller.signal });
+            resp = await fetchImpl(url, { method, headers, body, signal: controller.signal });
         }
         catch {
             throw new ConductorBridgeApiError(controller.signal.aborted ? "timeout" : "network");
@@ -218,6 +271,29 @@ export async function fetchConductorJsonPostWithTimeout(url, headers, body, time
         clearTimeout(timer);
     }
 }
+/**
+ * POST JSON with an `AbortController` timeout. Thin wrapper over
+ * {@link fetchConductorJsonWithMethodAndTimeout}.
+ */
+export async function fetchConductorJsonPostWithTimeout(url, headers, body, timeoutMs, fetchImpl) {
+    return fetchConductorJsonWithMethodAndTimeout("POST", url, headers, body, timeoutMs, fetchImpl);
+}
+/**
+ * PATCH JSON with an `AbortController` timeout. Thin wrapper over
+ * {@link fetchConductorJsonWithMethodAndTimeout}. Used by the per-ticket CAS
+ * status endpoint, which the backend declares as PATCH.
+ */
+export async function fetchConductorJsonPatchWithTimeout(url, headers, body, timeoutMs, fetchImpl) {
+    return fetchConductorJsonWithMethodAndTimeout("PATCH", url, headers, body, timeoutMs, fetchImpl);
+}
+/**
+ * PUT JSON with an `AbortController` timeout. Thin wrapper over
+ * {@link fetchConductorJsonWithMethodAndTimeout}. Used by endpoints that the
+ * backend declares as PUT (e.g. the Jira status transition endpoint).
+ */
+export async function fetchConductorJsonPutWithTimeout(url, headers, body, timeoutMs, fetchImpl) {
+    return fetchConductorJsonWithMethodAndTimeout("PUT", url, headers, body, timeoutMs, fetchImpl);
+}
 /**
  * Call the protected `POST /vcs/pull-requests/{pr_number}/merge` endpoint. The PR
  * number lives ONLY in the path; the API key travels ONLY in headers; the body
@@ -225,7 +301,7 @@ export async function fetchConductorJsonPostWithTimeout(url, headers, body, time
  * before the request is issued. Throws a sanitized {@link ConductorBridgeApiError}
  * on any failure.
  */
-export async function mergePullRequestForGate(access, request, fetchImpl = fetch) {
+export async function mergePullRequestForGate(access, request, fetchImpl = globalThis.fetch) {
     const pr = normalizePrNumber(request.pr_number);
     const sha = normalizeSha(request.expected_head_sha);
     if (pr === null || sha === null || !request.action_key || !request.repo_name) {
@@ -244,6 +320,51 @@ export async function mergePullRequestForGate(access, request, fetchImpl = fetch
     const parsed = await fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
     return parsed;
 }
+/**
+ * Call the protected `POST /vcs/pull-requests/{pr_number}/remediate` endpoint.
+ * The PR number lives ONLY in the path; the API key travels ONLY in headers; the
+ * body carries no branch name or provider token. A 409 (idempotency-key replay)
+ * is caught and returned as `{ ok: true, conflict: true }`; all other failures
+ * throw a sanitized {@link ConductorBridgeApiError}.
+ */
+export async function remediateEpicTicket(access, request, fetchImpl = globalThis.fetch) {
+    const pr = normalizePrNumber(request.pr_number);
+    if (pr === null ||
+        !request.epic_run_id ||
+        !request.ticket_key ||
+        !request.head_sha ||
+        !request.idempotency_key) {
+        throw new ConductorBridgeApiError("invalid-input");
+    }
+    requireNonNegativeSafeInteger(request.expected_row_version);
+    if (request.attempt_kind !== "nudge" && request.attempt_kind !== "redispatch") {
+        throw new ConductorBridgeApiError("invalid-input");
+    }
+    const url = buildConductorVcsUrl(access.baseUrl, `/vcs/pull-requests/${pr}/remediate`);
+    // The body omits pr_number (it is in the path) and never includes a branch name
+    // or provider token; extra fields would be rejected server-side (extra=forbid).
+    const body = JSON.stringify({
+        repo_name: access.repoName,
+        epic_run_id: request.epic_run_id,
+        ticket_key: request.ticket_key,
+        expected_row_version: request.expected_row_version,
+        head_sha: request.head_sha,
+        idempotency_key: request.idempotency_key,
+        attempt_kind: request.attempt_kind,
+        ...(request.reason ? { reason: request.reason } : {}),
+    });
+    try {
+        const parsed = await fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+        return { ok: true, conflict: false, response: parsed };
+    }
+    catch (err) {
+        if (err instanceof ConductorBridgeApiError && err.kind === "http" && err.status === 409) {
+            // Idempotency-key replay: the attempt was already recorded on a prior tick.
+            return { ok: true, conflict: true };
+        }
+        throw err;
+    }
+}
 // ---------------------------------------------------------------------------
 // Local boundary validators (reject before any fetch call)
 // ---------------------------------------------------------------------------
@@ -268,7 +389,7 @@ function requireNoSlashPathSegment(value) {
     }
 }
 const EPIC_TICKET_STATUS_VALUES = [
-    "planned", "ready", "dispatched", "running", "blocked", "abandoned", "done",
+    "planned", "ready", "dispatched", "running", "blocked", "abandoned", "done", "ready_for_review",
 ];
 function requireEpicTicketStatusValue(value) {
     if (typeof value !== "string" || !EPIC_TICKET_STATUS_VALUES.includes(value)) {
@@ -299,15 +420,21 @@ function epicDispatchTransitionApiPath(dispatchKey, nextStatus) {
  * Build the canonical dispatch idempotency key in lock-step with the server-side
  * `build_dispatch_key` Python helper.
  *
- * Format: `dispatch:{epicKey}:{ticketKey}:{planVersion}`.
+ * Format: `dispatch:{epicKey}:{ticketKey}:{planVersion}`. For a remediation
+ * re-dispatch (BAPI-441), pass `attempt > 0` to append an `:r{attempt}` suffix
+ * (e.g. `dispatch:BAPI-405:BAPI-441:3:r2`) so the re-dispatch claims a *distinct*
+ * key from the original epic dispatch and is not deduped against it. `attempt`
+ * defaults to 0, which yields the original (un-suffixed) key for normal dispatch.
  *
  * // TODO(epic-run-store): the epic component maps to the server-side epic_run_id component used by build_dispatch_key; confirm naming if the sibling renames it at integration.
  */
-export function buildEpicDispatchKey(epicKey, ticketKey, planVersion) {
+export function buildEpicDispatchKey(epicKey, ticketKey, planVersion, attempt = 0) {
     requireNonEmptyString(epicKey);
     requireNonEmptyString(ticketKey);
     requireNonNegativeSafeInteger(planVersion);
-    return `dispatch:${epicKey}:${ticketKey}:${planVersion}`;
+    requireNonNegativeSafeInteger(attempt);
+    const base = `dispatch:${epicKey}:${ticketKey}:${planVersion}`;
+    return attempt > 0 ? `${base}:r${attempt}` : base;
 }
 // ---------------------------------------------------------------------------
 // Epic supervision lease claim/renew
@@ -334,7 +461,7 @@ function parseEpicSupervisionLeaseResult(parsed) {
  * acquired/renewed from held-by-other and terminal so the control loop can decide
  * whether to act or exit as an observer. Validates inputs before the request.
  */
-export async function claimEpicSupervisionLease(access, request, fetchImpl = fetch) {
+export async function claimEpicSupervisionLease(access, request, fetchImpl = globalThis.fetch) {
     requireNonEmptyString(request.epicKey);
     requireNonEmptyString(request.leaseOwner);
     requirePositiveSafeInteger(request.ttlSeconds);
@@ -355,12 +482,31 @@ export async function claimEpicSupervisionLease(access, request, fetchImpl = fet
  * Returns the server payload verbatim — no ready-set computation, plan-hash
  * assertion, or derived control-loop fields are added.
  */
-export async function fetchEpicRunState(access, epicKey, fetchImpl = fetch) {
+export async function fetchEpicRunState(access, epicKey, fetchImpl = globalThis.fetch) {
     requireNonEmptyString(epicKey);
     const url = buildConductorJiraUrl(access.baseUrl, `${epicRunApiPath(epicKey)}/state`, { repo_name: access.repoName });
     const parsed = await fetchConductorJsonWithTimeout(url, conductorGetHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
     return parsed;
 }
+/**
+ * GET `/jira/epic-runs/runs?repo_name=<repo>&status=active` and return the
+ * list of active epic runs. Caps at 20 results — enough for typical deployments
+ * and prevents runaway iteration in the producer resolution seam.
+ */
+export async function fetchActiveEpicRuns(access, fetchImpl = globalThis.fetch) {
+    const url = buildConductorJiraUrl(access.baseUrl, `${EPIC_RUNS_API_PREFIX}/runs`, {
+        repo_name: access.repoName,
+        status: "active",
+        limit: "20",
+    });
+    const parsed = await fetchConductorJsonWithTimeout(url, conductorGetHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    if (parsed && typeof parsed === "object") {
+        const runs = parsed.runs;
+        if (Array.isArray(runs))
+            return runs;
+    }
+    return [];
+}
 // ---------------------------------------------------------------------------
 // Per-ticket CAS status advancement
 // ---------------------------------------------------------------------------
@@ -393,13 +539,14 @@ function parseAdvanceEpicTicketStatusResult(parsed) {
     throw new ConductorBridgeApiError("server");
 }
 /**
- * POST to the per-ticket CAS status endpoint. Surfaces CAS conflicts as a distinct
- * non-throwing outcome so the control loop can re-read rather than crashing.
+ * PATCH the per-ticket CAS status endpoint
+ * (`PATCH /runs/{epic_run_id}/tickets/{ticket_key}`). Surfaces structured CAS
+ * conflicts as a distinct non-throwing outcome where the backend returns one;
+ * the current backend instead raises a 400 VALIDATION on a stale row_version,
+ * which surfaces as a thrown `ConductorBridgeApiError("http", 400)`.
  * Transport/auth/server failures still throw a sanitized {@link ConductorBridgeApiError}.
- *
- * // TODO(epic-run-store): ticket requires POST but sibling currently declares PATCH /runs/{epic_run_id}/tickets/{ticket_key}; reconcile HTTP method at integration.
  */
-export async function advanceEpicTicketStatus(access, request, fetchImpl = fetch) {
+export async function advanceEpicTicketStatus(access, request, fetchImpl = globalThis.fetch) {
     requireNonEmptyString(request.epicKey);
     requireNonEmptyString(request.ticketKey);
     requireNonNegativeSafeInteger(request.expectedRowVersion);
@@ -408,7 +555,10 @@ export async function advanceEpicTicketStatus(access, request, fetchImpl = fetch
     if (request.dispatchRunId !== undefined) {
         requireNonEmptyString(request.dispatchRunId);
     }
-    // TODO(epic-run-store): ticket requires POST; sibling is currently PATCH — reconcile at integration
+    // The backend declares this endpoint as PATCH /runs/{epic_run_id}/tickets/{ticket_key}
+    // (api/routes/epic_runs.py:489). The body matches PatchEpicTicketStatusRequest:
+    // repo_name + expected_row_version are required; status/plan_version/dispatch_run_id
+    // are optional and accepted (the model does not forbid extras).
     const CAS_ENDPOINT_PATH = `${epicRunApiPath(request.epicKey)}/tickets/${encodeURIComponent(request.ticketKey)}`;
     const url = buildConductorJiraUrl(access.baseUrl, CAS_ENDPOINT_PATH);
     const body = JSON.stringify({
@@ -418,7 +568,7 @@ export async function advanceEpicTicketStatus(access, request, fetchImpl = fetch
         expected_row_version: request.expectedRowVersion,
         ...(request.dispatchRunId ? { dispatch_run_id: request.dispatchRunId } : {}),
     });
-    const parsed = await fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    const parsed = await fetchConductorJsonPatchWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
     return parseAdvanceEpicTicketStatusResult(parsed);
 }
 /**
@@ -427,7 +577,7 @@ export async function advanceEpicTicketStatus(access, request, fetchImpl = fetch
  * ticks and re-plans is safe. Throws a sanitized {@link ConductorBridgeApiError}
  * on any transport/auth/server error.
  */
-export async function createEpicTicketStatus(access, request, fetchImpl = fetch) {
+export async function createEpicTicketStatus(access, request, fetchImpl = globalThis.fetch) {
     requireNonEmptyString(request.epicKey);
     requireNonEmptyString(request.ticketKey);
     requireEpicTicketStatusValue(request.status);
@@ -486,13 +636,13 @@ function parseEpicDispatchResult(parsed) {
  * outcome so a crashed-then-retried tick never double-dispatches. The dispatch key
  * is composed exclusively via {@link buildEpicDispatchKey}.
  */
-export async function recordEpicDispatch(access, request, fetchImpl = fetch) {
+export async function recordEpicDispatch(access, request, fetchImpl = globalThis.fetch) {
     requireNonEmptyString(request.epicKey);
     requireNonEmptyString(request.ticketKey);
     requireNonEmptyString(request.leaseOwner);
     requireNonNegativeSafeInteger(request.planVersion);
     requirePositiveSafeInteger(request.ttlSeconds);
-    const dispatchKey = buildEpicDispatchKey(request.epicKey, request.ticketKey, request.planVersion);
+    const dispatchKey = buildEpicDispatchKey(request.epicKey, request.ticketKey, request.planVersion, request.attempt ?? 0);
     const url = buildConductorJiraUrl(access.baseUrl, `${EPIC_RUNS_API_PREFIX}/dispatch/claim`);
     const body = JSON.stringify({
         repo_name: access.repoName,
@@ -515,7 +665,7 @@ export async function recordEpicDispatch(access, request, fetchImpl = fetch) {
  * Dispatch keys containing `/` are rejected before the request because transition
  * endpoints embed the key as a URL path segment.
  */
-export async function transitionEpicDispatch(access, request, fetchImpl = fetch) {
+export async function transitionEpicDispatch(access, request, fetchImpl = globalThis.fetch) {
     requireNonEmptyString(request.dispatchKey);
     requireNoSlashPathSegment(request.dispatchKey);
     requireEpicDispatchTransitionStatus(request.nextStatus);
@@ -537,7 +687,7 @@ export async function transitionEpicDispatch(access, request, fetchImpl = fetch)
  * in the `X-API-Key` header, never in the URL. Throws a sanitized
  * {@link ConductorBridgeApiError} on any transport/auth/server error.
  */
-export async function storeEpicPlan(access, request, fetchImpl = fetch) {
+export async function storeEpicPlan(access, request, fetchImpl = globalThis.fetch) {
     requireNonEmptyString(request.epicKey);
     requirePositiveSafeInteger(request.planVersion);
     requireNonEmptyString(request.planHash);
@@ -562,7 +712,7 @@ export async function storeEpicPlan(access, request, fetchImpl = fetch) {
  * monotonic constraint violation). Other errors throw a sanitized
  * {@link ConductorBridgeApiError}.
  */
-export async function approveEpicPlan(access, request, fetchImpl = fetch) {
+export async function approveEpicPlan(access, request, fetchImpl = globalThis.fetch) {
     requireNonEmptyString(request.epicKey);
     requirePositiveSafeInteger(request.planVersion);
     const url = buildConductorJiraUrl(access.baseUrl, `${epicRunApiPath(request.epicKey)}/approve-plan`);
@@ -589,7 +739,7 @@ export async function approveEpicPlan(access, request, fetchImpl = fetch) {
  * Returns the response as a {@link GetEpicPlanResponse}. The API key travels
  * ONLY in the `X-API-Key` header, never in the URL.
  */
-export async function getEpicPlan(access, epicKey, planVersion, fetchImpl = fetch) {
+export async function getEpicPlan(access, epicKey, planVersion, fetchImpl = globalThis.fetch) {
     requireNonEmptyString(epicKey);
     const url = buildConductorJiraUrl(access.baseUrl, `${epicRunApiPath(epicKey)}/plan`, { repo_name: access.repoName, plan_version: String(planVersion) });
     const parsed = await fetchConductorJsonWithTimeout(url, conductorGetHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
@@ -604,7 +754,7 @@ export async function getEpicPlan(access, epicKey, planVersion, fetchImpl = fetc
  * holds the lock) and `"idle"` (no lock is held). Throws a sanitized
  * {@link ConductorBridgeApiError} on any transport/auth/server failure.
  */
-export async function fetchParseStatus(access, fetchImpl = fetch) {
+export async function fetchParseStatus(access, fetchImpl = globalThis.fetch) {
     const url = buildConductorJiraUrl(access.baseUrl, "/parse-status", {
         repo_name: access.repoName,
     });
@@ -618,8 +768,85 @@ export async function fetchParseStatus(access, fetchImpl = fetch) {
  * safe. Returns the response envelope verbatim. Throws a sanitized
  * {@link ConductorBridgeApiError} on any transport/auth/server failure.
  */
-export async function triggerRepositoryParse(access, fetchImpl = fetch) {
+export async function triggerRepositoryParse(access, fetchImpl = globalThis.fetch) {
     const url = buildConductorJiraUrl(access.baseUrl, "/parse-repository");
     const body = JSON.stringify({ repo_name: access.repoName });
     return fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
 }
+/**
+ * Call the protected `DELETE /vcs/pull-requests/{pr_number}/branch` endpoint.
+ * Treats 404-equivalent responses as idempotent success (already deleted).
+ * Throws a sanitized {@link ConductorBridgeApiError} on auth/server/network
+ * failures.
+ */
+export async function deletePullRequestBranch(access, prNumber, expectedHeadSha, fetchImpl = globalThis.fetch) {
+    const pr = normalizePrNumber(prNumber);
+    if (pr === null) {
+        throw new ConductorBridgeApiError("invalid-input");
+    }
+    const url = buildConductorVcsUrl(access.baseUrl, `/vcs/pull-requests/${pr}/branch?repo_name=${encodeURIComponent(access.repoName)}&expected_head_sha=${encodeURIComponent(expectedHeadSha)}`);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), CONDUCTOR_FETCH_TIMEOUT_MS);
+    try {
+        let resp;
+        try {
+            resp = await fetchImpl(url, {
+                method: "DELETE",
+                headers: { "X-API-Key": access.apiKey },
+                body: "",
+                signal: controller.signal,
+            });
+        }
+        catch {
+            throw new ConductorBridgeApiError(controller.signal.aborted ? "timeout" : "network");
+        }
+        // 404 from the provider → branch already gone → idempotent success
+        if (resp.status === 404) {
+            return { deleted: false, branch: null, reason: "not_found" };
+        }
+        if (!resp.ok) {
+            if (resp.status === 401 || resp.status === 403) {
+                throw new ConductorBridgeApiError("unauthorized", resp.status);
+            }
+            if (resp.status >= 500) {
+                throw new ConductorBridgeApiError("server", resp.status);
+            }
+            throw new ConductorBridgeApiError("http", resp.status);
+        }
+        try {
+            return (await resp.json());
+        }
+        catch {
+            throw new ConductorBridgeApiError("network");
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Call `PUT /jira/tickets/{ticketNumber}/jira-status` to transition the ticket's
+ * Jira status on truly-done. Uses `target_status: "auto"` for server-side resolution.
+ * Treats HTTP 400 (no matching transition / already in target) as a benign skip.
+ * Throws a sanitized {@link ConductorBridgeApiError} on auth/server/network failures.
+ */
+export async function transitionJiraStatus(access, ticketNumber, targetStatus = "auto", fetchImpl = globalThis.fetch) {
+    if (!ticketNumber) {
+        throw new ConductorBridgeApiError("invalid-input");
+    }
+    // repo_name travels in the JSON body only (TransitionJiraStatusRequest) — the
+    // backend ignores any query param, so don't duplicate it in the URL.
+    const url = buildConductorJiraUrl(access.baseUrl, `/tickets/${encodeURIComponent(ticketNumber)}/jira-status`);
+    const body = JSON.stringify({ repo_name: access.repoName, target_status: targetStatus });
+    try {
+        await fetchConductorJsonPutWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+        return { status: "transitioned" };
+    }
+    catch (err) {
+        // HTTP 400 = no matching transition / already in target → benign skip.
+        if (err instanceof ConductorBridgeApiError && err.kind === "http" && err.status === 400) {
+            return { status: "skipped" };
+        }
+        throw err;
+    }
+}

package/build/conductor/cli.js

@@ -528,7 +528,7 @@ export async function runDoctorCommand(argv) {
     // scheduleDeps omitted: buildConductorDoctorReport lazily loads schedule-run.
     const report = await buildConductorDoctorReport({});
     if (bools.has("--json")) {
-        console.log(JSON.stringify({ ...report.ledger, git_hooks: report.git_hooks, epic_tick: report.epic_tick }));
+        console.log(JSON.stringify({ ...report.ledger, git_hooks: report.git_hooks, epic_tick: report.epic_tick, mcp_profile: report.mcp_profile }));
         return 0;
     }
     console.log(formatConductorDoctorReport(report));
@@ -662,6 +662,24 @@ export function parseEpicTickArgs(argv) {
     const leaseTtlSeconds = parsePositiveIntFlag(values, "--lease-ttl-seconds");
     return { epicKey: epicKeyRaw.trim(), scheduledAt, leaseTtlSeconds, help: false };
 }
+/**
+ * Default the PreToolUse hook ON for epic-dispatched workers so the supervisor
+ * gets worker-liveness (`tool.intent`) signals without the operator having to
+ * export `BAPI_CONDUCTOR_ENABLE_PRE_TOOL_USE=1` (BAPI-441/A1 finding).
+ *
+ * Both the child-env copy and the hook registration key off this SAME
+ * parent-process env flag, read at dispatch time, so setting it once at the
+ * epic-tick boundary covers the whole tick. Only defaults when the flag is
+ * UNSET — an explicit "0"/"" still disables it, because `isConductorFlagEnabled`
+ * treats those as false. Mutates the supplied env in place (defaults to
+ * `process.env`) and returns it.
+ */
+export function applyEpicTickPreToolUseDefault(env = process.env) {
+    if (env.BAPI_CONDUCTOR_ENABLE_PRE_TOOL_USE === undefined) {
+        env.BAPI_CONDUCTOR_ENABLE_PRE_TOOL_USE = "1";
+    }
+    return env;
+}
 /**
  * Run the `epic-tick` command. Lazily imports the epic runtime so a plain
  * `conductor doctor` / `emit-event` invocation never eagerly resolves the
@@ -673,6 +691,9 @@ export async function runEpicTickCommand(argv) {
         console.log(getConductorUsage());
         return 0;
     }
+    // Enable supervisor worker-liveness by default for the whole tick (see the
+    // helper's doc comment); set before runEpicTick dispatches any worker.
+    applyEpicTickPreToolUseDefault();
     // `runEpicTick` is imported LAZILY so the store/supervisor graph is not
     // evaluated for other conductor CLI commands that never need it.
     const { runEpicTick, buildProductionEpicRuntimeDeps } = await import("./epic-runtime.js");