@bridge_gpt/mcp-server 0.2.58 → 0.2.60

package/build/mcp-host-entry-adapter.js

@@ -10,6 +10,12 @@ export function adaptBridgeEntryForHostTarget(entry, target) {
         args: [...entry.args],
         env: { ...entry.env },
     };
+    // The marker belongs to the installed physical registration, never the
+    // portable logical entry or committed .bridge/config. Replacing an entry
+    // refreshes it; removing the registration removes it automatically.
+    delete physical.env.BAPI_MCP_HOST_FAMILY;
+    if (target.routingHostFamily)
+        physical.env.BAPI_MCP_HOST_FAMILY = target.routingHostFamily;
     if (adapter.transportType !== undefined)
         physical.type = adapter.transportType;
     if (adapter.extraEntryKeys)

package/build/mcp-host-targets.js

@@ -67,6 +67,7 @@ export function hostAdapterForTarget(target) {
 export const MCP_HOST_TARGETS = {
     "claude-code": {
         id: "claude-code",
+        routingHostFamily: "claude_code",
         label: "Claude Code",
         scope: "project",
         relPath: ".mcp.json",
@@ -106,6 +107,7 @@ export const MCP_HOST_TARGETS = {
     },
     codex: {
         id: "codex",
+        routingHostFamily: "codex",
         label: "OpenAI Codex",
         scope: "global",
         absPathResolver: (homedir) => joinPath(homedir, ".codex/config.toml"),

package/build/mcp-install-state.js

@@ -64,12 +64,46 @@ function normalizePlatforms(ids) {
     const wanted = new Set(ids);
     return HOST_PLATFORM_ORDER.filter((id) => wanted.has(id));
 }
-/** Dedupe + stably order relative project config paths. */
+/**
+ * Is this a plain, repository-relative POSIX path safe to record?
+ *
+ * BAPI-1136. The install manifest is read back by `doctor` and by the installer
+ * itself to decide which files Bridge manages. A recorded absolute path, a `..`
+ * escape, or a Windows separator therefore names a file OUTSIDE the project that
+ * a later tool would treat as project-owned. The install-state file's own path is
+ * excluded for the same reason — recording it would make the manifest claim
+ * itself as a managed artifact.
+ */
+export function isRecordableProjectPath(relPath) {
+    if (typeof relPath !== "string" || relPath.length === 0)
+        return false;
+    if (relPath.includes("\\"))
+        return false;
+    if (relPath.startsWith("/"))
+        return false;
+    if (/^[A-Za-z]:/.test(relPath))
+        return false;
+    if (relPath === MCP_INSTALL_STATE_RELPATH)
+        return false;
+    const segments = relPath.split("/");
+    if (segments.some((seg) => seg.length === 0 || seg === "." || seg === ".."))
+        return false;
+    return true;
+}
+/**
+ * Dedupe + stably order relative project config paths, DROPPING any path that is
+ * not recordable.
+ *
+ * BAPI-1136 widened this from a non-empty-string filter. The filter runs on the
+ * read side too, so a malformed path written by an older build (or by hand) is
+ * dropped rather than faithfully reserialized — a normalizer that preserves
+ * every value it was handed turns one bad write into a permanent one.
+ */
 function normalizeProjectPaths(paths) {
     const seen = new Set();
     const out = [];
     for (const p of paths) {
-        if (typeof p === "string" && p.length > 0 && !seen.has(p)) {
+        if (isRecordableProjectPath(p) && !seen.has(p)) {
             seen.add(p);
             out.push(p);
         }
@@ -337,8 +371,12 @@ async function persistMcpInstallState(cwd, state, finalPath, deps) {
  * has no field for one, and the serializer emits only schema-approved keys.
  */
 export async function recordInstalledProjectArtifact(cwd, relPath, deps) {
-    if (typeof relPath !== "string" || relPath.length === 0) {
-        return { ok: false, error: "artifact path must be a non-empty relative path" };
+    if (!isRecordableProjectPath(relPath)) {
+        return {
+            ok: false,
+            error: "artifact path must be a repository-relative POSIX path with no absolute prefix, " +
+                "traversal segment, empty segment, or backslash, and must not be the install-state file itself",
+        };
     }
     const existing = await readMcpInstallState(cwd, deps);
     const priorPlatforms = existing.status === "valid" ? existing.state.selectedPlatforms : [];

package/build/mcp-invoke.js

@@ -306,21 +306,21 @@ export async function resolveBapiInvocation(projectRoot, deps) {
         BAPI_PROJECT_ROOT: projectRoot,
         BAPI_REPO_NAME: repoName,
     };
-    // BAPI-527: `CONDUCTOR_NODE_PATH` is NON-SECRET operational metadata (the
+    // BAPI-527: `EPIC_IMPLEMENTER_NODE_PATH` is NON-SECRET operational metadata (the
     // captured conductor Node path used by the worker-ledger CLI subprocess).
     // `buildChildEnv` already inherits the full parent env, so this re-affirms the
     // pass-through explicitly and ONLY when present — it is a non-secret allowlist
     // entry, never a credential. It is emphatically NOT the MCP server's re-exec
     // command: the spawned command stays `deps.execPath` + `[scriptPath]` below.
-    const conductorNodePath = deps.env.CONDUCTOR_NODE_PATH;
+    const conductorNodePath = deps.env.EPIC_IMPLEMENTER_NODE_PATH;
     if (typeof conductorNodePath === "string" && conductorNodePath.trim().length > 0) {
-        overlay.CONDUCTOR_NODE_PATH = conductorNodePath;
+        overlay.EPIC_IMPLEMENTER_NODE_PATH = conductorNodePath;
     }
     // BAPI-727: overlay the endpoint ONLY when `--base-url` was supplied, mirroring
-    // the conditional `CONDUCTOR_NODE_PATH` overlay directly above. The absent case
+    // the conditional `EPIC_IMPLEMENTER_NODE_PATH` overlay directly above. The absent case
     // must add, delete, normalize, and override nothing — `buildChildEnv` already
     // inherits the parent's `BAPI_BASE_URL`, and the server keeps its own production
-    // default for callers that were never given a URL. Like `CONDUCTOR_NODE_PATH`,
+    // default for callers that were never given a URL. Like `EPIC_IMPLEMENTER_NODE_PATH`,
     // this is non-secret routing metadata, not a credential.
     if (typeof deps.baseUrl === "string" && deps.baseUrl.length > 0) {
         overlay.BAPI_BASE_URL = deps.baseUrl;

package/build/mcp-profile.js

@@ -15,7 +15,7 @@
  */
 const VALID_GROUPS = new Set([
     "core",
-    "conductor",
+    "epic_implementer",
     "estimation",
     "pipeline-authoring",
     "sfcc",
@@ -49,7 +49,7 @@ export function resolveProfiles(raw) {
         // rather than an implicit widening of an existing user's surface.
         return new Set([
             "core",
-            "conductor",
+            "epic_implementer",
             "estimation",
             "pipeline-authoring",
             "sfcc",

package/build/mcp-provisioning.js

@@ -67,7 +67,7 @@ export function serverNameForMcpTarget(target) {
  * node executable is a single substitutable field), and the npm-channel fallback
  * as `{ command: "npx", args: ["-y", "<spec>", "mcp-invoke", …] }`.
  *
- * BAPI-527: `.mcp.json` remains intentionally ENV-FREE. `CONDUCTOR_NODE_PATH`
+ * BAPI-527: `.mcp.json` remains intentionally ENV-FREE. `EPIC_IMPLEMENTER_NODE_PATH`
  * (the captured conductor Node path for the worker-ledger CLI subprocess) is NOT
  * written here — it is inherited at runtime from the worker SHELL env that
  * `start-tickets` injects at the spawn boundary, never stored as a registration
@@ -77,7 +77,7 @@ export function serverNameForMcpTarget(target) {
  *
  * BAPI-724: the executor caller's `invocation` is resolved BEFORE spawn from its
  * OWN running process (`resolveMcpShimInvocationForRuntime`, absolute-build-path
- * form preferred) and never depends on a worker-injected `CONDUCTOR_NODE_PATH`
+ * form preferred) and never depends on a worker-injected `EPIC_IMPLEMENTER_NODE_PATH`
  * or any other worker-shell env — the executor worker environment carries no
  * such key at all (see `executor/env.ts`).
  *

package/build/mcp-server-invocation.js

@@ -17,7 +17,7 @@
  * server file is invoked (`node <absPath>/index.js` vs `npx @…`). It does NOT
  * change WHICH Node binary runs that file — the `nodeExecutable` field is kept as
  * a single substitutable value (never string-concatenated into the command) so
- * the later Ticket 3 (P2) work can point it at `CONDUCTOR_NODE_PATH` without
+ * the later Ticket 3 (P2) work can point it at `EPIC_IMPLEMENTER_NODE_PATH` without
  * re-plumbing argv construction.
  */
 import path from "node:path";
@@ -48,7 +48,7 @@ export function isTransientNpxEntryPath(entryPath) {
  * Build the concrete `{ command, args }` launch pair for a target + worktree from
  * a structured invocation. Pure — no filesystem or process access. The
  * `nodeExecutable` is returned as the standalone `command`, never concatenated
- * with the server entry path, so `CONDUCTOR_NODE_PATH` can substitute it later.
+ * with the server entry path, so `EPIC_IMPLEMENTER_NODE_PATH` can substitute it later.
  */
 export function buildMcpShimCommand(invocation, target, absoluteWorktreePath) {
     if (invocation.form === "absolute-build-path") {
@@ -141,7 +141,7 @@ function basenameAnySep(filePath) {
  * NOTE (scope boundary): this ticket changes WHICH server file is invoked, not
  * WHICH Node runtime runs it. `nodeExecutable` defaults to `"node"` (NOT
  * `process.execPath`) to preserve today's worker runtime selection; Ticket 3 (P2)
- * can later inject `CONDUCTOR_NODE_PATH` into this single field.
+ * can later inject `EPIC_IMPLEMENTER_NODE_PATH` into this single field.
  */
 export function resolveMcpShimInvocationForRuntime(deps) {
     const nodeExecutable = deps.nodeExecutable ?? "node";

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.
@@ -102,6 +102,19 @@ const CI_NOT_GREEN_REASON = "ci_not_green";
  * moves an unreadable, unsupported, or malformed review configuration.
  */
 const REVIEW_NOT_APPROVED_REASON = "review_not_approved";
+/**
+ * BAPI-1234 — the server's migration-graph merge guard. Both are named here so
+ * the mapping is explicit rather than an accident of the default branch, and
+ * both are `needs_human`: repeating the call against the same base and head
+ * reproduces the same refusal. `migration_graph_invalid` means a human must
+ * renumber the PR's own migration; `migration_graph_unreadable` means the graph
+ * could not be proven either way. The exact reason is returned unchanged so the
+ * caller can tell them apart; no server-supplied text is added.
+ */
+const MIGRATION_GRAPH_REFUSAL_REASONS = new Set([
+    "migration_graph_invalid",
+    "migration_graph_unreadable",
+]);
 // ---------------------------------------------------------------------------
 // Envelope construction
 // ---------------------------------------------------------------------------
@@ -560,6 +573,8 @@ function retryHintForFailure(reason, ciSummary) {
     }
     if (reason === REVIEW_NOT_APPROVED_REASON)
         return "retry_later";
+    if (MIGRATION_GRAPH_REFUSAL_REASONS.has(reason))
+        return "needs_human";
     return "needs_human";
 }
 /**
@@ -614,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)
@@ -703,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);
     }
@@ -715,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
@@ -876,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");
+}