@bridge_gpt/mcp-server 0.2.53 → 0.2.55

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

@@ -15,6 +15,7 @@ import { resolveBapiCredentials } from "../credential-store.js";
 import { resolveStartTicketsRepoName } from "../start-tickets-repo.js";
 import { normalizePrNumber, normalizeSha } from "./git-ci-types.js";
 import { ConductorValidationError } from "./errors.js";
+import { resolveDeclaredRunBaseBranch } from "./run-branch.js";
 /** Default Bridge API base URL when `BAPI_BASE_URL` is unset. */
 export const CONDUCTOR_DEFAULT_BASE_URL = "https://bridgegpt-api.com";
 /** Default per-request timeout for conductor Bridge API calls. */
@@ -257,9 +258,26 @@ function redactDiagnosticValues(diagnostics, secrets) {
  * values in `headers` (e.g. `X-API-Key`) are additionally redacted from the
  * preview so a body that echoes the credential can never surface it.
  */
-async function readSanitizedErrorDiagnostics(resp, headers = {}) {
+async function readSanitizedErrorDiagnostics(resp, headers = {}, options = {}) {
     try {
-        const diagnostics = extractSanitizedErrorDiagnostics(stripWebhookUrlsDeep(await resp.json()));
+        const parsed = stripWebhookUrlsDeep(await resp.json());
+        const diagnostics = extractSanitizedErrorDiagnostics(parsed);
+        if (options.readErrorField && !diagnostics.bodyPreview) {
+            // BAPI-1154: opt-in only. The route layer's `_http_error` envelope carries
+            // its server-authored explanation in `detail.error`, which the shared
+            // extractor deliberately does not read (pinned by its own tests). The
+            // repair verbs render that explanation to the operator who asked, so they
+            // opt in; every other caller's diagnostics are unchanged.
+            const detail = parsed && typeof parsed === "object" && !Array.isArray(parsed)
+                ? parsed["detail"]
+                : undefined;
+            const error = detail && typeof detail === "object" && !Array.isArray(detail)
+                ? detail["error"]
+                : undefined;
+            if (typeof error === "string" && error.trim()) {
+                diagnostics.bodyPreview = boundedErrorPreview(error.trim());
+            }
+        }
         const secrets = Object.entries(headers)
             .filter(([k]) => /key|authorization|token/i.test(k))
             .map(([, v]) => v);
@@ -502,8 +520,8 @@ function conductorPostHeaders(access) {
  * request body in the error. The timer is always cleared. Shared core for the
  * POST and PATCH wrappers below.
  */
-async function fetchConductorJsonWithMethodAndTimeout(method, url, headers, body, timeoutMs, fetchImpl) {
-    const { body: parsed } = await fetchConductorJsonWithMethodStatusAndTimeout(method, url, headers, body, timeoutMs, fetchImpl);
+async function fetchConductorJsonWithMethodAndTimeout(method, url, headers, body, timeoutMs, fetchImpl, errorOptions = {}) {
+    const { body: parsed } = await fetchConductorJsonWithMethodStatusAndTimeout(method, url, headers, body, timeoutMs, fetchImpl, errorOptions);
     return parsed;
 }
 /**
@@ -517,7 +535,7 @@ async function fetchConductorJsonWithMethodAndTimeout(method, url, headers, body
  * that only sees the body has to issue another request to learn which happened.
  * Success statuses only; every non-2xx path still throws exactly as before.
  */
-async function fetchConductorJsonWithMethodStatusAndTimeout(method, url, headers, body, timeoutMs, fetchImpl) {
+async function fetchConductorJsonWithMethodStatusAndTimeout(method, url, headers, body, timeoutMs, fetchImpl, errorOptions = {}) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
@@ -529,7 +547,7 @@ async function fetchConductorJsonWithMethodStatusAndTimeout(method, url, headers
             throw new ConductorBridgeApiError(controller.signal.aborted ? "timeout" : "network");
         }
         if (!resp.ok) {
-            const diagnostics = await readSanitizedErrorDiagnostics(resp, headers);
+            const diagnostics = await readSanitizedErrorDiagnostics(resp, headers, errorOptions);
             if (resp.status === 401 || resp.status === 403) {
                 throw new ConductorBridgeApiError("unauthorized", resp.status, diagnostics);
             }
@@ -860,15 +878,19 @@ export async function readEpicRunCompletionState(access, epicRunId, fetchImpl =
     if (!isEpicRunStatus(status)) {
         return { ok: false, reason: "malformed" };
     }
+    // BAPI-1127: the declared branch comes from the ONE canonical resolver, not a
+    // third inline read. The read this replaced consulted `base_branch` only (so a
+    // `baseBranch` row reported no feature branch at all) and assigned the value
+    // untrimmed (so `"  epic/X  "` reached the wind-down PR path with its
+    // whitespace intact). `policy_json` is untrusted boundary input and the
+    // resolver takes it as `unknown` by design — every non-mapping shape declares
+    // nothing rather than throwing.
     const policyJson = epicRun["policy_json"];
-    let featureBranch;
-    if (policyJson && typeof policyJson === "object" && !Array.isArray(policyJson)) {
-        const baseBranch = policyJson["base_branch"];
-        if (typeof baseBranch === "string" && baseBranch.trim().length > 0) {
-            featureBranch = baseBranch;
-        }
-    }
-    return { ok: true, state: featureBranch ? { status, featureBranch } : { status } };
+    const featureBranch = resolveDeclaredRunBaseBranch(policyJson);
+    return {
+        ok: true,
+        state: featureBranch !== undefined ? { status, featureBranch } : { status },
+    };
 }
 /**
  * GET `/jira/epic-runs/runs?repo_name=<repo>&status=active` and return the
@@ -1160,6 +1182,155 @@ export async function adoptCurrentHeadAndUnparkTicket(access, request, fetchImpl
     });
     return postUnparkLikeRequest(url, conductorPostHeaders(access), body, fetchImpl);
 }
+// ---------------------------------------------------------------------------
+// BAPI-1154 — run-addressed operator repair verbs (CLI-only; no MCP tool)
+// ---------------------------------------------------------------------------
+// Each client sends only its documented body and returns the server's bounded,
+// authoritative result. None accepts or transmits a head SHA, gate identity,
+// action key, branch, provider credential, actor, row version, or idempotency
+// receipt: ownership, identity, and state are the SERVER's to decide. A named
+// refusal surfaces as a thrown `ConductorBridgeApiError` carrying the server's
+// `errorCode` (e.g. `TICKET_NOT_IN_RUN`), which the CLI renders by code.
+function parseRepairNullableString(value) {
+    return typeof value === "string" ? value : null;
+}
+function parseRepairBase(parsed) {
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new ConductorBridgeApiError("server");
+    }
+    const p = parsed;
+    if (typeof p["epic_run_id"] !== "string" ||
+        typeof p["committed"] !== "boolean" ||
+        typeof p["event_recorded"] !== "boolean") {
+        throw new ConductorBridgeApiError("server");
+    }
+    return p;
+}
+function parseScopeReparseResult(parsed) {
+    const p = parseRepairBase(parsed);
+    if (typeof p["scope_id"] !== "string" || typeof p["parse_scheduled"] !== "boolean") {
+        throw new ConductorBridgeApiError("server");
+    }
+    return {
+        epic_run_id: p["epic_run_id"],
+        scope_id: p["scope_id"],
+        before: parseRepairNullableString(p["before"]),
+        after: parseRepairNullableString(p["after"]),
+        committed: p["committed"],
+        event_recorded: p["event_recorded"],
+        outcome: typeof p["outcome"] === "string" ? p["outcome"] : "",
+        parse_scheduled: p["parse_scheduled"],
+    };
+}
+function parseDispatchRemediationResult(parsed) {
+    const p = parseRepairBase(parsed);
+    if (typeof p["ticket_key"] !== "string") {
+        throw new ConductorBridgeApiError("server");
+    }
+    const jobId = p["job_id"];
+    return {
+        epic_run_id: p["epic_run_id"],
+        ticket_key: p["ticket_key"],
+        before: parseRepairNullableString(p["before"]),
+        after: parseRepairNullableString(p["after"]),
+        committed: p["committed"],
+        event_recorded: p["event_recorded"],
+        job_type: typeof p["job_type"] === "string" ? p["job_type"] : "",
+        job_id: typeof jobId === "number" && Number.isSafeInteger(jobId) ? jobId : null,
+    };
+}
+function parseMergeChildRouteResponse(parsed) {
+    const p = parseRepairBase(parsed);
+    const prNumber = p["pr_number"];
+    if (typeof prNumber !== "number" || !Number.isSafeInteger(prNumber) || prNumber <= 0) {
+        throw new ConductorBridgeApiError("server");
+    }
+    let localExecution = null;
+    const local = p["local_execution"];
+    if (local && typeof local === "object" && !Array.isArray(local)) {
+        const l = local;
+        const sha = normalizeSha(l["expected_head_sha"]);
+        if (sha === null) {
+            // An approval that names no usable head cannot be executed safely.
+            throw new ConductorBridgeApiError("server");
+        }
+        localExecution = {
+            expected_head_sha: sha,
+            merge_method: parseRepairNullableString(l["merge_method"]),
+        };
+    }
+    return {
+        epic_run_id: p["epic_run_id"],
+        pr_number: prNumber,
+        ticket_key: typeof p["ticket_key"] === "string" ? p["ticket_key"] : "",
+        before: parseRepairNullableString(p["before"]),
+        after: parseRepairNullableString(p["after"]),
+        committed: p["committed"],
+        event_recorded: p["event_recorded"],
+        reason: parseRepairNullableString(p["reason"]),
+        local_execution: localExecution,
+    };
+}
+async function postRepairRequest(access, apiPath, body, fetchImpl) {
+    return fetchConductorJsonWithMethodAndTimeout("POST", buildConductorJiraUrl(access.baseUrl, apiPath), conductorPostHeaders(access), JSON.stringify({ repo_name: access.repoName, ...body }), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl, 
+    // The server's refusal explanation is the operator-facing message here.
+    { readErrorField: true });
+}
+/**
+ * POST `/jira/epic-runs/runs/{epic_run_id}/scope-reparse` — re-drive the run's
+ * OWN index scope through the retry-reparse lifecycle. Body: `{repo_name,
+ * scope_id}`. The server refuses a scope not bound to the run (`404
+ * TICKET_NOT_IN_RUN`) with nothing written.
+ */
+export async function scopeReparse(access, request, fetchImpl = globalThis.fetch) {
+    requireNonEmptyString(request.epicRunId);
+    requireNonEmptyString(request.scopeId);
+    const parsed = await postRepairRequest(access, `${epicRunApiPath(request.epicRunId)}/scope-reparse`, { scope_id: request.scopeId }, fetchImpl);
+    return parseScopeReparseResult(parsed);
+}
+/**
+ * POST `/jira/epic-runs/runs/{epic_run_id}/tickets/{ticket_key}/dispatch-remediation`
+ * — body `{repo_name, context}`. The SERVER selects `remediate` or
+ * `reconcile_overlap` and admits the job through the reconciler's own sequence;
+ * this client never names a job type.
+ */
+export async function dispatchRemediation(access, request, fetchImpl = globalThis.fetch) {
+    requireNonEmptyString(request.epicRunId);
+    requireNonEmptyString(request.ticketKey);
+    requireNonEmptyString(request.context);
+    const parsed = await postRepairRequest(access, `${epicRunApiPath(request.epicRunId)}/tickets/${encodeURIComponent(request.ticketKey)}/dispatch-remediation`, { context: request.context }, fetchImpl);
+    return parseDispatchRemediationResult(parsed);
+}
+/**
+ * POST `/jira/epic-runs/runs/{epic_run_id}/merge-child` — body EXACTLY
+ * `{repo_name, pr_number}`. The server composes the head, gate, and action key.
+ * When the repository merges locally the response carries a `local_execution`
+ * approval the caller completes with {@link completeMergeChild}.
+ */
+export async function mergeChild(access, request, fetchImpl = globalThis.fetch) {
+    requireNonEmptyString(request.epicRunId);
+    requirePositiveSafeInteger(request.prNumber);
+    const parsed = await postRepairRequest(access, `${epicRunApiPath(request.epicRunId)}/merge-child`, { pr_number: request.prNumber }, fetchImpl);
+    return parseMergeChildRouteResponse(parsed);
+}
+/**
+ * POST `/jira/epic-runs/runs/{epic_run_id}/merge-child/complete` — body
+ * `{repo_name, pr_number, result, reason?}`. No SHA and no action key: the server
+ * recomposes the merge identity and reads the merge commit from the provider.
+ */
+export async function completeMergeChild(access, request, fetchImpl = globalThis.fetch) {
+    requireNonEmptyString(request.epicRunId);
+    requirePositiveSafeInteger(request.prNumber);
+    if (!["merged", "already_merged", "failed"].includes(request.result)) {
+        throw new ConductorBridgeApiError("invalid-input");
+    }
+    const parsed = await postRepairRequest(access, `${epicRunApiPath(request.epicRunId)}/merge-child/complete`, {
+        pr_number: request.prNumber,
+        result: request.result,
+        ...(request.reason !== undefined ? { reason: request.reason } : {}),
+    }, fetchImpl);
+    return parseMergeChildRouteResponse(parsed);
+}
 /**
  * Idempotently seed an epic ticket status row via POST to the per-epic tickets
  * endpoint. The backend uses ON CONFLICT DO NOTHING so repeated seeding across
@@ -1765,6 +1936,8 @@ export const CONDUCTOR_REVIEW_ALIGNMENT_STATUSES = new Set([
     "not_configured",
     "invalid",
 ]);
+/** Upper bound of the server's capped `fresh_reconciler_count` ("two or more"). */
+export const READINESS_FRESH_RECONCILER_COUNT_CAP = 2;
 const READINESS_SOURCES = new Set(["epic", "project_default", "none"]);
 const ACTIONS_LEVELS = new Set(["write", "read", "none", "unknown"]);
 function readinessShapeError() {
@@ -1916,6 +2089,32 @@ export function parseConductorReadinessResponse(body) {
         },
         review_workflow: parseReviewWorkflow(root),
         conductor_ci_workflow: parseConductorCiWorkflow(root),
+        unattended: parseUnattended(root),
+        bring_up: parseBringUp(root),
+    };
+}
+/**
+ * Parse the optional `bring_up` block (BAPI-1153). Same older-server rule as the
+ * blocks above: absent (or null) is `null`; a PRESENT block is validated
+ * strictly, every field required, and the capped count range-checked. A
+ * malformed block throws the same field-free shape error as everything else.
+ */
+function parseBringUp(body) {
+    const raw = body.bring_up;
+    if (raw === undefined || raw === null)
+        return null;
+    const o = requireObject(raw);
+    const freshCount = requireInt(o, "fresh_reconciler_count");
+    if (freshCount < 0 || freshCount > READINESS_FRESH_RECONCILER_COUNT_CAP) {
+        throw readinessShapeError();
+    }
+    return {
+        migration_readable: requireBool(o, "migration_readable"),
+        database_migration_current: requireBool(o, "database_migration_current"),
+        heartbeat_readable: requireBool(o, "heartbeat_readable"),
+        worker_present: requireBool(o, "worker_present"),
+        fresh_reconciler_count: freshCount,
+        single_transition_authority: requireBool(o, "single_transition_authority"),
     };
 }
 /**
@@ -1949,6 +2148,28 @@ function parseConductorCiWorkflow(body) {
         migration_guard_present: requireBool(o, "migration_guard_present"),
     };
 }
+/**
+ * Parse the optional `unattended` block (BAPI-1102). Same rule as above.
+ *
+ * `notify_webhook_default_verified` is the one tri-state: absent is coerced to
+ * `null` rather than to `false`, because "not verified here" and "verified as
+ * broken" are different statements and only one of them is evidence. Every other
+ * field is a strict boolean and a wrong type throws.
+ */
+function parseUnattended(body) {
+    const raw = body.unattended;
+    if (raw === undefined || raw === null)
+        return null;
+    const o = requireObject(raw);
+    return {
+        conductor_allowed: requireBool(o, "conductor_allowed"),
+        notify_webhook_default_declared: requireBool(o, "notify_webhook_default_declared"),
+        notify_webhook_default_verified: o.notify_webhook_default_verified === undefined
+            ? null
+            : requireNullableBool(o, "notify_webhook_default_verified"),
+        repository_readiness_confirmed: requireBool(o, "repository_readiness_confirmed"),
+    };
+}
 /**
  * GET `/jira/epic-runs/conductor-readiness?repo_name=<repo>`.
  *

package/build/conductor/bring-up-facts.js

@@ -0,0 +1,187 @@
+/** The pinned operator runbook every remedy below points into. */
+export const BRING_UP_RUNBOOK = "docs/claude/epic-conductor-v2-operator-runbook.md";
+/**
+ * The client-derived refusal vocabulary, IN REFUSAL ORDER.
+ *
+ * Kebab case, because these are computed by the client (the server reports
+ * facts, not refusals) and `second-reconciler-detected` is the mandated name;
+ * the snake-case unattended reasons mirror SERVER codes and are a separate
+ * vocabulary. Each fact's "unreadable" precedes its "bad", so an operator is
+ * never told to repair a condition that could not even be read.
+ */
+export const BRING_UP_REFUSAL_REASONS = [
+    "bring-up-facts-unreported",
+    "database-migration-unreadable",
+    "database-migration-behind",
+    "worker-heartbeat-unreadable",
+    "worker-not-present",
+    "second-reconciler-detected",
+];
+// ---------------------------------------------------------------------------
+// Fixed remediations
+// ---------------------------------------------------------------------------
+export const BRING_UP_UNREPORTED_REMEDIATION = "upgrade the Bridge API deploy to a build that reports the bring-up safety facts; " +
+    "their state is unknown here, not healthy.";
+export const DATABASE_MIGRATION_UNREADABLE_REMEDIATION = "retry; the migration state could not be read, which is not the same as confirmed-behind. " +
+    `If it persists, check the applied revision with \`alembic current\` (${BRING_UP_RUNBOOK} §3d).`;
+export const DATABASE_MIGRATION_BEHIND_REMEDIATION = "confirm the applied revision with `alembic current` (not `alembic heads`, which reads the " +
+    "migration scripts), apply this checkout's migrations with `alembic -c alembic.ini upgrade head`, " +
+    `then retry (${BRING_UP_RUNBOOK} §3d).`;
+export const WORKER_HEARTBEAT_UNREADABLE_REMEDIATION = "retry once the Bridge API database is reachable; the reconciler heartbeat could not be read, " +
+    "so worker presence is unknown, not confirmed absent.";
+export const WORKER_NOT_PRESENT_REMEDIATION = "start a worker (`python worker.py`, or bring up a local plane) — a server started with " +
+    "DISABLE_SCHEDULER=true runs none. Create and approve only against a server that has a " +
+    `worker (${BRING_UP_RUNBOOK} §3d).`;
+export const SECOND_RECONCILER_REMEDIATION = "find and stop the extra reconciler: check `ps aux | grep worker.py` for a reparented " +
+    `survivor of an earlier plane (${BRING_UP_RUNBOOK} §6), and note that a dev server started ` +
+    "without DISABLE_SCHEDULER=true runs a reconciler too. A reconciler stopped in the last 120 " +
+    "seconds still counts — heartbeat rows are not deleted on shutdown — so wait and retry.";
+// ---------------------------------------------------------------------------
+// Classification
+// ---------------------------------------------------------------------------
+const UNREPORTED_DETAIL = "not reported by this Bridge API deploy";
+function unreported(id) {
+    return {
+        id,
+        state: "unreported",
+        detail: UNREPORTED_DETAIL,
+        remediation: BRING_UP_UNREPORTED_REMEDIATION,
+        refusal: "bring-up-facts-unreported",
+    };
+}
+/** Database migration head: behind refuses; ahead is the intended model. */
+export function classifyDatabaseMigration(bringUp) {
+    const id = "database-migration-current";
+    if (bringUp === null)
+        return unreported(id);
+    if (!bringUp.migration_readable) {
+        return {
+            id,
+            state: "unreadable",
+            detail: "the migration state could not be read (unknown, not confirmed behind)",
+            remediation: DATABASE_MIGRATION_UNREADABLE_REMEDIATION,
+            refusal: "database-migration-unreadable",
+        };
+    }
+    if (!bringUp.database_migration_current) {
+        return {
+            id,
+            state: "bad",
+            detail: "the database is BEHIND the server's code migration head",
+            remediation: DATABASE_MIGRATION_BEHIND_REMEDIATION,
+            refusal: "database-migration-behind",
+        };
+    }
+    return { id, state: "ok", detail: "the database is at (or ahead of) the code migration head" };
+}
+/** Worker presence, from the durable reconciler heartbeat. */
+export function classifyWorkerPresent(bringUp) {
+    const id = "worker-present";
+    if (bringUp === null)
+        return unreported(id);
+    if (!bringUp.heartbeat_readable) {
+        return {
+            id,
+            state: "unreadable",
+            detail: "the reconciler heartbeat could not be read (unknown, not confirmed absent)",
+            remediation: WORKER_HEARTBEAT_UNREADABLE_REMEDIATION,
+            refusal: "worker-heartbeat-unreadable",
+        };
+    }
+    if (!bringUp.worker_present) {
+        return {
+            id,
+            state: "bad",
+            detail: "0 fresh reconcilers — no worker is running against this deployment",
+            remediation: WORKER_NOT_PRESENT_REMEDIATION,
+            refusal: "worker-not-present",
+        };
+    }
+    return { id, state: "ok", detail: "a reconciler heartbeat is fresh" };
+}
+/**
+ * Single transition authority. Refuses only on TWO OR MORE fresh reconcilers;
+ * zero is the worker fact's finding and is not repeated here as a refusal.
+ */
+export function classifySingleTransitionAuthority(bringUp) {
+    const id = "single-transition-authority";
+    if (bringUp === null)
+        return unreported(id);
+    if (!bringUp.heartbeat_readable) {
+        return {
+            id,
+            state: "unreadable",
+            detail: "the reconciler heartbeat could not be read (unknown, not confirmed)",
+            remediation: WORKER_HEARTBEAT_UNREADABLE_REMEDIATION,
+            refusal: "worker-heartbeat-unreadable",
+        };
+    }
+    if (bringUp.fresh_reconciler_count >= 2) {
+        return {
+            id,
+            state: "bad",
+            detail: "2+ fresh reconcilers — more than one transition authority is ticking",
+            remediation: SECOND_RECONCILER_REMEDIATION,
+            refusal: "second-reconciler-detected",
+        };
+    }
+    if (bringUp.fresh_reconciler_count === 0) {
+        return {
+            id,
+            state: "bad",
+            detail: "0 fresh reconcilers — no transition authority is ticking",
+            remediation: WORKER_NOT_PRESENT_REMEDIATION,
+            refusal: "worker-not-present",
+        };
+    }
+    return { id, state: "ok", detail: "exactly 1 fresh reconciler" };
+}
+/** All three verdicts, in render order. */
+export function classifyBringUpFacts(bringUp) {
+    return [
+        classifyDatabaseMigration(bringUp),
+        classifyWorkerPresent(bringUp),
+        classifySingleTransitionAuthority(bringUp),
+    ];
+}
+/**
+ * The FIRST refusal the block produces, in {@link BRING_UP_REFUSAL_REASONS}
+ * order, or `null` when all three facts hold.
+ *
+ * Order comes from the vocabulary constant, never from the order the verdicts
+ * happened to be computed, so a given combination of failures always names the
+ * same reason.
+ */
+export function firstBringUpRefusal(bringUp) {
+    const reasons = new Set(classifyBringUpFacts(bringUp)
+        .map((verdict) => verdict.refusal)
+        .filter((reason) => reason !== undefined));
+    return BRING_UP_REFUSAL_REASONS.find((reason) => reasons.has(reason)) ?? null;
+}
+/**
+ * The operator sentence for one refusal: the fact, the observed condition, and
+ * one concrete remedy. The caller appends its own closing sentence ("No run was
+ * created."), because only the caller knows what it did not do.
+ */
+export const BRING_UP_REFUSAL_MESSAGES = {
+    "bring-up-facts-unreported": "the Bridge API did not report the bring-up safety facts (database migration, worker " +
+        "presence, single reconciler), so none of them could be confirmed. " +
+        capitalize(BRING_UP_UNREPORTED_REMEDIATION),
+    "database-migration-unreadable": "database migration: the server could not read whether its database is at the migration " +
+        "head, so this is unknown, not confirmed behind. " +
+        capitalize(DATABASE_MIGRATION_UNREADABLE_REMEDIATION),
+    "database-migration-behind": "database migration: the server's database is BEHIND its code's migration head, so the " +
+        "code would run against a schema that was never applied. " +
+        capitalize(DATABASE_MIGRATION_BEHIND_REMEDIATION),
+    "worker-heartbeat-unreadable": "worker presence: the durable reconciler heartbeat could not be read, so whether a worker " +
+        "is running is unknown, not confirmed absent. " +
+        capitalize(WORKER_HEARTBEAT_UNREADABLE_REMEDIATION),
+    "worker-not-present": "worker presence: no reconciler heartbeat is fresh, so nothing would drive this run. " +
+        capitalize(WORKER_NOT_PRESENT_REMEDIATION),
+    "second-reconciler-detected": "single transition authority: two or more reconcilers are ticking the shared database, " +
+        "and two transition authorities wedge an epic. " +
+        capitalize(SECOND_RECONCILER_REMEDIATION),
+};
+function capitalize(text) {
+    return text.length === 0 ? text : text[0].toUpperCase() + text.slice(1);
+}

package/build/conductor/claude-hook.js

@@ -175,10 +175,12 @@ export function buildConductorEmitEventArgs(event) {
     return args;
 }
 /**
- * Resolve how to invoke `conductor emit-event`. Prefers `BAPI_CONDUCTOR_CLI_FILE`
- * (run via the current Node executable so no global install is required),
- * otherwise falls back to `BAPI_CONDUCTOR_BIN` or the bare `conductor` binary on
- * PATH. `emitArgs` are appended after the `emit-event` subcommand.
+ * Resolve how to invoke `epic-implementer emit-event`. Prefers
+ * `BAPI_CONDUCTOR_CLI_FILE` (run via the current Node executable so no global
+ * install is required), otherwise falls back to `BAPI_CONDUCTOR_BIN` or the
+ * bare `epic-implementer` binary on PATH — never the retained `conductor`
+ * name, which is now a fixed migration stub (S4/BAPI-1080). `emitArgs` are
+ * appended after the `emit-event` subcommand.
  */
 export function resolveConductorEmitCommand(env, emitArgs) {
     const cliFile = env.BAPI_CONDUCTOR_CLI_FILE;
@@ -188,7 +190,7 @@ export function resolveConductorEmitCommand(env, emitArgs) {
             args: [cliFile.trim(), "emit-event", ...emitArgs],
         };
     }
-    const bin = nonEmpty(env.BAPI_CONDUCTOR_BIN) ? env.BAPI_CONDUCTOR_BIN.trim() : "conductor";
+    const bin = nonEmpty(env.BAPI_CONDUCTOR_BIN) ? env.BAPI_CONDUCTOR_BIN.trim() : "epic-implementer";
     return { command: bin, args: ["emit-event", ...emitArgs] };
 }
 const defaultConductorSpawn = (command, args, input) => {

package/build/conductor/cli.js

@@ -18,6 +18,7 @@ import { ConductorValidationError, ConductorEpicTickV1FrozenError, toConductorEr
 import { emitConductorEvent, purgeConductorLedger, sendWorkerMessage, checkWorkerMessages, } from "./store.js";
 import { isDuplicateConstraintError } from "./producer-ledger.js";
 import { SEMANTIC_EVENT_TYPES } from "./taxonomy.js";
+import { DRIVER_CONTEXT_MAX_BYTES } from "./repair-contract.js";
 import { installConductorGitHooks, resolveConductorHookBin } from "./git-hooks.js";
 import { runFileScopeGuardCli } from "./file-scope-guard.js";
 import { runPostCommitHookProducer, runReferenceTransactionHookProducer } from "./git-producer.js";
@@ -78,6 +79,15 @@ export function getConductorUsage() {
         "  adopt-current-head-and-unpark",
         "                       Recover a ticket parked by a PR-head drift: adopt the",
         "                       CURRENT PR head and unpark in one step.",
+        "  scope-reparse --epic-run-id <id> --scope-id <scope>",
+        "                       Re-drive the run's OWN index scope through retry-reparse",
+        "                       and schedule its parse. Refused if the scope is not the run's.",
+        "  dispatch-remediation --epic-run-id <id> --ticket-key <key> --context-file <path>",
+        `                       Dispatch a remediation job carrying driver context (UTF-8,`,
+        `                       at most DRIVER_CONTEXT_MAX_BYTES = ${DRIVER_CONTEXT_MAX_BYTES} bytes; never truncated).`,
+        "  merge-child --epic-run-id <id> --pr <number>",
+        "                       Merge the run's PR-bound child through the shared merge",
+        "                       service; the server composes the head and gate identity.",
         "",
         "supervise options:",
         "  --run-id <id>             Run/session identifier to supervise (required)",
@@ -241,6 +251,10 @@ const VALID_COMMANDS = new Set([
     "abandon-run",
     "unpark",
     "adopt-current-head-and-unpark",
+    // BAPI-1154: CLI-only run-addressed repair verbs — never registered as MCP tools.
+    "scope-reparse",
+    "dispatch-remediation",
+    "merge-child",
     // Private, and deliberately ABSENT from the usage text: `__hook-bin` exists as
     // the bundled-artifact regression guard for BAPI-772 (mirroring `plane
     // __entrypoint`), not as a supported operator workflow.
@@ -1237,6 +1251,20 @@ export async function runConductorCli(argv) {
                 const { runAdoptCurrentHeadAndUnparkCommand } = await import("./recovery-cli.js");
                 return await runAdoptCurrentHeadAndUnparkCommand(parsed.argv);
             }
+            // BAPI-1154: the three run-addressed repair verbs — CLI-only, and lazily
+            // imported exactly like the four recovery verbs above.
+            case "scope-reparse": {
+                const { runScopeReparseCommand } = await import("./recovery-cli.js");
+                return await runScopeReparseCommand(parsed.argv);
+            }
+            case "dispatch-remediation": {
+                const { runDispatchRemediationCommand } = await import("./recovery-cli.js");
+                return await runDispatchRemediationCommand(parsed.argv);
+            }
+            case "merge-child": {
+                const { runMergeChildCommand } = await import("./recovery-cli.js");
+                return await runMergeChildCommand(parsed.argv);
+            }
             default:
                 console.error('Error: Unknown command. Run "conductor --help" for usage.');
                 return 1;