@bridge_gpt/mcp-server 0.2.59 → 0.2.60

package/build/merge-workflow-install.js

@@ -0,0 +1,638 @@
+/**
+ * `install-bridge conductor --merge-workflow` — the generate-and-PR installer
+ * (BAPI-1136).
+ *
+ * One command generates the Epic Implementer merge workflow plus its two review
+ * artifacts, commits them on a managed branch, pushes with the CUSTOMER's own
+ * git identity, and opens a pull request with the customer's own `gh`. It never
+ * merges that pull request, and Bridge never writes to the repository at all.
+ * The customer's review IS the security control: this workflow is the one file
+ * that can perform a privileged merge, so a human deciding to merge it is the
+ * whole point rather than an inconvenience on the way to automation.
+ *
+ * ## Domain logic lives here, not in the CLI
+ *
+ * `install-bridge.ts` parses arguments and builds seams. Everything below — the
+ * preflight, the four-way classification, the consent summary, the branch /
+ * commit / push / PR sequence — is here so it is unit-testable with in-memory
+ * fakes and so the CLI layer stays thin.
+ *
+ * ## Read-only until it is not
+ *
+ * The ENTIRE preflight completes before the first branch, file write,
+ * install-state write, commit, push, or pull request. That ordering is the
+ * design: a failure discovered halfway through leaves a branch, or a file, or a
+ * pushed ref in a customer's repository that they now have to understand and
+ * clean up. Nothing here can partially install.
+ *
+ * ## Four content states, and why `identical` is not the only no-op
+ *
+ * A file at the managed path is one of four things: absent, byte-identical to
+ * what this build renders, a complete older version Bridge itself published, or
+ * something else. Only the first and third are installable. "Something else"
+ * includes a hand-edit, a truncation, a newer version from a future build, and a
+ * file that merely claims a lower version in its marker — all of them get the
+ * same fail-closed treatment, because this installer cannot tell a benign edit
+ * from a hostile one and must not guess about a file that can merge code.
+ *
+ * ## Secret discipline
+ *
+ * No path here accepts, prompts for, reads, writes, or prints a credential. The
+ * Bridge API key is referenced by NAME only. Raw `git` and `gh` output never
+ * reaches the operator: every failure is a stable named reason plus one
+ * remediation sentence, because subprocess text is unbounded and can carry a
+ * remote URL with an embedded token.
+ */
+import { MERGE_WORKFLOW_EXPECTED_VERSION, MERGE_WORKFLOW_PATH, } from "./conductor/merge-execution-contract.js";
+import { MERGE_WORKFLOW_API_KEY_SECRET_NAME, } from "./merge-workflow-config.js";
+import { MERGE_WORKFLOW_CLASSIFICATION_TEXT, classifyMergeWorkflowContent, } from "./merge-workflow-drift.js";
+import { MERGE_WORKFLOW_CODEOWNERS_RELPATH, MERGE_WORKFLOW_GUIDANCE_RELPATH, MERGE_WORKFLOW_MANAGED_RELPATHS, MergeWorkflowCodeOwnerError, renderMergeWorkflowCodeownersFragment, renderMergeWorkflowGuidance, validateMergeWorkflowCodeOwner, } from "./merge-workflow-codeowners.js";
+import { renderEpicImplementerMergeWorkflow } from "./merge-workflow.js";
+import { MCP_INSTALL_STATE_RELPATH } from "./mcp-install-state.js";
+// ---------------------------------------------------------------------------
+// Managed identity
+// ---------------------------------------------------------------------------
+/** The managed branch this installer creates, for a fresh installation. */
+export const MERGE_WORKFLOW_INSTALL_BRANCH = "bridge/merge-workflow-v" + String(MERGE_WORKFLOW_EXPECTED_VERSION);
+/** The managed branch this installer creates when upgrading an older version. */
+export const MERGE_WORKFLOW_UPGRADE_BRANCH = "bridge/merge-workflow-upgrade-v" + String(MERGE_WORKFLOW_EXPECTED_VERSION);
+/** Fixed, secret-free commit subject for a fresh installation. */
+export const MERGE_WORKFLOW_INSTALL_COMMIT_SUBJECT = "Add the Bridge Epic Implementer merge workflow";
+/** Fixed, secret-free commit subject for an upgrade. */
+export const MERGE_WORKFLOW_UPGRADE_COMMIT_SUBJECT = "Upgrade the Bridge Epic Implementer merge workflow";
+/** Pull request title for a fresh installation. */
+export const MERGE_WORKFLOW_INSTALL_PR_TITLE = MERGE_WORKFLOW_INSTALL_COMMIT_SUBJECT;
+/** Pull request title for an upgrade. */
+export const MERGE_WORKFLOW_UPGRADE_PR_TITLE = MERGE_WORKFLOW_UPGRADE_COMMIT_SUBJECT;
+// ---------------------------------------------------------------------------
+// Outcomes
+// ---------------------------------------------------------------------------
+/**
+ * Every named failure this installer can report.
+ *
+ * Closed on purpose: each value is printed verbatim as the first token of a
+ * stderr line, so the vocabulary is an operator-facing contract, and the set has
+ * to be greppable rather than assembled from subprocess text.
+ */
+export const MERGE_WORKFLOW_INSTALL_FAILURE_REASONS = [
+    /** `git` is not on PATH. */
+    "git_unavailable",
+    /** `gh` is not on PATH. */
+    "gh_unavailable",
+    /** The requested directory is not the root of the active git worktree. */
+    "not_repository_root",
+    /** The worktree or index carries uncommitted changes. */
+    "worktree_not_clean",
+    /** The repository default branch could not be resolved, or the two sources disagreed. */
+    "default_branch_unresolved",
+    /** The push remote is missing, or is not a canonical github.com repository. */
+    "remote_not_github",
+    /** The local, remote, and `gh` repository identities do not agree. */
+    "repository_identity_mismatch",
+    /** `--codeowner` is missing or invalid. */
+    "codeowner_invalid",
+    /** The installed workflow is a hand-edit or an unrecognized version. */
+    "workflow_modified_or_unrecognized",
+    /** A companion artifact exists with contents this installer did not write. */
+    "companion_artifact_conflict",
+    /** An open managed pull request exists but does not match the expected shape. */
+    "existing_pr_unverifiable",
+    /** A filesystem write failed. */
+    "write_failed",
+    /** A git branch, stage, commit, or push failed. */
+    "git_failed",
+    /** Opening the pull request failed. */
+    "pr_open_failed",
+    /** A required write surface was declined, or no prompt was available. */
+    "consent_declined",
+];
+// ---------------------------------------------------------------------------
+// Path safety
+// ---------------------------------------------------------------------------
+/**
+ * Reject any managed path that is not a plain, repository-relative POSIX path.
+ *
+ * The three managed paths are constants, so this can never fire in production —
+ * which is exactly why it is here. It is the assertion that keeps a future edit
+ * from introducing an absolute path, a `..` escape, or a Windows separator into
+ * the one code path that writes files and stages them for commit.
+ */
+export function isSafeManagedRelPath(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;
+    const segments = relPath.split("/");
+    if (segments.some((s) => s.length === 0 || s === "." || s === ".."))
+        return false;
+    return true;
+}
+function joinCwd(cwd, rel) {
+    const base = cwd.endsWith("/") ? cwd.slice(0, -1) : cwd;
+    return `${base}/${rel}`;
+}
+function isEnoent(err) {
+    return typeof err === "object" && err !== null && err.code === "ENOENT";
+}
+/** Read a file, mapping "absent" to `null` and any other error to a throw. */
+async function readOrNull(deps, absPath) {
+    try {
+        return await deps.readFile(absPath);
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return null;
+        throw err;
+    }
+}
+// ---------------------------------------------------------------------------
+// Remote identity
+// ---------------------------------------------------------------------------
+/**
+ * Parse `owner/name` out of a git remote URL, accepting ONLY canonical
+ * github.com forms.
+ *
+ * GitHub Enterprise and every non-GitHub host return `null`. This feature is
+ * GitHub.com-only: the workflow it installs uses `${{ github.token }}` and the
+ * GitHub REST surface, and quietly "succeeding" against a host where the result
+ * cannot work would open a pull request that can never actuate anything.
+ */
+export function parseGithubRemote(remoteUrl) {
+    if (typeof remoteUrl !== "string")
+        return null;
+    const trimmed = remoteUrl.trim();
+    if (trimmed.length === 0)
+        return null;
+    const patterns = [
+        /^https:\/\/github\.com\/([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/,
+        /^ssh:\/\/git@github\.com\/([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/,
+        /^git@github\.com:([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/,
+    ];
+    for (const pattern of patterns) {
+        const m = pattern.exec(trimmed);
+        if (m)
+            return `${m[1]}/${m[2]}`;
+    }
+    return null;
+}
+/** One remediation sentence per named failure. Printed after the reason token. */
+const REMEDIATION = {
+    git_unavailable: "Install git and re-run; this command creates the branch with your own git.",
+    gh_unavailable: "Install the GitHub CLI (`gh`) and authenticate it; this command opens the pull request as you.",
+    not_repository_root: "Run this command from the root of the repository that should receive the workflow.",
+    worktree_not_clean: "Commit or set aside your local changes first; this command refuses to stage anything it did not generate.",
+    default_branch_unresolved: "Check that the repository has a default branch and that `gh` can read it, then re-run.",
+    remote_not_github: "Point the push remote at a github.com repository; this feature is GitHub.com-only.",
+    repository_identity_mismatch: "Make the local remote and the `gh` default repository agree, then re-run.",
+    codeowner_invalid: "Pass exactly one real reviewer as `--codeowner @org/team` or `--codeowner @user`.",
+    workflow_modified_or_unrecognized: "Review the existing file by hand; this command never overwrites a workflow Bridge did not write.",
+    companion_artifact_conflict: "Review the differing file by hand and remove or reconcile it, then re-run.",
+    existing_pr_unverifiable: "Inspect the open Bridge merge-workflow pull request by hand and close it if it is not the one you want.",
+    write_failed: "Check directory permissions for the repository and re-run.",
+    git_failed: "Check the reported branch with git by hand; nothing already created has been removed.",
+    pr_open_failed: "The branch is pushed; open the pull request by hand, or re-run this command to reuse it.",
+    consent_declined: "Re-run in an interactive terminal and accept the write to continue.",
+};
+function fail(reason) {
+    return { outcome: "failed", reason, remediation: REMEDIATION[reason] };
+}
+async function commandSucceeds(run, args) {
+    try {
+        const result = await run(args);
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function captureStdout(run, args) {
+    try {
+        const result = await run(args);
+        if (result.status !== 0)
+            return null;
+        return result.stdout.trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run the complete read-only preflight.
+ *
+ * Every check here is a read. Nothing it calls creates a branch, writes a file,
+ * touches install state, commits, pushes, or opens a pull request — which is
+ * what lets the caller treat a failure as "nothing happened".
+ *
+ * The progress lines are emitted in a fixed order — repository/worktree, default
+ * branch, remote, git, gh, code owner — so two runs on different machines
+ * produce comparable output.
+ */
+export async function runMergeWorkflowPreflight(deps, options) {
+    // Managed paths are constants; this guards a future edit, not today's input.
+    for (const relPath of MERGE_WORKFLOW_MANAGED_RELPATHS) {
+        if (!isSafeManagedRelPath(relPath))
+            return { ok: false, result: fail("write_failed") };
+    }
+    if (!(await commandSucceeds(deps.runGit, ["--version"]))) {
+        return { ok: false, result: fail("git_unavailable") };
+    }
+    if (!(await commandSucceeds(deps.runGh, ["--version"]))) {
+        return { ok: false, result: fail("gh_unavailable") };
+    }
+    const repositoryRoot = await captureStdout(deps.runGit, ["rev-parse", "--show-toplevel"]);
+    if (!repositoryRoot)
+        return { ok: false, result: fail("not_repository_root") };
+    const normalizedCwd = deps.cwd.endsWith("/") ? deps.cwd.slice(0, -1) : deps.cwd;
+    const normalizedRoot = repositoryRoot.endsWith("/")
+        ? repositoryRoot.slice(0, -1)
+        : repositoryRoot;
+    if (normalizedRoot !== normalizedCwd) {
+        return { ok: false, result: fail("not_repository_root") };
+    }
+    deps.log(`  repository root: ${normalizedRoot}`);
+    // A clean worktree is required BEFORE a branch exists, so an unrelated
+    // customer change can never be swept into the managed commit below.
+    //
+    // `--untracked-files=all` rather than the default: git otherwise COLLAPSES an
+    // untracked directory to a single `?? .bridge/` entry, and the one path that
+    // must be tolerated below could not then be distinguished from its neighbours.
+    const status = await captureStdout(deps.runGit, ["status", "--porcelain", "--untracked-files=all"]);
+    if (status === null)
+        return { ok: false, result: fail("git_failed") };
+    const dirty = status
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        // The install manifest is Bridge's OWN record, written by this command and
+        // deliberately never staged. Counting it as a customer change made a
+        // successful install poison the very re-run the ticket requires to be a
+        // clean no-op: the first run left the file behind, and the second refused
+        // with `worktree_not_clean`. Exactly one path is tolerated, by full name, so
+        // any other file under `.bridge/` still makes the worktree dirty.
+        .filter((line) => !line.endsWith(MCP_INSTALL_STATE_RELPATH));
+    if (dirty.length > 0)
+        return { ok: false, result: fail("worktree_not_clean") };
+    deps.log("  worktree: clean");
+    const ghDefaultBranch = await captureStdout(deps.runGh, [
+        "repo",
+        "view",
+        "--json",
+        "defaultBranchRef",
+        "--jq",
+        ".defaultBranchRef.name",
+    ]);
+    if (!ghDefaultBranch)
+        return { ok: false, result: fail("default_branch_unresolved") };
+    deps.log(`  default branch: ${ghDefaultBranch}`);
+    const remoteName = "origin";
+    const remoteUrl = await captureStdout(deps.runGit, ["remote", "get-url", remoteName]);
+    if (!remoteUrl)
+        return { ok: false, result: fail("remote_not_github") };
+    const remoteRepository = parseGithubRemote(remoteUrl);
+    if (!remoteRepository)
+        return { ok: false, result: fail("remote_not_github") };
+    deps.log(`  remote: ${remoteName} -> ${remoteRepository}`);
+    const ghRepository = await captureStdout(deps.runGh, [
+        "repo",
+        "view",
+        "--json",
+        "nameWithOwner",
+        "--jq",
+        ".nameWithOwner",
+    ]);
+    if (!ghRepository)
+        return { ok: false, result: fail("repository_identity_mismatch") };
+    if (ghRepository !== remoteRepository) {
+        return { ok: false, result: fail("repository_identity_mismatch") };
+    }
+    deps.log(`  gh: authenticated for ${ghRepository}`);
+    let codeOwner;
+    try {
+        codeOwner = validateMergeWorkflowCodeOwner(options.codeOwner);
+    }
+    catch (err) {
+        if (err instanceof MergeWorkflowCodeOwnerError) {
+            return { ok: false, result: fail("codeowner_invalid") };
+        }
+        throw err;
+    }
+    deps.log(`  code owner: ${codeOwner}`);
+    // --- content classification -------------------------------------------
+    let existingWorkflow;
+    try {
+        existingWorkflow = await readOrNull(deps, joinCwd(normalizedRoot, MERGE_WORKFLOW_PATH));
+    }
+    catch {
+        return { ok: false, result: fail("write_failed") };
+    }
+    const classification = classifyMergeWorkflowContent(existingWorkflow);
+    deps.log(`  workflow: ${MERGE_WORKFLOW_CLASSIFICATION_TEXT[classification]}`);
+    if (classification === "modified_or_unrecognized") {
+        return { ok: false, result: fail("workflow_modified_or_unrecognized") };
+    }
+    // Companion artifacts are inspected BEFORE any write. An existing file whose
+    // bytes differ from what this owner would produce is a conflict, not a target:
+    // it may be a previous install for a DIFFERENT code owner, or a customer edit.
+    const companions = [
+        [MERGE_WORKFLOW_CODEOWNERS_RELPATH, renderMergeWorkflowCodeownersFragment(codeOwner)],
+        [MERGE_WORKFLOW_GUIDANCE_RELPATH, renderMergeWorkflowGuidance(codeOwner)],
+    ];
+    let allCompanionsIdentical = true;
+    for (const [relPath, expected] of companions) {
+        let existing;
+        try {
+            existing = await readOrNull(deps, joinCwd(normalizedRoot, relPath));
+        }
+        catch {
+            return { ok: false, result: fail("write_failed") };
+        }
+        if (existing === null) {
+            allCompanionsIdentical = false;
+            continue;
+        }
+        if (existing !== expected) {
+            return { ok: false, result: fail("companion_artifact_conflict") };
+        }
+    }
+    // The aggregate no-op requires EVERY managed artifact to match. A workflow that
+    // is already identical while its guidance is missing is still an installation.
+    const effective = classification === "identical" && !allCompanionsIdentical ? "not_installed" : classification;
+    return {
+        ok: true,
+        preflight: {
+            repositoryRoot: normalizedRoot,
+            defaultBranch: ghDefaultBranch,
+            remoteName,
+            repository: ghRepository,
+            codeOwner,
+            classification: effective,
+        },
+    };
+}
+/**
+ * Find an open pull request already carrying this installation.
+ *
+ * Looked up by the deterministic managed BRANCH identity rather than by title:
+ * a title is prose anyone can change, while the branch is the thing this command
+ * would otherwise try to create.
+ */
+async function findExistingManagedPr(deps, branch) {
+    const raw = await captureStdout(deps.runGh, [
+        "pr",
+        "list",
+        "--state",
+        "open",
+        "--head",
+        branch,
+        "--json",
+        "url,headRefName,baseRefName,files",
+        "--limit",
+        "1",
+    ]);
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed) || parsed.length === 0)
+            return null;
+        const first = parsed[0];
+        const files = Array.isArray(first.files)
+            ? first.files
+                .map((f) => (f && typeof f === "object" ? f.path : undefined))
+                .filter((p) => typeof p === "string")
+            : [];
+        if (typeof first.url !== "string")
+            return null;
+        return {
+            url: first.url,
+            headRefName: typeof first.headRefName === "string" ? first.headRefName : "",
+            baseRefName: typeof first.baseRefName === "string" ? first.baseRefName : "",
+            files,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Confirm a detected pull request really is this installation's review surface.
+ *
+ * Reporting an unverified pull request as "already open" would tell an operator
+ * the review exists when it might touch different files, target a different
+ * base, or have been opened for something else entirely.
+ */
+function existingPrIsExpected(pr, branch, defaultBranch) {
+    if (pr.headRefName !== branch)
+        return false;
+    if (pr.baseRefName !== defaultBranch)
+        return false;
+    if (pr.files.length === 0)
+        return false;
+    const managed = new Set(MERGE_WORKFLOW_MANAGED_RELPATHS);
+    return pr.files.every((f) => managed.has(f));
+}
+// ---------------------------------------------------------------------------
+// Pull request body
+// ---------------------------------------------------------------------------
+/** Render the pull request body. Deterministic, and free of any secret value. */
+export function renderMergeWorkflowPrBody(codeOwner, upgrade) {
+    const owner = validateMergeWorkflowCodeOwner(codeOwner);
+    return [
+        upgrade
+            ? "This pull request upgrades the Bridge Epic Implementer merge workflow to contract version " +
+                String(MERGE_WORKFLOW_EXPECTED_VERSION) + "."
+            : "This pull request installs the Bridge Epic Implementer merge workflow, contract version " +
+                String(MERGE_WORKFLOW_EXPECTED_VERSION) + ".",
+        "",
+        "The workflow is the write actor for Epic Implementer child merges. Bridge's own",
+        "GitHub App installation is `contents: read` and cannot merge; the ephemeral",
+        "`GITHUB_TOKEN` issued to this workflow can. Reviewing it before it lands is the",
+        "security control, which is why this pull request was opened rather than applied.",
+        "",
+        "## Files",
+        "",
+        ...MERGE_WORKFLOW_MANAGED_RELPATHS.map((p) => `- \`${p}\``),
+        "",
+        "## What you must do after merging",
+        "",
+        "1. Create a repository Actions secret named `" +
+            MERGE_WORKFLOW_API_KEY_SECRET_NAME +
+            "` holding a Bridge API key for this repository. Bridge never sees the value.",
+        "2. Copy the rule from `" +
+            MERGE_WORKFLOW_CODEOWNERS_RELPATH +
+            "` into your active CODEOWNERS file.",
+        "3. Add a default-branch repository rule requiring a pull request and code-owner",
+        "   review, so `" + MERGE_WORKFLOW_PATH + "` cannot be rewritten without review.",
+        "",
+        "Code owner proposed for that path: " + owner,
+        "",
+        "## What this pull request does not do",
+        "",
+        "It does not merge itself, enable anything, or change repository settings. Bridge",
+        "performed no write to this repository: the branch, the commit, and this pull",
+        "request were all created locally with your own git and `gh`.",
+        "",
+        "See `" + MERGE_WORKFLOW_GUIDANCE_RELPATH + "` for the full setup steps.",
+        "",
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Orchestration
+// ---------------------------------------------------------------------------
+async function consent(deps, promptText) {
+    if (!deps.confirmWrite)
+        return false;
+    return await deps.confirmWrite(promptText);
+}
+/**
+ * Generate the managed artifacts and open the customer's review pull request.
+ *
+ * Returns a process exit code: `0` for every success shape (new pull request,
+ * upgrade pull request, verified existing pull request, byte-identical no-op,
+ * dry run) and `1` for every failure. A failure prints the stable reason token
+ * first and one remediation sentence second, both on stderr.
+ *
+ * Nothing already created is undone on a later failure. A branch that exists, a
+ * file that was written, or a ref that was pushed is left in place with a
+ * bounded recovery instruction: deleting a customer's branch to tidy up after
+ * ourselves is a destructive act taken on incomplete information.
+ */
+export async function runMergeWorkflowInstall(cwd, options, deps) {
+    const report = (result) => {
+        if (result.outcome === "failed") {
+            deps.errorLog(`${result.reason}`);
+            deps.errorLog(result.remediation);
+            return 1;
+        }
+        return 0;
+    };
+    deps.log("Bridge merge-workflow installer");
+    deps.log("  preflight:");
+    const pre = await runMergeWorkflowPreflight({ ...deps, cwd }, options);
+    if (!pre.ok)
+        return report(pre.result);
+    const preflight = pre.preflight;
+    if (preflight.classification === "identical") {
+        deps.log("");
+        deps.log("Clean no-op: every managed artifact already matches this build.");
+        deps.log(`  ${MERGE_WORKFLOW_PATH} (contract version ${MERGE_WORKFLOW_EXPECTED_VERSION})`);
+        deps.log("Nothing was written and no pull request was opened.");
+        return 0;
+    }
+    const upgrade = preflight.classification === "managed_version_older";
+    const branch = upgrade ? MERGE_WORKFLOW_UPGRADE_BRANCH : MERGE_WORKFLOW_INSTALL_BRANCH;
+    // Asked BEFORE a local branch exists, so a verified open pull request is
+    // reported instead of duplicated rather than after a duplicate branch is made.
+    const existing = await findExistingManagedPr(deps, branch);
+    if (existing) {
+        if (!existingPrIsExpected(existing, branch, preflight.defaultBranch)) {
+            return report(fail("existing_pr_unverifiable"));
+        }
+        deps.log("");
+        deps.log(`${upgrade ? "Upgrade" : "Installation"} pull request is already open.`);
+        deps.log(`  branch: ${branch}`);
+        deps.log(`  pull request: ${existing.url}`);
+        deps.log("Review and merge it; re-running this command opens nothing new.");
+        return 0;
+    }
+    deps.log("");
+    deps.log(upgrade ? "Planned upgrade:" : "Planned installation:");
+    deps.log(`  branch: ${branch}`);
+    for (const relPath of MERGE_WORKFLOW_MANAGED_RELPATHS)
+        deps.log(`  file:   ${relPath}`);
+    deps.log(`  commit: ${upgrade ? MERGE_WORKFLOW_UPGRADE_COMMIT_SUBJECT : MERGE_WORKFLOW_INSTALL_COMMIT_SUBJECT}`);
+    deps.log(`  push:   ${preflight.remoteName}/${branch} (your git identity)`);
+    deps.log(`  pull request: into ${preflight.defaultBranch} (your gh identity)`);
+    if (options.dryRun) {
+        deps.log("");
+        deps.log("--dry-run: nothing was written, committed, pushed, or opened.");
+        return 0;
+    }
+    if (!(await consent(deps, `Create branch ${branch}, write ${MERGE_WORKFLOW_MANAGED_RELPATHS.length} files, commit, push, and open a pull request? [y/N] `))) {
+        return report(fail("consent_declined"));
+    }
+    // --- first mutation: the branch ----------------------------------------
+    if (!(await commandSucceeds(deps.runGit, ["checkout", "-b", branch]))) {
+        return report(fail("git_failed"));
+    }
+    const artifacts = [
+        [MERGE_WORKFLOW_PATH, renderEpicImplementerMergeWorkflow()],
+        [MERGE_WORKFLOW_CODEOWNERS_RELPATH, renderMergeWorkflowCodeownersFragment(preflight.codeOwner)],
+        [MERGE_WORKFLOW_GUIDANCE_RELPATH, renderMergeWorkflowGuidance(preflight.codeOwner)],
+    ];
+    const written = [];
+    for (const [relPath, content] of artifacts) {
+        const absPath = joinCwd(preflight.repositoryRoot, relPath);
+        const parent = absPath.slice(0, absPath.lastIndexOf("/"));
+        try {
+            // Read-compare-write: an identical target is never rewritten, so a partial
+            // re-run does not churn file mtimes or produce an empty diff entry.
+            const existingContent = await readOrNull(deps, absPath);
+            if (existingContent !== content) {
+                await deps.mkdir(parent, { recursive: true });
+                await deps.writeFile(absPath, content, { encoding: "utf-8" });
+            }
+            written.push(relPath);
+        }
+        catch {
+            return report(fail("write_failed"));
+        }
+        // Recorded per artifact, with the POSIX repository-relative path only.
+        await deps.recordArtifact(preflight.repositoryRoot, relPath);
+    }
+    // Only the explicit managed paths are staged, passed after `--` so a path can
+    // never be read as a git option.
+    if (!(await commandSucceeds(deps.runGit, ["add", "--", ...MERGE_WORKFLOW_MANAGED_RELPATHS]))) {
+        return report(fail("git_failed"));
+    }
+    const commitSubject = upgrade
+        ? MERGE_WORKFLOW_UPGRADE_COMMIT_SUBJECT
+        : MERGE_WORKFLOW_INSTALL_COMMIT_SUBJECT;
+    if (!(await commandSucceeds(deps.runGit, ["commit", "-m", commitSubject]))) {
+        return report(fail("git_failed"));
+    }
+    if (!(await commandSucceeds(deps.runGit, [
+        "push",
+        "--set-upstream",
+        preflight.remoteName,
+        branch,
+    ]))) {
+        return report(fail("git_failed"));
+    }
+    const prTitle = upgrade ? MERGE_WORKFLOW_UPGRADE_PR_TITLE : MERGE_WORKFLOW_INSTALL_PR_TITLE;
+    const prUrl = await captureStdout(deps.runGh, [
+        "pr",
+        "create",
+        "--base",
+        preflight.defaultBranch,
+        "--head",
+        branch,
+        "--title",
+        prTitle,
+        "--body",
+        renderMergeWorkflowPrBody(preflight.codeOwner, upgrade),
+    ]);
+    if (!prUrl) {
+        deps.errorLog("pr_open_failed");
+        deps.errorLog(`${REMEDIATION.pr_open_failed} The branch ${branch} is pushed to ${preflight.remoteName} and was left in place.`);
+        return 1;
+    }
+    deps.log("");
+    deps.log(upgrade ? "Upgrade pull request opened." : "Installation pull request opened.");
+    deps.log(`  branch: ${branch}`);
+    for (const relPath of written)
+        deps.log(`  file:   ${relPath}`);
+    deps.log(`  pull request: ${prUrl}`);
+    deps.log("");
+    deps.log("Next, in this order:");
+    deps.log("  1. Review the pull request — the workflow is what performs the privileged merge.");
+    deps.log(`  2. Create the repository Actions secret ${MERGE_WORKFLOW_API_KEY_SECRET_NAME} through GitHub. Never pass its value to this command.`);
+    deps.log(`  3. Merge the rule in ${MERGE_WORKFLOW_CODEOWNERS_RELPATH} into your active CODEOWNERS file.`);
+    deps.log("  4. Add a default-branch rule requiring a pull request and code-owner review.");
+    deps.log("  5. Merge the pull request yourself; Bridge never merges it.");
+    return 0;
+}