@bridge_gpt/mcp-server 0.2.59 → 0.2.62

package/build/merge-workflow.js

@@ -0,0 +1,956 @@
+/**
+ * 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.
+ *
+ * ## Two jobs, one managed file (contract version 2, BAPI-1259)
+ *
+ * The `operation` dispatch input selects exactly one job. `child_merge` (the
+ * default, and the only value Bridge's child-merge dispatch ever implies) runs
+ * the unchanged `merge` job. `integration_action` runs the `integration` job,
+ * which performs ONE server-issued integration action — merging the base into
+ * the exact run-bound epic branch (`sync_base`), or taking the ONE matching
+ * integration pull request out of draft (`mark_ready`) — fetched from Bridge's
+ * dedicated integration-action contract, never from the merge-command contract.
+ * The integration job has no merge-pull-request step at all: no path in this
+ * file merges an integration pull request into the default branch.
+ *
+ * ## 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 { CHILD_MERGE_WORKFLOW_OPERATION, INTEGRATION_ACTION_FETCH_PATH, INTEGRATION_ACTION_PROTOCOL_VERSION, INTEGRATION_ACTION_REPORT_PATH, INTEGRATION_ACTION_WORKFLOW_OPERATION, 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",
+];
+/**
+ * Every refusal the rendered `integration` job can emit (BAPI-1259), as a
+ * closed vocabulary. Kept separate from {@link MERGE_WORKFLOW_REFUSAL_REASONS}
+ * so neither job can emit the other's refusal by accident.
+ */
+export const INTEGRATION_WORKFLOW_REFUSAL_REASONS = [
+    /** The repository-level Bridge API key secret is absent or empty. */
+    "bridge_api_key_secret_missing",
+    /** Bridge did not return the integration action under this dispatch's lease. */
+    "integration_action_unavailable",
+    /** The fetched action is unusable here: wrong version, actor, operation, or shape. */
+    "integration_action_rejected",
+    /** The action names a repository or action id that is not this workflow's live context. */
+    "repository_identity_mismatch",
+    /** The repository default branch could not be read, so the branch guard cannot be applied. */
+    "default_branch_unresolved",
+    /** The action's epic branch IS the repository default branch. Never retried. */
+    "epic_branch_is_default_branch",
+];
+/**
+ * The closed outcome tokens the `integration` job may report. Mirrors the
+ * server's `INTEGRATION_ACTION_OUTCOMES`; the job reports FACTS only.
+ */
+export const INTEGRATION_WORKFLOW_REPORTED_OUTCOMES = [
+    "applied",
+    "already_satisfied",
+    "conflict",
+    "authority_unavailable",
+    "authority_lost",
+    "head_drift",
+    "pr_ambiguous",
+    "indeterminate",
+    "failed",
+];
+/**
+ * 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.",
+        "#",
+        "# THE INTEGRATION JOB (contract version 2)",
+        "#",
+        "# Dispatched with `operation: integration_action`, the `integration` job runs",
+        "# instead of `merge`. It performs one integration action Bridge issued for an",
+        "# epic run: merge the base into the run's exact `epic/` branch, or take that",
+        "# epic's ONE integration pull request out of draft. It fetches the action from",
+        "# Bridge's dedicated integration-action contract, re-validates the lease and",
+        "# the epic head immediately before writing, and reports only facts. It never",
+        "# merges a pull request, never writes the default branch, and never force-pushes.",
+        "#",
+        "# A push or a ready-for-review event made with this job's GITHUB_TOKEN does not",
+        "# start other workflows (GitHub's recursion guard). If your required checks",
+        "# must re-run after a base synchronization, prefer a local or machine-token",
+        "# executor for integration actions; otherwise Bridge blocks the run with a",
+        "# specific reason once its final-observation window lapses.",
+        "#",
+        "# 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",
+        "      operation:",
+        "        description: >-",
+        "          Which job runs. `" + CHILD_MERGE_WORKFLOW_OPERATION + "` (the default) merges an approved",
+        "          child pull request; `" + INTEGRATION_ACTION_WORKFLOW_OPERATION + "` performs one integration",
+        "          action. Selects a job only; the work itself is fetched from Bridge.",
+        "        required: false",
+        "        default: " + CHILD_MERGE_WORKFLOW_OPERATION,
+        "        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",
+        // A job-level `if:` is an expression without the `${{ }}` wrapper.
+        "    if: inputs.operation == '" + CHILD_MERGE_WORKFLOW_OPERATION + "'",
+        "    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 // ""\')"',
+        // BAPI-1257: NOT `.isCrossRepository // true`. jq's `//` yields its
+        // right-hand side when the left is null OR FALSE, so that spelling mapped a
+        // legitimate `false` (a same-repository pull request — every epic child)
+        // onto `true` and refused the merge as fork-origin. The lane could not merge
+        // anything. An explicit null test keeps the intended fail-closed default for
+        // an ABSENT field while reading a present `false` as itself.
+        '          cross_repo="$(printf \'%s\' "$pr_json" | jq -r \'if .isCrossRepository == null then true else .isCrossRepository end\')"',
+        '          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",
+        "",
+        "",
+        "  # =========================================================================",
+        "  # The integration job (contract version 2, BAPI-1259). Runs ONLY for",
+        "  # `operation: " + INTEGRATION_ACTION_WORKFLOW_OPERATION + "`. It performs one server-issued integration action and",
+        "  # reports facts. It contains no pull-request merge step.",
+        "  # =========================================================================",
+        "  integration:",
+        "    name: Perform one Epic Implementer integration action",
+        "    if: inputs.operation == '" + INTEGRATION_ACTION_WORKFLOW_OPERATION + "'",
+        "    runs-on: ubuntu-latest",
+        "    timeout-minutes: 10",
+        "    env:",
+        "      BAPI_BASE_URL: " + BASE_URL_EXPR,
+        "      BAPI_API_KEY: " + SECRET_EXPR,
+        "      ACTION_ID: " + gh("inputs.action_key"),
+        "      CLAIM_TOKEN: " + 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:",
+        "      - 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",
+        "",
+        "      # ------------------------------------------------------------------",
+        "      # Fetch the action. This is the ONLY source of what to do: the",
+        "      # operation, the exact epic branch, and the expected heads. The claim",
+        "      # token reaches Bridge in a jq-built body and the key through a 0600",
+        "      # curl config file; neither is ever an argv element.",
+        "      # ------------------------------------------------------------------",
+        "      - name: Fetch the integration action",
+        "        shell: bash",
+        "        run: |",
+        "          set -uo pipefail",
+        "          set +x",
+        "          umask 077",
+        "          curlrc=\"${RUNNER_TEMP}/bapi-integ.curlrc\"",
+        "          reqbody=\"${RUNNER_TEMP}/bapi-integ-request.json\"",
+        "          respbody=\"${RUNNER_TEMP}/bapi-integ-action.json\"",
+        "          trap 'rm -f \"$curlrc\" \"$reqbody\" \"$respbody\"' EXIT",
+        "          jq -rn 'env.BAPI_API_KEY | \"header = \\\"X-API-Key: \\(.)\\\"\"' > \"$curlrc\"",
+        "          jq -n '{protocol_version: " + String(INTEGRATION_ACTION_PROTOCOL_VERSION) + ", repo_name: (env.ACTION_ID | split(\":\") | .[1] // \"\"), action_id: env.ACTION_ID, claim_token: env.CLAIM_TOKEN}' > \"$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 \"$respbody\" \\",
+        "            --write-out '%{http_code}' \\",
+        "            \"${BAPI_BASE_URL%/}" + INTEGRATION_ACTION_FETCH_PATH + "\" || echo \"000\")\"",
+        "          if [ \"$code\" != \"200\" ]; then",
+        "            echo \"REFUSAL_REASON=integration_action_unavailable\" >> \"$GITHUB_ENV\"",
+        "            echo \"::error::Bridge did not return the integration action for this dispatch (HTTP $code).\"",
+        "            exit 1",
+        "          fi",
+        "          version=\"$(jq -r '.protocol_version // \"\"' \"$respbody\")\"",
+        "          action_id=\"$(jq -r '.action_id // \"\"' \"$respbody\")\"",
+        "          actor=\"$(jq -r '.actor // \"\"' \"$respbody\")\"",
+        "          operation=\"$(jq -r '.operation // \"\"' \"$respbody\")\"",
+        "          repo_name=\"$(jq -r '.repo_name // \"\"' \"$respbody\")\"",
+        "          provider_repository=\"$(jq -r '.provider_repository // \"\"' \"$respbody\")\"",
+        "          epic_key=\"$(jq -r '.epic_key // \"\"' \"$respbody\")\"",
+        "          epic_branch=\"$(jq -r '.epic_branch // \"\"' \"$respbody\")\"",
+        "          base_branch=\"$(jq -r '.base_branch // \"\"' \"$respbody\")\"",
+        "          expected_epic_head_sha=\"$(jq -r '.expected_epic_head_sha // \"\"' \"$respbody\")\"",
+        "          expected_base_sha=\"$(jq -r '.expected_base_sha // \"\"' \"$respbody\")\"",
+        "          pr_number=\"$(jq -r '.pr_number // \"\"' \"$respbody\")\"",
+        "          key_repo_name=\"$(jq -rn 'env.ACTION_ID | split(\":\") | .[1] // \"\"')\"",
+        "          if [ \"$provider_repository\" != \"$REPO_FULL_NAME\" ] \\",
+        "            || [ \"$action_id\" != \"$ACTION_ID\" ] \\",
+        "            || [ \"$repo_name\" != \"$key_repo_name\" ]; then",
+        "            echo \"REFUSAL_REASON=repository_identity_mismatch\" >> \"$GITHUB_ENV\"",
+        "            echo \"::error::The integration action does not match this repository and dispatch.\"",
+        "            exit 1",
+        "          fi",
+        "          # From here on the action is identified, so a refusal is reportable.",
+        "          echo \"ACTION_FETCHED=true\" >> \"$GITHUB_ENV\"",
+        "          if [ \"$version\" != \"" + String(INTEGRATION_ACTION_PROTOCOL_VERSION) + "\" ] || [ \"$actor\" != \"github_actions\" ]; then",
+        "            echo \"REFUSAL_REASON=integration_action_rejected\" >> \"$GITHUB_ENV\"",
+        "            echo \"::error::The integration action uses a protocol version or actor this workflow does not perform.\"",
+        "            exit 1",
+        "          fi",
+        "          case \"$operation\" in",
+        "            sync_base|mark_ready) ;;",
+        "            *)",
+        "              echo \"REFUSAL_REASON=integration_action_rejected\" >> \"$GITHUB_ENV\"",
+        "              echo \"::error::The integration action names an operation this workflow does not perform.\"",
+        "              exit 1",
+        "              ;;",
+        "          esac",
+        "          case \"$epic_branch\" in",
+        "            epic/*) ;;",
+        "            *)",
+        "              echo \"REFUSAL_REASON=integration_action_rejected\" >> \"$GITHUB_ENV\"",
+        "              echo \"::error::The integration action does not name an epic branch.\"",
+        "              exit 1",
+        "              ;;",
+        "          esac",
+        "          if ! [[ \"$expected_epic_head_sha\" =~ ^[0-9a-f]{40}$ ]] \\",
+        "            || ! [[ \"$expected_base_sha\" =~ ^[0-9a-f]{40}$ ]] \\",
+        "            || [ -z \"$base_branch\" ] \\",
+        "            || ! [[ \"$pr_number\" =~ ^[0-9]*$ ]]; then",
+        "            echo \"REFUSAL_REASON=integration_action_rejected\" >> \"$GITHUB_ENV\"",
+        "            echo \"::error::The integration action carries unusable branch or commit fields.\"",
+        "            exit 1",
+        "          fi",
+        "          {",
+        "            echo \"OPERATION=$operation\"",
+        "            echo \"EPIC_KEY=$epic_key\"",
+        "            echo \"EPIC_BRANCH=$epic_branch\"",
+        "            echo \"BASE_BRANCH=$base_branch\"",
+        "            echo \"EXPECTED_EPIC_HEAD_SHA=$expected_epic_head_sha\"",
+        "            echo \"EXPECTED_BASE_SHA=$expected_base_sha\"",
+        "            echo \"ACTION_PR_NUMBER=$pr_number\"",
+        "          } >> \"$GITHUB_ENV\"",
+        "",
+        "      - name: Guard the epic 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 branch guard cannot be applied.\"",
+        "            exit 1",
+        "          fi",
+        "          # Hard denial, never retried: an integration action writes only the",
+        "          # run-bound epic branch, never the default branch.",
+        "          if [ \"$EPIC_BRANCH\" = \"$default_branch\" ]; then",
+        "            echo \"REFUSAL_REASON=epic_branch_is_default_branch\" >> \"$GITHUB_ENV\"",
+        "            echo \"::error::The integration action names the repository default branch; this workflow never writes it.\"",
+        "            exit 1",
+        "          fi",
+        "",
+        "      # ------------------------------------------------------------------",
+        "      # Revalidate IMMEDIATELY before writing: the lease and policy generation",
+        "      # (a fresh fetch must still succeed) and the live epic head (it must",
+        "      # still be the expected one). A mismatch is reported as a fact and",
+        "      # nothing is written.",
+        "      # ------------------------------------------------------------------",
+        "      - name: Revalidate authority and the epic head",
+        "        shell: bash",
+        "        run: |",
+        "          set -uo pipefail",
+        "          set +x",
+        "          umask 077",
+        "          curlrc=\"${RUNNER_TEMP}/bapi-integ-revalidate.curlrc\"",
+        "          reqbody=\"${RUNNER_TEMP}/bapi-integ-revalidate.json\"",
+        "          trap 'rm -f \"$curlrc\" \"$reqbody\"' EXIT",
+        "          jq -rn 'env.BAPI_API_KEY | \"header = \\\"X-API-Key: \\(.)\\\"\"' > \"$curlrc\"",
+        "          jq -n '{protocol_version: " + String(INTEGRATION_ACTION_PROTOCOL_VERSION) + ", repo_name: (env.ACTION_ID | split(\":\") | .[1] // \"\"), action_id: env.ACTION_ID, claim_token: env.CLAIM_TOKEN}' > \"$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%/}" + INTEGRATION_ACTION_FETCH_PATH + "\" || echo \"000\")\"",
+        "          if [ \"$code\" != \"200\" ]; then",
+        "            { echo \"OUTCOME=authority_lost\"; echo \"SKIP_WRITE=true\"; } >> \"$GITHUB_ENV\"",
+        "            echo \"::warning::The integration action's lease is no longer held (HTTP $code); nothing was written.\"",
+        "            exit 0",
+        "          fi",
+        "          live_head=\"$(gh api \"repos/$REPO_FULL_NAME/branches/$EPIC_BRANCH\" --jq '.commit.sha // \"\"' 2>/dev/null || echo \"\")\"",
+        "          if [ \"$live_head\" != \"$EXPECTED_EPIC_HEAD_SHA\" ]; then",
+        "            { echo \"OUTCOME=head_drift\"; echo \"SKIP_WRITE=true\"; } >> \"$GITHUB_ENV\"",
+        "            echo \"::warning::The epic branch moved away from the expected head; nothing was written.\"",
+        "            exit 0",
+        "          fi",
+        "",
+        "      # ------------------------------------------------------------------",
+        "      # sync_base: merge the EXACT expected base SHA into the run-bound epic",
+        "      # branch through the provider's merge API. No checkout, no force. The",
+        "      # outcome is read from the HTTP status and, when that is unknown, from",
+        "      # a read-back of the branch — never guessed, and never retried blindly.",
+        "      # ------------------------------------------------------------------",
+        "      - name: Merge the base into the epic branch",
+        "        if: env.OPERATION == 'sync_base' && env.SKIP_WRITE != 'true'",
+        "        shell: bash",
+        "        run: |",
+        "          set -uo pipefail",
+        "          set +x",
+        "          message=\"Merge $BASE_BRANCH into $EPIC_BRANCH ($EPIC_KEY integration preparation)\"",
+        "          out=\"$(gh api --include --method POST \"repos/$REPO_FULL_NAME/merges\" \\",
+        "            -f base=\"$EPIC_BRANCH\" -f head=\"$EXPECTED_BASE_SHA\" -f commit_message=\"$message\" \\",
+        "            2>/dev/null || true)\"",
+        "          http=\"$(printf '%s\\n' \"$out\" | head -n 1 | awk '{print $2}')\"",
+        "          body=\"$(printf '%s\\n' \"$out\" | sed '1,/^\\r*$/d')\"",
+        "          parents_of() {",
+        "            gh api \"repos/$REPO_FULL_NAME/commits/$1\" --jq '[.parents[].sha] | join(\" \")' 2>/dev/null || echo \"\"",
+        "          }",
+        "          outcome=\"indeterminate\"",
+        "          result=\"\"",
+        "          case \"$http\" in",
+        "            201)",
+        "              result=\"$(printf '%s' \"$body\" | jq -r '.sha // \"\"' 2>/dev/null || echo \"\")\"",
+        "              if [ -n \"$result\" ] && [ \"$(parents_of \"$result\")\" = \"$EXPECTED_EPIC_HEAD_SHA $EXPECTED_BASE_SHA\" ]; then",
+        "                outcome=\"applied\"",
+        "              else",
+        "                outcome=\"head_drift\"",
+        "              fi",
+        "              ;;",
+        "            204) outcome=\"already_satisfied\"; result=\"$EXPECTED_EPIC_HEAD_SHA\" ;;",
+        "            409) outcome=\"conflict\" ;;",
+        "            401|403|404) outcome=\"authority_unavailable\" ;;",
+        "            *)",
+        "              # Lost response: read the branch back and match it to THIS action.",
+        "              live_head=\"$(gh api \"repos/$REPO_FULL_NAME/branches/$EPIC_BRANCH\" --jq '.commit.sha // \"\"' 2>/dev/null || echo \"\")\"",
+        "              if [ -n \"$live_head\" ] && [ \"$live_head\" != \"$EXPECTED_EPIC_HEAD_SHA\" ] \\",
+        "                && [ \"$(parents_of \"$live_head\")\" = \"$EXPECTED_EPIC_HEAD_SHA $EXPECTED_BASE_SHA\" ]; then",
+        "                outcome=\"applied\"; result=\"$live_head\"",
+        "              fi",
+        "              ;;",
+        "          esac",
+        "          { echo \"OUTCOME=$outcome\"; echo \"RESULT_SHA=$result\"; } >> \"$GITHUB_ENV\"",
+        "",
+        "      # ------------------------------------------------------------------",
+        "      # mark_ready: find the ONE open pull request from the epic branch to the",
+        "      # base branch (creating it only when absence is conclusive), confirm its",
+        "      # head is the expected epic head, and take it out of draft. There is no",
+        "      # merge command here.",
+        "      # ------------------------------------------------------------------",
+        "      - name: Take the integration pull request out of draft",
+        "        if: env.OPERATION == 'mark_ready' && env.SKIP_WRITE != 'true'",
+        "        shell: bash",
+        "        run: |",
+        "          set -uo pipefail",
+        "          set +x",
+        "          owner=\"${REPO_FULL_NAME%%/*}\"",
+        "          list_prs() {",
+        "            gh api \"repos/$REPO_FULL_NAME/pulls?state=open&per_page=100&head=$owner:$EPIC_BRANCH&base=$BASE_BRANCH\" 2>/dev/null || echo \"\"",
+        "          }",
+        "          report() { { echo \"OUTCOME=$1\"; echo \"RESULT_PR=${2:-}\"; } >> \"$GITHUB_ENV\"; exit 0; }",
+        "          prs=\"$(list_prs)\"",
+        "          count=\"$(printf '%s' \"$prs\" | jq 'if type == \"array\" then length else -1 end' 2>/dev/null || echo -1)\"",
+        "          if [ \"$count\" = \"0\" ]; then",
+        "            gh api --method POST \"repos/$REPO_FULL_NAME/pulls\" \\",
+        "              -f title=\"$EPIC_KEY: epic integration branch\" -f head=\"$EPIC_BRANCH\" \\",
+        "              -f base=\"$BASE_BRANCH\" -F draft=false \\",
+        "              -f body=\"Integration pull request for $EPIC_KEY, opened by the Epic Implementer. A human reviews and merges it.\" \\",
+        "              >/dev/null 2>&1 || true",
+        "            # Confirm by probing, never by trusting the create response: a lost",
+        "            # response must not become a second pull request.",
+        "            prs=\"$(list_prs)\"",
+        "            count=\"$(printf '%s' \"$prs\" | jq 'if type == \"array\" then length else -1 end' 2>/dev/null || echo -1)\"",
+        "          fi",
+        "          if [ \"$count\" = \"-1\" ] || [ \"$count\" = \"0\" ]; then report indeterminate; fi",
+        "          if [ \"$count\" != \"1\" ]; then report pr_ambiguous; fi",
+        "          number=\"$(printf '%s' \"$prs\" | jq -r '.[0].number // \"\"')\"",
+        "          head_sha=\"$(printf '%s' \"$prs\" | jq -r '.[0].head.sha // \"\"')\"",
+        "          draft=\"$(printf '%s' \"$prs\" | jq -r 'if .[0].draft == true then \"true\" else \"false\" end')\"",
+        "          if [ \"$head_sha\" != \"$EXPECTED_EPIC_HEAD_SHA\" ]; then report head_drift \"$number\"; fi",
+        "          if [ \"$draft\" != \"true\" ]; then report already_satisfied \"$number\"; fi",
+        "          gh pr ready \"$number\" --repo \"$REPO_FULL_NAME\" >/dev/null 2>&1 || true",
+        "          after=\"$(gh api \"repos/$REPO_FULL_NAME/pulls/$number\" --jq 'if .draft == false then \"ready\" else \"draft\" end' 2>/dev/null || echo \"\")\"",
+        "          case \"$after\" in",
+        "            ready) report applied \"$number\" ;;",
+        "            draft) report failed \"$number\" ;;",
+        "            *) report indeterminate \"$number\" ;;",
+        "          esac",
+        "",
+        "      # ------------------------------------------------------------------",
+        "      # Report facts. Runs whenever the action was identified, including after",
+        "      # a refusal. Bridge records the report and decides nothing from it: the",
+        "      # reconciler re-observes the repository before completing any run.",
+        "      # ------------------------------------------------------------------",
+        "      - name: Report the integration action facts to Bridge",
+        "        if: always() && env.ACTION_FETCHED == 'true'",
+        "        shell: bash",
+        "        run: |",
+        "          set -uo pipefail",
+        "          set +x",
+        "          umask 077",
+        "          curlrc=\"${RUNNER_TEMP}/bapi-integ-report.curlrc\"",
+        "          reqbody=\"${RUNNER_TEMP}/bapi-integ-report.json\"",
+        "          trap 'rm -f \"$curlrc\" \"$reqbody\"' EXIT",
+        "          jq -rn 'env.BAPI_API_KEY | \"header = \\\"X-API-Key: \\(.)\\\"\"' > \"$curlrc\"",
+        "          jq -n '{protocol_version: " + String(INTEGRATION_ACTION_PROTOCOL_VERSION) + ", repo_name: (env.ACTION_ID | split(\":\") | .[1] // \"\"), action_id: env.ACTION_ID, claim_token: env.CLAIM_TOKEN, outcome: (if (env.REFUSAL_REASON // \"\") != \"\" then \"failed\" else (env.OUTCOME // \"indeterminate\") end), result_epic_head_sha: (if (env.RESULT_SHA // \"\") == \"\" then null else env.RESULT_SHA end), pr_number: (if (env.RESULT_PR // \"\") == \"\" then null else (env.RESULT_PR | tonumber) end), detail_code: (if (env.REFUSAL_REASON // \"\") == \"\" then null else env.REFUSAL_REASON end)}' > \"$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%/}" + INTEGRATION_ACTION_REPORT_PATH + "\" || echo \"000\")\"",
+        "          if [ \"$code\" = \"200\" ]; then",
+        "            echo \"Reported the integration action facts.\"",
+        "            exit 0",
+        "          fi",
+        "          echo \"::warning::The integration action report was not accepted (HTTP $code); Bridge re-observes the repository and expires the action on its own.\"",
+        "          exit 0",
+        "",
+    ];
+    return lines.join("\n");
+}