@bridge_gpt/mcp-server 0.2.19 → 0.2.21

package/build/conductor/local-merge.js

@@ -9,47 +9,149 @@
  *
  * It mirrors the backend merge guard's decision order — approval precondition →
  * re-read PR head (drift / not-open guard) → revalidate required CI for the EXACT
- * head SHA → provider merge — and returns the SAME `merge.*` ledger events the
- * backend route returns, so the rest of {@link processGateMetMerge} is unchanged.
+ * expected head SHA, waiting briefly for transient post-remediation CI to turn
+ * green (BAPI-566 Bug B) → re-read PR head once more (close the CI-wait race) →
+ * provider merge — and returns the SAME `merge.*` ledger events the backend route
+ * returns, so the rest of {@link processGateMetMerge} is unchanged. `ci_not_green`
+ * is a bounded, pre-provider-merge failure and is NEVER a merge conflict; merge
+ * conflicts are still detected only after a `gh pr merge` attempt fails.
+ *
+ * BAPI-572 hardening:
+ *  - The default command runner is now ASYNC (`spawn`-based, replacing the old
+ *    synchronous runner) and abort-aware, so a slow/hung `gh` never blocks the
+ *    Node event loop — this lets the executor keep heartbeating while a local
+ *    merge is in flight.
+ *  - "Already merged at the expected head" is treated as SUCCESS on ANY read
+ *    (initial, post-CI, and after an ambiguous `gh` failure), not `pr_not_open`.
+ *  - Every AMBIGUOUS `gh` failure (view/merge timeout, view failure/unparseable,
+ *    CI poll failure, generic non-conflict merge failure) re-checks the merged
+ *    state before reporting failure, so a successful-but-slow merge that GitHub
+ *    already accepted is never lost as a false failure.
  *
  * Subprocess safety: argument arrays (never a shell string), a validated numeric
  * PR number, a merge method from a fixed allowlist, `GH_PROMPT_DISABLED` to avoid
  * interactive hangs, and no token/secret ever logged. Default OFF everywhere.
  */
-import { spawnSync } from "child_process";
-import { pollCiChecksForCommit, } from "./bridge-api-client.js";
+import { spawn } from "child_process";
+import { pollCiChecksForCommit, ConductorBridgeApiError, safeDiagnosticMessage, } from "./bridge-api-client.js";
 import { isLikelyGhMergeConflictOutput, isPrMergeConflict, parseGhPrMergeabilityFields, } from "./github-mergeability.js";
 const MERGE_METHODS = new Set(["squash", "merge", "rebase"]);
+/**
+ * `gh pr view` field set for a merged-state / head-drift read. Includes
+ * `mergeCommit` so an already-merged PR can be detected (and its merge commit
+ * SHA recorded) directly from the same read that guards head drift.
+ */
+const PR_STATE_JSON = "headRefOid,state,mergeCommit";
+/**
+ * Broader `gh pr view` field set used only for the post-merge-failure re-read:
+ * it must detect BOTH "already merged at the expected head" and a merge conflict
+ * (`mergeable` / `mergeStateStatus`) from a single read.
+ */
+const PR_STATE_MERGEABILITY_JSON = "headRefOid,state,mergeCommit,mergeable,mergeStateStatus";
 /**
  * Hard wall-clock cap on every `gh` subprocess. The epic-tick runs in a single
- * stateless process with no separate scheduler thread — a `gh` call that hangs
- * (network stall, an auth prompt that slips past GH_PROMPT_DISABLED) would block
- * the Node event loop indefinitely, freezing the whole tick. Killing at 60s
- * yields a `timedOut` result the executor maps to a distinct `*_timeout` reason.
+ * stateless process — a `gh` call that hangs (network stall, an auth prompt that
+ * slips past GH_PROMPT_DISABLED) must not wedge the tick. The async runner kills
+ * the child at 60s and returns a `timedOut` result the executor maps to a
+ * distinct `*_timeout` reason (and then re-checks the merged state, since a
+ * killed `gh pr merge` may still have landed at GitHub).
  */
 const DEFAULT_COMMAND_TIMEOUT_MS = 60_000;
+/**
+ * Bounded wait for the exact expected head's required CI to turn green before a
+ * provider merge (BAPI-566 Bug B). A code_review remediation that pushes a new
+ * head can advance to `merging` on the same tick its CI is still running; without
+ * this wait the very first merge attempt races that CI and fails `ci_not_green`,
+ * stalling the run until the 45-min watchdog. The wait is a total wall-clock cap
+ * across polls; `ci_not_green` is only returned once it expires. Kept short so a
+ * genuinely red head fails fast rather than tying up the tick.
+ */
+const DEFAULT_CI_WAIT_TIMEOUT_MS = 180_000;
+const DEFAULT_CI_WAIT_POLL_INTERVAL_MS = 5_000;
+/** Real-timer sleep; overridable via the `sleep` dep for deterministic tests. */
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Coerce an untrusted wait option to a bounded non-negative integer of ms. */
+function sanitizeWaitMs(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? Math.floor(value)
+        : fallback;
+}
 /** Coerce an untrusted method value to a safe allowlisted method (default squash). */
 export function resolveLocalMergeMethod(value) {
     return typeof value === "string" && MERGE_METHODS.has(value)
         ? value
         : "squash";
 }
-function defaultRunCommand(cmd, args, env) {
-    const result = spawnSync(cmd, args, {
-        encoding: "utf8",
-        env: { ...process.env, ...env },
-        timeout: DEFAULT_COMMAND_TIMEOUT_MS,
+/**
+ * Async, abort-aware default command runner. Uses `spawn` (never a synchronous
+ * runner) so a slow/hung `gh` does not block the Node event loop — the heartbeat
+ * loop keeps running while a local merge is in flight. Enforces the per-command
+ * wall-clock timeout by killing the child (`timedOut: true`) and also kills the
+ * child when the injected abort signal fires. Never builds a shell string and
+ * never logs raw stdout/stderr.
+ */
+async function defaultRunCommand(cmd, args, env, signal) {
+    return await new Promise((resolve) => {
+        let settled = false;
+        let timedOut = false;
+        let stdout = "";
+        let stderr = "";
+        const child = spawn(cmd, args, { env: { ...process.env, ...env } });
+        const killChild = () => {
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                /* the process may already be gone */
+            }
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killChild();
+        }, DEFAULT_COMMAND_TIMEOUT_MS);
+        const onAbort = () => {
+            timedOut = true;
+            killChild();
+        };
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (signal)
+                signal.removeEventListener("abort", onAbort);
+            resolve(result);
+        };
+        if (signal) {
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener("abort", onAbort);
+        }
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", () => {
+            // Spawn/exec error (e.g. `gh` not found): surface as a non-zero, non-timeout
+            // failure so the executor's ambiguous-failure verification still runs.
+            finish({ status: null, stdout, stderr, timedOut });
+        });
+        child.on("close", (code, sig) => {
+            finish({
+                status: code,
+                stdout,
+                stderr,
+                timedOut: timedOut || sig === "SIGKILL" || sig === "SIGTERM",
+            });
+        });
     });
-    // On timeout spawnSync kills the child (status: null, signal: "SIGTERM") and
-    // sets `error.code === "ETIMEDOUT"`. Surface that as a first-class flag.
-    const timedOut = result.error?.code === "ETIMEDOUT" ||
-        result.signal === "SIGTERM";
-    return {
-        status: result.status,
-        stdout: result.stdout ?? "",
-        stderr: result.stderr ?? "",
-        timedOut,
-    };
 }
 function buildResponse(request, status, reason, terminal, ledgerEvents) {
     return {
@@ -105,6 +207,171 @@ export function allRequiredChecksGreen(pollResponse, requiredChecks) {
     };
     return requiredChecks.every((name) => isGreen(byName.get(name)));
 }
+/** Extract `mergeCommit.oid` from a parsed `gh pr view` object when present. */
+function extractMergeCommitOid(parsed) {
+    const mc = parsed?.mergeCommit;
+    if (mc && typeof mc === "object" && typeof mc.oid === "string") {
+        return mc.oid;
+    }
+    return undefined;
+}
+/**
+ * True only when the PR is MERGED (case-insensitive) at the EXACT expected head
+ * SHA (case-insensitive). This is the "already merged at expected head" signal
+ * that must be reported as SUCCESS on any attempt, never `pr_not_open`.
+ */
+function isMergedAtExpectedHead(state, headOid, expectedSha) {
+    return (typeof state === "string" &&
+        state.toUpperCase() === "MERGED" &&
+        typeof headOid === "string" &&
+        headOid.toLowerCase() === expectedSha.toLowerCase());
+}
+/**
+ * Read the PR's `headRefOid` + `state` + `mergeCommit` via `gh pr view`. Extracted
+ * so the head-drift / not-open / already-merged guard can run BOTH before the CI
+ * wait and again right before provider merge (BAPI-566 Bug B: the head can drift
+ * while we wait for CI). Returns the raw parsed values; the caller applies the
+ * MERGED-at-head / OPEN / exact-head checks.
+ */
+async function readPrMergeState(run, ghEnv, pr, json = PR_STATE_JSON) {
+    const view = await run("gh", ["pr", "view", String(pr), "--json", json], ghEnv);
+    if (view.timedOut)
+        return { ok: false, reason: "gh_pr_view_timeout" };
+    if (view.status !== 0)
+        return { ok: false, reason: "gh_pr_view_failed" };
+    try {
+        const parsed = JSON.parse(view.stdout);
+        return {
+            ok: true,
+            headOid: parsed.headRefOid,
+            state: parsed.state,
+            mergeCommitOid: extractMergeCommitOid(parsed),
+            raw: parsed,
+        };
+    }
+    catch {
+        return { ok: false, reason: "gh_pr_view_unparseable" };
+    }
+}
+/**
+ * Build the SUCCESS response for a PR that is already merged at the expected
+ * head — used by the initial read short-circuit, the post-CI read short-circuit,
+ * and the post-ambiguous-failure verification. Emits a single `merge.succeeded`
+ * ledger event carrying `already_merged: true` and, when known, the merge commit
+ * SHA (so `buildMergeJobResult` populates `commit_sha`/`head_sha`).
+ */
+function buildAlreadyMergedResponse(request, baseDetails, mergeCommitSha) {
+    const details = {
+        ...baseDetails,
+        already_merged: true,
+        ...(mergeCommitSha ? { merge_commit_sha: mergeCommitSha } : {}),
+    };
+    return buildResponse(request, "succeeded", null, true, [
+        { type: "merge.succeeded", status: "succeeded", details },
+    ]);
+}
+/**
+ * Extract secret-free poll-failure detail from a thrown error. Returns `undefined`
+ * for anything that is not a {@link ConductorBridgeApiError} with a poll-relevant
+ * `kind` (so unknown/non-bridge throws keep the legacy `ci_poll_failed` routing and
+ * never persist raw exception text). The `diagnostic` is bounded and redacted via the
+ * established {@link safeDiagnosticMessage} helper.
+ */
+function ciPollFailureDetailFromError(err) {
+    if (!(err instanceof ConductorBridgeApiError))
+        return undefined;
+    const kind = err.kind;
+    if (kind !== "timeout" &&
+        kind !== "network" &&
+        kind !== "unauthorized" &&
+        kind !== "server" &&
+        kind !== "http") {
+        return undefined;
+    }
+    const detail = {
+        kind,
+        diagnostic: safeDiagnosticMessage(err, "ci_poll_failed"),
+    };
+    if (typeof err.status === "number" && Number.isInteger(err.status)) {
+        detail.status = err.status;
+    }
+    return detail;
+}
+/**
+ * Map preserved poll-failure detail to a stable, distinct merge failure reason.
+ * Missing/unknown detail collapses to the legacy `ci_poll_failed`; an `http` kind
+ * with a usable integer status yields `ci_poll_http_<status>`, otherwise `ci_poll_http`.
+ */
+function ciPollFailureReasonFromDetail(detail) {
+    if (!detail)
+        return "ci_poll_failed";
+    switch (detail.kind) {
+        case "timeout":
+            return "ci_poll_timeout";
+        case "network":
+            return "ci_poll_network";
+        case "unauthorized":
+            return "ci_poll_unauthorized";
+        case "server":
+            return "ci_poll_server";
+        case "http":
+            return typeof detail.status === "number" && Number.isInteger(detail.status)
+                ? `ci_poll_http_${detail.status}`
+                : "ci_poll_http";
+    }
+}
+/**
+ * A CI-wait failure reason is an AMBIGUOUS poll read (a merge GitHub may already
+ * have accepted, masked by a flaky poll) when it shares the `ci_poll_` prefix —
+ * including the legacy `ci_poll_failed`. Such reasons must re-verify merged state
+ * before reporting failure. `ci_not_green` and `merge_aborted` are deterministic
+ * and never re-verify.
+ */
+function isAmbiguousCiPollFailureReason(reason) {
+    return reason.startsWith("ci_poll_");
+}
+/**
+ * Poll required CI for the EXACT expected head, immediately and then on an
+ * interval, until every required check is green or the total wall-clock budget
+ * expires (BAPI-566 Bug B). If a poll throws, returns a distinct `ci_poll_*` reason
+ * derived from the thrown {@link ConductorBridgeApiError} kind/status (BAPI-577 Part A;
+ * legacy/unknown throws still yield `ci_poll_failed`), preserving the secret-free
+ * detail on the result. `ci_not_green` is returned only after the budget is exhausted.
+ * Never polls the branch name or PR head alias — only `expectedSha`.
+ *
+ * BAPI-572 abort-awareness: the CI-wait loop is the longest-running,
+ * non-`gh`-subprocess phase of a merge. It must short-circuit with `merge_aborted`
+ * as soon as the injected abort signal fires — otherwise a merge job the executor
+ * already reported timed-out/abandoned could keep polling for its full
+ * `ciWaitTimeoutMs` budget and then fire a REAL `gh pr merge` minutes later.
+ */
+async function waitForRequiredChecksGreen(pollCi, access, expectedSha, requiredChecks, timeoutMs, pollIntervalMs, sleep, now, signal) {
+    const start = now();
+    for (;;) {
+        if (signal?.aborted)
+            return { ok: false, reason: "merge_aborted" };
+        let pollResponse;
+        try {
+            pollResponse = await pollCi(access, expectedSha);
+        }
+        catch (err) {
+            // Preserve the caught bridge poll error's coarse kind/status instead of
+            // flattening every failure to an opaque `ci_poll_failed` (BAPI-577 Part A).
+            // Unknown/non-bridge throws yield `undefined` detail → legacy `ci_poll_failed`.
+            const pollFailure = ciPollFailureDetailFromError(err);
+            return { ok: false, reason: ciPollFailureReasonFromDetail(pollFailure), pollFailure };
+        }
+        if (allRequiredChecksGreen(pollResponse, requiredChecks))
+            return { ok: true };
+        if (now() - start >= timeoutMs)
+            return { ok: false, reason: "ci_not_green" };
+        await sleep(pollIntervalMs);
+        // Re-check after the sleep so an abort during the interval stops the loop
+        // before the next poll (and, critically, before any provider merge).
+        if (signal?.aborted)
+            return { ok: false, reason: "merge_aborted" };
+    }
+}
 /**
  * Build a `(access, request) => Promise<ConductorMergeResponse>` that performs the
  * merge locally via `gh`. Drop-in replacement for `mergePullRequestForGate` used
@@ -112,8 +379,19 @@ export function allRequiredChecksGreen(pollResponse, requiredChecks) {
  */
 export function makeLocalMergeExecutor(options = {}, deps = {}) {
     const method = resolveLocalMergeMethod(options.method);
-    const run = deps.runCommand ?? defaultRunCommand;
+    const rawRun = deps.runCommand ?? defaultRunCommand;
+    // Always await the runner: the production default is async (a hung `gh` would
+    // otherwise block the event loop and starve the executor heartbeat), and
+    // injected synchronous test runners are still awaited transparently. The abort
+    // signal is threaded to the default runner so an overall merge timeout can
+    // cancel in-flight subprocess work.
+    const run = (cmd, args, env) => Promise.resolve(rawRun(cmd, args, env, deps.signal));
     const pollCi = deps.pollCi ?? pollCiChecksForCommit;
+    const sleep = deps.sleep ?? defaultSleep;
+    const now = deps.now ?? (() => Date.now());
+    const signal = deps.signal;
+    const ciWaitTimeoutMs = sanitizeWaitMs(options.ciWaitTimeoutMs, DEFAULT_CI_WAIT_TIMEOUT_MS);
+    const ciWaitPollIntervalMs = sanitizeWaitMs(options.ciWaitPollIntervalMs, DEFAULT_CI_WAIT_POLL_INTERVAL_MS);
     // Non-interactive + no-noise env for gh; the caller's env (incl. any token)
     // is overlaid first, then the safety pins.
     const ghEnv = {
@@ -133,9 +411,47 @@ export function makeLocalMergeExecutor(options = {}, deps = {}) {
             merge_method: method,
             executor: "local",
         };
-        const fail = (reason) => buildResponse(request, "failed", reason, false, [
-            { type: "merge.failed", status: "failed", reason, details: baseDetails },
-        ]);
+        const fail = (reason, pollFailure) => {
+            // Attach the secret-free poll-error detail (kind/status/bounded diagnostic)
+            // to the persisted failure so the executor_jobs row is diagnosable without
+            // reproducing. Never includes raw body/headers/key (see CiPollFailureDetail).
+            const details = pollFailure
+                ? {
+                    ...baseDetails,
+                    poll_error: {
+                        kind: pollFailure.kind,
+                        ...(typeof pollFailure.status === "number" ? { status: pollFailure.status } : {}),
+                        diagnostic: pollFailure.diagnostic,
+                    },
+                }
+                : baseDetails;
+            return buildResponse(request, "failed", reason, false, [
+                { type: "merge.failed", status: "failed", reason, details },
+            ]);
+        };
+        /**
+         * Re-check the merged state after an AMBIGUOUS `gh` failure (a `gh` timeout,
+         * an unparseable/failed view, a CI poll failure, or a generic non-conflict
+         * merge failure). Performs ONE fresh `gh pr view` and returns the already-
+         * merged SUCCESS response when GitHub shows the PR merged at the expected
+         * head; returns `null` when the read fails, is unparseable, is not merged, or
+         * is merged at a different head (so the caller keeps the original failure).
+         */
+        const verifyMergedStateAfterAmbiguousFailure = async () => {
+            const read = await readPrMergeState(run, ghEnv, pr);
+            if (!read.ok)
+                return null;
+            if (isMergedAtExpectedHead(read.state, read.headOid, expectedSha)) {
+                return buildAlreadyMergedResponse(request, baseDetails, read.mergeCommitOid);
+            }
+            return null;
+        };
+        // 0. Abort precondition — if the overall merge timeout / ownership abandonment
+        //    already fired before this flow reached a decision point, do NOT take any
+        //    effectful action (never fire a provider merge for a job the executor has
+        //    already reported failed/abandoned). `merge_aborted` is a bounded retryable.
+        if (signal?.aborted)
+            return fail("merge_aborted");
         // 1. Approval precondition — never merge when approval is required.
         if (options.approvalRequired) {
             return buildResponse(request, "pending_approval", "local_merge_approval_required", false, [
@@ -147,84 +463,115 @@ export function makeLocalMergeExecutor(options = {}, deps = {}) {
                 },
             ]);
         }
-        // 2. Re-read PR head + open-state (head-drift / closed guard).
-        const view = run("gh", ["pr", "view", String(pr), "--json", "headRefOid,state"], ghEnv);
-        if (view.timedOut)
-            return fail("gh_pr_view_timeout");
-        if (view.status !== 0)
-            return fail("gh_pr_view_failed");
-        let headOid;
-        let state;
-        try {
-            const parsed = JSON.parse(view.stdout);
-            headOid = parsed.headRefOid;
-            state = parsed.state;
+        // 2. Re-read PR head + open/merged state (head-drift / closed / already-merged
+        //    guard). An already-merged PR at the expected head short-circuits to
+        //    success on ANY attempt. An ambiguous view failure re-verifies the merged
+        //    state before failing.
+        const firstRead = await readPrMergeState(run, ghEnv, pr);
+        if (!firstRead.ok) {
+            const verified = await verifyMergedStateAfterAmbiguousFailure();
+            if (verified)
+                return verified;
+            return fail(firstRead.reason);
         }
-        catch {
-            return fail("gh_pr_view_unparseable");
+        if (isMergedAtExpectedHead(firstRead.state, firstRead.headOid, expectedSha)) {
+            return buildAlreadyMergedResponse(request, baseDetails, firstRead.mergeCommitOid);
         }
-        if (typeof state === "string" && state.toUpperCase() !== "OPEN")
-            return fail("pr_not_open");
-        if (typeof headOid !== "string" || headOid.toLowerCase() !== expectedSha.toLowerCase()) {
+        if (typeof firstRead.headOid !== "string" || firstRead.headOid.toLowerCase() !== expectedSha.toLowerCase()) {
             return fail("head_drift");
         }
-        // 3. Revalidate required CI green for the exact head SHA.
-        let pollResponse;
-        try {
-            pollResponse = await pollCi(access, expectedSha);
+        if (typeof firstRead.state === "string" && firstRead.state.toUpperCase() !== "OPEN") {
+            return fail("pr_not_open");
+        }
+        // 3. Revalidate required CI green for the EXACT expected head, waiting briefly
+        //    for transient post-remediation CI to turn green before failing ci_not_green.
+        const ciWait = await waitForRequiredChecksGreen(pollCi, access, expectedSha, requiredChecks, ciWaitTimeoutMs, ciWaitPollIntervalMs, sleep, now, signal);
+        if (!ciWait.ok) {
+            // Any `ci_poll_*` reason (the legacy `ci_poll_failed` plus the distinct
+            // BAPI-577 kinds) is an AMBIGUOUS infrastructure read failure — a merge that
+            // GitHub already accepted could be masked by a flaky poll. Re-verify the
+            // merged state before reporting. ci_not_green and merge_aborted are
+            // deterministic (CI is red / the job was aborted); they never verify and
+            // never proceed to a provider merge.
+            if (isAmbiguousCiPollFailureReason(ciWait.reason)) {
+                const verified = await verifyMergedStateAfterAmbiguousFailure();
+                if (verified)
+                    return verified;
+            }
+            return fail(ciWait.reason, ciWait.pollFailure);
+        }
+        // 3b. Re-read PR head/state after the CI wait — the head can drift, the PR can
+        //     close, or the merge can already have landed while we waited for CI.
+        const secondRead = await readPrMergeState(run, ghEnv, pr);
+        if (!secondRead.ok) {
+            const verified = await verifyMergedStateAfterAmbiguousFailure();
+            if (verified)
+                return verified;
+            return fail(secondRead.reason);
+        }
+        if (isMergedAtExpectedHead(secondRead.state, secondRead.headOid, expectedSha)) {
+            return buildAlreadyMergedResponse(request, baseDetails, secondRead.mergeCommitOid);
         }
-        catch {
-            return fail("ci_poll_failed");
+        if (typeof secondRead.headOid !== "string" || secondRead.headOid.toLowerCase() !== expectedSha.toLowerCase()) {
+            return fail("head_drift");
+        }
+        if (typeof secondRead.state === "string" && secondRead.state.toUpperCase() !== "OPEN") {
+            return fail("pr_not_open");
         }
-        if (!allRequiredChecksGreen(pollResponse, requiredChecks))
-            return fail("ci_not_green");
-        // 4. Provider merge.
-        const merge = run("gh", ["pr", "merge", String(pr), `--${method}`, "--match-head-commit", expectedSha], ghEnv);
+        // 4. Provider merge. Final abort guard: if the overall timeout / ownership
+        //    abandonment fired during the CI wait or the post-CI re-read, do NOT fire
+        //    the real `gh pr merge` — the executor has already reported this job.
+        if (signal?.aborted)
+            return fail("merge_aborted");
+        const merge = await run("gh", ["pr", "merge", String(pr), `--${method}`, "--match-head-commit", expectedSha], ghEnv);
         if (merge.status !== 0) {
-            // A hung `gh` (killed by the wall-clock timeout) is operationally distinct
-            // from a permission/conflict failure — keep it mapped to gh_merge_timeout.
+            // Decision order after a merge-command failure (BAPI-572 Step 5):
+            //   1. timeout → verify already-merged, else gh_merge_timeout (ambiguous);
+            //   2. conflict-like output → gh_merge_conflict (deterministic);
+            //   3. re-read PR state / mergeability;
+            //   4. merged at expected head → success;
+            //   5. conflict mergeability → gh_merge_conflict;
+            //   6. otherwise → gh_merge_failed (verified non-merged, ambiguous).
             if (merge.timedOut) {
+                // A hung `gh pr merge` (killed by the wall-clock timeout) is ambiguous —
+                // the merge may already have landed at GitHub. Verify before failing.
+                const verified = await verifyMergedStateAfterAmbiguousFailure();
+                if (verified)
+                    return verified;
                 const reason = "gh_merge_timeout";
                 return buildResponse(request, "failed", reason, false, [
                     { type: "merge.attempted", status: "attempted", details: baseDetails },
                     { type: "merge.failed", status: "failed", reason, details: baseDetails },
                 ]);
             }
-            // BAPI-494: classify a conflict / non-fast-forward failure distinctly so it
-            // folds to `blocked` and remediates instead of hiding behind gh_merge_failed.
-            // First match the sanitized failure output; if inconclusive, do ONE follow-up
-            // mergeability re-read (only AFTER a merge failure — never before a successful
-            // or guarded merge) and check it. Raw stdout/stderr is used only for defensive
-            // classification and is never copied into event data or logs.
-            let mergeability = { mergeable: null, mergeStateStatus: null };
-            let isConflict = isLikelyGhMergeConflictOutput(merge);
-            if (!isConflict) {
-                const recheck = run("gh", ["pr", "view", String(pr), "--json", "mergeable,mergeStateStatus"], ghEnv);
-                if (recheck.status === 0) {
-                    try {
-                        mergeability = parseGhPrMergeabilityFields(JSON.parse(recheck.stdout));
-                        isConflict = isPrMergeConflict(mergeability);
-                    }
-                    catch {
-                        /* best-effort classification only */
-                    }
-                }
+            // BAPI-494: a conflict / non-fast-forward failure is DETERMINISTIC — classify
+            // it distinctly (no merged-state verification) so it folds to `blocked` and
+            // remediates instead of hiding behind gh_merge_failed. Raw stdout/stderr is
+            // used only for defensive classification and is never copied into event data.
+            if (isLikelyGhMergeConflictOutput(merge)) {
+                return buildConflictResponse(request, baseDetails, expectedSha, {
+                    mergeable: null,
+                    mergeStateStatus: null,
+                });
             }
-            if (isConflict) {
-                const reason = "gh_merge_conflict";
-                // Head-scoped to the attempted head SHA so the fold blocks the exact head; a
-                // later rebase clears it via the stale-head logic. mergeable/mergeStateStatus
-                // are included only when known.
-                const conflictDetails = {
-                    ...baseDetails,
-                    head_sha: expectedSha,
-                    ...(mergeability.mergeable ? { mergeable: mergeability.mergeable } : {}),
-                    ...(mergeability.mergeStateStatus ? { mergeStateStatus: mergeability.mergeStateStatus } : {}),
-                };
-                return buildResponse(request, "failed", reason, false, [
-                    { type: "merge.attempted", status: "attempted", details: baseDetails },
-                    { type: "merge.conflict", status: "failed", reason, details: conflictDetails },
-                ]);
+            // Generic non-conflict merge failure is AMBIGUOUS. Do ONE re-read that
+            // detects BOTH already-merged-at-head AND conflict mergeability, then:
+            //   merged at head → success; conflict → gh_merge_conflict; else gh_merge_failed.
+            const recheck = await readPrMergeState(run, ghEnv, pr, PR_STATE_MERGEABILITY_JSON);
+            if (recheck.ok) {
+                if (isMergedAtExpectedHead(recheck.state, recheck.headOid, expectedSha)) {
+                    return buildAlreadyMergedResponse(request, baseDetails, recheck.mergeCommitOid);
+                }
+                let mergeability = { mergeable: null, mergeStateStatus: null };
+                try {
+                    mergeability = parseGhPrMergeabilityFields(recheck.raw);
+                }
+                catch {
+                    /* best-effort classification only */
+                }
+                if (isPrMergeConflict(mergeability)) {
+                    return buildConflictResponse(request, baseDetails, expectedSha, mergeability);
+                }
             }
             const mergeFailReason = "gh_merge_failed";
             return buildResponse(request, "failed", mergeFailReason, false, [
@@ -234,13 +581,10 @@ export function makeLocalMergeExecutor(options = {}, deps = {}) {
         }
         // 5. Best-effort resolve the squash/merge commit SHA for the audit trail.
         let mergeCommitSha;
-        const post = run("gh", ["pr", "view", String(pr), "--json", "mergeCommit"], ghEnv);
+        const post = await run("gh", ["pr", "view", String(pr), "--json", "mergeCommit"], ghEnv);
         if (post.status === 0) {
             try {
-                const oid = JSON.parse(post.stdout)?.mergeCommit;
-                if (oid && typeof oid === "object" && typeof oid.oid === "string") {
-                    mergeCommitSha = oid.oid;
-                }
+                mergeCommitSha = extractMergeCommitOid(JSON.parse(post.stdout));
             }
             catch {
                 /* best-effort only */
@@ -256,3 +600,22 @@ export function makeLocalMergeExecutor(options = {}, deps = {}) {
         ]);
     };
 }
+/**
+ * Build a `gh_merge_conflict` failure with bounded, secret-free details. Only
+ * sanitized fields are included (head SHA + mergeability status when known); raw
+ * stdout/stderr is never copied into event data. Head-scoped to the attempted
+ * head so the fold blocks the exact head; a later rebase clears it.
+ */
+function buildConflictResponse(request, baseDetails, expectedSha, mergeability) {
+    const reason = "gh_merge_conflict";
+    const conflictDetails = {
+        ...baseDetails,
+        head_sha: expectedSha,
+        ...(mergeability.mergeable ? { mergeable: mergeability.mergeable } : {}),
+        ...(mergeability.mergeStateStatus ? { mergeStateStatus: mergeability.mergeStateStatus } : {}),
+    };
+    return buildResponse(request, "failed", reason, false, [
+        { type: "merge.attempted", status: "attempted", details: baseDetails },
+        { type: "merge.conflict", status: "failed", reason, details: conflictDetails },
+    ]);
+}