@bridge_gpt/mcp-server 0.2.16 → 0.2.18

package/build/conductor/epic-runtime.js

@@ -18,12 +18,16 @@
  * Epic Run TS client (already available in bridge-api-client.ts as of BAPI-407).
  */
 import { spawnSync } from "child_process";
-import { resolveConductorBridgeApiAccess, claimEpicSupervisionLease, fetchEpicRunState, advanceEpicTicketStatus, createEpicTicketStatus, recordEpicDispatch, transitionEpicDispatch, fetchParseStatus, triggerRepositoryParse, getEpicPlan, buildEpicDispatchKey, fetchEffectiveSupervisorConfig, fetchEffectiveSupervisorSetup, fetchPrReviewStatus, remediateEpicTicket, deletePullRequestBranch, transitionJiraStatus, } from "./bridge-api-client.js";
+import { resolveConductorBridgeApiAccess, claimEpicSupervisionLease, fetchEpicRunState, advanceEpicTicketStatus, createEpicTicketStatus, updateEpicRunStatus, recordEpicDispatch, transitionEpicDispatch, fetchParseStatus, triggerRepositoryParse, getEpicPlan, buildEpicDispatchKey, fetchEffectiveSupervisorConfig, fetchEffectiveSupervisorSetup, remediateEpicTicket, deletePullRequestBranch, transitionJiraStatus, safeDiagnosticMessage, } from "./bridge-api-client.js";
 import { processGateMetMerge } from "./supervisor-merge.js";
+import { observePrCiOnce } from "./pr-ci-producer.js";
+import { runGhCommand } from "./pr-discovery.js";
+import { isPrMergeConflict, parseGhPrMergeabilityFields, } from "./github-mergeability.js";
 import { makeLocalMergeExecutor, resolveLocalMergeMethod } from "./local-merge.js";
 import { emitConductorEventIfNew } from "./producer-ledger.js";
 import { rebuildObservedState, extractWorkerLiveness, } from "./epic-state.js";
 import { reconcileEpic } from "./epic-reconcile.js";
+import { normalizeDeclaredTouchedFiles } from "./file-scope-guard.js";
 import { buildSupervisorRemediationWorkerMessage } from "./supervisor-message-relay.js";
 import { sendWorkerMessage } from "./store.js";
 import { hashPlan } from "./plan.js";
@@ -49,6 +53,12 @@ const ACTIVE_WORKER_STATUSES = new Set(["dispatched", "running"]);
  */
 const PARSE_WAIT_EVENT_SOURCE = "conductor-supervisor";
 const PARSE_WAIT_EVENT_PRODUCER = "epic-parse-wait";
+/**
+ * BAPI-494: source + producer tags for the durable `merge.conflict` marker the
+ * done-gate pass emits when a `ready_for_review` ticket's PR is un-mergeable.
+ */
+const MERGE_CONFLICT_EVENT_SOURCE = "conductor-supervisor";
+const MERGE_CONFLICT_EVENT_PRODUCER = "epic-mergeability";
 function defaultLeaseOwner() {
     return `epic-tick-${process.pid}`;
 }
@@ -61,6 +71,191 @@ async function defaultDispatchSeam(_epicKey, ticketKey, _attempt = 0) {
 async function defaultPostActionWaitSeam(_epicKey, _ticketKey) {
     // no-op: parse-after-merge wait is a sibling ticket's concern
 }
+export function parsePrBindingFromGhJson(stdout) {
+    let pr;
+    try {
+        pr = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    const num = pr.number;
+    const sha = pr.headRefOid;
+    const state = typeof pr.state === "string" ? pr.state : "";
+    if (typeof num === "number" &&
+        Number.isInteger(num) &&
+        num >= 1 &&
+        typeof sha === "string" &&
+        /^[0-9a-f]{7,40}$/i.test(sha) &&
+        state.toUpperCase() === "OPEN") {
+        // BAPI-494: parse mergeability defensively from the same JSON object — unknown
+        // values become null and never reject an otherwise valid open PR binding.
+        const mergeability = parseGhPrMergeabilityFields(pr);
+        return {
+            prNumber: num,
+            headSha: sha,
+            mergeable: mergeability.mergeable,
+            mergeStateStatus: mergeability.mergeStateStatus,
+        };
+    }
+    return null;
+}
+/**
+ * Shared gh-discovery PR-binding resolver: resolve BOTH the PR number and the
+ * CURRENT head SHA for a ticket from its `feature/<KEY>` branch via
+ * `gh pr view ... --json number,headRefOid,state`. This is the single
+ * gh-discovery path used by BOTH the Conductor done-gate pass and the
+ * remediation CAS dispatch (BAPI-487 Requirement 1). It intentionally does NOT
+ * consult `epic_supervisor_setup.pr_bindings` — nothing auto-populates that map,
+ * so the legacy `pr_bindings` seam always returned null and stranded remediation.
+ *
+ * Fail-closed: returns null for any failed `gh` invocation, empty stdout, or a
+ * closed/merged PR / malformed number / non-hex head SHA (all enforced by
+ * {@link parsePrBindingFromGhJson}). `options.runGh` is injectable for pure unit
+ * tests; `options.cwd` defaults to the Conductor's current working directory.
+ */
+export function resolveTicketPrBindingFromGh(ticketKey, options = {}) {
+    const runGh = options.runGh ?? runGhCommand;
+    const ghRes = runGh(
+    // BAPI-494: mergeability fields added to the SAME per-ticket binding call — the
+    // done-gate reads mergeability inside this existing call, spawning no new gh process.
+    ["pr", "view", `feature/${ticketKey}`, "--json", "number,headRefOid,state,mergeable,mergeStateStatus"], { cwd: options.cwd ?? process.cwd() });
+    if (ghRes.ok && ghRes.stdout.trim()) {
+        const parsed = parsePrBindingFromGhJson(ghRes.stdout);
+        // Normalize the head SHA to lowercase so downstream head-scoped comparisons
+        // (blocked-head vs. current-head, gate.met dedupe) are case-stable.
+        return parsed
+            ? { ...parsed, headSha: parsed.headSha.toLowerCase() }
+            : null;
+    }
+    return null;
+}
+/**
+ * For each `ready_for_review` ticket — and (BAPI-487) each `blocked` ticket whose
+ * live PR head has advanced past the head that blocked it — ask the conductor to
+ * evaluate the composite done-gate itself via {@link observePrCiOnce}, the
+ * correctness backstop for FINDING 6 where a worker never self-emits `gate.met`.
+ * `observePrCiOnce` binds to the CURRENT head SHA, fails closed on any
+ * unavailable/ambiguous/stale-head signal, and idempotently emits `gate.met`
+ * (deduped by ticket+PR+head_sha) so the fold + merge-enqueue happens exactly once
+ * regardless of whether the worker also emitted it.
+ *
+ * A `blocked` ticket is re-evaluated ONLY when its PR binding resolves AND either
+ * the recorded blocked head is unknown (fail-closed recovery) or the current head
+ * differs from it — a ticket still blocked on its current head is left blocked so
+ * a same-head failure is never bypassed.
+ *
+ * Fully fail-closed and non-blocking: a per-ticket observation error is caught and
+ * logged so it can never crash or stall the reconcile loop; tickets that are
+ * neither `ready_for_review` nor advanced-head `blocked`, and tickets without a
+ * PR binding, are skipped.
+ */
+export async function runConductorDoneGatePass(ticketStatuses, deps) {
+    for (const [ticketKey, status] of ticketStatuses) {
+        if (status !== "ready_for_review" && status !== "blocked")
+            continue;
+        const prBinding = deps.resolvePrBinding(ticketKey);
+        if (prBinding === null) {
+            deps.log(`[epic-tick] done-gate poll for ${ticketKey}: skipped (no PR binding)`);
+            continue;
+        }
+        // BAPI-487: gate a `blocked` ticket's re-evaluation on its head advancing.
+        if (status === "blocked") {
+            const blockedHead = deps.resolveBlockedHeadSha?.(ticketKey) ?? null;
+            if (blockedHead === null) {
+                deps.log(`[epic-tick] done-gate re-eval for ${ticketKey}: blocked with no recorded head; ` +
+                    `polling current head ${prBinding.headSha} fail-closed as recovery`);
+            }
+            else if (blockedHead.toLowerCase() === prBinding.headSha.toLowerCase()) {
+                deps.log(`[epic-tick] done-gate poll for ${ticketKey}: skipped (still blocked on current head ${prBinding.headSha})`);
+                continue;
+            }
+            else {
+                deps.log(`[epic-tick] done-gate re-eval for ${ticketKey}: blocked head ${blockedHead} ` +
+                    `superseded by current head ${prBinding.headSha}; re-evaluating`);
+            }
+        }
+        // Stamp the ticket's run_id AND worker_id onto the emitted gate.met via a
+        // per-ticket env override (observePrCiOnce reads BAPI_CONDUCTOR_RUN_ID/
+        // _WORKER_ID from env, env taking precedence). run_id correlates the fold to
+        // the ticket; a non-empty worker_id is required for the merge to enqueue
+        // (merge-ledger extractMergeActionIdentityFromGateEvent). Both must be present
+        // or the conductor-emitted gate.met folds/merges to nothing.
+        const runId = deps.resolveRunId?.(ticketKey) ?? null;
+        const workerId = deps.resolveWorkerId?.(ticketKey) ?? null;
+        // BAPI-494: a `ready_for_review` PR that is already un-mergeable
+        // (CONFLICTING/DIRTY) can never be re-reviewed (claude-review won't verdict an
+        // unmergeable branch) or merged — so it would sit at ready_for_review forever.
+        // Route it into the head-scoped `merge.conflict` blocking path (folded next
+        // tick, remediated as a resume-mode redispatch) BEFORE re-polling CI, and skip
+        // CI observation for this ticket. Only `ready_for_review` conflicts are emitted
+        // here; a `blocked` ticket already has routing + stale-head re-evaluation.
+        if (status === "ready_for_review" && isPrMergeConflict(prBinding)) {
+            try {
+                await deps.emitConflictSignal?.({
+                    ticketKey,
+                    repoName: deps.access.repoName,
+                    prNumber: prBinding.prNumber,
+                    headSha: prBinding.headSha,
+                    mergeable: prBinding.mergeable,
+                    mergeStateStatus: prBinding.mergeStateStatus,
+                    runId,
+                    workerId,
+                });
+                deps.log(`[epic-tick] done-gate conflict for ${ticketKey}: PR #${prBinding.prNumber} ` +
+                    `not mergeable at head ${prBinding.headSha}; emitted merge.conflict`);
+            }
+            catch (err) {
+                const safeMsg = err instanceof Error ? err.constructor.name : "conflict emit error";
+                deps.errorLog(`[epic-tick] done-gate conflict-signal failed (${safeMsg}) for ${ticketKey}; continuing`);
+            }
+            continue;
+        }
+        const perTicketEnv = {
+            ...deps.env,
+            ...(runId ? { BAPI_CONDUCTOR_RUN_ID: runId } : {}),
+            ...(workerId ? { BAPI_CONDUCTOR_WORKER_ID: workerId } : {}),
+        };
+        try {
+            const observeResult = await deps.observePrCi({
+                repoName: deps.access.repoName,
+                prNumber: prBinding.prNumber,
+                headSha: prBinding.headSha,
+            }, {
+                env: perTicketEnv,
+                resolveAccess: async () => ({ ok: true, access: deps.access }),
+            });
+            deps.log(`[epic-tick] done-gate poll for ${ticketKey}: ${observeResult.reason}`);
+        }
+        catch (err) {
+            const safeMsg = err instanceof Error ? err.constructor.name : "observe error";
+            deps.errorLog(`[epic-tick] done-gate poll failed (${safeMsg}) for ${ticketKey}; continuing`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// N-3 run self-completion (BAPI-507)
+// ---------------------------------------------------------------------------
+/**
+ * BAPI-507 (N-3): should the epic run self-complete this tick? True ONLY when the
+ * approved plan has at least one ticket AND every plan ticket's effective status
+ * is exactly `"done"` in `observed.ticket_statuses`. Any node that is
+ * `abandoned` / `blocked` / `ready_for_review` / `running` / `reviewing` /
+ * `ready` / `dispatched` / `planned`, missing from the status map, or any other
+ * non-`done` value makes this return `false`. Conservative done-only policy: a
+ * plan ending in a `done` + `abandoned` mix does NOT auto-complete — an operator
+ * decides how to close a run with abandoned nodes. Pure: no I/O, no clock.
+ */
+function shouldSelfCompleteEpicRun(plan, observed) {
+    if (plan.tickets.length === 0)
+        return false;
+    for (const ticket of plan.tickets) {
+        if (observed.ticket_statuses.get(ticket.ticket_key) !== "done") {
+            return false;
+        }
+    }
+    return true;
+}
 // ---------------------------------------------------------------------------
 // runEpicTick
 // ---------------------------------------------------------------------------
@@ -91,6 +286,28 @@ export async function runEpicTick(options, deps = {}) {
     const claimLeaseFn = deps.claimLease ?? claimEpicSupervisionLease;
     const fetchEpicStateFn = deps.fetchEpicState ?? fetchEpicRunState;
     const releaseLease = deps.releaseLease;
+    const env = deps.env ?? process.env;
+    const observePrCiSeamFn = deps.observePrCiSeam ?? observePrCiOnce;
+    // BAPI-507 (N-3): default self-completion seam CASes the run active → done via
+    // the existing PATCH /runs/{id} path, addressing the run by its concrete UUID.
+    const completeEpicRunFn = deps.completeEpicRun ??
+        (async (acc, epicRunId) => {
+            await updateEpicRunStatus(acc, {
+                epicKey: epicRunId,
+                status: "done",
+                expectedStatus: "active",
+            });
+        });
+    // BAPI-494: a single durable event emitter reused by BOTH the parse-after-merge
+    // marker block and the done-gate `merge.conflict` wiring, so there is one
+    // injectable ledger path (not a second hardcoded emitter).
+    const emitConductorEventFn = deps.emitConductorEvent ?? emitConductorEventIfNew;
+    // FINDING 1 (BAPI-463): a dry-run tick must exercise the full dispatch-resolution
+    // path (ready-set → resolved command + model routing) yet persist NO authoritative
+    // dispatch state. Without this guard, `correlateRunId` writes a `run_spawned` row
+    // under the REAL dispatch_key, and the next real tick's `claimDispatchKey` returns
+    // `already-spawned`, silently skipping the real worker spawn.
+    const isDryRun = env.BAPI_CONDUCTOR_DISPATCH_DRY_RUN === "1";
     const startMs = nowFn();
     // ---------------------------------------------------------------------------
     // Step 0: Resolve Bridge API access (offline / fail-closed guard)
@@ -225,7 +442,6 @@ export async function runEpicTick(options, deps = {}) {
             const settleMs = 5000;
             const fetchParseStatusFn = deps.fetchParseStatus ?? fetchParseStatus;
             const triggerParseFn = deps.triggerParse ?? triggerRepositoryParse;
-            const emitConductorEventFn = deps.emitConductorEvent ?? emitConductorEventIfNew;
             for (let i = 0; i < observed.unfolded_terminal_signals.length; i++) {
                 const signal = observed.unfolded_terminal_signals[i];
                 if (signal.signal_type !== "merge.succeeded")
@@ -393,6 +609,12 @@ export async function runEpicTick(options, deps = {}) {
             // liveness window) and setup (pr_bindings) once. Fail-open: if the config
             // read fails, remediationConfig stays undefined and reconcile skips the
             // remediation pass entirely (dispatch/merge steps unaffected).
+            //
+            // BAPI-487: `prBindings` is retained ONLY for the legacy teardown seam
+            // (which needs just the PR number). Both the done-gate observation and the
+            // remediation CAS resolve their PR binding via gh-discovery
+            // (resolveTicketPrBindingFromGh), never from this map — nothing
+            // auto-populates `pr_bindings`, so relying on it stranded remediation.
             let remediationConfig;
             let livenessWindowSeconds = 120;
             let prBindings = {};
@@ -461,6 +683,14 @@ export async function runEpicTick(options, deps = {}) {
             for (const [tk, info] of reviewLatestDispatchByTicket) {
                 reviewTicketRunIdMap.set(tk, info.runId);
             }
+            // Legacy PR-number-only resolver from `pr_bindings`. BAPI-487: this is now
+            // consumed ONLY by the teardownSeam, which needs just the number and is
+            // outside this ticket's remediation critical path. Both the done-gate
+            // observation and the remediation CAS resolve their PR binding via
+            // gh-discovery (resolveTicketPrBindingFromGh / resolvePrBinding) instead,
+            // because nothing auto-populates `pr_bindings` (confirmed NULL for repo
+            // `bapi`), so this legacy path always returns null. Teardown is left on it
+            // deliberately rather than silently migrated.
             const resolvePrNumber = (ticketKey) => {
                 const raw = prBindings[ticketKey];
                 if (typeof raw === "number" && Number.isInteger(raw) && raw >= 1)
@@ -473,6 +703,92 @@ export async function runEpicTick(options, deps = {}) {
                 }
                 return null;
             };
+            // gh-discovery PR binding used by BOTH the done-gate pass and the
+            // remediation CAS (BAPI-487 Requirement 1). Delegates to the shared
+            // `resolveTicketPrBindingFromGh` helper so the two seams cannot diverge; it
+            // resolves the number AND the current head SHA from `feature/<KEY>` and
+            // fail-closes unless the PR is OPEN with a well-formed number + head SHA.
+            const resolvePrBinding = (ticketKey) => resolveTicketPrBindingFromGh(ticketKey, { cwd: process.cwd() });
+            // ---------------------------------------------------------------------
+            // Step 4.5: Conductor-driven done-gate for ready_for_review tickets
+            // (FINDING 6, BAPI-463) — the correctness backstop for the hands-off run.
+            //
+            // Workers do not reliably self-emit `gate.met` (a ticket can reach
+            // ready_for_review via `run.stopped` alone), so the merge enqueue — gated on
+            // `gate.met` only — would stall forever awaiting a worker signal. Here the
+            // CONDUCTOR evaluates the composite done-gate itself via the existing
+            // `observePrCiOnce`, which binds to the resolved CURRENT head SHA, evaluates
+            // the pure fail-closed done-gate (required-CI green + current-head review
+            // verdict), and idempotently emits `gate.met` (deduped by ticket+PR+head_sha)
+            // so this tick or the next one folds it and enqueues the merge exactly once.
+            // Worker-emitted `gate.met` stays a valid fast-path; this pass never removes it.
+            // The pass is best-effort and fully fail-closed: an observation error is
+            // caught per-ticket so it can never crash or block the reconcile loop, and
+            // `observePrCiOnce` emits nothing on an unavailable/ambiguous/stale-head signal.
+            // run_id → worker_id from the ledger (first worker_id seen per run) so the
+            // conductor-emitted gate.met carries the real worker's id; fall back to a
+            // synthetic conductor id so the merge-identity presence check always passes.
+            const runIdToWorkerId = new Map();
+            for (const ev of localEvents) {
+                if (ev.run_id && ev.worker_id && !runIdToWorkerId.has(ev.run_id)) {
+                    runIdToWorkerId.set(ev.run_id, ev.worker_id);
+                }
+            }
+            const resolveTicketRunId = (tk) => ticketRunIdMap.get(tk) ?? latestDispatchByTicket.get(tk)?.runId ?? null;
+            const resolveDoneGateWorkerId = (tk) => {
+                const rid = resolveTicketRunId(tk);
+                if (rid && runIdToWorkerId.has(rid))
+                    return runIdToWorkerId.get(rid);
+                return `conductor:${tk}`;
+            };
+            await runConductorDoneGatePass(observed.ticket_statuses, {
+                observePrCi: observePrCiSeamFn,
+                resolvePrBinding,
+                // BAPI-487: re-evaluate a blocked ticket only when its PR head advanced
+                // past the head recorded on its latest blocking signal.
+                resolveBlockedHeadSha: (tk) => observed.ticket_blocked_heads?.get(tk) ?? null,
+                resolveRunId: resolveTicketRunId,
+                resolveWorkerId: resolveDoneGateWorkerId,
+                // BAPI-494: convert a detected conflict into a durable, head-scoped
+                // `merge.conflict` ledger event stamped with the ticket's dispatch run/worker
+                // so the fold correlates it and the remediation pass redispatches. Emitted via
+                // the shared injectable emitter, idempotent per conflict head. Folded next tick
+                // (this pass runs after rebuildObservedState), matching the gate.met latency.
+                emitConflictSignal: (input) => {
+                    emitConductorEventFn({
+                        source: MERGE_CONFLICT_EVENT_SOURCE,
+                        type: "merge.conflict",
+                        subject: input.ticketKey,
+                        run_id: input.runId,
+                        worker_id: input.workerId,
+                        producer: MERGE_CONFLICT_EVENT_PRODUCER,
+                        observed_via: "supervisor",
+                        time: new Date(nowFn()).toISOString(),
+                        data: {
+                            summary: `PR #${input.prNumber} for ${input.ticketKey} is not mergeable`,
+                            status: "blocked",
+                            reason: "merge.conflict",
+                            details: {
+                                epic_key,
+                                ticket_key: input.ticketKey,
+                                repo: input.repoName,
+                                pr_number: input.prNumber,
+                                head_sha: input.headSha,
+                                mergeable: input.mergeable,
+                                mergeStateStatus: input.mergeStateStatus,
+                            },
+                        },
+                    }, {
+                        event_type: "merge.conflict",
+                        run_id: input.runId ?? undefined,
+                        commit_sha: input.headSha,
+                    });
+                },
+                access,
+                env,
+                log,
+                errorLog,
+            });
             const maxSeqForRun = (runId) => {
                 let maxSeq = 0;
                 for (const ev of localEvents) {
@@ -489,25 +805,57 @@ export async function runEpicTick(options, deps = {}) {
                     nextStatus,
                     planVersion,
                 }),
-                seedTicketStatus: async (ek, tk, planVersion) => {
+                seedTicketStatus: async (_ek, tk, planVersion) => {
+                    // A6/BAPI-507: address the run by its concrete epic_run_id — the
+                    // endpoint path is /runs/{epic_run_id}/tickets. Passing the UUID (not
+                    // the Jira epic key `_ek`) skips the epic-key→active-run resolution and
+                    // its multi-active-run CONFLICT edge. The backend read-back makes a
+                    // re-seed of an existing row a clean 2xx no-op.
                     await createEpicTicketStatus(access, {
-                        epicKey: ek,
+                        epicKey: epicRunState.epic_run.epic_run_id,
                         ticketKey: tk,
                         status: "planned",
                         planVersion,
                     });
                 },
-                claimDispatchKey: async (ek, tk, planVersion, role, attempt = 0) => recordEpicDispatch(access, {
-                    epicKey: ek,
-                    ticketKey: tk,
-                    planVersion,
-                    leaseOwner: lease_owner,
-                    ttlSeconds: DEFAULT_DISPATCH_KEY_TTL_SECONDS,
-                    attempt,
-                    // BAPI-445: a review-role claim appends ":review" to the dispatch key
-                    // so the run-id maps above can separate review runs from impl runs.
-                    reviewRole: role === "review",
-                }),
+                claimDispatchKey: async (ek, tk, planVersion, role, attempt = 0) => {
+                    // FINDING 1 (BAPI-463): in dry-run mode, DO NOT persist a real dispatch
+                    // claim. Return a synthetic "claimed" result (run_id null) so the reconcile
+                    // pass proceeds to resolve the command + model routing (still exercised) but
+                    // no authoritative `run_spawned` row is written under the real dispatch_key.
+                    if (isDryRun) {
+                        const suffix = `${role === "review" ? ":review" : ""}${attempt > 0 ? `:r${attempt}` : ""}`;
+                        const nowIso = new Date(nowFn()).toISOString();
+                        log(`[DRY RUN] claiming dispatch key skipped for ${tk} (epic=${ek}, role=${role ?? "implementation"}, attempt=${attempt}); no run_spawned row persisted`);
+                        return {
+                            ok: true,
+                            kind: "claimed",
+                            dispatch: {
+                                dispatch_key: `dry-run:${ek}:${tk}:v${planVersion}${suffix}`,
+                                epic_run_id: ek,
+                                ticket_key: tk,
+                                plan_version: planVersion,
+                                status: "pending",
+                                run_id: null,
+                                lease_owner: lease_owner,
+                                lease_expires_at: null,
+                                created_at: nowIso,
+                                updated_at: nowIso,
+                            },
+                        };
+                    }
+                    return recordEpicDispatch(access, {
+                        epicKey: ek,
+                        ticketKey: tk,
+                        planVersion,
+                        leaseOwner: lease_owner,
+                        ttlSeconds: DEFAULT_DISPATCH_KEY_TTL_SECONDS,
+                        attempt,
+                        // BAPI-445: a review-role claim appends ":review" to the dispatch key
+                        // so the run-id maps above can separate review runs from impl runs.
+                        reviewRole: role === "review",
+                    });
+                },
                 // BAPI-445 spec re-review seams. dispatchReviewSeam is wired only when the
                 // factory provides it (gate stays off otherwise); the liveness + attempt
                 // accessors read the review-scoped maps built above.
@@ -522,6 +870,13 @@ export async function runEpicTick(options, deps = {}) {
                 },
                 countReviewAttempts: (tk) => reviewAttemptCounts.get(tk) ?? 0,
                 correlateRunId: async (dispatchKey, runId) => {
+                    // FINDING 1 (BAPI-463): dry-run must not transition the dispatch row to
+                    // `run_spawned`. Skipping this keeps the real dispatch_key un-claimed so a
+                    // subsequent real tick spawns the worker instead of hitting `already-spawned`.
+                    if (isDryRun) {
+                        log(`[DRY RUN] correlate run_id skipped for dispatch_key=${dispatchKey} (run_id=${runId}); no run_spawned transition persisted`);
+                        return;
+                    }
                     await transitionEpicDispatch(access, {
                         dispatchKey,
                         nextStatus: "run_spawned",
@@ -615,19 +970,30 @@ export async function runEpicTick(options, deps = {}) {
                     return extractWorkerLiveness(localEvents, runId, nowFn(), livenessWindowSeconds);
                 },
                 remediateCas: async (ek, tk, attemptKind, reason) => {
-                    const prNumber = resolvePrNumber(tk);
-                    if (prNumber === null) {
+                    // BAPI-487 Requirement 1: resolve the PR number + head SHA via the same
+                    // gh-discovery the done-gate pass uses, NOT the never-populated
+                    // `pr_bindings` map (which stranded remediation on `remediate: no PR
+                    // binding`). resolvePrBinding returns both the number and the current
+                    // head SHA, so the separate legacy review-status head-SHA fetch is gone.
+                    const prBinding = resolvePrBinding(tk);
+                    if (prBinding === null) {
                         throw new Error(`remediate: no PR binding for ${tk}`);
                     }
-                    const reviewStatus = (await fetchPrReviewStatus(access, prNumber));
-                    const headSha = reviewStatus?.detail?.head_sha ?? null;
-                    if (!headSha) {
-                        throw new Error(`remediate: no head_sha for PR ${prNumber}`);
-                    }
-                    const rowVersion = observed.ticket_row_versions.get(tk) ?? 0;
+                    const prNumber = prBinding.prNumber;
+                    const headSha = prBinding.headSha;
+                    // BAPI-500: remediation runs AFTER the fold step in the SAME reconcile
+                    // pass. When this ticket folded to `blocked` this tick, the block CAS
+                    // already bumped its row_version to snapshot+1, so prefer the confirmed
+                    // same-pass post-fold version; fall back to the tick-start snapshot when
+                    // the ticket was not folded this tick, then to 0. Sending the stale
+                    // tick-start snapshot is exactly the deterministic 400 loop this fixes.
+                    const rowVersion = observed.ticket_post_fold_row_versions?.get(tk) ??
+                        observed.ticket_row_versions.get(tk) ??
+                        0;
                     // Deterministic block-state idempotency key: stable for a given durable
                     // row_version so a same-tick retry replays (409, swallowed); advances
-                    // with the next attempt.
+                    // with the next attempt. Derived from the SAME local `rowVersion` sent
+                    // as `expected_row_version` so the key and the CAS token stay in lockstep.
                     const idempotencyKey = `remediate:${ek}:${tk}:${rowVersion}`;
                     const result = await remediateEpicTicket(access, {
                         pr_number: prNumber,
@@ -695,6 +1061,24 @@ export async function runEpicTick(options, deps = {}) {
             for (const w of reconcileResult.warnings) {
                 errorLog(`[epic-tick] warning: ${w}`);
             }
+            // Step 5.5 (N-3 / BAPI-507): self-complete the run once every approved-plan
+            // ticket is durably `done`. Deferred while any terminal signal folded THIS
+            // tick is still unpersisted (`unfolded_terminal_signals`) so the run closes
+            // on a SUBSEQUENT tick — after Postgres durably reflects all-done — rather
+            // than from a same-tick local projection. Fail-open: a stale CAS (a
+            // concurrent terminal transition already closed the run, or the top-of-tick
+            // terminal guard will) is bounded operational noise, never a tick failure.
+            if (shouldSelfCompleteEpicRun(plan, observed) &&
+                observed.unfolded_terminal_signals.length === 0) {
+                try {
+                    await completeEpicRunFn(access, epicRunState.epic_run.epic_run_id);
+                    log(`[epic-tick] epic=${epic_key} self-completed: all plan tickets done`);
+                }
+                catch (err) {
+                    errorLog(`[epic-tick] self-completion CAS failed for epic=${epic_key}: ` +
+                        `${safeDiagnosticMessage(err, "self-complete error")}`);
+                }
+            }
         }
         else {
             log(`[epic-tick] no plan available for epic=${epic_key}; skipping dispatch and merge steps`);
@@ -780,6 +1164,10 @@ export async function buildProductionEpicRuntimeDeps(epicKey) {
     // Shared closure state populated by fetchPlan and consumed by dispatchSeam.
     let cachedPlanVersion = 0;
     const automationMap = new Map();
+    // BAPI-507 (N-2): per-ticket normalized declared touched-file set, sourced from
+    // the plan DAG node's `touched_files`. Consumed by dispatchSeam to inject the
+    // declared file scope into the implementation worker's environment.
+    const touchedFilesMap = new Map();
     const fetchPlan = async (ek, acc) => {
         let response;
         try {
@@ -797,18 +1185,32 @@ export async function buildProductionEpicRuntimeDeps(epicKey) {
             return null;
         const dag = response.plan_blob;
         cachedPlanVersion = response.plan_version;
-        // Populate the automation map for the dispatch seam.
+        // Populate the automation + declared-touched-files maps for the dispatch seam.
         for (const node of dag.nodes) {
+            const nodeKey = node.ticket_key.trim();
             const kind = node.automations?.[0]?.kind;
             if (kind) {
-                automationMap.set(node.ticket_key.trim(), kind);
+                automationMap.set(nodeKey, kind);
+            }
+            // BAPI-507 (N-2): normalize defensively (trim, drop blanks, dedupe, sort;
+            // no filesystem access). Missing/non-array touched_files → unspecified, so
+            // the ticket simply gets no declared scope rather than failing dispatch.
+            const declared = normalizeDeclaredTouchedFiles(node.touched_files);
+            if (declared.length > 0) {
+                touchedFilesMap.set(nodeKey, declared);
             }
         }
-        // Map DAG nodes to EpicTicketNode (drop automations/status/edges).
-        const tickets = dag.nodes.map((n) => ({
-            ticket_key: n.ticket_key.trim(),
-            depends_on: (n.depends_on ?? []).map((k) => k.trim()),
-        }));
+        // Map DAG nodes to EpicTicketNode, preserving each node's normalized declared
+        // touched-file set (drop automations/status/edges).
+        const tickets = dag.nodes.map((n) => {
+            const nodeKey = n.ticket_key.trim();
+            const declared = touchedFilesMap.get(nodeKey);
+            return {
+                ticket_key: nodeKey,
+                depends_on: (n.depends_on ?? []).map((k) => k.trim()),
+                ...(declared && declared.length > 0 ? { touched_files: declared } : {}),
+            };
+        });
         // Recompute the hash locally — do NOT trust the server-returned plan_hash.
         // This makes the integrity gate fail-closed: a tampered or drifted blob
         // will hash differently than approved_plan_hash and halt the tick.
@@ -836,11 +1238,18 @@ export async function buildProductionEpicRuntimeDeps(epicKey) {
         // path (ready-set → claim key → dispatch → correlate run_id) still exercises;
         // dry-run rows carry no runId, so a synthetic one is substituted for correlation.
         const dispatchDryRun = process.env.BAPI_CONDUCTOR_DISPATCH_DRY_RUN === "1";
+        // BAPI-507 (N-2): thread the ticket's declared file scope into the
+        // IMPLEMENTATION dispatch identity only. A `review-tickets` node does not open
+        // an implementation PR, so it gets no file-scope env (Step 8.5).
+        const declaredTouchedFiles = kind === "review-tickets" ? undefined : touchedFilesMap.get(tk);
         const identity = {
             epic_key: ek,
             epic_run_id: ek,
             plan_version: cachedPlanVersion,
             dispatch_key: buildEpicDispatchKey(ek, tk, cachedPlanVersion, attempt),
+            ...(declaredTouchedFiles && declaredTouchedFiles.length > 0
+                ? { declared_touched_files: declaredTouchedFiles }
+                : {}),
         };
         const deps = createDefaultStartTicketsDeps();
         let runId;
@@ -853,6 +1262,10 @@ export async function buildProductionEpicRuntimeDeps(epicKey) {
                 maxParallel: 1,
                 auto: true,
                 reviewOverrides: {},
+                // BAPI-474: the Conductor epic-dispatch path stays git-fetch-free — it
+                // already dispatches into the correct worktree/branch context, so the
+                // fresh-base materialization (an interactive-CLI concern) is unneeded here.
+                noRefreshBase: true,
             });
             if (!result.ok) {
                 throw new Error(`review-tickets dispatch failed: ${result.error}`);
@@ -941,6 +1354,9 @@ export async function buildProductionEpicRuntimeDeps(epicKey) {
             // Product directive: the spec re-review is `/review-ticket --auto --rounds=2`.
             rounds: 2,
             reviewOverrides: {},
+            // BAPI-474: see the sibling dispatchSeam comment — Conductor dispatch stays
+            // git-fetch-free.
+            noRefreshBase: true,
         });
         if (!result.ok) {
             throw new Error(`spec re-review dispatch failed: ${result.error}`);
@@ -1009,7 +1425,6 @@ export async function buildProductionEpicRuntimeDeps(epicKey) {
             state: null,
             liveness: null,
             elapsed_ms: 0,
-            ambiguous: false,
             context: {},
         };
         // Attempt to extract a ticket key from structured reason strings like
@@ -1022,10 +1437,7 @@ export async function buildProductionEpicRuntimeDeps(epicKey) {
         const assessment = {
             classification: "stuck",
             confidence: 1,
-            should_escalate: true,
             reason,
-            draft_escalation_text: null,
-            source: "degraded",
         };
         const idempotencyKey = makeSupervisorIdempotencyKey({
             run_id: ek,