@bridge_gpt/mcp-server 0.2.59 → 0.2.60

package/build/merge-workflow.js

@@ -0,0 +1,572 @@
+/**
+ * The Epic Implementer merge-workflow renderer (BAPI-1136, A2 slice 4).
+ *
+ * This module renders the ONE GitHub Actions workflow that performs the
+ * child-pull-request merge on the customer's own infrastructure, with the
+ * ephemeral `GITHUB_TOKEN` supplying the `contents: write` scope Bridge
+ * deliberately does not hold. It is the customer-side WRITE ACTOR of the A2
+ * "infra floors & write authority" epic.
+ *
+ * ## Why a TypeScript renderer and not a bundled YAML asset
+ *
+ * The ticket text asked for a template asset copied by
+ * `mcp_server/scripts/bundle-assets.js`. The review rejected that in favour of
+ * the repository's own established precedent (decision E-19):
+ * `claude-review-workflow.ts` already renders a workflow as compiled TypeScript,
+ * `tsc` already ships it in the published package, and a second mechanism for a
+ * single template would add a `*.generated.ts` that must never be hand-edited
+ * for no benefit. So this file is the workflow's ONLY byte source — nothing in
+ * `bundle-assets.js` changes.
+ *
+ * ## Why the renderer takes no parameters
+ *
+ * {@link renderEpicImplementerMergeWorkflow} is input-free and deterministic.
+ * The claude-review renderer interpolates org-specific literals because its
+ * template genuinely varies per customer; this one does not. Every
+ * customer-specific value the merge actuator needs — the Bridge API key, the
+ * base URL, the attempt's action key and lease — arrives at RUN time through a
+ * repository secret, a repository variable, or a dispatch input. If a customer
+ * value could alter the canonical bytes, then "the workflow on the default
+ * branch" would no longer be one reviewable artifact with one identity, and the
+ * byte-pin that makes drift detectable would be meaningless.
+ *
+ * ## The security shape, in one paragraph
+ *
+ * `workflow_dispatch` runs the workflow definition from the TRUSTED DEFAULT
+ * BRANCH, so a pull request that edits this file cannot change the version that
+ * actually runs against it. The two dispatch inputs are a wake-up and a lease
+ * correlator; they authorize nothing. Authorization is the durable, SHA-bound
+ * merge command the job fetches from Bridge, presenting the repository's own
+ * API-key secret and the per-attempt lease secret. Nothing is ever checked out,
+ * no third-party action runs, the merge carries an expected-head-SHA
+ * precondition, a fork-origin head is refused, and a base that is the repository
+ * default branch is refused outright.
+ *
+ * ## Secret discipline
+ *
+ * The rendered script never enables shell tracing, never echoes either dispatch
+ * input, never prints a response body, and never writes a credential or the
+ * lease to a workflow output, a step summary, or `$GITHUB_ENV`. The API key and
+ * the lease reach `curl` through a `umask 077` config file and a request body
+ * that `jq` builds FROM THE ENVIRONMENT, so neither is ever an argv element
+ * visible to another process in the runner; both files are removed by an `EXIT`
+ * trap. `gh` authenticates from `GH_TOKEN` in the environment for the same
+ * reason.
+ */
+import { MERGE_WORKFLOW_EXPECTED_VERSION, MERGE_WORKFLOW_PATH, MERGE_WORKFLOW_VERSION_MARKER_KEY, } from "./conductor/merge-execution-contract.js";
+import { MERGE_COMMAND_FETCH_PATH, MERGE_WORKFLOW_API_KEY_SECRET_NAME, MERGE_WORKFLOW_BASE_URL_VARIABLE_NAME, MERGE_WORKFLOW_DEFAULT_BASE_URL, } from "./merge-workflow-config.js";
+/**
+ * Every refusal the rendered workflow can emit, as a closed vocabulary.
+ *
+ * A refusal is always one of these tokens — never raw `curl`, `jq`, or `gh`
+ * output, and never an HTTP body. Raw subprocess text is unbounded and can echo
+ * a URL, a header, or provider detail into a log that is world-readable on a
+ * public repository.
+ *
+ * Exported so the static safety tests can assert the rendered template mentions
+ * exactly these and nothing else.
+ */
+export const MERGE_WORKFLOW_REFUSAL_REASONS = [
+    /** The repository-level Bridge API key secret is absent or empty. */
+    "bridge_api_key_secret_missing",
+    /** The durable merge command could not be fetched (includes the 404 the absent sibling child returns). */
+    "merge_command_unavailable",
+    /** The command was fetched but is unusable: missing fields, or an execution mode this actuator does not perform. */
+    "merge_command_rejected",
+    /** The command names a repository or action key that is not this workflow's live context. */
+    "repository_identity_mismatch",
+    /** The repository default branch could not be read, so the base guard cannot be applied. */
+    "default_branch_unresolved",
+    /** The pull request could not be read from live provider state. */
+    "pr_read_failed",
+    /** The pull request is not open. */
+    "pr_not_open",
+    /** The head is a fork or an otherwise unverifiable cross-repository ref. */
+    "fork_origin_denied",
+    /** The pull request targets the repository default branch. Never retried. */
+    "base_is_default_branch",
+    /** The live head moved away from the command's expected head SHA. Never retried. */
+    "head_sha_drift",
+    /** `gh pr merge` failed and the read-back did not show the merge landed. */
+    "gh_merge_failed",
+    /** The merge attempt's outcome could not be classified from the read-back. */
+    "merge_outcome_ambiguous",
+    /** The merge landed but its completion report was not accepted; the reconciler recovers. */
+    "completion_unreported",
+];
+/**
+ * Build a GitHub Actions expression without writing `${` in TypeScript source.
+ *
+ * The rendered lines below are ordinary double-quoted strings, not template
+ * literals, so this is belt-and-braces: it keeps every expression marker in one
+ * place and makes a grep for "which expressions does this template evaluate"
+ * answerable.
+ */
+const gh = (expr) => "${{ " + expr + " }}";
+const SECRET_EXPR = gh(`secrets.${MERGE_WORKFLOW_API_KEY_SECRET_NAME}`);
+const BASE_URL_EXPR = gh(`vars.${MERGE_WORKFLOW_BASE_URL_VARIABLE_NAME} || '${MERGE_WORKFLOW_DEFAULT_BASE_URL}'`);
+/**
+ * Render the canonical merge workflow.
+ *
+ * Deterministic and input-free: two calls in the same build return byte-identical
+ * output, and no customer value can alter a single byte. The result is
+ * newline-terminated.
+ */
+export function renderEpicImplementerMergeWorkflow() {
+    const lines = [
+        "# ===========================================================================",
+        "# Epic Implementer merge actuator — MANAGED FILE",
+        "#",
+        "# Generated by Bridge (`" + MERGE_WORKFLOW_PATH + "`). Do not hand-edit: the",
+        "# installer compares this file byte for byte against the version it ships and",
+        "# refuses to touch a modified or unrecognized copy.",
+        "#",
+        "# WHAT THIS WORKFLOW IS",
+        "#",
+        "# It performs the GitHub merge for an Epic Implementer child pull request that",
+        "# Bridge has already approved. Bridge's own GitHub App installation is",
+        "# `contents: read` and cannot merge; the ephemeral GITHUB_TOKEN issued to this",
+        "# job can. That is the entire reason this file exists, and it is why the file",
+        "# is worth a careful human review before it is merged.",
+        "#",
+        "# TRUSTED-BRANCH EXECUTION",
+        "#",
+        "# `workflow_dispatch` ALWAYS runs the workflow definition that is on the",
+        "# repository's DEFAULT BRANCH. A pull request that edits this file therefore",
+        "# cannot change the version of this workflow that runs against it — the copy",
+        "# under review is inert until it is merged into the default branch. Protect",
+        "# this path with a code-owner review rule so that merge is a deliberate act.",
+        "#",
+        "# THE TWO DISPATCH INPUTS AUTHORIZE NOTHING",
+        "#",
+        "# `action_key` is a wake-up: it names which approved attempt this run is for.",
+        "# `lease_owner` is lease-correlation data: it proves to Bridge that this run is",
+        "# the live attempt. Neither grants permission to merge anything, neither is",
+        "# trusted as the source of what to merge, and neither is ever echoed to the",
+        "# log, a step output, a job summary, or $GITHUB_ENV. Everything this job acts",
+        "# on comes from the durable, SHA-bound merge command it fetches from Bridge and",
+        "# then re-validates against live provider state.",
+        "#",
+        "# WHAT IT NEVER DOES",
+        "#",
+        "#   * It never checks out the repository, and never runs pull-request content.",
+        "#   * It uses no `uses:` step and no third-party action — only runner-provided",
+        "#     bash, curl, jq, and the GitHub CLI.",
+        "#   * It never merges into the repository default branch.",
+        "#   * It never merges a fork-origin or otherwise unverifiable head.",
+        "#   * It never merges a head that has moved from the approved SHA.",
+        "#",
+        "# RESIDUAL RACE (base retargeting)",
+        "#",
+        "# Base selection is not atomic with the provider merge. This job validates the",
+        "# base before merging, and Bridge's completion path re-reads the pull request",
+        "# and re-applies the same base guard afterwards. A base retargeted inside that",
+        "# window is detected on the completion side and refused there, which leaves the",
+        "# attempt recorded as refused rather than silently accepted. Recovering from a",
+        "# detected retarget race is a repository-administrator action, not a retry.",
+        "# ===========================================================================",
+        "",
+        "name: Epic Implementer merge",
+        "",
+        "# The machine-readable contract version. Bridge's eligibility probe requires",
+        "# EXACT equality with the version it understands; a newer file is a workflow it",
+        "# has never been taught to reason about and is refused rather than dispatched.",
+        "#",
+        "# WHY IT LIVES UNDER `env:` AND NOT AT TOP LEVEL. GitHub Actions validates a",
+        "# workflow against a CLOSED top-level schema — name, run-name, on, permissions,",
+        "# env, defaults, concurrency, jobs. An unknown top-level key is not a tolerated",
+        "# extension: it makes the whole file refuse to load with \"Invalid workflow",
+        "# file\", which would leave a permanently red annotation on the customer's",
+        "# default branch AND never register the `workflow_dispatch` trigger, so the",
+        "# actuator could not perform a single merge. The failure would also be QUIET:",
+        "# Bridge parses this file with PyYAML, which reads an unknown top-level key",
+        "# happily, so the eligibility probe would report the repository ready and the",
+        "# breakage would surface only as a dispatch error. Bridge's own",
+        "# `_resolve_version_marker` reads the marker from the top level OR from `env`,",
+        "# and declaring it in exactly one of them — this one — is both schema-legal and",
+        "# unambiguous. Declaring it in BOTH is what makes a document unreadable.",
+        "env:",
+        "  " + MERGE_WORKFLOW_VERSION_MARKER_KEY + ": " + String(MERGE_WORKFLOW_EXPECTED_VERSION),
+        "",
+        "on:",
+        "  workflow_dispatch:",
+        "    inputs:",
+        "      action_key:",
+        "        description: >-",
+        "          Durable merge-action key naming the approved attempt. A wake-up and a",
+        "          correlator only; it authorizes nothing by itself.",
+        "        required: true",
+        "        type: string",
+        "      lease_owner:",
+        "        description: >-",
+        "          Per-attempt lease secret proving this run is the live attempt. Never",
+        "          printed, never echoed, never written to an output.",
+        "        required: true",
+        "        type: string",
+        "",
+        "# Exactly the two scopes the merge needs, granted once at workflow level. No",
+        "# job overrides these, and no other permission is requested.",
+        "permissions:",
+        "  contents: write",
+        "  pull-requests: write",
+        "",
+        "# Grouped on the non-secret action key so two dispatches for the SAME attempt",
+        "# queue instead of racing. `cancel-in-progress: false` because cancelling a run",
+        "# that may already have merged would destroy the evidence. This is a courtesy,",
+        "# not a control: Bridge's single-use lease remains the authoritative guard",
+        "# against a second actuation.",
+        "concurrency:",
+        "  group: epic-implementer-merge-" + gh("inputs.action_key"),
+        "  cancel-in-progress: false",
+        "",
+        "jobs:",
+        "  merge:",
+        "    name: Merge the approved Epic Implementer pull request",
+        "    runs-on: ubuntu-latest",
+        "    timeout-minutes: 10",
+        "    env:",
+        "      BAPI_BASE_URL: " + BASE_URL_EXPR,
+        "      BAPI_API_KEY: " + SECRET_EXPR,
+        "      ACTION_KEY: " + gh("inputs.action_key"),
+        "      LEASE_OWNER: " + gh("inputs.lease_owner"),
+        "      REPO_FULL_NAME: " + gh("github.repository"),
+        "      GH_TOKEN: " + gh("github.token"),
+        "      GH_PROMPT_DISABLED: '1'",
+        "      GH_NO_UPDATE_NOTIFIER: '1'",
+        "    steps:",
+        "      # ------------------------------------------------------------------",
+        "      # 1. Fail before anything else when the repository secret is absent.",
+        "      #    Reported as a named reason so an operator sees the fix, not a",
+        "      #    404 from an unauthenticated call three steps later.",
+        "      # ------------------------------------------------------------------",
+        "      - name: Require the Bridge API key secret",
+        "        shell: bash",
+        "        run: |",
+        "          set -uo pipefail",
+        "          set +x",
+        '          if [ -z "${BAPI_API_KEY:-}" ]; then',
+        '            echo "REFUSAL_REASON=bridge_api_key_secret_missing" >> "$GITHUB_ENV"',
+        '            echo "::error::Repository secret ' +
+            MERGE_WORKFLOW_API_KEY_SECRET_NAME +
+            ' is not set. Create it with a Bridge API key for this repository."',
+        "            exit 1",
+        "          fi",
+        "",
+        "      # ------------------------------------------------------------------",
+        "      # 2. Fetch the durable, SHA-bound merge command. This is the ONLY",
+        "      #    authorization in the whole job. The API key reaches curl through a",
+        "      #    0600 config file and the lease through a jq-built body, so neither",
+        "      #    is ever an argv element; both files die with the step.",
+        "      #",
+        "      #    A 404 here is the EXPECTED state until the Bridge-side durable",
+        "      #    command store ships. The job refuses without retrying and without",
+        "      #    touching the pull request, so this actuator is inert rather than",
+        "      #    dangerous while that sibling is outstanding.",
+        "      # ------------------------------------------------------------------",
+        "      - name: Fetch the durable merge command",
+        "        shell: bash",
+        "        run: |",
+        "          set -uo pipefail",
+        "          set +x",
+        "          umask 077",
+        '          curlrc="${RUNNER_TEMP}/bapi-merge.curlrc"',
+        '          reqbody="${RUNNER_TEMP}/bapi-merge-request.json"',
+        '          respbody="${RUNNER_TEMP}/bapi-merge-command.json"',
+        "          trap 'rm -f \"$curlrc\" \"$reqbody\" \"$respbody\"' EXIT",
+        "          # Both reads are from the ENVIRONMENT, never from argv or a here-string.",
+        "          jq -rn 'env.BAPI_API_KEY | \"header = \\\"X-API-Key: \\(.)\\\"\"' > \"$curlrc\"",
+        "          jq -n '{repo_name: (env.ACTION_KEY | split(\":\") | .[1] // \"\"), action_key: env.ACTION_KEY, lease_owner: env.LEASE_OWNER}' > \"$reqbody\"",
+        "          # --retry 0: every refusal this endpoint returns is deterministic, and",
+        "          # retrying a lease-bound POST risks a second billable attempt.",
+        "          code=\"$(curl --silent --show-error --no-progress-meter --retry 0 \\",
+        "            --max-time 30 \\",
+        '            --config "$curlrc" \\',
+        "            --header 'Content-Type: application/json' \\",
+        "            --request POST \\",
+        '            --data-binary "@$reqbody" \\',
+        '            --output "$respbody" \\',
+        "            --write-out '%{http_code}' \\",
+        '            "${BAPI_BASE_URL%/}' +
+            MERGE_COMMAND_FETCH_PATH +
+            '" || echo "000")"',
+        '          if [ "$code" != "200" ]; then',
+        '            echo "REFUSAL_REASON=merge_command_unavailable" >> "$GITHUB_ENV"',
+        '            echo "::error::Bridge did not return a durable merge command (HTTP $code)."',
+        "            exit 1",
+        "          fi",
+        "          # Only non-secret projection fields are lifted into the job env. The",
+        "          # response body itself is never printed and never survives this step.",
+        '          cmd_action_key="$(jq -r \'.action_key // ""\' "$respbody")"',
+        '          cmd_repo_name="$(jq -r \'.repo_name // ""\' "$respbody")"',
+        '          cmd_repository="$(jq -r \'.github_repository // ""\' "$respbody")"',
+        '          lease_expires_at="$(jq -r \'.lease_expires_at // ""\' "$respbody")"',
+        '          pr_number="$(jq -r \'.pr_number // ""\' "$respbody")"',
+        '          expected_head_sha="$(jq -r \'.expected_head_sha // ""\' "$respbody")"',
+        '          merge_method="$(jq -r \'.merge_method // ""\' "$respbody")"',
+        '          execution="$(jq -r \'.execution // ""\' "$respbody")"',
+        '          case "$merge_method" in',
+        "            squash|merge|rebase) ;;",
+        "            *)",
+        '              echo "REFUSAL_REASON=merge_command_rejected" >> "$GITHUB_ENV"',
+        '              echo "::error::The merge command names an unsupported merge method."',
+        "              exit 1",
+        "              ;;",
+        "          esac",
+        '          if [ "$execution" != "github_actions" ]; then',
+        '            echo "REFUSAL_REASON=merge_command_rejected" >> "$GITHUB_ENV"',
+        '            echo "::error::The merge command was not issued for GitHub Actions execution."',
+        "            exit 1",
+        "          fi",
+        '          case "$pr_number" in',
+        "            ''|*[!0-9]*)",
+        '              echo "REFUSAL_REASON=merge_command_rejected" >> "$GITHUB_ENV"',
+        '              echo "::error::The merge command carries no usable pull request number."',
+        "              exit 1",
+        "              ;;",
+        "          esac",
+        '          if [ "${#expected_head_sha}" -ne 40 ]; then',
+        '            echo "REFUSAL_REASON=merge_command_rejected" >> "$GITHUB_ENV"',
+        '            echo "::error::The merge command carries no usable expected head SHA."',
+        "            exit 1",
+        "          fi",
+        "          # An already-expired lease cannot be closed, so merging on it would",
+        "          # perform a real write that no completion report could record. Refuse",
+        "          # before the first provider read rather than after the merge.",
+        '          if [ -n "$lease_expires_at" ]; then',
+        '            expiry_epoch="$(date -u -d "$lease_expires_at" +%s 2>/dev/null || echo "")"',
+        '            if [ -n "$expiry_epoch" ] && [ "$expiry_epoch" -le "$(date -u +%s)" ]; then',
+        '              echo "REFUSAL_REASON=merge_command_rejected" >> "$GITHUB_ENV"',
+        '              echo "::error::The merge command lease had already expired when this run started."',
+        "              exit 1",
+        "            fi",
+        "          fi",
+        "          # The live workflow context is authoritative. A command minted for a",
+        "          # different repository, or for a different attempt, is refused here —",
+        "          # before a single provider read is spent on it. Both repository",
+        "          # identities are checked: the provider one against github.repository,",
+        "          # and Bridge's own against the name carried inside the action key, so a",
+        "          # command whose two namespaces disagree cannot actuate either.",
+        '          key_repo_name="$(jq -rn \'env.ACTION_KEY | split(":") | .[1] // ""\')"',
+        '          if [ "$cmd_repository" != "$REPO_FULL_NAME" ] \\',
+        '            || [ "$cmd_action_key" != "$ACTION_KEY" ] \\',
+        '            || [ "$cmd_repo_name" != "$key_repo_name" ]; then',
+        '            echo "REFUSAL_REASON=repository_identity_mismatch" >> "$GITHUB_ENV"',
+        '            echo "::error::The merge command does not match this repository and attempt."',
+        "            exit 1",
+        "          fi",
+        '          {',
+        '            echo "PR_NUMBER=$pr_number"',
+        '            echo "EXPECTED_HEAD_SHA=$expected_head_sha"',
+        '            echo "MERGE_METHOD=$merge_method"',
+        '          } >> "$GITHUB_ENV"',
+        "",
+        "      # ------------------------------------------------------------------",
+        "      # 3. Read live provider state and apply every guard, in the order a",
+        "      #    cheap deterministic refusal comes before an expensive one. No ref",
+        "      #    is checked out at any point.",
+        "      # ------------------------------------------------------------------",
+        "      - name: Resolve the repository default branch",
+        "        shell: bash",
+        "        run: |",
+        "          set -uo pipefail",
+        "          set +x",
+        '          default_branch="$(gh api "repos/$REPO_FULL_NAME" --jq \'.default_branch // ""\' 2>/dev/null || echo "")"',
+        '          if [ -z "$default_branch" ]; then',
+        '            echo "REFUSAL_REASON=default_branch_unresolved" >> "$GITHUB_ENV"',
+        '            echo "::error::The repository default branch could not be read, so the base guard cannot be applied."',
+        "            exit 1",
+        "          fi",
+        '          echo "DEFAULT_BRANCH=$default_branch" >> "$GITHUB_ENV"',
+        "",
+        "      - name: Guard the pull request before merging",
+        "        shell: bash",
+        "        run: |",
+        "          set -uo pipefail",
+        "          set +x",
+        "          pr_json=\"$(gh pr view \"$PR_NUMBER\" --repo \"$REPO_FULL_NAME\" \\",
+        "            --json state,baseRefName,headRefOid,isCrossRepository,headRepositoryOwner,headRepository \\",
+        '            2>/dev/null || echo "")"',
+        '          if [ -z "$pr_json" ]; then',
+        '            echo "REFUSAL_REASON=pr_read_failed" >> "$GITHUB_ENV"',
+        '            echo "::error::Pull request #$PR_NUMBER could not be read."',
+        "            exit 1",
+        "          fi",
+        '          state="$(printf \'%s\' "$pr_json" | jq -r \'.state // ""\')"',
+        '          base_ref="$(printf \'%s\' "$pr_json" | jq -r \'.baseRefName // ""\')"',
+        '          head_sha="$(printf \'%s\' "$pr_json" | jq -r \'.headRefOid // ""\')"',
+        '          cross_repo="$(printf \'%s\' "$pr_json" | jq -r \'.isCrossRepository // true\')"',
+        '          head_repo="$(printf \'%s\' "$pr_json" | jq -r \'((.headRepositoryOwner.login // "") + "/" + (.headRepository.name // ""))\')"',
+        '          if [ "$state" != "OPEN" ]; then',
+        '            echo "REFUSAL_REASON=pr_not_open" >> "$GITHUB_ENV"',
+        '            echo "::error::Pull request #$PR_NUMBER is not open."',
+        "            exit 1",
+        "          fi",
+        "          # A fork head, or a head whose repository cannot be proven to be this",
+        "          # one, is refused. `isCrossRepository` defaults to true above so an",
+        "          # absent field fails closed rather than reading as same-repo.",
+        '          if [ "$cross_repo" != "false" ] || [ "$head_repo" != "$REPO_FULL_NAME" ]; then',
+        '            echo "REFUSAL_REASON=fork_origin_denied" >> "$GITHUB_ENV"',
+        '            echo "::error::Pull request #$PR_NUMBER has a fork-origin or unverifiable head."',
+        "            exit 1",
+        "          fi",
+        "          # The epic's AC-5 hard denial. Never retried: a default-branch base is",
+        "          # a decision that has to change, not a condition that can clear.",
+        '          if [ "$base_ref" = "$DEFAULT_BRANCH" ]; then',
+        '            echo "REFUSAL_REASON=base_is_default_branch" >> "$GITHUB_ENV"',
+        '            echo "::error::Pull request #$PR_NUMBER targets the repository default branch; this actuator never merges into it."',
+        "            exit 1",
+        "          fi",
+        "          # Head drift. Also never retried — the approval was bound to a SHA.",
+        '          if [ "$head_sha" != "$EXPECTED_HEAD_SHA" ]; then',
+        '            echo "REFUSAL_REASON=head_sha_drift" >> "$GITHUB_ENV"',
+        '            echo "::error::Pull request #$PR_NUMBER moved away from the approved head commit."',
+        "            exit 1",
+        "          fi",
+        "",
+        "      # ------------------------------------------------------------------",
+        "      # 4. The one privileged write. `--match-head-commit` re-asserts the",
+        "      #    expected head at the provider, so the guard above and the merge",
+        "      #    itself cannot disagree across the gap between them. The token",
+        "      #    reaches gh through GH_TOKEN in the environment, never argv.",
+        "      # ------------------------------------------------------------------",
+        "      - name: Merge the pull request",
+        "        shell: bash",
+        "        run: |",
+        "          set -uo pipefail",
+        "          set +x",
+        "          if gh pr merge \"$PR_NUMBER\" --repo \"$REPO_FULL_NAME\" \\",
+        '            "--$MERGE_METHOD" --match-head-commit "$EXPECTED_HEAD_SHA" >/dev/null 2>&1; then',
+        '            echo "MERGE_ATTEMPT=accepted" >> "$GITHUB_ENV"',
+        "          else",
+        '            echo "MERGE_ATTEMPT=rejected" >> "$GITHUB_ENV"',
+        "          fi",
+        "",
+        "      # ------------------------------------------------------------------",
+        "      # 5. Classify from a FRESH read rather than from the merge command's own",
+        "      #    exit status. A slow-but-successful merge that gh reported as a",
+        "      #    failure would otherwise be recorded as a failure and invite a",
+        "      #    second attempt at a pull request that is already merged.",
+        "      # ------------------------------------------------------------------",
+        "      - name: Classify the merge outcome",
+        "        shell: bash",
+        "        run: |",
+        "          set -uo pipefail",
+        "          set +x",
+        "          pr_json=\"$(gh pr view \"$PR_NUMBER\" --repo \"$REPO_FULL_NAME\" \\",
+        '            --json state,mergeCommit,headRefOid 2>/dev/null || echo "")"',
+        '          if [ -z "$pr_json" ]; then',
+        '            echo "REFUSAL_REASON=merge_outcome_ambiguous" >> "$GITHUB_ENV"',
+        '            echo "::error::Pull request #$PR_NUMBER could not be re-read after the merge attempt."',
+        "            exit 1",
+        "          fi",
+        '          state="$(printf \'%s\' "$pr_json" | jq -r \'.state // ""\')"',
+        '          merge_sha="$(printf \'%s\' "$pr_json" | jq -r \'.mergeCommit.oid // ""\')"',
+        '          if [ "$state" = "MERGED" ]; then',
+        '            {',
+        '              echo "MERGE_RESULT=merged"',
+        '              echo "MERGE_SHA=$merge_sha"',
+        '            } >> "$GITHUB_ENV"',
+        "            exit 0",
+        "          fi",
+        '          if [ "${MERGE_ATTEMPT:-}" = "rejected" ]; then',
+        '            echo "REFUSAL_REASON=gh_merge_failed" >> "$GITHUB_ENV"',
+        '            echo "::error::The merge was refused by GitHub and pull request #$PR_NUMBER is still open."',
+        "            exit 1",
+        "          fi",
+        '          echo "REFUSAL_REASON=merge_outcome_ambiguous" >> "$GITHUB_ENV"',
+        '          echo "::error::The merge attempt for pull request #$PR_NUMBER could not be classified."',
+        "          exit 1",
+        "",
+        "      # ------------------------------------------------------------------",
+        "      # 6. Report the final result. This runs only AFTER the merge/read-back",
+        "      #    sequence — it reports what happened and decides nothing. The lease",
+        "      #    secret travels in the completion contract's own `lease_owner` field",
+        "      #    and appears nowhere else.",
+        "      # ------------------------------------------------------------------",
+        "      - name: Report the merge result to Bridge",
+        "        shell: bash",
+        "        run: |",
+        "          set -uo pipefail",
+        "          set +x",
+        "          umask 077",
+        '          curlrc="${RUNNER_TEMP}/bapi-complete.curlrc"',
+        '          reqbody="${RUNNER_TEMP}/bapi-complete.json"',
+        "          trap 'rm -f \"$curlrc\" \"$reqbody\"' EXIT",
+        "          jq -rn 'env.BAPI_API_KEY | \"header = \\\"X-API-Key: \\(.)\\\"\"' > \"$curlrc\"",
+        "          jq -n '{repo_name: (env.ACTION_KEY | split(\":\") | .[1] // \"\"), action_key: env.ACTION_KEY, expected_head_sha: env.EXPECTED_HEAD_SHA, result: \"merged\", merge_sha: env.MERGE_SHA, lease_owner: env.LEASE_OWNER}' > \"$reqbody\"",
+        "          code=\"$(curl --silent --show-error --no-progress-meter --retry 0 \\",
+        "            --max-time 30 \\",
+        '            --config "$curlrc" \\',
+        "            --header 'Content-Type: application/json' \\",
+        "            --request POST \\",
+        '            --data-binary "@$reqbody" \\',
+        "            --output /dev/null \\",
+        "            --write-out '%{http_code}' \\",
+        '            "${BAPI_BASE_URL%/}/vcs/pull-requests/$PR_NUMBER/merge/complete" || echo "000")"',
+        '          if [ "$code" = "200" ]; then',
+        '            echo "Reported the merge of pull request #$PR_NUMBER."',
+        "            exit 0",
+        "          fi",
+        "          # A merged pull request whose report was not accepted is an UNREPORTED",
+        "          # outcome, not an unmerged one. Bridge's reconciler recovers it, with",
+        "          # the lease's own expiry as the backstop; a repository administrator",
+        "          # only needs to intervene if that recovery does not close the row.",
+        '          echo "::error::The merge of pull request #$PR_NUMBER landed but its completion report was not accepted (HTTP $code); Bridge will reconcile it."',
+        '          echo "REFUSAL_REASON=completion_unreported" >> "$GITHUB_ENV"',
+        "          exit 1",
+        "",
+        "      # ------------------------------------------------------------------",
+        "      # 7. Bounded failure report. Attempted for every denial that resolved",
+        "      #    enough identity to name the attempt — which means the command",
+        "      #    fetch succeeded. A failure BEFORE that point has no pull request",
+        "      #    number, so the completion route cannot be addressed at all; the",
+        "      #    lease expiry is the reconciler's backstop for that window.",
+        "      #",
+        "      #    A 409 here is EXPECTED for a default-branch base or a drifted head:",
+        "      #    Bridge's completion path re-applies both guards above the failure",
+        "      #    branch and refuses. It is never retried.",
+        "      # ------------------------------------------------------------------",
+        "      - name: Report a denial to Bridge",
+        "        if: failure()",
+        "        shell: bash",
+        "        run: |",
+        "          set -uo pipefail",
+        "          set +x",
+        '          if [ -z "${PR_NUMBER:-}" ] || [ -z "${EXPECTED_HEAD_SHA:-}" ]; then',
+        '            echo "::warning::Not enough resolved identity to report this denial; Bridge reconciles it when the lease expires."',
+        "            exit 0",
+        "          fi",
+        '          if [ "${REFUSAL_REASON:-}" = "completion_unreported" ]; then',
+        '            echo "::warning::The merge landed; no failure report is appropriate."',
+        "            exit 0",
+        "          fi",
+        "          umask 077",
+        '          curlrc="${RUNNER_TEMP}/bapi-denial.curlrc"',
+        '          reqbody="${RUNNER_TEMP}/bapi-denial.json"',
+        "          trap 'rm -f \"$curlrc\" \"$reqbody\"' EXIT",
+        "          jq -rn 'env.BAPI_API_KEY | \"header = \\\"X-API-Key: \\(.)\\\"\"' > \"$curlrc\"",
+        "          jq -n '{repo_name: (env.ACTION_KEY | split(\":\") | .[1] // \"\"), action_key: env.ACTION_KEY, expected_head_sha: env.EXPECTED_HEAD_SHA, result: \"failed\", reason: (env.REFUSAL_REASON // \"merge_outcome_ambiguous\"), lease_owner: env.LEASE_OWNER}' > \"$reqbody\"",
+        "          code=\"$(curl --silent --show-error --no-progress-meter --retry 0 \\",
+        "            --max-time 30 \\",
+        '            --config "$curlrc" \\',
+        "            --header 'Content-Type: application/json' \\",
+        "            --request POST \\",
+        '            --data-binary "@$reqbody" \\',
+        "            --output /dev/null \\",
+        "            --write-out '%{http_code}' \\",
+        '            "${BAPI_BASE_URL%/}/vcs/pull-requests/$PR_NUMBER/merge/complete" || echo "000")"',
+        '          case "$code" in',
+        "            200)",
+        '              echo "Reported denial ${REFUSAL_REASON:-unknown} for pull request #$PR_NUMBER."',
+        "              ;;",
+        "            409)",
+        '              echo "::warning::Bridge refused the denial report as already settled (HTTP 409). This is expected for a default-branch base or a drifted head and is not retried."',
+        "              ;;",
+        "            *)",
+        '              echo "::warning::The denial report was not accepted (HTTP $code); Bridge reconciles this attempt when the lease expires. Escalate to a repository administrator if it does not clear."',
+        "              ;;",
+        "          esac",
+        "",
+    ];
+    return lines.join("\n");
+}