@bridge_gpt/mcp-server 0.2.6 → 0.2.10

package/build/conductor/done-gate.js

@@ -1,15 +1,16 @@
 /**
  * Pure done-gate config parsing, CI snapshot normalization, and deterministic
- * gate evaluation (BAPI-395).
+ * gate evaluation (BAPI-395, BAPI-440).
  *
- * v1 supports exactly one gate condition — `required_ci_checks_green` — and fails
- * CLOSED everywhere: unset, disabled, malformed, and unsupported config all yield
- * an inactive result that can never emit `gate.met`. A gate is met only when every
- * configured required check is present, complete, and green for the exact
+ * Supports a heterogeneous ANDed conditions list: one or more CI conditions
+ * (`required_ci_checks_green`) plus zero or more review-state conditions
+ * (`review_state`). Fails CLOSED everywhere: unset, disabled, malformed,
+ * unknown/duplicate condition types all yield an inactive result that can never
+ * emit `gate.met`. A gate is met only when ALL conditions are met for the exact
  * `repo + pr_number + head_sha` binding. This module is pure (no I/O) and never
  * throws for caller input.
  */
-import { DEFAULT_GATE_NAME, REQUIRED_CI_CHECKS_GREEN, normalizeCheckName, normalizeSha, stableJsonHash, } from "./git-ci-types.js";
+import { DEFAULT_GATE_NAME, REQUIRED_CI_CHECKS_GREEN, REVIEW_STATE, normalizeCheckName, normalizeSha, stableJsonHash, } from "./git-ci-types.js";
 // ---------------------------------------------------------------------------
 // Config parsing
 // ---------------------------------------------------------------------------
@@ -22,7 +23,7 @@ function inactiveConfig(reason) {
         enabled: false,
         valid: false,
         reason,
-        condition: null,
+        conditions: [],
         config_hash: null,
         gate_name: DEFAULT_GATE_NAME,
     };
@@ -62,21 +63,11 @@ function coerceConfigObject(value) {
     return { kind: "invalid" };
 }
 /**
- * Extract and validate the single v1 condition from a config object. Requires
- * `conditions` to be an array containing exactly one `required_ci_checks_green`
- * condition whose `required_checks` is a non-empty array of unique, valid,
- * normalized check names. Returns the normalized condition or `null`.
+ * Parse and validate a single `required_ci_checks_green` condition entry.
+ * Returns the normalized condition or `null` on any validation failure.
  */
-function parseSingleCondition(object) {
-    const conditions = object.conditions;
-    if (!Array.isArray(conditions) || conditions.length !== 1)
-        return null;
-    const condition = conditions[0];
-    if (!isPlainObject(condition))
-        return null;
-    if (condition.type !== REQUIRED_CI_CHECKS_GREEN)
-        return null;
-    const rawChecks = condition.required_checks;
+function parseCiChecksCondition(entry) {
+    const rawChecks = entry.required_checks;
     if (!Array.isArray(rawChecks) || rawChecks.length === 0)
         return null;
     const normalized = [];
@@ -84,19 +75,103 @@ function parseSingleCondition(object) {
     for (const raw of rawChecks) {
         const name = normalizeCheckName(raw);
         if (name === null)
-            return null; // invalid name invalidates the whole config
+            return null;
         if (seen.has(name))
-            return null; // duplicate after normalization
+            return null;
         seen.add(name);
         normalized.push(name);
     }
     return { type: REQUIRED_CI_CHECKS_GREEN, required_checks: normalized };
 }
+/** Valid review source values. */
+const VALID_REVIEW_SOURCES = new Set(["sticky_verdict", "native_review_decision", "min_approvals", "combination"]);
+/**
+ * Parse and validate a single `review_state` condition entry.
+ * Returns the normalized condition or `null` on any validation failure.
+ */
+function parseReviewStateCondition(entry) {
+    const source = entry.source;
+    if (typeof source !== "string" || !VALID_REVIEW_SOURCES.has(source))
+        return null;
+    const condition = { type: REVIEW_STATE, source: source };
+    if (entry.require_sticky_verdict !== undefined) {
+        if (typeof entry.require_sticky_verdict !== "boolean")
+            return null;
+        condition.require_sticky_verdict = entry.require_sticky_verdict;
+    }
+    if (entry.require_native_decision !== undefined) {
+        if (typeof entry.require_native_decision !== "boolean")
+            return null;
+        condition.require_native_decision = entry.require_native_decision;
+    }
+    if (entry.min_approvals !== undefined) {
+        if (typeof entry.min_approvals !== "number" || !Number.isInteger(entry.min_approvals) || entry.min_approvals < 0)
+            return null;
+        condition.min_approvals = entry.min_approvals;
+    }
+    if (entry.logic !== undefined) {
+        if (entry.logic !== "and")
+            return null;
+        condition.logic = "and";
+    }
+    // For combination source, at least one sub-source must be active; otherwise
+    // the condition would trivially pass with an empty failures array (fail-open).
+    if (condition.source === "combination") {
+        const hasSticky = condition.require_sticky_verdict === true;
+        const hasNative = condition.require_native_decision === true;
+        const hasMin = typeof condition.min_approvals === "number" && condition.min_approvals > 0;
+        if (!hasSticky && !hasNative && !hasMin)
+            return null;
+    }
+    return condition;
+}
+/**
+ * Parse the `conditions` array from a config object into a validated
+ * {@link GateCondition}[] list. Returns `null` if the array is missing, empty,
+ * contains any invalid/unknown/duplicate condition type, or any individual
+ * condition fails validation. Fail-closed.
+ */
+function parseConditions(object) {
+    const raw = object.conditions;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return null;
+    const seenTypes = new Set();
+    const parsed = [];
+    for (const entry of raw) {
+        if (!isPlainObject(entry))
+            return null;
+        const type = entry.type;
+        if (typeof type !== "string")
+            return null;
+        if (seenTypes.has(type))
+            return null; // duplicate type
+        if (type === REQUIRED_CI_CHECKS_GREEN) {
+            const condition = parseCiChecksCondition(entry);
+            if (condition === null)
+                return null;
+            seenTypes.add(type);
+            parsed.push(condition);
+        }
+        else if (type === REVIEW_STATE) {
+            const condition = parseReviewStateCondition(entry);
+            if (condition === null)
+                return null;
+            seenTypes.add(type);
+            parsed.push(condition);
+        }
+        else {
+            return null; // unknown condition type → fail closed
+        }
+    }
+    return parsed;
+}
 /**
  * Parse a raw `conductor_done_gate` value into a fail-closed
  * {@link NormalizedDoneGateConfig}. Active (`enabled && valid`) only when the
- * value is an enabled object with `enabled === true` (strict boolean) and exactly
- * one valid v1 condition. Every other shape is inactive with a safe reason.
+ * value is an enabled object with `enabled === true` (strict boolean) and at
+ * least one valid condition (CI and/or review). Every other shape is inactive
+ * with a safe reason. Fail-closed on any unknown, duplicate, or malformed
+ * condition type.
  */
 export function parseDoneGateConfig(value) {
     const coerced = coerceConfigObject(value);
@@ -111,21 +186,35 @@ export function parseDoneGateConfig(value) {
             return inactiveConfig("disabled");
         return inactiveConfig("invalid: 'enabled' must be the boolean true");
     }
-    const condition = parseSingleCondition(object);
-    if (condition === null) {
-        return inactiveConfig("invalid: expected exactly one valid required_ci_checks_green condition");
+    const conditions = parseConditions(object);
+    if (conditions === null) {
+        return inactiveConfig("invalid: conditions must be a non-empty array of valid, non-duplicate condition objects");
     }
     const gateName = DEFAULT_GATE_NAME;
     const configHash = stableJsonHash({
         gate_name: gateName,
-        type: condition.type,
-        required_checks: condition.required_checks,
+        conditions: conditions.map((c) => {
+            if (c.type === REQUIRED_CI_CHECKS_GREEN) {
+                return { type: c.type, required_checks: c.required_checks };
+            }
+            // review_state: include all non-undefined fields deterministically
+            const r = { type: c.type, source: c.source };
+            if (c.require_sticky_verdict !== undefined)
+                r.require_sticky_verdict = c.require_sticky_verdict;
+            if (c.require_native_decision !== undefined)
+                r.require_native_decision = c.require_native_decision;
+            if (c.min_approvals !== undefined)
+                r.min_approvals = c.min_approvals;
+            if (c.logic !== undefined)
+                r.logic = c.logic;
+            return r;
+        }),
     });
     return {
         enabled: true,
         valid: true,
         reason: "active",
-        condition,
+        conditions,
         config_hash: configHash,
         gate_name: gateName,
     };
@@ -214,8 +303,16 @@ function normalizeOneCheck(name, raw) {
 export function normalizeCiSnapshot(response) {
     const checks = [];
     const byName = new Map();
-    if (isPlainObject(response)) {
-        const rawChecks = response.checks;
+    // The raw `pollCiChecksForCommit` response is an envelope
+    // (`{ available, reason, action, detail: { checks, unknown_checks } }`), while
+    // unit tests and some callers pass an already-unwrapped object
+    // (`{ checks, unknown_checks }`). Prefer the unwrapped top-level fields and only
+    // fall back to `detail.*` when the top-level field is absent, so both shapes
+    // normalize identically and existing unwrapped-shape behavior is preserved.
+    const source = isPlainObject(response) ? response : undefined;
+    const detail = source && isPlainObject(source.detail) ? source.detail : undefined;
+    if (source) {
+        const rawChecks = source.checks ?? detail?.checks;
         if (Array.isArray(rawChecks)) {
             for (const entry of rawChecks) {
                 if (!isPlainObject(entry))
@@ -238,8 +335,9 @@ export function normalizeCiSnapshot(response) {
         }
     }
     const unknownChecks = [];
-    if (isPlainObject(response) && Array.isArray(response.unknown_checks)) {
-        for (const raw of response.unknown_checks) {
+    const rawUnknown = source ? source.unknown_checks ?? detail?.unknown_checks : undefined;
+    if (Array.isArray(rawUnknown)) {
+        for (const raw of rawUnknown) {
             const name = normalizeCheckName(raw);
             if (name !== null && !unknownChecks.includes(name))
                 unknownChecks.push(name);
@@ -264,46 +362,190 @@ export function normalizeCiSnapshot(response) {
     };
 }
 // ---------------------------------------------------------------------------
+// Review snapshot normalization
+// ---------------------------------------------------------------------------
+const REVIEW_VERDICT_APPROVED = "approved";
+const REVIEW_VERDICT_CHANGES_REQUESTED = "changes_requested";
+const REVIEW_VERDICT_UNKNOWN = "unknown";
+/**
+ * Normalize a raw backend review-status response into a {@link NormalizedReviewSnapshot}.
+ * Returns `null` when the envelope indicates unavailability (`available: false`) or
+ * is missing, so callers can fail-closed without emitting false-negative events.
+ */
+export function normalizeReviewSnapshot(raw) {
+    if (!isPlainObject(raw))
+        return null;
+    if (raw.available === false)
+        return null;
+    const detail = isPlainObject(raw.detail) ? raw.detail : null;
+    if (detail === null)
+        return null;
+    const reviewDecision = typeof detail.review_decision === "string" && detail.review_decision.length > 0
+        ? detail.review_decision
+        : null;
+    const approvals = typeof detail.approvals === "number" && Number.isInteger(detail.approvals) && detail.approvals >= 0
+        ? detail.approvals
+        : 0;
+    const rawVerdict = detail.sticky_verdict;
+    let stickyVerdict;
+    if (rawVerdict === REVIEW_VERDICT_APPROVED) {
+        stickyVerdict = "approved";
+    }
+    else if (rawVerdict === REVIEW_VERDICT_CHANGES_REQUESTED) {
+        stickyVerdict = "changes_requested";
+    }
+    else if (rawVerdict === REVIEW_VERDICT_UNKNOWN) {
+        stickyVerdict = "unknown";
+    }
+    else {
+        stickyVerdict = null;
+    }
+    const headSha = typeof detail.head_sha === "string" && detail.head_sha.trim().length > 0
+        ? detail.head_sha.trim()
+        : null;
+    const reviewStateHash = stableJsonHash({
+        review_decision: reviewDecision,
+        approvals,
+        sticky_verdict: stickyVerdict,
+    });
+    return { review_decision: reviewDecision, approvals, sticky_verdict: stickyVerdict, head_sha: headSha, review_state_hash: reviewStateHash };
+}
+/**
+ * Deterministically evaluate a review-state condition against a normalized snapshot.
+ * Pure and fail-closed: a null snapshot or any unknown/missing source yields
+ * `passed: false` and `changesRequested: false` (never a false positive).
+ */
+export function evaluateReviewCondition(condition, snapshot) {
+    if (snapshot === null) {
+        return { passed: false, changesRequested: false, reason: "review snapshot unavailable" };
+    }
+    const source = condition.source;
+    if (source === "sticky_verdict") {
+        if (snapshot.sticky_verdict === "approved")
+            return { passed: true, changesRequested: false, reason: "sticky verdict approved" };
+        if (snapshot.sticky_verdict === "changes_requested")
+            return { passed: false, changesRequested: true, reason: "sticky verdict requests changes" };
+        return { passed: false, changesRequested: false, reason: `sticky verdict not approved: ${snapshot.sticky_verdict ?? "null"}` };
+    }
+    if (source === "native_review_decision") {
+        const dec = snapshot.review_decision?.toUpperCase();
+        if (dec === "APPROVED")
+            return { passed: true, changesRequested: false, reason: "native review decision approved" };
+        if (dec === "CHANGES_REQUESTED")
+            return { passed: false, changesRequested: true, reason: "native review decision requests changes" };
+        return { passed: false, changesRequested: false, reason: `native review decision not approved: ${snapshot.review_decision ?? "null"}` };
+    }
+    if (source === "min_approvals") {
+        const required = typeof condition.min_approvals === "number" ? condition.min_approvals : 1;
+        if (snapshot.approvals >= required)
+            return { passed: true, changesRequested: false, reason: `approvals ${snapshot.approvals} >= ${required}` };
+        return { passed: false, changesRequested: false, reason: `approvals ${snapshot.approvals} < ${required}` };
+    }
+    if (source === "combination") {
+        // All enabled sub-sources must pass (AND logic).
+        const requireSticky = condition.require_sticky_verdict === true;
+        const requireNative = condition.require_native_decision === true;
+        const minApprovals = typeof condition.min_approvals === "number" ? condition.min_approvals : 0;
+        const failures = [];
+        let changesRequested = false;
+        if (requireSticky) {
+            if (snapshot.sticky_verdict === "changes_requested")
+                changesRequested = true;
+            if (snapshot.sticky_verdict !== "approved")
+                failures.push(`sticky verdict not approved: ${snapshot.sticky_verdict ?? "null"}`);
+        }
+        if (requireNative) {
+            const dec = snapshot.review_decision?.toUpperCase();
+            if (dec === "CHANGES_REQUESTED")
+                changesRequested = true;
+            if (dec !== "APPROVED")
+                failures.push(`native decision not approved: ${snapshot.review_decision ?? "null"}`);
+        }
+        if (minApprovals > 0 && snapshot.approvals < minApprovals) {
+            failures.push(`approvals ${snapshot.approvals} < ${minApprovals}`);
+        }
+        if (failures.length > 0)
+            return { passed: false, changesRequested, reason: failures.join("; ") };
+        return { passed: true, changesRequested: false, reason: "all combination sources satisfied" };
+    }
+    return { passed: false, changesRequested: false, reason: `unknown review source: ${source}` };
+}
+// ---------------------------------------------------------------------------
 // Gate evaluation
 // ---------------------------------------------------------------------------
 function failedEvaluation(reason) {
     return { met: false, reason };
 }
 /**
- * Deterministically evaluate a done gate for one binding. Returns `met: true` with
- * canonical `gate.met` event data (allowlisted top-level keys only) when every
- * configured required check is present, complete, and green; otherwise `met:
- * false` with a fail-closed reason and no event data. Pure and deterministic:
- * identical inputs always produce deep-equal output.
+ * Deterministically evaluate a done gate for one binding against both a CI
+ * snapshot and an optional review snapshot. Returns `met: true` with canonical
+ * `gate.met` event data (allowlisted top-level keys only) only when ALL configured
+ * conditions are met; otherwise `met: false` with a fail-closed reason. Pure and
+ * deterministic: identical inputs always produce deep-equal output. Never throws.
  */
-export function evaluateDoneGate(config, binding, snapshot, evaluatedAtIso) {
-    if (!config.enabled || !config.valid || config.condition === null) {
+export function evaluateDoneGate(config, binding, snapshot, evaluatedAtIso, reviewSnapshot = null) {
+    if (!config.enabled || !config.valid || config.conditions.length === 0) {
         return failedEvaluation(`gate inactive: ${config.reason}`);
     }
     const headSha = normalizeSha(binding.head_sha);
     if (headSha === null) {
         return failedEvaluation("invalid binding: head_sha is not a valid SHA");
     }
+    // Per-condition evaluation accumulators
+    const allFailureReasons = [];
+    // CI check status (for the structured details payload)
+    let checkResults = [];
+    let ciConditionType;
+    let requiredChecks;
+    // Review condition result (for the structured details payload)
+    let reviewResult;
     const byName = new Map();
     for (const check of snapshot.checks)
         byName.set(check.name, check);
     const unknownSet = new Set(snapshot.unknown_checks);
-    const checkResults = [];
-    const unmet = [];
-    for (const name of config.condition.required_checks) {
-        const check = byName.get(name);
-        if (!check) {
-            checkResults.push({ name, present: false, complete: false, green: false });
-            unmet.push(unknownSet.has(name) ? `${name} (unknown)` : `${name} (missing)`);
-            continue;
+    for (const condition of config.conditions) {
+        if (condition.type === REQUIRED_CI_CHECKS_GREEN) {
+            ciConditionType = condition.type;
+            requiredChecks = [...condition.required_checks];
+            checkResults = [];
+            const unmet = [];
+            for (const name of condition.required_checks) {
+                const check = byName.get(name);
+                if (!check) {
+                    checkResults.push({ name, present: false, complete: false, green: false });
+                    unmet.push(unknownSet.has(name) ? `${name} (unknown)` : `${name} (missing)`);
+                    continue;
+                }
+                checkResults.push({ name, present: true, complete: check.complete, green: check.green });
+                if (!check.green) {
+                    unmet.push(check.complete ? `${name} (not green)` : `${name} (pending)`);
+                }
+            }
+            if (unmet.length > 0) {
+                allFailureReasons.push(`required checks not green: ${unmet.join(", ")}`);
+            }
         }
-        checkResults.push({ name, present: true, complete: check.complete, green: check.green });
-        if (!check.green) {
-            unmet.push(check.complete ? `${name} (not green)` : `${name} (pending)`);
+        else if (condition.type === REVIEW_STATE) {
+            reviewResult = evaluateReviewCondition(condition, reviewSnapshot);
+            if (!reviewResult.passed) {
+                allFailureReasons.push(`review condition not met: ${reviewResult.reason}`);
+            }
         }
     }
-    if (unmet.length > 0) {
-        return failedEvaluation(`required checks not green: ${unmet.join(", ")}`);
+    if (allFailureReasons.length > 0) {
+        return failedEvaluation(allFailureReasons.join("; "));
+    }
+    // Build structured per-condition details for telemetry
+    const ciCheckStatus = {};
+    if (ciConditionType !== undefined) {
+        ciCheckStatus.condition_type = ciConditionType;
+        ciCheckStatus.required_checks = requiredChecks;
+        ciCheckStatus.check_results = checkResults;
+    }
+    const reviewStatus = {};
+    if (reviewResult !== undefined) {
+        reviewStatus.passed = reviewResult.passed;
+        reviewStatus.reason = reviewResult.reason;
     }
     const details = {
         repo: binding.repo,
@@ -311,11 +553,12 @@ export function evaluateDoneGate(config, binding, snapshot, evaluatedAtIso) {
         head_sha: headSha,
         gate_name: config.gate_name,
         config_hash: config.config_hash,
-        condition_type: config.condition.type,
-        required_checks: [...config.condition.required_checks],
-        check_results: checkResults,
         evaluated_at: evaluatedAtIso,
+        ci_check_status: ciCheckStatus,
     };
+    if (reviewResult !== undefined) {
+        details.review_status = reviewStatus;
+    }
     const gateEventData = {
         summary: `Done gate "${config.gate_name}" met for ${binding.subject}`,
         status: "met",

package/build/conductor/epic-reconcile.js

@@ -1,6 +1,6 @@
 /**
  * Deterministic observed→desired reconciliation for the Epic Supervisor
- * (BAPI-408).
+ * (BAPI-408, BAPI-436).
  *
  * Executes five steps in order:
  *   1. Fold terminal signals into Postgres via CAS
@@ -9,10 +9,15 @@
  *   4. Action approved merges via C6 delegation
  *   5. Schedule post-action wait hooks
  *
+ * Dispatch is purely merge-gated (BAPI-436): dependents are dispatched only
+ * after their predecessor reaches "done", which requires a merge.succeeded
+ * signal. gate.met and run.stopped fold to the intermediate "ready_for_review"
+ * state — dependents do NOT dispatch on these signals.
+ *
  * All durable mutations go through injected seams so the logic is testable
  * without real network, ledger, or terminal access.
  */
-import { computeReadySet } from "./epic-state.js";
+import { computeReadySet, decideRemediation } from "./epic-state.js";
 import { extractMergeActionIdentityFromGateEvent } from "./merge-ledger.js";
 // ---------------------------------------------------------------------------
 // reconcileEpic
@@ -21,7 +26,7 @@ import { extractMergeActionIdentityFromGateEvent } from "./merge-ledger.js";
  * Execute the deterministic observed→desired reconciliation pass. All I/O is
  * behind injected seams; the ready-set is computed by pure code (no LLM).
  */
-export async function reconcileEpic(access, observed, plan, deps) {
+export async function reconcileEpic(access, observed, plan, deps, supervisorConfig) {
     const result = {
         signals_folded: 0,
         dispatched: 0,
@@ -43,6 +48,22 @@ export async function reconcileEpic(access, observed, plan, deps) {
         if (casResult.ok) {
             result.signals_folded += 1;
             deps.log(`[epic-reconcile] folded ${signal.signal_type} for ${signal.ticket_key} → ${signal.next_status}`);
+            // BAPI-442: fire teardown + Jira transition strictly after merge.succeeded
+            // CAS → done. Both are fail-open: errors are logged and never abort the pass.
+            if (signal.signal_type === "merge.succeeded") {
+                if (supervisorConfig?.teardown_enabled && deps.teardownSeam) {
+                    await deps.teardownSeam(observed.epic_key, signal.ticket_key).catch((e) => {
+                        const safeMsg = e instanceof Error ? e.constructor.name : "teardown error";
+                        deps.log(`[epic-reconcile] teardown error for ${signal.ticket_key}: ${safeMsg}`);
+                    });
+                }
+                if (deps.jiraTransitionSeam) {
+                    await deps.jiraTransitionSeam(observed.epic_key, signal.ticket_key).catch((e) => {
+                        const safeMsg = e instanceof Error ? e.constructor.name : "jira error";
+                        deps.log(`[epic-reconcile] jira-transition error for ${signal.ticket_key}: ${safeMsg}`);
+                    });
+                }
+            }
         }
         else {
             // CAS conflict: another tick already advanced this ticket — non-fatal
@@ -61,8 +82,24 @@ export async function reconcileEpic(access, observed, plan, deps) {
     }
     // Step 2: Compute the ready-set (pure — never calls LLM)
     const readySet = computeReadySet(plan, observed.ticket_statuses);
-    // Step 3: Dispatch each ready ticket idempotently
+    // Step 3: Dispatch each ready ticket idempotently.
+    //
+    // NOTE (BAPI-442): an earlier draft performed a synchronous two-phase
+    // planned → ready_for_review → ready spec re-review here — it spawned
+    // /review-ticket and then dispatched implementation in the SAME tick. That did
+    // not actually gate implementation on the review (the verdict was never
+    // consulted and the review run_id was discarded), and it overloaded the
+    // BAPI-436 "ready_for_review" (awaiting-merge) state, leaving a liveness gap
+    // if the conductor crashed between the CAS and the dispatch. That path has
+    // been removed. `auto_rereview_enabled` is reserved until real review-gating —
+    // a distinct `reviewing` status, review-run correlation, multi-tick re-entry,
+    // and a spec-review verdict signal — is built (BAPI-445). Until then a ready
+    // ticket dispatches implementation directly regardless of the flag.
     for (const ticketKey of readySet) {
+        if (supervisorConfig?.auto_rereview_enabled) {
+            deps.log(`[epic-reconcile] auto_rereview_enabled is set but review-gating is not yet ` +
+                `implemented (BAPI-445); dispatching ${ticketKey} directly`);
+        }
         let claimResult;
         try {
             claimResult = await deps.claimDispatchKey(observed.epic_key, ticketKey, observed.plan_version);
@@ -118,6 +155,86 @@ export async function reconcileEpic(access, observed, plan, deps) {
             result.warnings.push(`correlate-failed for ${ticketKey}: ${safeMsg}`);
         }
     }
+    // Step 3.5: Remediation pass (BAPI-441) — re-act on blocked tickets under
+    // budget. Keyed off the folded "blocked" status + per-ticket counters, NOT a
+    // computeReadySet change (the ready-set still returns only planned tickets).
+    // Skipped entirely unless the remediation seams + supervisorConfig are wired.
+    const remediationWired = supervisorConfig !== undefined &&
+        deps.readWorkerLiveness !== undefined &&
+        deps.remediateCas !== undefined &&
+        deps.sendNudge !== undefined &&
+        deps.resumeDispatch !== undefined;
+    if (remediationWired) {
+        const cfg = supervisorConfig;
+        const readWorkerLiveness = deps.readWorkerLiveness;
+        const sendNudge = deps.sendNudge;
+        const resumeDispatch = deps.resumeDispatch;
+        const remediateCas = deps.remediateCas;
+        for (const [ticketKey, status] of observed.ticket_statuses) {
+            if (status !== "blocked")
+                continue;
+            // Per-ticket try/catch so a single ticket's failure never aborts the pass.
+            try {
+                const counters = observed.ticket_remediation_counters?.get(ticketKey) ?? {
+                    attempts: 0,
+                    no_progress: 0,
+                };
+                const liveness = await readWorkerLiveness(observed.epic_key, ticketKey);
+                const decision = decideRemediation(counters.attempts, counters.no_progress, liveness.alive, cfg);
+                if (decision === "escalate") {
+                    await escalate(observed.epic_key, `remediation-budget-exhausted:${ticketKey}`);
+                    deps.log(`[epic-reconcile] remediation escalate ${ticketKey} ` +
+                        `(attempts=${counters.attempts} no_progress=${counters.no_progress})`);
+                    continue;
+                }
+                // The attempt being recorded is the next one (1-based).
+                const attempt = counters.attempts + 1;
+                const attemptKind = decision;
+                // The folding reason frames the nudge (message type + digest). Default to
+                // the review path when the ledger no longer carries the blocking event.
+                const reason = observed.ticket_blocked_reasons?.get(ticketKey) ?? "review.changes_requested";
+                // A nudge needs a worker to address it to. The liveness scan already
+                // resolved the worker id from the same heartbeat that proved the worker
+                // alive; if it is missing we cannot relay, so skip BEFORE recording an
+                // attempt — otherwise the CAS would burn a budget unit with nothing sent.
+                if (decision === "nudge" && !liveness.workerId) {
+                    result.warnings.push(`remediation nudge skipped for ${ticketKey}: alive worker has no worker_id`);
+                    continue;
+                }
+                // Record the attempt durably FIRST. The remediate endpoint builds the
+                // (backend-redacted) review digest for a nudge and returns it, and is
+                // idempotent (a 409 replay returns conflict, not throw). An unexpected
+                // remediate failure is absorbed as a per-ticket warning so the rest of
+                // the pass still runs (crash-replay safe).
+                let casOutcome;
+                try {
+                    casOutcome = await remediateCas(observed.epic_key, ticketKey, attemptKind, reason);
+                }
+                catch (err) {
+                    const safeMsg = err instanceof Error ? err.constructor.name : "remediate error";
+                    result.warnings.push(`remediate-cas-failed for ${ticketKey} (${attemptKind}): ${safeMsg}`);
+                    continue;
+                }
+                if (casOutcome.conflict) {
+                    // Idempotency replay: the attempt was already recorded (and acted on)
+                    // on a prior tick. Do not re-act — the crash-replay self-heals here.
+                    result.warnings.push(`remediation replay swallowed for ${ticketKey} (${attemptKind})`);
+                    continue;
+                }
+                if (decision === "nudge") {
+                    await sendNudge(observed.epic_key, ticketKey, attempt, casOutcome.reviewDigest, casOutcome.truncated, reason, liveness.workerId);
+                }
+                else {
+                    await resumeDispatch(observed.epic_key, ticketKey, attempt);
+                }
+                deps.log(`[epic-reconcile] remediation ${decision} ${ticketKey} attempt=${attempt}`);
+            }
+            catch (err) {
+                const safeMsg = err instanceof Error ? err.constructor.name : "remediation error";
+                result.warnings.push(`remediation-error for ${ticketKey}: ${safeMsg}`);
+            }
+        }
+    }
     // Step 4: Action approved merges via C6 delegation
     for (const event of observed.pending_merge_events) {
         const identity = extractMergeActionIdentityFromGateEvent(event);