@bridge_gpt/mcp-server 0.2.50 → 0.2.52

package/build/executor/job-runner.js

@@ -14,10 +14,10 @@
  * `spec_review`, plus per-job worker-log tee, watch registry, and optional
  * read-only viewer tabs wired around every spawned worker.
  */
-import { rm } from "node:fs/promises";
+import { rm, readdir, lstat, unlink } from "node:fs/promises";
 import os from "node:os";
 import { runHeartbeatLoop } from "./heartbeat.js";
-import { isExecutorNamedError, toExecutorFailure, secretFreeErrorMessage, MissingVerdictArtifact, PreSpawnVerification, RequiredMcpRegistration, McpSurfaceMismatch, WorkerStartupFatal, WORKER_STARTUP_FATAL_MESSAGE, formatMcpSurfaceMismatch, ClaudeNotAuthenticated, CLAUDE_NOT_AUTHENTICATED_MESSAGE, ExecutorAdapterUnavailable, ExecutorNamedError, WorktreeBusy, StaleArtifactCleanupFailed, WORKTREE_BUSY_MESSAGE, } from "./job-errors.js";
+import { isExecutorNamedError, toExecutorFailure, secretFreeErrorMessage, MissingVerdictArtifact, PreSpawnVerification, RequiredMcpRegistration, McpSurfaceMismatch, WorkerStartupFatal, WORKER_STARTUP_FATAL_MESSAGE, formatMcpSurfaceMismatch, ClaudeNotAuthenticated, CLAUDE_NOT_AUTHENTICATED_MESSAGE, ExecutorAdapterUnavailable, ExecutorNamedError, WorktreeBusy, StaleArtifactCleanupFailed, WORKTREE_BUSY_MESSAGE, WorkerEnvFilePresent, WORKER_ENV_FILE_PRESENT_MESSAGE, } from "./job-errors.js";
 import { buildConductorMergeAccessForExecutorJob, buildDefaultMergeLocalDeps, runExecutorMergeJob, MERGE_RETRYABLE, MERGE_FAILED, } from "./merge-job.js";
 import { createObservationState } from "./observation.js";
 import { getWorktreeMcpRegistrationTargets, normalizeWorktreePathForRegistration, provisionMcpRegistrationForWorktree, } from "../mcp-provisioning.js";
@@ -27,9 +27,13 @@ import { resolveExecutorAgentId } from "./agent-identity.js";
 import { createProcessTerminationController, runProcessWithTimeout } from "./process.js";
 import { prepareResumeSpawn } from "./resume-pre-spawn.js";
 import { renderPromptSpecPrompt } from "./prompt-spec.js";
+import { defaultResolveBinPath } from "../start-tickets-conductor.js";
+/** The packaged bin basename of the deterministic worker guard (BAPI-1020). */
+const WORKER_GUARD_BIN_FILENAME = "worker-guard-hook-bin.js";
 import { buildGenericSuccessResult, buildSmokeResult, commitResidue, readCompletionArtifacts, resolveJobTimeoutSeconds, } from "./results.js";
 import { sendTerminalMutationWithRetry } from "./terminal-mutation.js";
 import { removeStaleVerdictArtifacts } from "./stale-artifacts.js";
+import { stripWorkerEnvFiles } from "./env-file-guard.js";
 import { isVerdictJobType, readVerdictArtifact } from "./verdict-artifact.js";
 import { createWorkerLogTee, closeWorkerLogTee, distinctWorkerLogSessionIds, formatWorkerLogSessionInvariantWarning, teeAsyncIterable, } from "./worker-log.js";
 import { acquireExecutorWorktreeLock, } from "./worktree-lock.js";
@@ -392,7 +396,7 @@ async function checkAdapterMcpAdvisoryForPreparedWorktree(worktreePath, deps, ad
  * `controls.signal` (overall-timeout abort) is threaded into local merge deps
  * without changing the local `gh` credential model.
  */
-export async function defaultRunMergeForClaimed(job, deps, _options, controls) {
+export async function defaultRunMergeForClaimed(job, deps, options, controls) {
     const accessResult = await buildConductorMergeAccessForExecutorJob({
         env: deps.env,
         cwd: deps.cwd,
@@ -419,6 +423,12 @@ export async function defaultRunMergeForClaimed(job, deps, _options, controls) {
         // Thread the overall-timeout abort signal into local merge deps WITHOUT
         // changing the local `gh` credential model (the signal is not a credential).
         localMergeDeps: buildDefaultMergeLocalDeps(deps, controls?.signal),
+        // BAPI-951: the executor's own configured base — resolveExecutorJobBaseBranch
+        // (called inside runExecutorMergeJob) resolves the CHILD PR's base from the
+        // job's persisted run base, falling back to this value for a legacy job.
+        repositoryBaseBranch: options.baseBranch,
+        epicIntegrationAdvisoryLog: deps.errorLog,
+        cwd: deps.cwd,
     });
 }
 /** An in-memory owned process for the no-op `smoke` acceptance job. */
@@ -493,6 +503,18 @@ async function superviseProcess(params) {
     isDoneRef.value = true;
     const loopOutcome = await hb;
     params.observation.setExitCode(result.exitCode);
+    if (loopOutcome.kind === "auth_fatal") {
+        // BAPI-1021 (AC-5): notify the runner immediately with ONLY the bounded
+        // identifiers — never carried onto `result` itself, so the process's own
+        // classification/completion handling is unaffected and the job continues
+        // to drain normally.
+        params.control?.reportAuthFatal?.({
+            jobId: params.job.id,
+            repoName: params.job.repo_name,
+            category: "heartbeat",
+            httpStatus: loopOutcome.httpStatus,
+        });
+    }
     return loopOutcome.kind === "server_stop"
         ? { ...result, serverStopRequested: true }
         : result;
@@ -509,7 +531,33 @@ function terminalToRunResult(terminal, successStatus) {
             return { status: "abandoned", reason: "deadman" };
         case "skipped":
             return { status: "abandoned", reason: "already_abandoned" };
+        case "auth_fatal":
+            // BAPI-1021 (AC-5): a halted authentication/access condition, not an
+            // ordinary job failure or a lost/stale claim — `reportAuthFatal` (called
+            // by the wrapper below, before this mapping runs) is what actually
+            // notifies the runner.
+            return { status: "abandoned", reason: "auth_fatal" };
+    }
+}
+/**
+ * BAPI-1021 (AC-5): send a terminal mutation via
+ * {@link sendTerminalMutationWithRetry}, and — on an `auth_fatal` outcome —
+ * notify the runner exactly once via `control.reportAuthFatal`, carrying ONLY
+ * the job ID, repository, operation category, and HTTP status. Every other
+ * outcome passes through completely unchanged.
+ */
+async function sendTerminalMutationWithAuthReport(params, job, control) {
+    const terminal = await sendTerminalMutationWithRetry(params);
+    if (terminal.outcome === "auth_fatal") {
+        const notice = {
+            jobId: job.id,
+            repoName: job.repo_name,
+            category: params.kind,
+            httpStatus: terminal.httpStatus,
+        };
+        control?.reportAuthFatal?.(notice);
     }
+    return terminal;
 }
 /** Dispatch and run a single claimed job. */
 export async function runClaimedJob(job, httpClient, options, deps, _report, seams = {}, 
@@ -543,10 +591,10 @@ control) {
     // ensure/recreate or worker-spawn logic — it ensures no worktree and spawns no
     // worker (TDD §5/§9).
     if (job.job_type === "merge") {
-        return runMergeJob(job, httpClient, options, deps, ownership, observation, seams);
+        return runMergeJob(job, httpClient, options, deps, ownership, observation, seams, control);
     }
     if (job.job_type === "smoke") {
-        return runSmokeJob(job, httpClient, options, deps, ownership, observation);
+        return runSmokeJob(job, httpClient, options, deps, ownership, observation, control);
     }
     // `implement`/`resume`/`spec_review` and the recovery jobs (`remediate`/
     // `ci_fix`/`rebase`) all run through the real headless-spawn path — dispatched
@@ -634,7 +682,7 @@ function createMergeFlowProcess(startMerge) {
  * ignored. The local merge executor's outcome otherwise drives `/complete`
  * (success) or `/fail`; stale/retry/invalid terminal outcomes reuse T3a handling.
  */
-async function runMergeJob(job, httpClient, options, deps, ownership, observation, seams) {
+async function runMergeJob(job, httpClient, options, deps, ownership, observation, seams, control) {
     // Resolve + enforce payload.timeout_seconds BEFORE starting any merge work.
     const timeout = resolveJobTimeoutSeconds(job, options.defaultJobTimeoutSeconds);
     if (!timeout.ok) {
@@ -658,6 +706,7 @@ async function runMergeJob(job, httpClient, options, deps, ownership, observatio
         proc: flow.proc,
         timeoutSeconds,
         collectTelemetry: async () => ({}),
+        control,
     });
     // Ownership abandonment (stale-claim / dead-man) wins: never send a terminal
     // mutation for a claim we no longer own, and never process a late outcome.
@@ -667,7 +716,7 @@ async function runMergeJob(job, httpClient, options, deps, ownership, observatio
     // Overall merge flow timed out: fail the active claim as RETRYABLE and ignore
     // any later merge promise resolution (the abort has already been signalled).
     if (procResult.classification === "timeout") {
-        const terminal = await sendTerminalMutationWithRetry({
+        const terminal = await sendTerminalMutationWithAuthReport({
             kind: "fail",
             send: () => httpClient.fail(job, {
                 error_kind: MERGE_RETRYABLE,
@@ -679,13 +728,13 @@ async function runMergeJob(job, httpClient, options, deps, ownership, observatio
             options,
             ownership,
             log: deps.log,
-        });
+        }, job, control);
         return terminalToRunResult(terminal, "failed");
     }
     // A thrown error inside the merge flow maps to a bounded MergeFailed.
     const flowError = flow.getError();
     if (flowError !== undefined) {
-        const terminal = await sendTerminalMutationWithRetry({
+        const terminal = await sendTerminalMutationWithAuthReport({
             kind: "fail",
             send: () => httpClient.fail(job, {
                 error_kind: MERGE_FAILED,
@@ -697,14 +746,14 @@ async function runMergeJob(job, httpClient, options, deps, ownership, observatio
             options,
             ownership,
             log: deps.log,
-        });
+        }, job, control);
         return terminalToRunResult(terminal, "failed");
     }
     const outcome = flow.getOutcome();
     if (outcome === undefined) {
         // Clean process result with no stored outcome — an internal invariant break;
         // fail loud rather than silently reporting success.
-        const terminal = await sendTerminalMutationWithRetry({
+        const terminal = await sendTerminalMutationWithAuthReport({
             kind: "fail",
             send: () => httpClient.fail(job, {
                 error_kind: MERGE_FAILED,
@@ -716,7 +765,7 @@ async function runMergeJob(job, httpClient, options, deps, ownership, observatio
             options,
             ownership,
             log: deps.log,
-        });
+        }, job, control);
         return terminalToRunResult(terminal, "failed");
     }
     if (outcome.ok) {
@@ -727,24 +776,24 @@ async function runMergeJob(job, httpClient, options, deps, ownership, observatio
             result: outcome.result,
             telemetry: observation.snapshot(),
         };
-        const terminal = await sendTerminalMutationWithRetry({
+        const terminal = await sendTerminalMutationWithAuthReport({
             kind: "complete",
             send: () => httpClient.complete(job, completion),
             deps,
             options,
             ownership,
             log: deps.log,
-        });
+        }, job, control);
         return terminalToRunResult(terminal, "completed");
     }
-    const terminal = await sendTerminalMutationWithRetry({
+    const terminal = await sendTerminalMutationWithAuthReport({
         kind: "fail",
         send: () => httpClient.fail(job, { ...outcome.failure, telemetry: observation.snapshot() }),
         deps,
         options,
         ownership,
         log: deps.log,
-    });
+    }, job, control);
     return terminalToRunResult(terminal, "failed");
 }
 /**
@@ -761,7 +810,7 @@ async function runMergeJob(job, httpClient, options, deps, ownership, observatio
  * job to give it something to register MCP into would be a materially larger,
  * unratified change to that architectural boundary, not a wiring task.
  */
-async function runSmokeJob(job, httpClient, options, deps, ownership, observation) {
+async function runSmokeJob(job, httpClient, options, deps, ownership, observation, control) {
     const timeout = resolveJobTimeoutSeconds(job, options.defaultJobTimeoutSeconds);
     if (!timeout.ok) {
         // Consistent with runSpawnJob: a timeout-contract failure fails the job
@@ -790,6 +839,7 @@ async function runSmokeJob(job, httpClient, options, deps, ownership, observatio
         proc,
         timeoutSeconds,
         collectTelemetry: async () => ({}),
+        control,
     });
     if (ownership.abandoned) {
         return { status: "abandoned", reason: ownership.abandonReason };
@@ -807,14 +857,14 @@ async function runSmokeJob(job, httpClient, options, deps, ownership, observatio
         result,
         telemetry: observation.snapshot(),
     };
-    const terminal = await sendTerminalMutationWithRetry({
+    const terminal = await sendTerminalMutationWithAuthReport({
         kind: "complete",
         send: () => httpClient.complete(job, completion),
         deps,
         options,
         ownership,
         log: deps.log,
-    });
+    }, job, control);
     return terminalToRunResult(terminal, "completed");
 }
 /**
@@ -1278,6 +1328,14 @@ async function runPreparedSpawn(params) {
             worktreePath,
             baseBranch: effectiveBaseBranch,
             homedir: deps.homedir(),
+            // BAPI-1020 — the prepared worktree's own branch and the packaged guard bin.
+            // `branch` comes from `prepareSpawn`'s `wt.branch`, i.e. the worktree the
+            // executor actually created, never from job payload text: the guard decides
+            // "is this push destination mine?" by comparing against it, so a value the
+            // payload could influence would let a job nominate its own safe branch.
+            workerBranch: branch,
+            workerGuardHookBinPath: (seams.resolveWorkerGuardBinPath ??
+                (() => defaultResolveBinPath(WORKER_GUARD_BIN_FILENAME)))(),
         });
         // Log on WARNING PRESENCE, not on `!ok` (BAPI-815/R2). The git-exclude
         // hygiene step can degrade without failing the deny layer — present-but-
@@ -1348,6 +1406,13 @@ async function runPreparedSpawn(params) {
             writeFile: deps.writeFile,
             appendFile: deps.appendFile,
             platform: deps.platform,
+            // BAPI-1021 (AC-6): the archive seams. All optional on `ExecutorDeps`
+            // already, so this is source-compatible with every existing deps
+            // builder — archival simply does not run when either is absent.
+            rename: deps.rename,
+            stat: deps.stat,
+            now: deps.now,
+            errorLog: deps.errorLog,
         });
     }
     catch {
@@ -1470,6 +1535,10 @@ async function runPreparedSpawn(params) {
             mcpConfigPath: mcpContract.configPath,
             effectiveBaseBranch,
             indexScope,
+            // BAPI-1020 — becomes `BAPI_WORKER_BRANCH` in the worker environment, which
+            // is the deterministic guard's only source of branch identity. Same
+            // provenance as the deny-provisioning value above: the prepared worktree.
+            workerBranch: branch,
             parentEnv: deps.env,
         });
         assertUsableSpawnShape(spawnShape, adapter);
@@ -1508,6 +1577,44 @@ async function runPreparedSpawn(params) {
         return { status: "failed", reason: "executor_adapter_unavailable" };
     }
     const mcpSurface = createMcpSurfaceObserver(mcpContract.expectedServerNames, (line) => initParsing.value.parseInitEvent(line));
+    // --- Worker env-file strip (FAIL-CLOSED, BAPI-1019/A.4) ---------------
+    // THE LAST thing that touches the worktree before a worker exists. Placed
+    // after the deny layer, after MCP provisioning and its verification, and after
+    // spawn-shape/observer construction precisely so nothing that runs later can
+    // re-introduce a file the guard just confirmed gone. Everything between this
+    // call and `deps.spawnProcess` below is pure in-memory work.
+    //
+    // Fail-CLOSED, following `StaleArtifactCleanupFailed` rather than the
+    // fail-OPEN deny-layer posture two hundred lines up. The deny layer shrinks a
+    // safety margin when it degrades; this gate is the margin. Architecture Miss 28
+    // was a worker that reached the operator's real database through a copied
+    // `.env` and truncated it — so "could not confirm the worktree is clean" must
+    // refuse, never proceed and hope.
+    const stripEnvFiles = seams.stripWorkerEnvFiles ?? stripWorkerEnvFiles;
+    const stripped = await stripEnvFiles(worktreePath, {
+        readdir: (dirPath) => readdir(dirPath),
+        // `lstat`/`unlink` only — the guard must never resolve a symlink, because an
+        // entry pointing at the main checkout would resolve to the operator's real
+        // `.env` and unlinking THAT would delete it. The narrow bag is the
+        // enforcement: no `stat`, `readlink`, or `readFile` is reachable from here.
+        lstat: (target) => lstat(target),
+        unlink: (target) => unlink(target),
+        platform: deps.platform,
+    });
+    if (!stripped.ok) {
+        await closeWorkerLog();
+        await finalizeRegistry();
+        // Exactly ONE bounded stderr line: the job id and the closed guard category.
+        // No worktree path (it carries a username), no removed filename, no errno, no
+        // exception text.
+        deps.errorLog(`[executor] job ${job.id}: refusing to spawn, worker env files unconfirmed: ${stripped.category}`);
+        await httpClient.fail(job, {
+            error_kind: WorkerEnvFilePresent,
+            error_message: WORKER_ENV_FILE_PRESENT_MESSAGE,
+            classification: "crashed",
+        });
+        return { status: "failed", reason: "worker_env_file_present" };
+    }
     let proc;
     try {
         proc = deps.spawnProcess(spawnShape.executable, spawnShape.argv, {
@@ -1577,6 +1684,7 @@ async function runPreparedSpawn(params) {
         // and an MCP containment refusal all converge on one `SIGTERM` and one grace
         // timer for this child (BAPI-828).
         terminationController,
+        control,
     });
     // --- Adapter lifecycle (EXPLICIT, BAPI-781) ---------------------------
     // Consumed rather than assumed. Claude declares `{ kind: "none" }` and so
@@ -1736,14 +1844,14 @@ async function runPreparedSpawn(params) {
                         classification: "crashed",
                     };
                 await finalizeRegistry();
-                const terminal = await sendTerminalMutationWithRetry({
+                const terminal = await sendTerminalMutationWithAuthReport({
                     kind: "fail",
                     send: () => httpClient.fail(job, { ...failure, ...commitResidue(git), telemetry: observation.snapshot() }),
                     deps,
                     options,
                     ownership,
                     log: deps.log,
-                });
+                }, job, control);
                 return terminalToRunResult(terminal, "failed");
             }
             // BAPI-528 Wave 3 M2: verdict jobs (`spec_review`) also produce a
@@ -1763,14 +1871,14 @@ async function runPreparedSpawn(params) {
                 ...commitResidue(git),
                 telemetry: observation.snapshot(),
             };
-            const terminal = await sendTerminalMutationWithRetry({
+            const terminal = await sendTerminalMutationWithAuthReport({
                 kind: "complete",
                 send: () => httpClient.complete(job, completion),
                 deps,
                 options,
                 ownership,
                 log: deps.log,
-            });
+            }, job, control);
             await finalizeRegistry();
             return terminalToRunResult(terminal, "completed");
         }
@@ -1800,7 +1908,7 @@ async function runPreparedSpawn(params) {
         });
         if (!finalization.ok) {
             await finalizeRegistry();
-            const terminal = await sendTerminalMutationWithRetry({
+            const terminal = await sendTerminalMutationWithAuthReport({
                 kind: "fail",
                 send: () => httpClient.fail(job, {
                     ...finalization.failure,
@@ -1811,7 +1919,7 @@ async function runPreparedSpawn(params) {
                 options,
                 ownership,
                 log: deps.log,
-            });
+            }, job, control);
             return terminalToRunResult(terminal, "failed");
         }
         // BAPI-862: attach the pull request the EXECUTOR verified. `pr_url` was never
@@ -1834,14 +1942,14 @@ async function runPreparedSpawn(params) {
             ...commitResidue(git),
             telemetry: observation.snapshot(),
         };
-        const terminal = await sendTerminalMutationWithRetry({
+        const terminal = await sendTerminalMutationWithAuthReport({
             kind: "complete",
             send: () => httpClient.complete(job, completion),
             deps,
             options,
             ownership,
             log: deps.log,
-        });
+        }, job, control);
         await finalizeRegistry();
         return terminalToRunResult(terminal, "completed");
     }
@@ -1863,7 +1971,7 @@ async function runPreparedSpawn(params) {
     const authDetection = adapter.authFailureDetection;
     const authFailure = authDetection?.supported === true &&
         authDetection.value.classify(procResult.stdoutExcerpt).notAuthenticated;
-    const terminal = await sendTerminalMutationWithRetry({
+    const terminal = await sendTerminalMutationWithAuthReport({
         kind: "fail",
         send: () => httpClient.fail(job, {
             error_kind: authFailure ? ClaudeNotAuthenticated : classificationToErrorKind(procResult.classification),
@@ -1878,6 +1986,6 @@ async function runPreparedSpawn(params) {
         options,
         ownership,
         log: deps.log,
-    });
+    }, job, control);
     return terminalToRunResult(terminal, "failed");
 }

package/build/executor/merge-job.js

@@ -23,7 +23,9 @@
  */
 import { makeLocalMergeExecutor, resolveLocalMergeMethod, } from "../conductor/local-merge.js";
 import { resolveConductorBridgeApiAccess, } from "../conductor/bridge-api-client.js";
+import { createProductionEpicIntegrationGhRunner, ensureEpicIntegrationPullRequest, formatEpicIntegrationPullRequestOutcome, EPIC_BRANCH_PREFIX, } from "../epic-integration-pr.js";
 import { secretFreeErrorMessage } from "./job-errors.js";
+import { resolveExecutorJobBaseBranch } from "./base-branch.js";
 function positiveIntOrNull(value) {
     return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null;
 }
@@ -38,8 +40,21 @@ function asString(value) {
  * Extract and validate merge fields. Prefers the claimed-job `expected_head_sha`
  * over any payload copy, validates `pr_number` as a positive integer, and fails
  * (before any subprocess) when the PR number or expected head SHA is absent.
+ *
+ * BAPI-1021 (AC-11): also resolves the two branch-ref expectations the local
+ * merge executor's ref-verification guard needs, and fails closed — before any
+ * `makeLocalMergeExecutor` construction or `runCommand` seam is reached — when
+ * either cannot be resolved:
+ *
+ *  - `expectedBaseBranch` via {@link resolveExecutorJobBaseBranch}, the SAME
+ *    resolver every other PR-producing job type uses, with `repositoryBaseBranch`
+ *    as its documented legacy fallback for a payload omitting `base_branch`.
+ *  - `expectedHeadBranch` EXCLUSIVELY from a trimmed, nonblank
+ *    `job.expected_branch` — never from payload data, which is untrusted and
+ *    job-type-generic. There is no fallback: a merge job with no known expected
+ *    head branch cannot be ref-verified.
  */
-export function readMergeJobPayloadFields(job) {
+export function readMergeJobPayloadFields(job, repositoryBaseBranch) {
     const payload = job.payload && typeof job.payload === "object" ? job.payload : {};
     const prNumber = positiveIntOrNull(payload.pr_number);
     if (prNumber === null) {
@@ -49,6 +64,15 @@ export function readMergeJobPayloadFields(job) {
     if (!expectedHeadSha) {
         return { ok: false, error: "merge job requires an expected_head_sha (top-level or payload)" };
     }
+    const baseResolution = resolveExecutorJobBaseBranch(job, repositoryBaseBranch);
+    if (!baseResolution.ok) {
+        return { ok: false, error: baseResolution.error };
+    }
+    const expectedBaseBranch = baseResolution.baseBranch;
+    const expectedHeadBranch = asString(job.expected_branch ?? undefined);
+    if (!expectedHeadBranch) {
+        return { ok: false, error: "merge job requires a nonblank expected_branch" };
+    }
     const method = resolveLocalMergeMethod(payload.method);
     const requiredChecks = Array.isArray(payload.required_checks)
         ? payload.required_checks.filter((c) => typeof c === "string")
@@ -58,7 +82,17 @@ export function readMergeJobPayloadFields(job) {
     const ciWaitPollIntervalMs = nonNegativeIntOrUndefined(payload.ci_wait_poll_interval_ms);
     return {
         ok: true,
-        fields: { prNumber, expectedHeadSha, method, requiredChecks, actionKey, ciWaitTimeoutMs, ciWaitPollIntervalMs },
+        fields: {
+            prNumber,
+            expectedHeadSha,
+            method,
+            requiredChecks,
+            actionKey,
+            ciWaitTimeoutMs,
+            ciWaitPollIntervalMs,
+            expectedBaseBranch,
+            expectedHeadBranch,
+        },
     };
 }
 /** Construct the {@link ConductorMergeRequest} for the local merge executor. */
@@ -120,10 +154,18 @@ export function buildMergeJobResult(response, fields) {
  *    safe to re-fire the same merge later.
  *  - {@link MERGE_CONFLICT}: needs a rebase before it can merge.
  *  - {@link MERGE_FAILED}: deterministic other failure (bad state, missing input).
+ *  - {@link MERGE_REF_MISMATCH}: BAPI-1021 — a DELIBERATE, terminal safety
+ *    refusal: the PR's current base or head branch did not match the caller's
+ *    expectation, so no provider merge was attempted. This is neither
+ *    retryable (the mismatch will not resolve itself) nor a rebase target (it
+ *    is not a conflict) — see `_merge_entry_failure_is_retryable` and
+ *    `_merge_entry_failure_requires_rebase` on the backend gate-retry path,
+ *    which both explicitly exclude it.
  */
 export const MERGE_RETRYABLE = "MergeRetryable";
 export const MERGE_CONFLICT = "MergeConflict";
 export const MERGE_FAILED = "MergeFailed";
+export const MERGE_REF_MISMATCH = "MergeRefMismatch";
 /** Reasons whose failure is transient/infrastructure and safe to retry. */
 const RETRYABLE_MERGE_REASONS = new Set([
     "gh_pr_view_timeout",
@@ -147,10 +189,18 @@ const RETRYABLE_MERGE_REASONS = new Set([
  * `ci_poll_`-prefixed reason is retryable — a prefix match keeps unbounded HTTP-status
  * variants covered so a distinct reason never accidentally downgrades to
  * {@link MERGE_FAILED}. Conflict classification is checked first so it is never masked.
+ *
+ * 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
+ * transient or conflict-shaped failure, and must not be re-firable by any
+ * future classification change.
  */
 export function classifyMergeFailureErrorKind(response) {
     const hasConflictEvent = response.ledger_events.some((ev) => ev.type === "merge.conflict");
     const reason = asString(response.reason ?? undefined);
+    if (reason === "ref_mismatch")
+        return MERGE_REF_MISMATCH;
     if (hasConflictEvent || reason === "gh_merge_conflict")
         return MERGE_CONFLICT;
     if (reason && (reason.startsWith("ci_poll_") || RETRYABLE_MERGE_REASONS.has(reason))) {
@@ -164,22 +214,59 @@ export function classifyMergeFailureErrorKind(response) {
  * `error_message` includes only the sanitized merge status and reason (never raw
  * `gh` output). `classification` stays within the executor's vocabulary; the
  * `error_kind` is the routing signal.
+ *
+ * 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.
  */
 export function buildMergeJobFailure(response) {
     const reason = asString(response.reason ?? undefined) ?? response.status;
+    const errorKind = classifyMergeFailureErrorKind(response);
     return {
-        error_kind: classifyMergeFailureErrorKind(response),
+        error_kind: errorKind,
         error_message: secretFreeErrorMessage(new Error(`local merge ${response.status}: ${reason}`)),
-        classification: "crashed",
+        classification: errorKind === MERGE_REF_MISMATCH ? "clean_exit" : "crashed",
     };
 }
+/**
+ * Post-merge draft epic-integration-PR retry (BAPI-951). Invoked ONLY after a
+ * successful ticket-bound merge whose child PR based on `epic/<EPIC>` — never
+ * for a `main`/other-based merge, and never for any failed merge. Wrapped in
+ * its own try/catch (the shared helper is already non-throwing, but this
+ * guards against a future/injected implementation replacing an already-decided
+ * merge outcome). NEVER changes the returned result, the `error_kind`, or the
+ * `/complete` payload — only emits a sanitized advisory line.
+ */
+async function tryEnsurePostMergeEpicIntegrationPr(seams, childBaseBranch) {
+    try {
+        if (!childBaseBranch.startsWith(EPIC_BRANCH_PREFIX))
+            return;
+        const epicKey = childBaseBranch.slice(EPIC_BRANCH_PREFIX.length);
+        if (epicKey.length === 0)
+            return;
+        const gh = seams.epicIntegrationGh ?? createProductionEpicIntegrationGhRunner();
+        const outcome = await ensureEpicIntegrationPullRequest({
+            epicKey,
+            epicBranch: childBaseBranch,
+            baseBranch: seams.repositoryBaseBranch,
+            command: "executor merge",
+            gh,
+            cwd: seams.cwd,
+        });
+        seams.epicIntegrationAdvisoryLog?.(`epic integration pr: ${JSON.stringify(formatEpicIntegrationPullRequestOutcome(outcome))}`);
+    }
+    catch {
+        // Advisory-only: never allowed to affect the already-decided merge outcome.
+    }
+}
 /**
  * Run the deterministic merge. NEVER ensures/recreates a worktree and NEVER
  * spawns a worker. Returns a completion result on a succeeded merge, else a
  * bounded, secret-free executor failure.
  */
 export async function runExecutorMergeJob(job, seams) {
-    const resolution = readMergeJobPayloadFields(job);
+    const resolution = readMergeJobPayloadFields(job, seams.repositoryBaseBranch);
     if (!resolution.ok) {
         return {
             ok: false,
@@ -197,6 +284,11 @@ export async function runExecutorMergeJob(job, seams) {
         method: fields.method,
         ciWaitTimeoutMs: fields.ciWaitTimeoutMs,
         ciWaitPollIntervalMs: fields.ciWaitPollIntervalMs,
+        // BAPI-1021 (AC-11): pass the already-resolved expectations through
+        // unchanged so verification and the post-merge enrichment below use one
+        // authoritative value — neither re-resolves it independently.
+        expectedBaseBranch: fields.expectedBaseBranch,
+        expectedHeadBranch: fields.expectedHeadBranch,
     }, seams.localMergeDeps);
     let response;
     try {
@@ -213,7 +305,11 @@ export async function runExecutorMergeJob(job, seams) {
         };
     }
     if (response.status === "succeeded") {
-        return { ok: true, result: buildMergeJobResult(response, fields) };
+        // Build the successful outcome COMPLETELY first — enrichment can only ever
+        // add an advisory log line, never alter what is returned.
+        const result = buildMergeJobResult(response, fields);
+        await tryEnsurePostMergeEpicIntegrationPr(seams, fields.expectedBaseBranch);
+        return { ok: true, result };
     }
     return { ok: false, failure: buildMergeJobFailure(response) };
 }