@bridge_gpt/mcp-server 0.2.60 → 0.2.62

package/build/merge-workflow-config.js

@@ -131,3 +131,57 @@ export const MERGE_COMMAND_FETCH_RESPONSE_FIELDS = [
     "execution",
     "lease_expires_at",
 ];
+/**
+ * The integration-action actor contract the rendered workflow's
+ * `integration` job consumes (BAPI-1259).
+ *
+ * A DEDICATED contract, deliberately not an extension of the merge-command
+ * fetch above: an integration action is never a child merge, and a workflow
+ * that could interpret one as the other would be one refactor away from
+ * merging an integration pull request. The routes are mounted under
+ * {@link INTEGRATION_ACTION_PATH_PREFIX} in `api/routes/__init__.py`.
+ *
+ * The dispatch inputs only wake and correlate: `action_key` carries the
+ * server-minted action id (`integ:{repo}:{hex}`) and `lease_owner` carries the
+ * server-minted per-claim token. Everything the job acts on — the operation,
+ * the exact epic branch, the expected heads — comes from the fetch response.
+ */
+export const INTEGRATION_ACTION_PATH_PREFIX = "/epic-integration-actions";
+/** Re-read the approved work under the dispatched lease. */
+export const INTEGRATION_ACTION_FETCH_PATH = INTEGRATION_ACTION_PATH_PREFIX + "/fetch";
+/** Report bounded facts. Returns an acknowledgement only. */
+export const INTEGRATION_ACTION_REPORT_PATH = INTEGRATION_ACTION_PATH_PREFIX + "/report";
+/** The one protocol version the rendered job speaks (exact equality server-side). */
+export const INTEGRATION_ACTION_PROTOCOL_VERSION = 1;
+/** The dispatch `operation` value that selects the integration job. */
+export const INTEGRATION_ACTION_WORKFLOW_OPERATION = "integration_action";
+/** The dispatch `operation` default that selects the child-merge job. */
+export const CHILD_MERGE_WORKFLOW_OPERATION = "child_merge";
+/**
+ * The operations the WORKFLOW may perform. `correct` is absent on purpose: a
+ * correction needs a worker, which only a local or durable executor runs, so the
+ * server never issues one to the workflow and the job refuses one if it arrives.
+ */
+export const INTEGRATION_WORKFLOW_OPERATIONS = ["sync_base", "mark_ready"];
+/** The request fields of the fetch, in the contract's own spelling. */
+export const INTEGRATION_ACTION_FETCH_REQUEST_FIELDS = [
+    "protocol_version",
+    "repo_name",
+    "action_id",
+    "claim_token",
+];
+/** The response fields the rendered job reads from the fetch. */
+export const INTEGRATION_ACTION_FETCH_RESPONSE_FIELDS = [
+    "protocol_version",
+    "action_id",
+    "operation",
+    "actor",
+    "repo_name",
+    "provider_repository",
+    "epic_key",
+    "epic_branch",
+    "base_branch",
+    "expected_epic_head_sha",
+    "expected_base_sha",
+    "pr_number",
+];

package/build/merge-workflow-drift.js

@@ -33,11 +33,42 @@ export function canonicalMergeWorkflowSha() {
  * Every Bridge-published historical rendering of the merge workflow, by Git blob
  * SHA, with the contract version it declared.
  *
- * Empty at contract version 1: there is no earlier published version to upgrade
- * FROM. A future contract version adds its predecessor's SHA here, and only
- * then can {@link classifyMergeWorkflowContent} return `managed_version_older`.
+ * A future contract version adds its predecessor's SHA here, and only then can
+ * {@link classifyMergeWorkflowContent} return `managed_version_older`.
+ *
+ * ## Why a version-1 entry exists without a version bump (BAPI-1257)
+ *
+ * The first entry is a rendering that was published AS version 1 and then
+ * corrected WITHIN version 1. Its fork-origin guard read
+ * `jq -r '.isCrossRepository // true'`, and jq's `//` yields its right-hand side
+ * when the left is null OR FALSE — so a same-repository pull request, which
+ * every epic child is, read as `true` and the merge was refused as fork-origin.
+ * That rendering could never merge anything.
+ *
+ * The marker version is deliberately NOT bumped: the wire contract, the dispatch
+ * inputs and the command-fetch protocol are all unchanged, and
+ * `MERGE_WORKFLOW_EXPECTED_VERSION` is the server's deploy-ordering check, not a
+ * byte checksum. But without this entry a repository holding that rendering
+ * classifies as `modified_or_unrecognized`, and the installer's preflight hard
+ * refuses to touch a workflow Bridge does not recognise — leaving no automated
+ * path off a copy that cannot merge. Registering the superseded SHA restores it:
+ * the copy classifies `managed_version_older` and the installer opens its
+ * ordinary upgrade pull request.
+ *
+ * The SHA is the Git blob SHA of the complete superseded rendering, which is
+ * what {@link canonicalMergeWorkflowSha} computes for the current one.
+ *
+ * ## The version-1 entry added by BAPI-1259
+ *
+ * `0d44c814…` is the last version-1 rendering (the one BAPI-1257 corrected).
+ * Contract version 2 adds the `operation` input and the integration job, so a
+ * repository holding that rendering is an ordinary managed older version and
+ * the installer opens its upgrade pull request.
  */
-export const MANAGED_MERGE_WORKFLOW_HISTORY = new Map();
+export const MANAGED_MERGE_WORKFLOW_HISTORY = new Map([
+    ["3d4956c9447223c37075069352cdd9aae2d561dc", 1],
+    ["0d44c81436005beb3c314de1b98eaf972ef3b4db", 1],
+]);
 /**
  * Classify an installed copy against the canonical bytes.
  *

package/build/merge-workflow.js

@@ -42,6 +42,18 @@
  * 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
@@ -54,7 +66,7 @@
  * 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";
+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.
  *
@@ -94,6 +106,40 @@ export const MERGE_WORKFLOW_REFUSAL_REASONS = [
     /** 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.
  *
@@ -156,6 +202,22 @@ export function renderEpicImplementerMergeWorkflow() {
         "#   * 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",
@@ -203,6 +265,14 @@ export function renderEpicImplementerMergeWorkflow() {
         "          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.",
@@ -222,6 +292,8 @@ export function renderEpicImplementerMergeWorkflow() {
         "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:",
@@ -394,7 +466,13 @@ export function renderEpicImplementerMergeWorkflow() {
         '          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\')"',
+        // 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"',
@@ -567,6 +645,312 @@ export function renderEpicImplementerMergeWorkflow() {
         "              ;;",
         "          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");
 }