@bridge_gpt/mcp-server 0.2.37 → 0.2.39

package/build/merge-pull-request.js

@@ -0,0 +1,562 @@
+/**
+ * merge_pull_request — the fail-closed, server-decided protected merge tool (BAPI-799).
+ *
+ * The agent asks; the SERVER decides. This module holds no VCS credential, spawns
+ * no `gh` subprocess, and implements no merge of its own. It resolves the
+ * authoritative required-check set, constructs the deterministic action key, POSTs
+ * the protected root-mounted route, and renders the server's decision as one
+ * compact JSON text envelope. Every branch — including every error branch —
+ * resolves to that envelope; nothing throws through the MCP transport.
+ *
+ * WHY A FIXED ENVELOPE
+ * --------------------
+ * A merge is the one operation whose outcome an agent must never guess at. The
+ * envelope therefore always opens with the same six keys in the same order —
+ * `merged`, `outcome`, `reason`, `retry_hint`, `evaluated_head_sha`, `pr_number` —
+ * so a caller can branch on `merged` without parsing prose, and can always tell
+ * WHICH pull request and WHICH commit the answer is about. `merged: true` is the
+ * ONLY success; `dry_run`, `pending_approval`, and `lease_held` are non-progress
+ * outcomes that read as "nothing happened", not as "not yet, keep waiting".
+ *
+ * DIAGNOSTIC ALLOWLIST
+ * --------------------
+ * Only `actual_head_sha`, `ci_summary`, `paths`, `hint`, and `http_status` may
+ * follow the six stable fields, and each is copied from an authoritative server
+ * location. Raw ledger events, provider payloads, request headers, credentials,
+ * the action key, worker claims, and reviewer claims are never serialized here.
+ *
+ * REVIEW PRE-CHECK IS ADVISORY, NOT PROOF (BAPI-800)
+ * --------------------------------------------------
+ * When the configured done gate carries a `review_state` condition, this module
+ * reads the review-status route and evaluates the condition BEFORE dispatching
+ * the merge — so an obviously unreviewed PR is refused without a round trip.
+ * That check is advisory in the precise sense that matters: requiring the
+ * route's `detail.head_sha` to equal `expected_head_sha` is a PRECONDITION, not
+ * evidence that the review was *of* that head.
+ *
+ * The fields that do prove head binding — `sticky_reviewed_sha`, and the
+ * head-matching native decision/approval pair — are server-only and are not in
+ * the route's `detail`. So a legacy approved comment carrying no `Reviewed-SHA`
+ * line passes here and is then refused by the server as
+ * `refused` / `review_not_approved`. That sequence is EXPECTED, not a bug: the
+ * server holds the proof, and its answer is surfaced verbatim.
+ *
+ * FROZEN-TREE BOUNDARY
+ * --------------------
+ * This module lives OUTSIDE `conductor/` and consumes it only through pure,
+ * I/O-free seams: `git-ci-types.js`, `done-gate.js`, and `merge-identity.js`. The
+ * action key and gate identity are imported rather than reimplemented, because a
+ * second copy that drifts by one character produces a 409 the caller cannot act on.
+ */
+import { DEFAULT_GATE_NAME, REQUIRED_CI_CHECKS_GREEN, REVIEW_STATE, normalizeCheckName, } from "./conductor/git-ci-types.js";
+import { evaluateReviewCondition, normalizeReviewSnapshot, parseDoneGateConfig, } from "./conductor/done-gate.js";
+import { buildGateIdentity, makeMergeActionKey } from "./conductor/merge-identity.js";
+/**
+ * The exact remediation for a `dry_run`. Fixed text, because a caller that has to
+ * infer WHICH setting to flip from a reason code guesses wrong.
+ */
+const DRY_RUN_HINT = "set auto_merge_enabled=true on the project default via PUT /jira/epic-runs/supervisor-config/defaults/";
+/**
+ * Guidance for a post-dispatch transport failure. The action key makes the request
+ * idempotent, so repeating it verbatim is safe and is the ONLY safe move: the merge
+ * may or may not have landed, and this side cannot tell which.
+ */
+const UNKNOWN_HINT = "the request was sent but its outcome was not observed; repeat this call with identical arguments — the server's action key makes it idempotent";
+/** The one required-check resolution failure this handler ever reports. */
+const REQUIRED_CHECKS_EMPTY = "required_checks_empty";
+/** Server `failed` reasons whose remedy is genuinely "wait and repeat". */
+const CI_NOT_GREEN_REASON = "ci_not_green";
+/**
+ * The one review refusal the SERVER can issue that is worth waiting on: a
+ * verdict for this head may still be posted. Its siblings —
+ * `review_unavailable`, `review_source_unsupported`, `review_config_invalid` —
+ * fall through to `needs_human` below, because no amount of repeating the call
+ * moves an unreadable, unsupported, or malformed review configuration.
+ */
+const REVIEW_NOT_APPROVED_REASON = "review_not_approved";
+// ---------------------------------------------------------------------------
+// Envelope construction
+// ---------------------------------------------------------------------------
+/** Wrap a JSON envelope as the single MCP text content item. */
+function text(envelope) {
+    return { content: [{ type: "text", text: JSON.stringify(envelope) }] };
+}
+/**
+ * Build the envelope with the six stable fields FIRST, in fixed order, then only
+ * the approved diagnostics that are actually present. Insertion order is the
+ * serialized key order, and callers pin it — so this is the only place an envelope
+ * is ever constructed.
+ */
+function envelope(merged, outcome, reason, retryHint, evaluatedHeadSha, prNumber, diagnostics = {}) {
+    const result = {
+        merged,
+        outcome,
+        reason,
+        retry_hint: retryHint,
+        evaluated_head_sha: evaluatedHeadSha,
+        pr_number: prNumber,
+    };
+    if (diagnostics.actual_head_sha !== undefined)
+        result.actual_head_sha = diagnostics.actual_head_sha;
+    if (diagnostics.ci_summary !== undefined)
+        result.ci_summary = diagnostics.ci_summary;
+    if (diagnostics.paths !== undefined)
+        result.paths = diagnostics.paths;
+    if (diagnostics.hint !== undefined)
+        result.hint = diagnostics.hint;
+    if (diagnostics.http_status !== undefined)
+        result.http_status = diagnostics.http_status;
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Input validation
+// ---------------------------------------------------------------------------
+const SHA_RE = /^[0-9a-fA-F]{40}$/;
+/** Narrow an unknown to a plain (non-array, non-null) object. */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Validate the two inputs BEFORE any URL, header, or fetch operation.
+ *
+ * The MCP registration's Zod schema already rejects both cases at the protocol
+ * boundary, so this is defense in depth for a direct call — but it runs first
+ * regardless, because "reject before dispatch" is the only ordering in which an
+ * invalid PR number cannot become a real request against SOME pull request.
+ *
+ * Returns the reason for rejection, or `null` when both inputs are usable.
+ */
+function validateInputs(prNumber, expectedHeadSha) {
+    if (typeof prNumber !== "number" ||
+        !Number.isSafeInteger(prNumber) ||
+        prNumber <= 0) {
+        return "invalid_pr_number";
+    }
+    if (typeof expectedHeadSha !== "string" || !SHA_RE.test(expectedHeadSha)) {
+        return "invalid_expected_head_sha";
+    }
+    return null;
+}
+/**
+ * Read a response body as JSON without throwing. A body that is absent, empty, or
+ * not JSON yields `undefined` and is handled as an unusable payload by the caller.
+ */
+async function readJson(resp) {
+    try {
+        const body = await resp.text();
+        if (body.trim().length === 0)
+            return undefined;
+        return JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Normalize, de-duplicate, and order a candidate check-name list. Response order is
+ * preserved because it is the order the authoritative source declared, and the
+ * server recomputes the same action key over the same sequence.
+ */
+function normalizeCheckNames(raw) {
+    const out = [];
+    const seen = new Set();
+    for (const candidate of raw) {
+        const name = normalizeCheckName(candidate);
+        if (name === null || seen.has(name))
+            continue;
+        seen.add(name);
+        out.push(name);
+    }
+    return out;
+}
+/**
+ * Resolve the required checks from the ONE authoritative source, in priority order.
+ *
+ * The effective supervisor defaults win whenever they carry a `done_gate_config` at
+ * all. A config that is PRESENT but malformed is still authoritative — it resolves
+ * to no checks and the merge is refused. Falling back to the CI resolver there
+ * would be the worst possible behavior: it would silently substitute a discovered
+ * check set for the one an operator deliberately configured and got wrong.
+ *
+ * Returns `null` when the authoritative source could not be read at all, which the
+ * caller treats exactly like "resolved no checks" — fail closed, never dispatch.
+ */
+async function resolveRequiredChecks(deps, expectedHeadSha) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    // URL and header construction sit OUTSIDE the try on purpose. A failure there is
+    // a broken dependency, not an unreadable config, and it belongs to the handler's
+    // outer containment boundary — reporting it as "resolved no checks" would
+    // describe the wrong thing. Only the request itself failing means unreadable.
+    const defaultsUrl = deps.buildGetUrl("/epic-runs/supervisor-setup/defaults/", {
+        repo_name: deps.repoName,
+    });
+    const defaultsHeaders = await deps.getHeaders();
+    let defaultsResp;
+    try {
+        defaultsResp = await fetchImpl(defaultsUrl, { headers: defaultsHeaders });
+    }
+    catch {
+        return null;
+    }
+    if (!defaultsResp.ok) {
+        // Consume and normalize the body through the shared handler so no raw upstream
+        // text is retained; the status alone drives the fail-closed decision.
+        await deps.handleResponse(defaultsResp).catch(() => "");
+        return null;
+    }
+    const defaults = await readJson(defaultsResp);
+    if (!isPlainObject(defaults))
+        return null;
+    // Presence semantics: the defaults response ALWAYS carries the key (the Pydantic
+    // model serializes it as null when unset), so "explicitly present" means present
+    // and non-null. Only that state is authoritative.
+    const rawGateConfig = defaults.done_gate_config;
+    if (rawGateConfig !== undefined && rawGateConfig !== null) {
+        const parsed = parseDoneGateConfig(rawGateConfig);
+        if (!parsed.enabled || !parsed.valid) {
+            return { checks: [], configHash: null, reviewCondition: null };
+        }
+        const condition = parsed.conditions.find((c) => c.type === REQUIRED_CI_CHECKS_GREEN);
+        if (condition === undefined || condition.type !== REQUIRED_CI_CHECKS_GREEN) {
+            return { checks: [], configHash: null, reviewCondition: null };
+        }
+        // Same parse, same moment: the review condition is read out of the result
+        // that resolved the checks rather than re-fetched.
+        const review = parsed.conditions.find((c) => c.type === REVIEW_STATE);
+        const reviewCondition = review !== undefined && review.type === REVIEW_STATE ? review : null;
+        // Parser-provided order and hash are preserved verbatim — the server recomputes
+        // the action key over exactly these values.
+        return {
+            checks: [...condition.required_checks],
+            configHash: parsed.config_hash,
+            reviewCondition,
+        };
+    }
+    // Fallback: discover the checks through the CI resolver. `config_hash` is null
+    // here because no configured gate produced this set.
+    const resolverUrl = deps.buildUrl("/resolve-ci-checks");
+    const resolverHeaders = await deps.getPostHeaders();
+    let resolverResp;
+    try {
+        resolverResp = await fetchImpl(resolverUrl, {
+            method: "POST",
+            headers: resolverHeaders,
+            body: JSON.stringify({
+                repo_name: deps.repoName,
+                commit_ref: expectedHeadSha,
+            }),
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!resolverResp.ok) {
+        await deps.handleResponse(resolverResp).catch(() => "");
+        return null;
+    }
+    const resolved = await readJson(resolverResp);
+    if (!isPlainObject(resolved))
+        return null;
+    const detail = resolved.detail;
+    if (!isPlainObject(detail))
+        return { checks: [], configHash: null, reviewCondition: null };
+    const rawChecks = detail.checks;
+    if (!Array.isArray(rawChecks))
+        return { checks: [], configHash: null, reviewCondition: null };
+    // STRICTLY `true`. A missing or truthy-but-not-boolean `required` is not a
+    // declaration that the check gates a merge, and treating it as one would let an
+    // informational check block — or, worse, let a mis-typed one silently pass.
+    const requiredNames = rawChecks
+        .filter((entry) => isPlainObject(entry) && entry.required === true)
+        .map((entry) => entry.name);
+    // The resolver discovers CI checks only; it knows nothing about review policy,
+    // so this path is never review-gated.
+    return { checks: normalizeCheckNames(requiredNames), configHash: null, reviewCondition: null };
+}
+// ---------------------------------------------------------------------------
+// Review pre-check (BAPI-800)
+// ---------------------------------------------------------------------------
+/** The review sources this pre-check can evaluate against the route's `detail`. */
+const SUPPORTED_REVIEW_SOURCES = new Set(["verdict_protocol", "native_review_decision"]);
+const REVIEW_UNAVAILABLE_REASON = "review_unavailable";
+const REVIEW_SOURCE_UNSUPPORTED_REASON = "review_source_unsupported";
+const HEAD_SHA_DRIFT_REASON = "head_sha_drift";
+/**
+ * Evaluate the configured `review_state` condition before the merge is sent.
+ *
+ * Returns a refusal envelope, or `null` meaning "nothing objected — continue".
+ * Every failure direction is contained here and every one of them is a refusal:
+ * a review this side cannot read, cannot parse, or cannot evaluate is not a
+ * review that approved anything.
+ *
+ * `min_approvals` and `combination` are refused OUTRIGHT rather than approximated
+ * with a weaker rule. The server refuses them too, for the same reason: silently
+ * evaluating a different condition than the operator configured is worse than
+ * declining to evaluate at all.
+ */
+async function precheckReviewCondition(deps, condition, prNumber, expectedHeadSha) {
+    if (!SUPPORTED_REVIEW_SOURCES.has(condition.source)) {
+        return envelope(false, "review_source_unsupported", REVIEW_SOURCE_UNSUPPORTED_REASON, "needs_human", expectedHeadSha, prNumber);
+    }
+    const unavailable = () => envelope(false, "review_unavailable", REVIEW_UNAVAILABLE_REASON, "needs_human", expectedHeadSha, prNumber);
+    // URL and header construction sit OUTSIDE the try, matching the required-check
+    // resolver: a failure there is a broken dependency, not an unreadable review,
+    // and it belongs to the handler's outer containment boundary. The repository
+    // name comes from the server's environment and is query-encoded, so a name
+    // carrying a slash or a space cannot reshape the path.
+    const reviewUrl = deps.buildApiUrl(`/vcs/pull-requests/${prNumber}/reviews/status`) +
+        `?repo_name=${encodeURIComponent(deps.repoName)}`;
+    const reviewHeaders = await deps.getHeaders();
+    let reviewResp;
+    try {
+        reviewResp = await (deps.fetchImpl ?? fetch)(reviewUrl, { headers: reviewHeaders });
+    }
+    catch {
+        return unavailable();
+    }
+    if (!reviewResp.ok) {
+        await deps.handleResponse(reviewResp).catch(() => "");
+        return unavailable();
+    }
+    // `normalizeReviewSnapshot` returns null for `available: false` and for any
+    // body it cannot read as a review snapshot — the same answer, because both
+    // mean the same thing here.
+    const snapshot = normalizeReviewSnapshot(await readJson(reviewResp));
+    if (snapshot === null)
+        return unavailable();
+    // Head equality is checked BEFORE the evaluator, and takes precedence over an
+    // otherwise-approving verdict: a review of a different commit says nothing
+    // about this one. The evaluator never compares heads, which is exactly why
+    // this check cannot be folded into it.
+    if (snapshot.head_sha !== expectedHeadSha) {
+        const diagnostics = {};
+        if (typeof snapshot.head_sha === "string" && snapshot.head_sha.length > 0) {
+            diagnostics.actual_head_sha = snapshot.head_sha;
+        }
+        return envelope(false, "refused", HEAD_SHA_DRIFT_REASON, "needs_human", expectedHeadSha, prNumber, diagnostics);
+    }
+    const evaluation = evaluateReviewCondition(condition, snapshot);
+    if (!evaluation.passed) {
+        // A wait, not a park: a verdict for THIS head may still be posted. The
+        // evaluator's own reason is forwarded verbatim rather than flattened, so the
+        // caller can tell "no verdict yet" from "changes requested".
+        return envelope(false, "review_not_approved", evaluation.reason, "retry_later", expectedHeadSha, prNumber);
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Server-response interpretation
+// ---------------------------------------------------------------------------
+/**
+ * Pull the approved diagnostics out of the merge response's ledger events.
+ *
+ * The authoritative location is the FAILED event's
+ * `details.guard_outcomes` bundle, which the Python service builds through its
+ * secret-scrubbing evidence builder. Nothing else from the event — not its type,
+ * its action key, or the rest of the bundle — is read or forwarded.
+ */
+function extractDiagnostics(body) {
+    const diagnostics = {};
+    const events = body.ledger_events;
+    if (!Array.isArray(events))
+        return diagnostics;
+    for (const event of events) {
+        if (!isPlainObject(event) || event.status !== "failed")
+            continue;
+        const details = event.details;
+        if (!isPlainObject(details))
+            continue;
+        const guard = isPlainObject(details.guard_outcomes) ? details.guard_outcomes : {};
+        if (diagnostics.actual_head_sha === undefined && typeof guard.actual_head_sha === "string") {
+            diagnostics.actual_head_sha = guard.actual_head_sha;
+        }
+        if (diagnostics.ci_summary === undefined) {
+            const summary = isPlainObject(guard.ci_summary)
+                ? guard.ci_summary
+                : isPlainObject(details.ci_summary)
+                    ? details.ci_summary
+                    : undefined;
+            if (summary !== undefined)
+                diagnostics.ci_summary = summary;
+        }
+        if (diagnostics.paths === undefined && Array.isArray(guard.paths)) {
+            diagnostics.paths = guard.paths.filter((p) => typeof p === "string");
+        }
+    }
+    return diagnostics;
+}
+/**
+ * True when the authoritative CI summary shows at least one required check that is
+ * REPORTING and has not completed yet.
+ *
+ * This is the whole difference between "wait" and "act": a running check will
+ * settle on its own, while a check that completed red will still be red on the next
+ * identical call.
+ *
+ * A check the provider has not reported at all (`present: false`) does NOT count as
+ * pending. Absence is not evidence that work is in flight — it is equally
+ * consistent with a check that will never appear, and treating it as pending would
+ * send the caller into an unbounded retry loop over a condition no retry can move.
+ * Absent or malformed summary data reads the same way, for the same reason.
+ */
+function hasIncompleteRequiredCheck(ciSummary) {
+    if (!isPlainObject(ciSummary))
+        return false;
+    const checks = ciSummary.checks;
+    if (!Array.isArray(checks))
+        return false;
+    return checks.some((check) => isPlainObject(check) && check.complete !== true && check.present !== false);
+}
+/** Retry hint for a server `failed` reason. */
+function retryHintForFailure(reason, ciSummary) {
+    if (reason === CI_NOT_GREEN_REASON) {
+        return hasIncompleteRequiredCheck(ciSummary) ? "retry_later" : "needs_human";
+    }
+    if (reason === REVIEW_NOT_APPROVED_REASON)
+        return "retry_later";
+    return "needs_human";
+}
+/**
+ * Map one parsed 200-level merge response onto the envelope.
+ *
+ * `merged: true` is reachable from exactly one branch: `terminal === true` AND
+ * `status === "succeeded"` AND a recognized success reason. Every other shape,
+ * including a succeeded-but-not-terminal payload and any unrecognized status, is a
+ * non-success envelope. A merge tool that guesses generously about a malformed
+ * payload is worse than one that refuses.
+ */
+function interpretMergeResponse(body, expectedHeadSha, prNumber) {
+    const malformed = () => envelope(false, "error", "malformed_merge_response", "needs_human", expectedHeadSha, prNumber);
+    if (!isPlainObject(body))
+        return malformed();
+    const status = body.status;
+    const reason = typeof body.reason === "string" ? body.reason : null;
+    if (typeof status !== "string")
+        return malformed();
+    if (status === "succeeded") {
+        if (body.terminal !== true)
+            return malformed();
+        if (reason === "already_merged") {
+            return envelope(true, "already_merged", reason, null, expectedHeadSha, prNumber);
+        }
+        if (reason === "merged") {
+            return envelope(true, "merged", reason, null, expectedHeadSha, prNumber);
+        }
+        return malformed();
+    }
+    if (status === "dry_run") {
+        return envelope(false, "dry_run", reason, "needs_human", expectedHeadSha, prNumber, {
+            hint: DRY_RUN_HINT,
+        });
+    }
+    if (status === "pending_approval") {
+        return envelope(false, "pending_approval", reason, "needs_human", expectedHeadSha, prNumber);
+    }
+    if (status === "lease_held") {
+        return envelope(false, "lease_held", reason, "retry_later", expectedHeadSha, prNumber);
+    }
+    if (status === "failed") {
+        if (reason === null)
+            return malformed();
+        const diagnostics = extractDiagnostics(body);
+        return envelope(false, "refused", reason, retryHintForFailure(reason, diagnostics.ci_summary), expectedHeadSha, prNumber, diagnostics);
+    }
+    return malformed();
+}
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+/**
+ * Ask the Bridge API to merge a pull request, and render its decision.
+ *
+ * The outer `try` is a containment boundary, not error handling: an exception that
+ * escaped here would surface to the agent as an MCP transport failure with no
+ * envelope at all, and a caller facing a merge tool that "errored" cannot tell
+ * whether the merge happened. Every path returns an envelope instead.
+ */
+export async function mergePullRequestHandler(deps, args) {
+    // Read the identity fields defensively: `args` is a runtime value and this
+    // handler must echo the caller's own PR/SHA back even when they are unusable.
+    const rawPr = args?.pr_number;
+    const rawSha = args?.expected_head_sha;
+    const echoedSha = typeof rawSha === "string" ? rawSha : null;
+    const echoedPr = typeof rawPr === "number" ? rawPr : null;
+    try {
+        // (1) Reject invalid input before ANY dependency that could perform I/O.
+        // `error` is reused deliberately rather than minting a new outcome: the
+        // vocabulary above is closed, and an unusable argument is not a merge decision.
+        const invalid = validateInputs(rawPr, rawSha);
+        if (invalid !== null) {
+            return text(envelope(false, "error", invalid, "needs_human", echoedSha, echoedPr));
+        }
+        const prNumber = rawPr;
+        const expectedHeadSha = rawSha;
+        // (2) Resolve the authoritative required checks. This stage completes fully
+        // before the review pre-check below, so an unresolvable CI gate refuses
+        // without ever asking a review provider about a merge that could not have
+        // happened anyway.
+        const resolution = await resolveRequiredChecks(deps, expectedHeadSha);
+        if (resolution === null || resolution.checks.length === 0) {
+            // Nothing authoritative said which checks gate this merge, so no merge URL,
+            // no merge headers, and no request are constructed. A vacuous "all zero
+            // required checks are green" is the one CI pass that must never be possible.
+            return text(envelope(false, "gate_unresolved", REQUIRED_CHECKS_EMPTY, "needs_human", expectedHeadSha, prNumber));
+        }
+        // (2b) Review pre-check (BAPI-800). It runs only for a configured gate that
+        // carries a `review_state` condition, and it returns BEFORE the pre-POST
+        // section below — so a refusal here constructs no merge URL, no merge
+        // headers, no action key, and sends no merge request.
+        if (resolution.reviewCondition !== null) {
+            const refusal = await precheckReviewCondition(deps, resolution.reviewCondition, prNumber, expectedHeadSha);
+            if (refusal !== null)
+                return text(refusal);
+        }
+        // --- pre-POST section ---------------------------------------------------
+        const gateIdentity = buildGateIdentity(DEFAULT_GATE_NAME, resolution.configHash);
+        const actionKey = makeMergeActionKey(deps.repoName, prNumber, expectedHeadSha, gateIdentity);
+        // The body is built from server-side values only. No caller-supplied field is
+        // spread in, so an extra runtime `repo_name` argument cannot retarget the merge.
+        const mergeBody = {
+            repo_name: deps.repoName,
+            expected_head_sha: expectedHeadSha,
+            gate: {
+                name: DEFAULT_GATE_NAME,
+                config_hash: resolution.configHash,
+                required_checks: resolution.checks,
+            },
+            action_key: actionKey,
+        };
+        // (3) POST the protected root-mounted route. Wrapped on its own so a rejection
+        // AFTER dispatch is reported as genuinely unknown rather than as a failure.
+        let mergeResp;
+        try {
+            mergeResp = await (deps.fetchImpl ?? fetch)(deps.buildApiUrl(`/vcs/pull-requests/${prNumber}/merge`), {
+                method: "POST",
+                headers: await deps.getPostHeaders(),
+                body: JSON.stringify(mergeBody),
+            });
+        }
+        catch {
+            return text(envelope(false, "unknown", "merge_request_not_observed", "retry_later", expectedHeadSha, prNumber, {
+                hint: UNKNOWN_HINT,
+            }));
+        }
+        if (!mergeResp.ok) {
+            // Normalize and consume the body through the shared handler, then report the
+            // status only — raw upstream error text is never forwarded to the agent.
+            await deps.handleResponse(mergeResp).catch(() => "");
+            if (mergeResp.status === 409) {
+                return text(envelope(false, "action_key_mismatch", "action_key_mismatch", "needs_human", expectedHeadSha, prNumber));
+            }
+            return text(envelope(false, "error", "merge_request_failed", "needs_human", expectedHeadSha, prNumber, {
+                http_status: mergeResp.status,
+            }));
+        }
+        return text(interpretMergeResponse(await readJson(mergeResp), expectedHeadSha, prNumber));
+    }
+    catch {
+        // Containment: never throw through the MCP transport, and never serialize the
+        // exception — its text is unbounded and may carry a URL or header value.
+        return text(envelope(false, "error", "handler_error", "needs_human", echoedSha, echoedPr));
+    }
+}