@bridge_gpt/mcp-server 0.2.58 → 0.2.59

package/build/epic-shared/cut-protocol.js

@@ -0,0 +1,392 @@
+/**
+ * The shared EXACT-CUT protocol and scope-readiness poll (BAPI-843; BAPI-850).
+ *
+ * Extracted from `implement-epic init` so that the LLM-conductor pilot and the v2
+ * `setup-epic --feature-branch` entry point drive ONE implementation of the
+ * local cut — the same local `git` fetch, the same remote-ref existence check,
+ * the same exact-SHA push, and the same mismatch classification. This module is
+ * the single owner of those operations; neither CLI re-implements any of them.
+ *
+ * What the cut is: the server leases a hold on the canonical parse lock and
+ * names the commit the canonical index actually covers (`cut/begin`); this
+ * module creates `origin/<feature>` at EXACTLY that commit with the operator's
+ * own `git` — never the GitHub App, which is `contents: read` and cannot create
+ * refs — reads the ref back, and asks the server to record it as the scope's
+ * immutable cut (`cut/commit`). The hold is released on every outcome.
+ *
+ * Contract properties, fixed here and relied on by both CLIs:
+ *
+ * - **Never force-updates an existing branch.** The push refspec has no leading
+ *   `+`, so it can only create. A branch that already exists at any commit other
+ *   than the held cut commit is a refusal, never a repoint.
+ * - **Takes an already validated branch and SHA.** Callers validate the branch
+ *   name (`validateBranchName`) and normalize the candidate SHA before calling;
+ *   this module re-proves the SHA shape it pushes, but it is not a parser.
+ * - **No credential ever reaches argv.** The only subprocess is `git`, and its
+ *   arguments are refs, remotes, and SHAs. Bridge and GitHub credentials travel
+ *   only inside the typed client's headers.
+ * - **Every failure is classified, never thrown.** Callers get a discriminated
+ *   outcome with operator-ready sentences and the bounded facts (expected and
+ *   observed SHAs) they need to report; there is nothing to `try/catch`.
+ */
+import { execFile } from "node:child_process";
+import { abandonIndexScopeCut, beginIndexScopeCut, commitIndexScopeCut, getIndexScopeStatus, } from "./bridge-client.js";
+/**
+ * Poll bound for a scope bootstrap, shared by `implement-epic init` and
+ * `setup-epic`. A seed copies a repository's whole parse cache and the
+ * verifying parse then downloads and change-detects it, so the ceiling is
+ * generous; the interval is what keeps the poll cheap.
+ */
+export const SCOPE_BOOTSTRAP_POLL_INTERVAL_MS = 5_000;
+export const SCOPE_BOOTSTRAP_MAX_POLLS = 240; // ~20 minutes at the interval above.
+/**
+ * Build the default list-argument subprocess runner both CLIs use for `git`.
+ *
+ * One body rather than two copies: `execFile` with `shell: false`, a generous
+ * buffer for porcelain output, and an exit code that never throws — a missing
+ * binary resolves to a non-zero code the caller classifies.
+ */
+export function createExecFileRunCommand() {
+    return (file, args, options) => new Promise((resolve) => {
+        execFile(file, args, {
+            cwd: options?.cwd,
+            // Git porcelain output for a many-worktree checkout can be large.
+            maxBuffer: 16 * 1024 * 1024,
+            encoding: "utf-8",
+            timeout: options?.timeoutMs,
+            // Explicit: arguments are a list, never a concatenated shell string.
+            shell: false,
+        }, (error, stdout, stderr) => {
+            const code = error?.code;
+            resolve({
+                stdout: stdout ?? "",
+                stderr: stderr ?? "",
+                exitCode: typeof code === "number" ? code : error ? 1 : 0,
+            });
+        });
+    });
+}
+/** Run `git` in the operator's checkout. */
+export function runGit(deps, args) {
+    return Promise.resolve(deps.runCommand("git", args, { cwd: deps.cwd }));
+}
+/** The single trimmed line a `git rev-parse`-style command produced, or null. */
+export function firstOutputLine(result) {
+    const value = result.stdout.split("\n")[0]?.trim() ?? "";
+    return value.length === 0 ? null : value;
+}
+/** The SHA from `git ls-remote --heads origin <ref>` output, or null. */
+export function lsRemoteSha(result) {
+    const line = firstOutputLine(result);
+    if (line === null)
+        return null;
+    const sha = line.split(/\s+/)[0]?.trim() ?? "";
+    return sha.length === 0 ? null : sha;
+}
+/**
+ * Normalize a commit SHA to its canonical 40-character lowercase form, or `null`.
+ *
+ * Mirrors the server's own guard so a malformed value is refused HERE — before it
+ * becomes a `git push` refspec — rather than becoming an opaque git error or, far
+ * worse, a ref pushed at something that is not a commit.
+ */
+export function normalizeCommitSha(value) {
+    if (typeof value !== "string")
+        return null;
+    const normalized = value.trim().toLowerCase();
+    return /^[0-9a-f]{40}$/.test(normalized) ? normalized : null;
+}
+/**
+ * Read the head of `origin/<branch>` WITHOUT mutating anything.
+ *
+ * `sha: null` means the branch does not exist on origin. A failed `ls-remote`
+ * (no remote, no network, no git) is its own outcome, never "absent": treating an
+ * unanswered read as absence is how a push lands on top of a branch nobody saw.
+ */
+export async function readRemoteBranchHead(deps, branch) {
+    const result = await runGit(deps, ["ls-remote", "--heads", "origin", `refs/heads/${branch}`]);
+    if (result.exitCode !== 0) {
+        return { ok: false, error: `git ls-remote could not read origin/${branch}.` };
+    }
+    return { ok: true, sha: lsRemoteSha(result) };
+}
+/**
+ * Make sure the exact cut object is resolvable locally, fetching it if needed.
+ *
+ * The cut is pushed BY SHA, so the object must exist in the operator's
+ * repository. A base-branch fetch usually brings it along; when it did not — the
+ * index covers a commit that is no longer an ancestor of the base tip — one
+ * targeted, NON-MUTATING fetch of that SHA is attempted (it updates no ref,
+ * creates no branch, and checks nothing out). Returns `true` when the commit
+ * resolves.
+ */
+export async function ensureCommitResolvableLocally(deps, commitSha) {
+    const present = await runGit(deps, ["rev-parse", "--verify", "--quiet", `${commitSha}^{commit}`]);
+    if (present.exitCode === 0)
+        return true;
+    await runGit(deps, ["fetch", "origin", commitSha]);
+    const retry = await runGit(deps, ["rev-parse", "--verify", "--quiet", `${commitSha}^{commit}`]);
+    return retry.exitCode === 0;
+}
+/**
+ * Drive the exact cut: `cut/begin` → re-check the remote ref under the hold →
+ * create the ref at the held commit (if absent) → read it back → `cut/commit`,
+ * releasing the hold on EVERY outcome.
+ *
+ * Everything between `begin` and the release happens while the SERVER holds the
+ * canonical repository's parse lock, so the commit the index covers cannot move
+ * underneath the ref this module creates.
+ */
+export async function performExactIndexScopeCut(deps, access, request) {
+    const { featureBranch, baseBranch, candidateCommitSha } = request;
+    const lease = await beginIndexScopeCut(access, {
+        featureBranch,
+        baseBranch,
+        candidateCommitSha,
+        epicRunId: request.epicRunId ?? null,
+    }, deps.fetchImpl);
+    if (!lease.ok) {
+        return {
+            ok: false,
+            kind: "begin_refused",
+            failures: [`The index-scope cut could not begin: ${lease.error}`],
+            lease: null,
+            expectedSha: candidateCommitSha,
+            observedSha: null,
+        };
+    }
+    const cut = lease.value;
+    try {
+        if (cut.cut_commit_sha !== candidateCommitSha) {
+            // The server re-read the canonical snapshot under its own hold and named a
+            // different commit. Nothing has been pushed yet, so refusing costs nothing
+            // and continuing would cut the epic at a commit the preflight never checked.
+            return {
+                ok: false,
+                kind: "canonical_moved",
+                failures: [
+                    `The canonical index moved while init was preparing ` +
+                        `(preflight saw ${candidateCommitSha}, the cut hold names ${cut.cut_commit_sha}). Re-run init.`,
+                ],
+                lease: cut,
+                expectedSha: candidateCommitSha,
+                observedSha: cut.cut_commit_sha,
+            };
+        }
+        // Re-check `origin/<feature>` WHILE the hold is active. A preflight
+        // observation is evidence for a refusal, never for a mutation: another
+        // operator may have created the ref in between.
+        const held = await readRemoteBranchHead(deps, featureBranch);
+        if (!held.ok) {
+            return {
+                ok: false,
+                kind: "ls_remote_failed",
+                failures: [held.error],
+                lease: cut,
+                expectedSha: cut.cut_commit_sha,
+                observedSha: null,
+            };
+        }
+        const heldSha = held.sha;
+        if (heldSha !== null && heldSha !== cut.cut_commit_sha) {
+            return {
+                ok: false,
+                kind: "existing_ref_mismatch",
+                failures: [
+                    `origin/${featureBranch} exists at ${heldSha}, which is not the canonical indexed ` +
+                        `commit ${cut.cut_commit_sha}. Delete it or finish the previous run first.`,
+                ],
+                lease: cut,
+                expectedSha: cut.cut_commit_sha,
+                observedSha: heldSha,
+            };
+        }
+        let branchCreated = false;
+        if (heldSha === null) {
+            // Create the ref from the EXACT commit, with the operator's own git. No
+            // local checkout, no branch, no worktree — and deliberately not the GitHub
+            // App, which is `contents: read` and cannot create refs. Not a force push:
+            // the refspec has no leading `+`, so it can only create.
+            const pushed = await runGit(deps, [
+                "push",
+                "origin",
+                `${cut.cut_commit_sha}:refs/heads/${featureBranch}`,
+            ]);
+            if (pushed.exitCode !== 0) {
+                return {
+                    ok: false,
+                    kind: "push_failed",
+                    failures: [
+                        `Could not create origin/${featureBranch} at the canonical indexed commit ${cut.cut_commit_sha}.`,
+                    ],
+                    lease: cut,
+                    expectedSha: cut.cut_commit_sha,
+                    observedSha: null,
+                };
+            }
+            branchCreated = true;
+        }
+        // Read the ref BACK from origin. What matters is what the remote now holds,
+        // not what this process intended to push.
+        const confirmed = await readRemoteBranchHead(deps, featureBranch);
+        const confirmedSha = confirmed.ok ? confirmed.sha : null;
+        if (confirmedSha !== cut.cut_commit_sha) {
+            return {
+                ok: false,
+                kind: "confirm_failed",
+                failures: [`origin/${featureBranch} did not resolve to ${cut.cut_commit_sha} after the push.`],
+                lease: cut,
+                expectedSha: cut.cut_commit_sha,
+                observedSha: confirmedSha,
+            };
+        }
+        const committed = await commitIndexScopeCut(access, { scopeId: cut.scope_id, cutHoldId: cut.cut_hold_id, epicRefCommitSha: confirmedSha }, deps.fetchImpl);
+        if (!committed.ok) {
+            return {
+                ok: false,
+                kind: "commit_refused",
+                failures: [`The index-scope cut could not be recorded: ${committed.error}`],
+                lease: cut,
+                expectedSha: cut.cut_commit_sha,
+                observedSha: confirmedSha,
+            };
+        }
+        return { ok: true, lease: cut, branchCreated, outcome: committed.value.outcome };
+    }
+    finally {
+        // The hold is released on EVERY pre-seed outcome, including the success path
+        // (where the server already released it — abandon is idempotent). The seed
+        // acquires this same canonical lock itself and it is not reentrant, so
+        // handing off while still holding it would deadlock the epic against its own
+        // seed. A failed release never masks the primary failure: it is reported and
+        // the original outcome stands.
+        const abandoned = await abandonIndexScopeCut(access, { scopeId: cut.scope_id, cutHoldId: cut.cut_hold_id }, deps.fetchImpl);
+        if (!abandoned.ok) {
+            deps.errorLog(`announced: the cut hold could not be released cleanly: ${abandoned.error}`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Scope-readiness poll (BAPI-843; shared with `setup-epic` by BAPI-850)
+// ---------------------------------------------------------------------------
+/** The operator-facing label for each lifecycle state the poll reports. */
+export const SCOPE_LIFECYCLE_LABELS = Object.freeze({
+    provisioning: "Provisioning",
+    seeding: "Seeding",
+    verifying: "Verifying",
+    ready: "Ready",
+    failed: "Failed",
+});
+/**
+ * The fixed lifecycle label a heartbeat uses when the status READ itself failed
+ * (BAPI-963).
+ *
+ * A read failure is not a lifecycle state, and the raw error is deliberately not
+ * interpolated into a heartbeat: a per-poll line repeated for twenty minutes is
+ * the worst possible place to smuggle unbounded server text.
+ */
+export const SCOPE_BOOTSTRAP_UNREADABLE_STATE = "unreadable";
+/**
+ * Format one bootstrap heartbeat line (BAPI-963).
+ *
+ * Shared with `setup-epic` at this seam so both conductors compute progress the
+ * same way; RENDERING stays with each caller, because the pilot writes to its own
+ * stderr advisory channel and v2 reports progress server-side.
+ *
+ * The shape is fixed and grep-friendly — elapsed first, state second — because a
+ * ~30-minute seed that printed nothing was externally indistinguishable from a
+ * hang (sleeping process, 0% CPU, a frozen `updated_at`). Elapsed seconds are
+ * clamped at zero so a clock adjustment cannot render a negative age.
+ */
+export function formatScopeBootstrapHeartbeat(elapsedMs, state) {
+    const seconds = Math.max(0, Math.floor(elapsedMs / 1000));
+    // `lifecycle_state` is a required non-empty string on the wire, not a closed
+    // set. Bounding it to the known labels (plus the fixed `unreadable` and a
+    // catch-all) keeps an unvalidated server string out of a line that repeats
+    // every interval for up to twenty minutes.
+    return `Seeding scope: elapsed=${seconds}s state=${boundScopeLifecycleLabel(state)}`;
+}
+/** The label an unrecognized lifecycle state collapses to. Never `null`, never raw. */
+export const SCOPE_BOOTSTRAP_UNKNOWN_STATE = "unknown";
+/**
+ * Collapse any lifecycle state to a bounded, safe label (BAPI-1054).
+ *
+ * `lifecycle_state` is a required non-empty string on the wire, not a closed set,
+ * so an unrecognized value is possible and an error-bearing one
+ * (`unreadable (<server error>)`) is routine. Extracted from
+ * {@link formatScopeBootstrapHeartbeat}, which has always applied this rule, so
+ * every surface that renders a state applies the SAME one — a second spelling of
+ * "bounded" is how raw server text eventually reaches a terminal.
+ */
+export function boundScopeLifecycleLabel(state) {
+    return state === SCOPE_BOOTSTRAP_UNREADABLE_STATE || state in SCOPE_LIFECYCLE_LABELS
+        ? state
+        : SCOPE_BOOTSTRAP_UNKNOWN_STATE;
+}
+/**
+ * Describe the nominal polling window up front (BAPI-963).
+ *
+ * Computed from the interval and cap rather than hard-coded, so a change to
+ * either constant cannot leave the operator-facing duration claim stale. The
+ * window is NOMINAL: the observed pilot seed outran even this bound, which is
+ * why the wording promises a poll cadence rather than a completion time.
+ */
+export function describeScopeBootstrapWindow(intervalMs = SCOPE_BOOTSTRAP_POLL_INTERVAL_MS, maxPolls = SCOPE_BOOTSTRAP_MAX_POLLS) {
+    const intervalSeconds = Math.max(1, Math.round(intervalMs / 1000));
+    const windowMinutes = Math.max(1, Math.round((intervalMs * maxPolls) / 60_000));
+    return (`Seeding the epic's index scope. This copies the repository's whole parse cache and ` +
+        `verifies it, and commonly takes many minutes. Progress is reported every ` +
+        `${intervalSeconds}s; the poll gives up after about ${windowMinutes} minutes.`);
+}
+/**
+ * Poll a scope's lifecycle until it is `ready`, `failed`, or the bounded wait
+ * elapses, reporting each NEWLY observed lifecycle transition exactly once, in
+ * order, through `onTransition`.
+ *
+ * Readiness is a server-side fact this poll observes rather than concludes from
+ * any request of its own: `ready` is accepted ONLY when the status also proves
+ * `indexed_commit_sha == cut_commit_sha`. A `ready` whose watermark disagrees is
+ * reported as `ready_mismatch` — the control plane contradicting itself, which
+ * is worth refusing rather than proceeding on.
+ *
+ * A transient read failure is not a verdict: the poll keeps going and lets the
+ * bound be the thing that gives up. The interval and cap are the shared
+ * {@link SCOPE_BOOTSTRAP_POLL_INTERVAL_MS} / {@link SCOPE_BOOTSTRAP_MAX_POLLS}.
+ */
+export async function pollIndexScopeLifecycle(deps, access, scopeId, options = {}) {
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const maxPolls = options.maxPolls ?? SCOPE_BOOTSTRAP_MAX_POLLS;
+    const intervalMs = options.intervalMs ?? SCOPE_BOOTSTRAP_POLL_INTERVAL_MS;
+    const now = options.now ?? (() => new Date());
+    const startedAtMs = now().getTime();
+    let lastState = "unknown";
+    let lastStatus = null;
+    let lastReportedState = null;
+    for (let poll = 0; poll < maxPolls; poll += 1) {
+        await sleep(intervalMs);
+        const status = await getIndexScopeStatus(access, scopeId, deps.fetchImpl);
+        if (!status.ok) {
+            lastState = `unreadable (${status.error})`;
+            options.onPoll?.(now().getTime() - startedAtMs, SCOPE_BOOTSTRAP_UNREADABLE_STATE);
+            continue;
+        }
+        lastStatus = status.value;
+        lastState = status.value.lifecycle_state;
+        options.onPoll?.(now().getTime() - startedAtMs, lastState);
+        if (lastState !== lastReportedState) {
+            lastReportedState = lastState;
+            options.onTransition?.(lastState, status.value);
+        }
+        if (lastState === "ready") {
+            if (status.value.indexed_commit_sha !== null &&
+                status.value.indexed_commit_sha === status.value.cut_commit_sha) {
+                return { kind: "ready", status: status.value };
+            }
+            return { kind: "ready_mismatch", status: status.value };
+        }
+        if (lastState === "failed") {
+            return { kind: "failed", status: status.value, reason: status.value.last_error ?? "unknown" };
+        }
+    }
+    return { kind: "timeout", lastState, lastStatus };
+}

package/build/executor/env.js

@@ -8,7 +8,9 @@
  * written BEFORE spawn — see `../mcp-provisioning.js` wiring in
  * `job-runner.ts`), never via env vars. This builder still omits
  * `BRIDGE_MCP_PROFILE` (an absent profile selects the intended `core` tool
- * group default), every `BAPI_CONDUCTOR_*` key, `CONDUCTOR_NODE_PATH` (the
+ * group default), every Epic Implementer env key under BOTH the supported
+ * `BAPI_EPIC_IMPLEMENTER_*` prefix and the legacy Conductor prefix (BAPI-1190),
+ * the worker Node-path key under both its supported and legacy spellings (the
  * shim's node executable is resolved into the registration's command/args at
  * provisioning time instead), and all secret-bearing keys. It constructs a
  * FRESH object from a strict allowlist of non-secret operational keys — it
@@ -55,6 +57,7 @@
 import { PR_BASE_BRANCH_ENV_VAR, WORKER_BRANCH_ENV_VAR } from "../pr-base-contract.js";
 import { DECLARED_TOUCHED_FILES_ENV, normalizeDeclaredTouchedFiles, } from "../conductor/file-scope-guard.js";
 import { INDEX_SCOPE_ENV_VAR, validateOptionalIndexScope } from "../index-scope-contract.js";
+import { EPIC_IMPLEMENTER_ENV_PREFIX, EPIC_IMPLEMENTER_NODE_PATH_ENV, LEGACY_EPIC_IMPLEMENTER_ENV_PREFIX, LEGACY_EPIC_IMPLEMENTER_NODE_PATH_ENV, } from "../epic-implementer-env.js";
 /** Non-secret operational keys forwarded to the worker when present. */
 const ALLOWED_ENV_KEYS = [
     "PATH",
@@ -116,7 +119,10 @@ const SECRET_NAME_FRAGMENTS = ["TOKEN", "SECRET", "PASSWORD", "API_KEY"];
  */
 export const EXPLICIT_DENY_KEYS = [
     "BRIDGE_MCP_PROFILE",
-    "CONDUCTOR_NODE_PATH",
+    EPIC_IMPLEMENTER_NODE_PATH_ENV,
+    // BAPI-1190: the legacy spelling stays denied so a stale ambient value from an
+    // older package can never reach a worker during a version-skew window.
+    LEGACY_EPIC_IMPLEMENTER_NODE_PATH_ENV,
     "BAPI_API_KEY",
     // ANTHROPIC_API_KEY has NO passthrough exception (BAPI-791): it stays denied
     // absolutely, unlike CLAUDE_CODE_OAUTH_TOKEN below, which is denied here too
@@ -167,12 +173,15 @@ export const EXPLICIT_DENY_KEYS = [
 /**
  * True only when `key` is a safe, allowlisted operational key. Exported so the
  * allowlist is locally auditable/testable. A key is allowed iff it is in the
- * allowlist AND is not explicitly denied, does not begin with `BAPI_CONDUCTOR_`,
- * and does not contain a secret-name fragment.
+ * allowlist AND is not explicitly denied, does not begin with the supported
+ * `BAPI_EPIC_IMPLEMENTER_` prefix or the legacy Conductor prefix, and does not
+ * contain a secret-name fragment.
  *
- * The `BAPI_CONDUCTOR_` rejection is a WHOLE-PREFIX rule, not an enumerated list,
- * which is what makes it hold for keys added later. BAPI-722's
- * `BAPI_CONDUCTOR_DENY_PROBE_TIMEOUT_MS` is rejected twice over — it is absent from
+ * Both prefix rejections are WHOLE-PREFIX rules, not enumerated lists, which is
+ * what makes them hold for keys added later. BAPI-1190 keeps the legacy prefix
+ * rejected alongside the renamed one, so a stale name inherited during a
+ * version-skew window is filtered too. BAPI-722's
+ * `BAPI_EPIC_IMPLEMENTER_DENY_PROBE_TIMEOUT_MS` is rejected twice over — it is absent from
  * `ALLOWED_ENV_KEYS` and it carries the prefix — so it stays executor-process
  * configuration and can never reach a spawned worker. That is deliberate: a worker
  * runs no deny probe, and letting job-side state influence the executor's own
@@ -183,7 +192,9 @@ export function isExecutorEnvKeyAllowed(key) {
         return false;
     if (EXPLICIT_DENY_KEYS.includes(key))
         return false;
-    if (key.startsWith("BAPI_CONDUCTOR_"))
+    if (key.startsWith(EPIC_IMPLEMENTER_ENV_PREFIX))
+        return false;
+    if (key.startsWith(LEGACY_EPIC_IMPLEMENTER_ENV_PREFIX))
         return false;
     const upper = key.toUpperCase();
     if (SECRET_NAME_FRAGMENTS.some((fragment) => upper.includes(fragment)))

package/build/executor/heartbeat.js

@@ -22,7 +22,7 @@
  *    interval. This is TELEMETRY ONLY (R14): the marker is never persisted, never
  *    reported as `last_commit_sha`, and never drives an executor decision — the
  *    reconciler remains the sole consumer and the sole transition authority
- *    (`docs/claude/conductor-standing-rules.md`).
+ *    (`docs/claude/epic-implementer-standing-rules.md`).
  *
  *  - SERVER STOP (WS-B executor half). A heartbeat response carrying the
  *    server's stop request kills the owned worker like `stale_claim` does, but

package/build/executor/job-errors.js

@@ -143,12 +143,12 @@ export const WorkerEnvFilePresent = "ContractError.WorkerEnvFilePresent";
  * BAPI-1152 — `reconcile_overlap` failure kinds. Each names ONE way the
  * wrapper's merge-into-child could not reach a verified push, so an operator
  * reading the row knows which fact to go look at. None of them is a verdict: a
- * refused governance change and a moved head are NOT failures — they complete
- * with a fact envelope — so they have no kind here.
+ * moved head is NOT a failure — it completes with a fact envelope — so it has
+ * no kind here.
  *
  *  - `ContractError.ReconcileOverlapPayload` — the payload failed validation
  *    before any subprocess ran (missing/blank input SHA, unknown schema version,
- *    malformed command or region record).
+ *    malformed command record).
  *  - `ContractError.ReconcileOverlapBranchMismatch` — the prepared worktree's
  *    branch is not the job's top-level `expected_branch`, so the push destination
  *    cannot be trusted.

package/build/executor/job-runner.js

@@ -2114,7 +2114,7 @@ async function runPreparedSpawn(params) {
     }
     const git = observation.git();
     // BAPI-1152: a driver owns everything after a clean worker exit — staging, the
-    // governance scan, the commits, the guarded push, and finalization.
+    // commits, the guarded push, and finalization.
     if (driver && procResult.classification === "clean_exit") {
         await finalizeRegistry();
         const phase = await superviseDriverPhase({

package/build/executor/merge-job.js

@@ -166,6 +166,30 @@ export const MERGE_RETRYABLE = "MergeRetryable";
 export const MERGE_CONFLICT = "MergeConflict";
 export const MERGE_FAILED = "MergeFailed";
 export const MERGE_REF_MISMATCH = "MergeRefMismatch";
+/**
+ * BAPI-1234 — the server's migration-graph merge guard refused the merge. Two
+ * kinds, kept distinct because they call for different human responses:
+ *  - {@link MERGE_MIGRATION_GRAPH_INVALID}: merging this head onto the current
+ *    base produces a broken Alembic graph. A human renumbers the PR's own
+ *    never-applied migration.
+ *  - {@link MERGE_MIGRATION_GRAPH_UNREADABLE}: the merged graph could not be
+ *    proven either way. An operator checks the provider, then unparks.
+ * Like {@link MERGE_REF_MISMATCH}, both are deliberate terminal refusals: never
+ * retryable, never a rebase target, and reported as `clean_exit`.
+ */
+export const MERGE_MIGRATION_GRAPH_INVALID = "MergeMigrationGraphInvalid";
+export const MERGE_MIGRATION_GRAPH_UNREADABLE = "MergeMigrationGraphUnreadable";
+/** Server refusal reasons mapped to their dedicated terminal error kinds. */
+const MIGRATION_GRAPH_ERROR_KINDS = new Map([
+    ["migration_graph_invalid", MERGE_MIGRATION_GRAPH_INVALID],
+    ["migration_graph_unreadable", MERGE_MIGRATION_GRAPH_UNREADABLE],
+]);
+/** Error kinds that are deliberate refusals rather than crashes. */
+const DELIBERATE_REFUSAL_ERROR_KINDS = new Set([
+    MERGE_REF_MISMATCH,
+    MERGE_MIGRATION_GRAPH_INVALID,
+    MERGE_MIGRATION_GRAPH_UNREADABLE,
+]);
 /** Reasons whose failure is transient/infrastructure and safe to retry. */
 const RETRYABLE_MERGE_REASONS = new Set([
     "gh_pr_view_timeout",
@@ -190,6 +214,9 @@ const RETRYABLE_MERGE_REASONS = new Set([
  * variants covered so a distinct reason never accidentally downgrades to
  * {@link MERGE_FAILED}. Conflict classification is checked first so it is never masked.
  *
+ * BAPI-1234: `migration_graph_invalid` / `migration_graph_unreadable` map to
+ * their own terminal kinds, in the same early position and for the same reason.
+ *
  * BAPI-1021: `ref_mismatch` is classified BEFORE conflict, retryable-prefix, and
  * generic-failure handling, and is deliberately NEVER added to
  * {@link RETRYABLE_MERGE_REASONS} — it is a terminal safety refusal, not a
@@ -201,6 +228,9 @@ export function classifyMergeFailureErrorKind(response) {
     const reason = asString(response.reason ?? undefined);
     if (reason === "ref_mismatch")
         return MERGE_REF_MISMATCH;
+    const migrationGraphKind = reason ? MIGRATION_GRAPH_ERROR_KINDS.get(reason) : undefined;
+    if (migrationGraphKind)
+        return migrationGraphKind;
     if (hasConflictEvent || reason === "gh_merge_conflict")
         return MERGE_CONFLICT;
     if (reason && (reason.startsWith("ci_poll_") || RETRYABLE_MERGE_REASONS.has(reason))) {
@@ -217,8 +247,10 @@ export function classifyMergeFailureErrorKind(response) {
  *
  * BAPI-1021: a {@link MERGE_REF_MISMATCH} classifies as `classification:
  * "clean_exit"` rather than `"crashed"` — it is a deliberate refusal the
- * executor made correctly, not a crash. Every other merge outcome keeps its
- * existing `"crashed"` classification.
+ * executor made correctly, not a crash. BAPI-1234 adds the two migration-graph
+ * refusal kinds to that set: a `crashed` classification would make the
+ * backend's merge re-fire lane retry a merge the server will refuse identically.
+ * Every other merge outcome keeps its existing `"crashed"` classification.
  */
 export function buildMergeJobFailure(response) {
     const reason = asString(response.reason ?? undefined) ?? response.status;
@@ -226,7 +258,7 @@ export function buildMergeJobFailure(response) {
     return {
         error_kind: errorKind,
         error_message: secretFreeErrorMessage(new Error(`local merge ${response.status}: ${reason}`)),
-        classification: errorKind === MERGE_REF_MISMATCH ? "clean_exit" : "crashed",
+        classification: DELIBERATE_REFUSAL_ERROR_KINDS.has(errorKind) ? "clean_exit" : "crashed",
     };
 }
 /**

package/build/executor/observation.js

@@ -291,7 +291,7 @@ function parseRateLimitEvent(obj) {
 const RATE_LIMIT_CONSEQUENCE_TEXT = "The executor keeps claiming: a worker that hits the ceiling fails fast and its " +
     "job classifies as a worker failure under the normal retry budget.";
 /** Fixed runbook reference appended to every rate-limit diagnostic (BAPI-898). */
-const RATE_LIMIT_RUNBOOK_REFERENCE = "See docs/claude/epic-conductor-v2-operator-runbook.md §8.";
+const RATE_LIMIT_RUNBOOK_REFERENCE = "See docs/claude/epic-implementer-v2-operator-runbook.md §8.";
 /**
  * Render the operator-facing rate-limit line (BAPI-828, BAPI-898).
  *

package/build/executor/preflight.js

@@ -11,7 +11,7 @@ import { resolveAllExecutorApiAccess, resolveBaseUrl, EXECUTOR_BASE_URL_REQUIRED
  * time out, and letting a job influence the executor's own safety-probe budget
  * would be a privilege inversion.
  */
-export const DENY_PROBE_TIMEOUT_ENV_KEY = "BAPI_CONDUCTOR_DENY_PROBE_TIMEOUT_MS";
+export const DENY_PROBE_TIMEOUT_ENV_KEY = "BAPI_EPIC_IMPLEMENTER_DENY_PROBE_TIMEOUT_MS";
 /**
  * Accepted bounds for the resolved probe timeout. The lower bound keeps a
  * fat-fingered `1` from turning every probe into an instant HANG (which is FATAL —

package/build/executor/prompt-spec.js

@@ -2,7 +2,7 @@
  * Executor-side structured prompt-spec renderer (BAPI-550, TDD §6/§7).
  *
  * The reconciler ships a server-authored prompt template in a `spec_review` job's
- * `payload.prompt_spec` (from `src/python/llms/agents/conductor_jobs/prompt_specs.py`).
+ * `payload.prompt_spec` (from `src/python/llms/agents/epic_implementer_jobs/prompt_specs.py`).
  * This module validates that spec and renders it into the single `claude -p`
  * prompt string, substituting each declared `{{PLACEHOLDER}}` marker from real
  * runtime state (ticket spec, base/work branch, git log, prior revise reasons).