@bridge_gpt/mcp-server 0.2.59 → 0.2.60

package/build/merge-pull-request.js

@@ -78,7 +78,7 @@ import { DEFAULT_GATE_NAME, REQUIRED_CI_CHECKS_GREEN, REVIEW_STATE, normalizeChe
 import { MERGE_REVIEW_WAIVED_BY_DEGRADATION_REASON, VERDICTLESS_DISPOSITION_FAIL_OPEN, VERDICTLESS_DISPOSITION_PARK, } from "./conductor/git-ci-types.js";
 import { evaluateReviewCondition, normalizeReviewSnapshot, parseDoneGateConfig, } from "./conductor/done-gate.js";
 import { buildGateIdentity, makeMergeActionKey } from "./conductor/merge-identity.js";
-import { resolveLocalMergeMethod, runApprovedLocalMerge, } from "./conductor/local-merge.js";
+import { resolveLocalMergeMethod, runApprovedLocalMerge, resolveLocalMergeCredential, LOCAL_MERGE_CREDENTIAL_ENV_KEYS, LOCAL_MERGE_CREDENTIAL_MISSING_REASONS, } from "./conductor/local-merge.js";
 /**
  * The exact remediation for a `dry_run`. Fixed text, because a caller that has to
  * infer WHICH setting to flip from a reason code guesses wrong.
@@ -629,22 +629,86 @@ function interpretMergeResponse(body, expectedHeadSha, prNumber) {
 // ---------------------------------------------------------------------------
 /** The non-terminal status the server returns when it approves a local merge. */
 const LOCAL_APPROVAL_STATUS = "approved_for_local_execution";
-const DEFAULT_MERGE_EXECUTION = "local";
-/** Operator-fixable hints for the two preflight refusals. */
+export const DEFAULT_MERGE_EXECUTION = "local";
+/**
+ * The ONE place the legacy repository vocabulary is reconciled onto the typed
+ * policy vocabulary (BAPI-1133, A2). Exhaustive and pure.
+ *
+ * `local -> local` is the identity case. `server -> machine_token`, NOT
+ * `github_actions`: legacy `server` means the existing direct credentialed
+ * provider-API write through the App-mediated merge path
+ * (`executeApprovedLocalMerge`'s sibling branch on the server), so its typed
+ * equivalent is the direct-credential declaration. `github_actions` represents
+ * workflow-DISPATCH intent, which the legacy `server` behavior never performed
+ * and so can never be inferred from it. `server` is therefore structurally
+ * impossible as a {@link TypedMergeExecutionMode} — this function is the only
+ * place that mapping exists, so no other consumer can reimplement it
+ * differently.
+ */
+export function mapLegacyMergeExecutionModeToPolicyMode(mode) {
+    switch (mode) {
+        case "local":
+            return "local";
+        case "server":
+            return "machine_token";
+    }
+}
+/**
+ * Which configured credential a resolved legacy mode reads (BAPI-1136).
+ *
+ * Routed through {@link mapLegacyMergeExecutionModeToPolicyMode} rather than
+ * switching on the legacy value again, so there remains exactly ONE place where
+ * legacy `server` becomes typed `machine_token`. Typed `github_actions` never
+ * reaches this local path — that mode dispatches the customer's workflow and
+ * performs no local subprocess — so it falls back to the local key rather than
+ * inventing a third credential.
+ */
+export function resolveLocalCredentialMode(mode) {
+    const typed = mapLegacyMergeExecutionModeToPolicyMode(mode);
+    return typed === "machine_token" ? "machine_token" : "local";
+}
+/**
+ * Operator-fixable hints for every preflight and credential refusal.
+ *
+ * BAPI-1136 removed the `gh auth login` remediation outright. A merge no longer
+ * authenticates as whoever is logged into `gh`, so telling an operator to log in
+ * would send them to fix a thing that is not consulted — the most expensive kind
+ * of wrong hint, because following it appears reasonable and changes nothing.
+ *
+ * Each hint names the CONFIGURATION KEY to set, never where or how a secret
+ * manager should materialize the value: that is the operator's own infrastructure
+ * decision, and prescribing one would be guidance this tool cannot verify.
+ */
 const LOCAL_GH_HINTS = {
     local_gh_unavailable: "Install the GitHub CLI (`gh`) on the machine running this MCP server — local merges execute there.",
-    local_gh_unauthenticated: "Run `gh auth login` in the shell that hosts this MCP server — local merges use its GitHub session.",
+    local_merge_credential_missing: `Set ${LOCAL_MERGE_CREDENTIAL_ENV_KEYS.local} in the environment this MCP server is launched with. ` +
+        "It is a configured local scoped credential; Bridge never stores it and there is no ambient-login fallback.",
+    machine_merge_credential_missing: `Set ${LOCAL_MERGE_CREDENTIAL_ENV_KEYS.machine_token} in the environment this MCP server is launched with. ` +
+        "It is your machine user's credential; Bridge never stores it and there is no ambient-login fallback.",
+    local_merge_credential_invalid: `The configured ${LOCAL_MERGE_CREDENTIAL_ENV_KEYS.local} was rejected by GitHub. Rotate it and relaunch this MCP server.`,
+    machine_merge_credential_invalid: `The configured ${LOCAL_MERGE_CREDENTIAL_ENV_KEYS.machine_token} was rejected by GitHub. Rotate it and relaunch this MCP server.`,
+    local_merge_credential_unpermitted: `The configured ${LOCAL_MERGE_CREDENTIAL_ENV_KEYS.local} authenticates but cannot write to this repository. Grant it merge permission.`,
+    machine_merge_credential_unpermitted: `The configured ${LOCAL_MERGE_CREDENTIAL_ENV_KEYS.machine_token} authenticates but cannot write to this repository. Grant the machine user merge permission.`,
 };
 /**
- * Read the repository's merge execution mode.
+ * Read the repository's LEGACY merge execution mode.
  *
  * Mode is server-side configuration, never a tool argument: an agent must not be
  * able to choose who performs a privileged write. An unreadable or unrecognized
  * value falls back to `local`, which is the mode that works on an installation
  * without `contents: write` — defaulting to the broken mode on a transient
- * config read failure would park a perfectly mergeable pull request.
+ * config read failure would park a perfectly mergeable pull request. Total: every
+ * failure mode (network error, non-2xx, malformed body, missing/unknown
+ * `merge_execution`) resolves to {@link DEFAULT_MERGE_EXECUTION} rather than
+ * throwing.
+ *
+ * Returns only the legacy vocabulary — `local | server` — never a typed mode.
+ * `setup-epic.ts` maps this result through
+ * {@link mapLegacyMergeExecutionModeToPolicyMode} before composing it into a
+ * `RunPolicy` declaration; `mergePullRequestHandler` sends it straight to the
+ * existing merge route unchanged.
  */
-async function resolveMergeExecutionMode(deps) {
+export async function resolveMergeExecutionMode(deps) {
     try {
         const resp = await (deps.fetchImpl ?? fetch)(deps.buildGetUrl("/epic-runs/supervisor-config/defaults/", { repo_name: deps.repoName }), { headers: await deps.getHeaders() });
         if (!resp.ok)
@@ -718,7 +782,7 @@ async function reportLocalCompletion(deps, prNumber, body) {
  * left to time out; and a refusal here is always `needs_human`, because every
  * local failure this can produce is an operator fix, not a wait.
  */
-async function executeApprovedLocalMerge(deps, approval, prNumber, expectedHeadSha, actionKey) {
+async function executeApprovedLocalMerge(deps, approval, prNumber, expectedHeadSha, actionKey, credentialMode) {
     if (localApprovalMismatch(approval, prNumber, expectedHeadSha, actionKey)) {
         return envelope(false, "refused", "local_approval_mismatch", "needs_human", expectedHeadSha, prNumber);
     }
@@ -730,10 +794,34 @@ async function executeApprovedLocalMerge(deps, approval, prNumber, expectedHeadS
         gate: { name: DEFAULT_GATE_NAME },
         action_key: actionKey,
     };
+    // BAPI-1136. The credential is resolved HERE, before the executor is called,
+    // so an unconfigured mode refuses without spawning a privileged subprocess —
+    // and so the refusal names which key to set rather than surfacing whatever
+    // `gh` says when it has no identity.
+    const credential = resolveLocalMergeCredential(deps.runtimeEnv ?? process.env, credentialMode);
+    if (credential === null) {
+        const reason = LOCAL_MERGE_CREDENTIAL_MISSING_REASONS[credentialMode];
+        // The lease is still closed: an attempt that cannot run is an attempt that
+        // is over, and leaving the ledger row open would make the reconciler wait
+        // out a lease for a merge nobody is going to perform.
+        await reportLocalCompletion(deps, prNumber, {
+            repo_name: deps.repoName,
+            action_key: actionKey,
+            expected_head_sha: expectedHeadSha,
+            result: "failed",
+            reason,
+        });
+        const missingHint = LOCAL_GH_HINTS[reason];
+        return envelope(false, "refused", reason, "needs_human", expectedHeadSha, prNumber, {
+            ...(missingHint ? { hint: missingHint } : {}),
+        });
+    }
     let local;
     try {
         const runLocal = deps.runLocalMerge ?? runApprovedLocalMerge;
-        local = await runLocal(request, { method }, { env: process.env });
+        // Exactly the resolved credential — never `{ env: process.env }`, which is
+        // how the ambient identity used to reach the subprocess.
+        local = await runLocal(request, { method }, { credential });
     }
     catch {
         // The executor itself threw. Treat it exactly like a reported failure: close
@@ -891,7 +979,12 @@ export async function mergePullRequestHandler(deps, args) {
         if (executionMode === "local" &&
             isPlainObject(mergeJson) &&
             mergeJson.status === LOCAL_APPROVAL_STATUS) {
-            return text(withReviewWaiver(await executeApprovedLocalMerge(deps, mergeJson, prNumber, expectedHeadSha, actionKey), reviewWaiver));
+            return text(withReviewWaiver(await executeApprovedLocalMerge(deps, mergeJson, prNumber, expectedHeadSha, actionKey, 
+            // The AUTHORITATIVE typed axis decides which credential is read.
+            // Legacy `server` maps to typed `machine_token` through the one
+            // existing mapping function; nothing here re-derives that, and no
+            // tool argument can influence it.
+            resolveLocalCredentialMode(executionMode)), reviewWaiver));
         }
         return text(withReviewWaiver(interpretMergeResponse(mergeJson, expectedHeadSha, prNumber), reviewWaiver));
     }

package/build/merge-workflow-codeowners.js

@@ -0,0 +1,224 @@
+/**
+ * Customer-owned review artifacts for the merge workflow (BAPI-1136).
+ *
+ * The merge workflow is only as safe as the review gate on its path. This module
+ * renders the two artifacts that make that gate possible, and it renders NOTHING
+ * that enforces it — enforcement is a repository setting only the customer can
+ * apply.
+ *
+ * ## Why a fragment and not an edit to `.github/CODEOWNERS`
+ *
+ * A repository's CODEOWNERS file is live policy. An installer that rewrote it
+ * could reassign ownership of unrelated paths, drop a rule whose syntax it
+ * misparsed, or resolve a conflict nobody asked it to resolve — and it would do
+ * so inside a pull request whose reviewer is reading a workflow file, not a
+ * policy diff. So this emits a self-contained FRAGMENT at a dedicated path and
+ * tells the customer to merge it themselves. The fragment is real, reviewable
+ * CODEOWNERS syntax; it simply is not yet in force.
+ *
+ * ## Why the guidance is plain text
+ *
+ * It is read in a pull-request diff, in a terminal, and by a screen reader. So:
+ * descriptive headings, explicit "Required:" labels, short paragraphs, stable
+ * ordering, and no code block that needs horizontal scrolling.
+ *
+ * ## Secret discipline
+ *
+ * Neither renderer accepts, embeds, or invites a secret VALUE. The Bridge API
+ * key is named only — `BAPI_API_KEY` — and every command shown is one that
+ * cannot take a credential on argv.
+ */
+import { MERGE_WORKFLOW_EXPECTED_VERSION, MERGE_WORKFLOW_PATH, } from "./conductor/merge-execution-contract.js";
+import { MERGE_WORKFLOW_API_KEY_SECRET_NAME, MERGE_WORKFLOW_BASE_URL_VARIABLE_NAME, } from "./merge-workflow-config.js";
+/** Repo-relative path of the generated CODEOWNERS fragment. */
+export const MERGE_WORKFLOW_CODEOWNERS_RELPATH = ".bridge/merge-workflow/CODEOWNERS.fragment";
+/** Repo-relative path of the generated repository-rule guidance. */
+export const MERGE_WORKFLOW_GUIDANCE_RELPATH = ".bridge/merge-workflow/REPOSITORY-RULES.md";
+/**
+ * Every repo-relative path this installer may write, in the order a reader
+ * should see them. Exported as the single manifest so the preflight, the
+ * consent summary, the commit, and the install-state record cannot disagree
+ * about what "the managed artifacts" are.
+ */
+export const MERGE_WORKFLOW_MANAGED_RELPATHS = [
+    MERGE_WORKFLOW_PATH,
+    MERGE_WORKFLOW_CODEOWNERS_RELPATH,
+    MERGE_WORKFLOW_GUIDANCE_RELPATH,
+];
+/** Thrown when a code-owner value fails validation. Carries no rendered output. */
+export class MergeWorkflowCodeOwnerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MergeWorkflowCodeOwnerError";
+    }
+}
+/**
+ * A GitHub code owner: `@user` or `@org/team`.
+ *
+ * Deliberately rejects whitespace, quotes, `#` (which would comment out the rest
+ * of the CODEOWNERS line), `$`, `{`, `}`, and any second `/`. The pattern is an
+ * allowlist rather than a denylist so a character nobody thought about is
+ * rejected rather than rendered.
+ */
+const CODE_OWNER_PATTERN = /^@[A-Za-z0-9][A-Za-z0-9-]*(\/[A-Za-z0-9][A-Za-z0-9._-]*)?$/;
+const MAX_CODE_OWNER_LENGTH = 100;
+/**
+ * Values that parse as a code owner but are obviously a placeholder someone
+ * pasted from documentation. Accepting one would open a pull request assigning
+ * review of a write-enabled workflow to an account that does not exist, which
+ * reads as protected while protecting nothing.
+ */
+const PLACEHOLDER_CODE_OWNERS = new Set([
+    "@org/team",
+    "@owner/team",
+    "@your-org/your-team",
+    "@user",
+    "@username",
+    "@your-username",
+    "@example",
+    "@example/team",
+]);
+/**
+ * Validate a single code owner.
+ *
+ * Runs BEFORE any filesystem or git mutation — an invalid owner must cost
+ * nothing, and must never leave a half-written branch behind.
+ *
+ * @throws MergeWorkflowCodeOwnerError naming the problem, never echoing a value
+ *   longer than the bound above.
+ */
+export function validateMergeWorkflowCodeOwner(value) {
+    if (typeof value !== "string") {
+        throw new MergeWorkflowCodeOwnerError("--codeowner requires a value");
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new MergeWorkflowCodeOwnerError("--codeowner requires a non-empty value");
+    }
+    if (trimmed.length > MAX_CODE_OWNER_LENGTH) {
+        throw new MergeWorkflowCodeOwnerError("--codeowner value is too long");
+    }
+    if (/\s/.test(trimmed)) {
+        throw new MergeWorkflowCodeOwnerError("--codeowner takes exactly one owner; supply a single @user or @org/team");
+    }
+    if (!trimmed.startsWith("@")) {
+        throw new MergeWorkflowCodeOwnerError("--codeowner must start with @ (e.g. @org/team or @user)");
+    }
+    if (!CODE_OWNER_PATTERN.test(trimmed)) {
+        throw new MergeWorkflowCodeOwnerError("--codeowner must be a GitHub @user or @org/team handle");
+    }
+    if (PLACEHOLDER_CODE_OWNERS.has(trimmed.toLowerCase())) {
+        throw new MergeWorkflowCodeOwnerError("--codeowner looks like a documentation placeholder; supply the real reviewing team or user");
+    }
+    return trimmed;
+}
+/**
+ * Render the CODEOWNERS fragment for the merge-workflow path.
+ *
+ * Deterministic for a given owner, newline-terminated, and covering exactly one
+ * path. It claims no other file.
+ */
+export function renderMergeWorkflowCodeownersFragment(codeOwner) {
+    const owner = validateMergeWorkflowCodeOwner(codeOwner);
+    return [
+        "# Bridge-managed CODEOWNERS fragment for the Epic Implementer merge workflow.",
+        "#",
+        "# This file is NOT a CODEOWNERS file. GitHub reads CODEOWNERS only from",
+        "# .github/CODEOWNERS, CODEOWNERS, or docs/CODEOWNERS, so nothing here is in",
+        "# force until you copy the rule below into the file your repository actually",
+        "# uses. It is generated separately so an installer never rewrites live review",
+        "# policy on your behalf.",
+        "#",
+        "# The rule exists because " + MERGE_WORKFLOW_PATH + " is the one file in this",
+        "# repository that can perform a privileged merge. Whoever can change it can",
+        "# change what merges.",
+        "",
+        MERGE_WORKFLOW_PATH + " " + owner,
+        "",
+    ].join("\n");
+}
+/**
+ * Render the repository-rule guidance document.
+ *
+ * Deterministic for a given owner. States, in order: what was generated, what
+ * the customer must do, and what is NOT protected until they do it.
+ */
+export function renderMergeWorkflowGuidance(codeOwner) {
+    const owner = validateMergeWorkflowCodeOwner(codeOwner);
+    return [
+        "# Epic Implementer merge workflow — required repository setup",
+        "",
+        "Bridge generated three files in this pull request. Merging the pull request",
+        "installs them. It does not protect them: two of the three steps below are",
+        "repository settings that only you can apply.",
+        "",
+        "## What was generated",
+        "",
+        "- `" + MERGE_WORKFLOW_PATH + "` — the merge workflow itself, contract version " +
+            String(MERGE_WORKFLOW_EXPECTED_VERSION) + ".",
+        "- `" + MERGE_WORKFLOW_CODEOWNERS_RELPATH + "` — a CODEOWNERS rule for that path.",
+        "- `" + MERGE_WORKFLOW_GUIDANCE_RELPATH + "` — this document.",
+        "",
+        "## Required: create the repository secret",
+        "",
+        "Required. The workflow authenticates to Bridge with a repository-level Actions",
+        "secret named `" + MERGE_WORKFLOW_API_KEY_SECRET_NAME + "`, holding a Bridge API",
+        "key for this repository.",
+        "",
+        "Create it through GitHub's own secret interface — repository Settings, then",
+        "Secrets and variables, then Actions. Bridge never sees, transmits, stores, or",
+        "writes the value: the installer that opened this pull request has no flag, no",
+        "prompt, and no file field for a credential, and the value must never be",
+        "committed, printed, or pasted into a project file.",
+        "",
+        "Optional: set a repository Actions VARIABLE named",
+        "`" + MERGE_WORKFLOW_BASE_URL_VARIABLE_NAME + "` if this repository talks to a",
+        "Bridge deployment other than the default. A variable, not a secret, and not a",
+        "workflow input — the base URL decides which server authorizes a merge, so it",
+        "is repository configuration rather than something a caller supplies per run.",
+        "",
+        "## Required: merge the CODEOWNERS rule into your active CODEOWNERS file",
+        "",
+        "Required. GitHub reads code owners only from `.github/CODEOWNERS`,",
+        "`CODEOWNERS`, or `docs/CODEOWNERS`. The generated fragment sits at",
+        "`" + MERGE_WORKFLOW_CODEOWNERS_RELPATH + "` and enforces nothing where it is.",
+        "",
+        "Copy its single rule into the CODEOWNERS file your repository actually uses,",
+        "keeping your existing rules intact. The rule is:",
+        "",
+        "```",
+        MERGE_WORKFLOW_PATH + " " + owner,
+        "```",
+        "",
+        "CODEOWNERS is last-match-wins, so place it after any broader rule that also",
+        "matches `.github/workflows/`.",
+        "",
+        "## Required: add the default-branch repository rule",
+        "",
+        "Required. A CODEOWNERS entry requests a reviewer. It does not require one.",
+        "Until you add a rule, anyone who can push to the default branch can rewrite",
+        "the merge workflow.",
+        "",
+        "In repository Settings, under Rules, add a ruleset targeting the default",
+        "branch that requires a pull request before merging and requires review from",
+        "code owners. Restricting who can bypass the ruleset matters as much as the",
+        "rule itself.",
+        "",
+        "## What is not protected until you finish",
+        "",
+        "Enforcement is absent until the repository rule above is in place. Between",
+        "merging this pull request and applying that rule, the workflow is installed",
+        "and reviewable but its path is not review-gated.",
+        "",
+        "## If something fails later",
+        "",
+        "Bridge refuses to dispatch a merge when it cannot detect the workflow, or when",
+        "the workflow's contract version is not the one Bridge understands. Escalate",
+        "both to a repository administrator — they are the only person who can check",
+        "that the workflow is present on the default branch, that Actions is enabled",
+        "for this repository, and that the file has not been hand-edited. Re-running",
+        "the installer reports which of the four states the file is in and never",
+        "overwrites a file it did not write.",
+        "",
+    ].join("\n");
+}

package/build/merge-workflow-config.js

@@ -0,0 +1,133 @@
+/**
+ * Configuration names and the command-fetch contract the RENDERED merge workflow
+ * consumes (BAPI-1136).
+ *
+ * ## Why these live here and not in `conductor/merge-execution-contract.ts`
+ *
+ * That module documents itself as the byte-for-byte TypeScript MIRROR of
+ * `api/library/epic_implementer/merge_execution_contract.py`: every constant in
+ * it has a Python twin whose spelling must match exactly. None of the values
+ * below has one. They are the workflow's OWN runtime configuration — a GitHub
+ * Actions secret name, a GitHub Actions variable name, a fallback base URL, and
+ * the shape of an endpoint the rendered YAML calls — so keeping them in the
+ * mirror would have made that module two things at once.
+ *
+ * There is also a mechanical reason, and it is a good one: a static invariant
+ * forbids any `conductor/*.ts` except `bridge-api-client.ts` from containing the
+ * literal `BAPI_BASE_URL`, because conductor code must reach the Bridge API only
+ * through its dedicated sanitized client. This module reaches the Bridge API not
+ * at all — it names a string that the CUSTOMER's workflow reads from its own
+ * repository variables — but the guard is textual, and the right response to it
+ * was to put these values where they belong rather than to work around it.
+ */
+import { MERGE_WORKFLOW_EXPECTED_VERSION } from "./conductor/merge-execution-contract.js";
+/** Re-exported so a consumer needs one import for the workflow's whole contract. */
+export { MERGE_WORKFLOW_EXPECTED_VERSION };
+/**
+ * The ONE repository-level GitHub Actions secret the rendered workflow reads.
+ *
+ * Only the NAME lives here, and only the name ever appears in a rendered
+ * template, an installer message, or the README. The customer provisions the
+ * value themselves through GitHub's own secret UI or API; the installer never
+ * accepts, transmits, prints, or writes it (ratified review decision E-18).
+ *
+ * Repository-scoped rather than organization-scoped on purpose: a repository
+ * reviewer can create a repository secret, while an organization secret needs a
+ * second actor the install command cannot name in advance.
+ */
+export const MERGE_WORKFLOW_API_KEY_SECRET_NAME = "BAPI_API_KEY";
+/**
+ * The repository-level Actions VARIABLE (not a secret) that overrides the Bridge
+ * base URL the workflow calls back into.
+ *
+ * A variable, not a dispatch input: the two dispatch inputs are fixed at
+ * `action_key` and `lease_owner` (BAPI-1134), and a base URL supplied by whoever
+ * triggered the dispatch would let the caller choose which server authorizes the
+ * merge. Absent, the workflow uses {@link MERGE_WORKFLOW_DEFAULT_BASE_URL}.
+ */
+export const MERGE_WORKFLOW_BASE_URL_VARIABLE_NAME = "BAPI_BASE_URL";
+/** The hosted Bridge API the rendered workflow falls back to. */
+export const MERGE_WORKFLOW_DEFAULT_BASE_URL = "https://bridgegpt-api.com";
+/**
+ * The durable merge-command fetch contract the rendered workflow consumes.
+ *
+ * ## Why a named contract rather than a live route
+ *
+ * The SERVER half of this contract is not in the tree. BAPI-1134 shipped the
+ * dispatch emitter with its durable-command persistence resolved lazily
+ * (`api/library/epic_implementer/reconciler.py`'s
+ * `_resolve_durable_merge_command_store`, which imports
+ * `api.library.vcs.epic_implementer_merge_command_store.persist_merge_command`
+ * and returns `None` today), and recorded that store as "a slice of its own"
+ * blocked on an unnamed sibling. The BAPI-1136 review ratified carving that
+ * store and its fetch endpoint out as a separate A2 child that lands FIRST
+ * (decision E-14), with this child writing the workflow's fetch step against the
+ * named contract below.
+ *
+ * ## What that means operationally
+ *
+ * Until the sibling child lands, the endpoint answers 404 and the rendered
+ * workflow refuses with `merge_command_unavailable` before touching the pull
+ * request — no retry, no merge, no completion report. The merge lane is
+ * therefore INERT by construction rather than by a flag someone could flip: no
+ * dispatch is emitted at all while the command store is absent, and a dispatch
+ * that somehow arrived would be refused at the first step. That is the block on
+ * operational enablement; {@link MERGE_WORKFLOW_EXPECTED_VERSION} exact equality
+ * remains the SEPARATE deploy-ordering refusal it already was, and neither
+ * substitutes for the other.
+ *
+ * ## Shape
+ *
+ * Keyed by `action_key`, NOT by pull request number: the workflow learns the
+ * pull request FROM the command, so a PR-scoped route could not be called. That
+ * is also why a fetch failure cannot be reported through
+ * `POST /vcs/pull-requests/{pr}/merge/complete` — the path parameter is not yet
+ * resolved — and the lease's own expiry is the reconciler's backstop for that
+ * one window.
+ */
+export const MERGE_COMMAND_FETCH_METHOD = "POST";
+/** Root-mounted, repo-authorized path of the durable command fetch. */
+export const MERGE_COMMAND_FETCH_PATH = "/vcs/merge-commands/fetch";
+/**
+ * The request fields the fetch accepts, in the contract's own spelling.
+ *
+ * `lease_owner` is the per-attempt secret BAPI-1134 mints; it is presented here
+ * as PROOF that this dispatch is the live attempt, never echoed, and never a
+ * response field.
+ */
+export const MERGE_COMMAND_FETCH_REQUEST_FIELDS = [
+    "repo_name",
+    "action_key",
+    "lease_owner",
+];
+/**
+ * The separator and field position the Bridge repository name occupies inside a
+ * merge action key (`merge:{repo}:{pr}:{head_sha}:{gate_identity}`, built by
+ * `makeMergeActionKey`).
+ *
+ * The workflow derives `repo_name` from the key it was dispatched with rather
+ * than accepting a third dispatch input, so the Bridge-side identity and the
+ * attempt identity cannot disagree.
+ */
+export const MERGE_ACTION_KEY_REPO_FIELD_INDEX = 1;
+/**
+ * The response projection the workflow consumes, in the contract's own spelling.
+ *
+ * `lease_owner` is deliberately ABSENT: a response that echoed the live
+ * per-attempt secret would hand it to every log that captured the body.
+ *
+ * `github_repository` is the provider-side `owner/name` the command was issued
+ * against. The workflow compares it with `github.repository` before reading the
+ * pull request, so a command minted for a different repository cannot actuate
+ * here even if its key and lease were presented correctly.
+ */
+export const MERGE_COMMAND_FETCH_RESPONSE_FIELDS = [
+    "action_key",
+    "repo_name",
+    "github_repository",
+    "pr_number",
+    "expected_head_sha",
+    "merge_method",
+    "execution",
+    "lease_expires_at",
+];

package/build/merge-workflow-drift.js

@@ -0,0 +1,66 @@
+/**
+ * Canonical byte identity for the Epic Implementer merge workflow (BAPI-1136).
+ *
+ * The merge workflow is the one file in a customer repository that can perform a
+ * privileged write on Bridge's behalf, so "is the installed copy the copy Bridge
+ * ships?" has to be answerable cheaply, in more than one place, and with one
+ * answer. This module is that one place.
+ *
+ * It follows `claude-review-workflow-drift.ts`'s shape deliberately: a leaf
+ * module with NO filesystem, network, or subprocess access, importing only the
+ * shared Git blob hash so two workflow-identity implementations cannot drift
+ * apart about what "the same file" means. Callers acquire bytes however their
+ * own layer already does and hand them in.
+ *
+ * Nothing here logs file content: a classification carries a path, a pair of
+ * SHAs, and a closed-vocabulary state — never bytes, never provider text.
+ */
+import { computeGitBlobSha } from "./claude-review-workflow-drift.js";
+import { MERGE_WORKFLOW_PATH } from "./conductor/merge-execution-contract.js";
+import { renderEpicImplementerMergeWorkflow } from "./merge-workflow.js";
+export { MERGE_WORKFLOW_PATH };
+/**
+ * The Git blob SHA-1 of the workflow this build renders.
+ *
+ * Computed, never hardcoded. A checked-in literal would be a second byte source
+ * the renderer could silently diverge from — exactly the drift this module
+ * exists to make impossible.
+ */
+export function canonicalMergeWorkflowSha() {
+    return computeGitBlobSha(Buffer.from(renderEpicImplementerMergeWorkflow(), "utf8"));
+}
+/**
+ * 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`.
+ */
+export const MANAGED_MERGE_WORKFLOW_HISTORY = new Map();
+/**
+ * Classify an installed copy against the canonical bytes.
+ *
+ * `existing` is `null` for an absent file. The comparison is on RAW BYTES, not
+ * normalized text: a copy that differs only in line endings is still a copy this
+ * installer did not write, and treating it as identical would let a rewrite hide
+ * behind a whitespace-insensitive compare.
+ */
+export function classifyMergeWorkflowContent(existing) {
+    if (existing === null)
+        return "not_installed";
+    const canonical = renderEpicImplementerMergeWorkflow();
+    if (existing === canonical)
+        return "identical";
+    const sha = computeGitBlobSha(Buffer.from(existing, "utf8"));
+    if (MANAGED_MERGE_WORKFLOW_HISTORY.has(sha))
+        return "managed_version_older";
+    return "modified_or_unrecognized";
+}
+/** Operator-facing gloss for each classification. Secret-free and path-only. */
+export const MERGE_WORKFLOW_CLASSIFICATION_TEXT = {
+    not_installed: `${MERGE_WORKFLOW_PATH} is not installed`,
+    identical: `${MERGE_WORKFLOW_PATH} already matches the version this build ships`,
+    managed_version_older: `${MERGE_WORKFLOW_PATH} is an older Bridge-managed version and can be upgraded`,
+    modified_or_unrecognized: `${MERGE_WORKFLOW_PATH} has been modified or is not a version Bridge published`,
+};