@bridge_gpt/mcp-server 0.2.69 → 0.2.70

package/build/merge-workflow-install.js

@@ -1,49 +1,65 @@
 /**
- * `install-bridge conductor --merge-workflow` — the generate-and-PR installer
- * (BAPI-1136).
+ * The generate-and-PR artifact installer (BAPI-1136, generalized by BAPI-1460).
  *
- * 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
+ * One engine installs a named ARTIFACT SET: it generates the set's managed
+ * files, 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.
+ * Two sets exist today: the Epic Implementer merge workflow with its two review
+ * artifacts (`install-bridge conductor --merge-workflow`, below), and the
+ * Epic Implementer CI workflow (`epic-ci-workflow-install.ts`).
  *
  * ## 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.
+ * preflight, the classification, the consent summary, the worktree / 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.
+ * The ENTIRE preflight — local checks, the remote default-branch head, every
+ * managed file's content on that head, the open managed pull request, and the
+ * managed remote branch — completes before the first fetch, file write, commit,
+ * push, or pull request. Nothing here can partially install.
  *
- * ## Four content states, and why `identical` is not the only no-op
+ * ## The person's checkout is never touched
  *
- * 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.
+ * All branch and file work happens in a temporary, DETACHED `git worktree`
+ * created from the verified default-branch head, outside the person's checkout,
+ * and removed on every exit path. The person's HEAD, index, and working files
+ * are unchanged at the end: no checkout, switch, reset, or stash ever runs
+ * against them. Content is classified from the default branch, not from
+ * whatever the person has checked out.
+ *
+ * ## Content states, and why `identical` is not the only no-op
+ *
+ * A file at a managed path is absent, byte-identical to the proposal, a complete
+ * older version Bridge itself published, or something else. Only the first and
+ * third are installable. "Something else" — a hand edit, a truncation, a newer
+ * version, a file that merely claims a version — is never overwritten: the
+ * installer prints a unified diff of what it would have written against what is
+ * there and reports a named refusal.
+ *
+ * ## Re-runs find their own work
+ *
+ * A re-run that finds an open managed pull request whose contents match the
+ * proposal reports it and writes nothing. One whose contents differ is reported
+ * for manual reconciliation. A pushed managed branch with no open pull request
+ * (left by an earlier `pr_open_failed`) is reported with a fixed next step; it
+ * is never reused, overwritten, or deleted automatically.
  *
  * ## 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.
+ * No path here accepts, prompts for, reads, writes, or prints a credential. 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 { resolve } from "node:path";
+import { lstat as fsLstat, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { renderUnifiedDiff } from "./artifact-diff.js";
 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";
@@ -51,7 +67,7 @@ import { MERGE_WORKFLOW_CODEOWNERS_RELPATH, MERGE_WORKFLOW_GUIDANCE_RELPATH, MER
 import { renderEpicImplementerMergeWorkflow } from "./merge-workflow.js";
 import { MCP_INSTALL_STATE_RELPATH } from "./mcp-install-state.js";
 // ---------------------------------------------------------------------------
-// Managed identity
+// Managed identity (merge-workflow set)
 // ---------------------------------------------------------------------------
 /** 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);
@@ -73,7 +89,8 @@ export const MERGE_WORKFLOW_UPGRADE_PR_TITLE = MERGE_WORKFLOW_UPGRADE_COMMIT_SUB
  *
  * 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.
+ * to be greppable rather than assembled from subprocess text. Tokens may be
+ * added; none may be removed or renamed.
  */
 export const MERGE_WORKFLOW_INSTALL_FAILURE_REASONS = [
     /** `git` is not on PATH. */
@@ -106,6 +123,21 @@ export const MERGE_WORKFLOW_INSTALL_FAILURE_REASONS = [
     "pr_open_failed",
     /** A required write surface was declined, or no prompt was available. */
     "consent_declined",
+    // --- BAPI-1460 -----------------------------------------------------------
+    /** A remote read (default-branch head, managed file, PR, or branch) gave no reliable answer. */
+    "remote_state_unverifiable",
+    /** An open managed pull request carries contents that differ from the current proposal. */
+    "existing_pr_differs",
+    /** A managed branch is pushed but has no open pull request. */
+    "managed_branch_without_pr",
+    /** The default branch moved after consent and no plan could be re-approved at the new head. */
+    "default_branch_moved",
+    /** Another actor created the managed branch or pull request during this run. */
+    "managed_state_changed",
+    /** The temporary worktree could not be created. */
+    "worktree_failed",
+    /** The test command for the CI workflow is missing or invalid. */
+    "test_command_invalid",
 ];
 // ---------------------------------------------------------------------------
 // Path safety
@@ -113,10 +145,10 @@ export const MERGE_WORKFLOW_INSTALL_FAILURE_REASONS = [
 /**
  * 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.
+ * The managed paths are constants, so this can never fire in production — which
+ * is exactly why it is here. It 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)
@@ -137,49 +169,19 @@ function joinCwd(cwd, rel) {
     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;
-    }
+    const code = typeof err === "object" && err !== null ? err.code : undefined;
+    return code === "ENOENT" || code === "ENOTDIR";
 }
 // ---------------------------------------------------------------------------
 // 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;
-}
+// BAPI-1461: moved to a dependency-free module so credential resolution can use
+// it without loading this installer's graph; re-exported so this surface is unchanged.
+import { parseGithubRemote } from "./github-remote.js";
+export { parseGithubRemote };
+// ---------------------------------------------------------------------------
+// Remediation
+// ---------------------------------------------------------------------------
 /** 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.",
@@ -192,15 +194,29 @@ const REMEDIATION = {
     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.",
+    existing_pr_unverifiable: "Inspect the open Bridge 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.",
+    git_failed: "Check the reported branch with git by hand; nothing already pushed has been removed.",
+    pr_open_failed: "The branch is pushed; open a pull request from it by hand, or delete that remote branch, then re-run this command.",
     consent_declined: "Re-run in an interactive terminal and accept the write to continue.",
+    remote_state_unverifiable: "Check that `gh` is authenticated and can read this repository, then re-run; nothing was written.",
+    existing_pr_differs: "An open Bridge pull request differs from what this build proposes; review it and close it, then re-run.",
+    managed_branch_without_pr: "Open a pull request from the managed branch, or delete that remote branch, then re-run this command.",
+    default_branch_moved: "The default branch changed while this command ran; re-run it to review the new proposal.",
+    managed_state_changed: "Another managed branch or pull request appeared while this command ran; review it, then re-run.",
+    worktree_failed: "A temporary git worktree could not be created; check free disk space and `git worktree list`, then re-run.",
+    test_command_invalid: "Save a valid test command through Bridge setup, then re-run.",
 };
-function fail(reason) {
-    return { outcome: "failed", reason, remediation: REMEDIATION[reason] };
+/** The remediation sentence for a reason. */
+export function artifactSetRemediation(reason) {
+    return REMEDIATION[reason];
 }
+function fail(reason, extra = {}) {
+    return { outcome: "failed", reason, remediation: REMEDIATION[reason], warnings: [], ...extra };
+}
+// ---------------------------------------------------------------------------
+// Subprocess helpers
+// ---------------------------------------------------------------------------
 async function commandSucceeds(run, args) {
     try {
         const result = await run(args);
@@ -211,31 +227,242 @@ async function commandSucceeds(run, args) {
     }
 }
 async function captureStdout(run, args) {
+    const raw = await captureRawStdout(run, args);
+    return raw === null ? null : raw.trim();
+}
+/** Successful stdout, UNtrimmed — a leading status column is significant. */
+async function captureRawStdout(run, args) {
     try {
         const result = await run(args);
         if (result.status !== 0)
             return null;
-        return result.stdout.trim();
+        return result.stdout;
     }
     catch {
         return null;
     }
 }
+/** Whether a porcelain-v1 status line names exactly the install manifest. */
+function isInstallStateLine(line) {
+    // `XY <path>`: two status columns, a space, then the path.
+    return line.length > 3 && line.slice(3) === MCP_INSTALL_STATE_RELPATH;
+}
+/** Split `gh api --include` output into its status code and RAW body. */
+function parseIncludedResponse(stdout) {
+    const status = /^HTTP\/[0-9.]+ (\d{3})\b/.exec(stdout);
+    if (!status)
+        return null;
+    const crlf = stdout.indexOf("\r\n\r\n");
+    const lf = stdout.indexOf("\n\n");
+    let cut;
+    if (crlf >= 0 && (lf < 0 || crlf < lf))
+        cut = crlf + 4;
+    else if (lf >= 0)
+        cut = lf + 2;
+    else
+        return null;
+    return { status: Number(status[1]), body: stdout.slice(cut) };
+}
 /**
- * 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".
+ * Read one file's RAW bytes from the remote at an immutable commit, through
+ * `gh api`. A confirmed 404 is `absent`; anything else that is not a clean 200
+ * is `unverifiable` — an uncertain read must never authorize a replacement.
+ */
+async function readRemoteFile(deps, repository, sha, relPath) {
+    const encodedPath = relPath.split("/").map(encodeURIComponent).join("/");
+    let result;
+    try {
+        result = await deps.runGh([
+            "api",
+            "--include",
+            "-H",
+            "Accept: application/vnd.github.raw",
+            `repos/${repository}/contents/${encodedPath}?ref=${encodeURIComponent(sha)}`,
+        ]);
+    }
+    catch {
+        return { kind: "unverifiable" };
+    }
+    const parsed = parseIncludedResponse(result.stdout ?? "");
+    if (!parsed)
+        return { kind: "unverifiable" };
+    if (parsed.status === 200 && result.status === 0)
+        return { kind: "present", content: parsed.body };
+    if (parsed.status === 404)
+        return { kind: "absent" };
+    return { kind: "unverifiable" };
+}
+/** The SHA a remote branch points at; `null` when absent; `undefined` when unknown. */
+async function readRemoteBranchSha(deps, remoteName, branch) {
+    const ref = `refs/heads/${branch}`;
+    const raw = await captureRawStdout(deps.runGit, ["ls-remote", remoteName, ref]);
+    if (raw === null)
+        return undefined;
+    const lines = raw.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+    const matches = lines
+        .map((line) => line.split(/\s+/))
+        .filter((parts) => parts.length === 2 && parts[1] === ref);
+    if (matches.length === 0)
+        return lines.length === 0 ? null : undefined;
+    if (matches.length > 1 || !/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(matches[0][0]))
+        return undefined;
+    return matches[0][0];
+}
+/**
+ * Find an open pull request already carrying this installation, by the
+ * deterministic managed BRANCH identity (a title is prose anyone can change).
+ * A lookup failure is distinct from a reliable "no open PR".
+ */
+async function findExistingManagedPr(deps, repository, branch) {
+    const raw = await captureStdout(deps.runGh, [
+        "pr",
+        "list",
+        "--repo",
+        repository,
+        "--state",
+        "open",
+        "--head",
+        branch,
+        "--json",
+        "url,headRefName,headRefOid,baseRefName,isCrossRepository,files",
+        "--limit",
+        "2",
+    ]);
+    if (raw === null)
+        return { kind: "lookup_failed" };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { kind: "lookup_failed" };
+    }
+    if (!Array.isArray(parsed))
+        return { kind: "lookup_failed" };
+    if (parsed.length === 0)
+        return { kind: "none" };
+    if (parsed.length > 1) {
+        // Two open PRs from one managed branch name cannot both be ours.
+        return { kind: "found", pr: { url: "", headRefName: "", headRefOid: "", baseRefName: "", isCrossRepository: null, files: [] } };
+    }
+    const first = parsed[0];
+    if (typeof first.url !== "string")
+        return { kind: "lookup_failed" };
+    const files = Array.isArray(first.files)
+        ? first.files
+            .map((f) => (f && typeof f === "object" ? f.path : undefined))
+            .filter((p) => typeof p === "string")
+        : [];
+    return {
+        kind: "found",
+        pr: {
+            url: first.url,
+            headRefName: typeof first.headRefName === "string" ? first.headRefName : "",
+            headRefOid: typeof first.headRefOid === "string" ? first.headRefOid : "",
+            baseRefName: typeof first.baseRefName === "string" ? first.baseRefName : "",
+            isCrossRepository: typeof first.isCrossRepository === "boolean" ? first.isCrossRepository : null,
+            files,
+        },
+    };
+}
+/**
+ * Confirm a detected pull request has the shape of this installation's review
+ * surface: the managed head branch in THIS repository, the default branch as
+ * base, and only managed paths changed.
+ */
+function existingPrIsExpected(pr, branch, defaultBranch, managedPaths) {
+    if (pr.headRefName !== branch)
+        return false;
+    if (pr.baseRefName !== defaultBranch)
+        return false;
+    if (pr.isCrossRepository !== false)
+        return false;
+    if (!/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(pr.headRefOid))
+        return false;
+    if (pr.files.length === 0)
+        return false;
+    const managed = new Set(managedPaths);
+    return pr.files.every((f) => managed.has(f));
+}
+/** Whether every managed file at the PR head equals the proposal. `null` if unreadable. */
+async function prContentMatchesProposal(deps, repository, pr, proposals) {
+    for (const [relPath, proposal] of proposals) {
+        const file = await readRemoteFile(deps, repository, pr.headRefOid, relPath);
+        if (file.kind === "unverifiable")
+            return null;
+        if (file.kind === "absent" || file.content !== proposal)
+            return false;
+    }
+    return true;
+}
+function compareUrl(repository, defaultBranch, branch) {
+    return `https://github.com/${repository}/compare/${encodeURI(defaultBranch)}...${encodeURI(branch)}`;
+}
+/**
+ * Classify every managed artifact against the default branch at `sha`.
+ * Read-only. Prints each refused artifact's diff.
+ */
+async function classifyAtRemote(deps, descriptor, repository, sha, quiet) {
+    const proposals = new Map();
+    let allIdentical = true;
+    let upgrade = false;
+    const refusals = [];
+    for (const artifact of descriptor.artifacts) {
+        const proposal = artifact.render();
+        proposals.set(artifact.relPath, proposal);
+        const remote = await readRemoteFile(deps, repository, sha, artifact.relPath);
+        if (remote.kind === "unverifiable")
+            return { ok: false, result: fail("remote_state_unverifiable") };
+        const existing = remote.kind === "present" ? remote.content : null;
+        const classification = artifact.classify(existing);
+        if (artifact.progressLabel && classification.text && !quiet) {
+            deps.log(`  ${artifact.progressLabel}: ${classification.text}`);
+        }
+        if (classification.state === "conflict") {
+            refusals.push({
+                reason: classification.reason,
+                diff: { relPath: artifact.relPath, diff: renderUnifiedDiff(artifact.relPath, existing ?? "", proposal) },
+            });
+            continue;
+        }
+        if (classification.state !== "identical")
+            allIdentical = false;
+        if (classification.state === "managed_version_older")
+            upgrade = true;
+    }
+    if (refusals.length > 0) {
+        if (!quiet) {
+            for (const { diff } of refusals) {
+                deps.log("");
+                deps.log(`Not overwriting ${diff.relPath}. What this command would have written, against what is there:`);
+                for (const line of diff.diff.replace(/\n$/, "").split("\n"))
+                    deps.log(line);
+            }
+        }
+        return {
+            ok: false,
+            result: fail(refusals[0].reason, { diffs: refusals.map((r) => r.diff) }),
+        };
+    }
+    return {
+        ok: true,
+        classification: allIdentical ? "identical" : upgrade ? "managed_version_older" : "not_installed",
+        proposals,
+    };
+}
+/**
+ * Run the complete read-only preflight for an artifact set.
  *
- * 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.
+ * Every check here is a read: executables, repository root, clean worktree,
+ * default branch, remote and `gh` identity, set-specific options, the remote
+ * default-branch head (via `ls-remote`, no fetch), and each managed file's raw
+ * bytes at that head (via `gh api`). Nothing it calls creates a branch, writes a
+ * file, touches install state, fetches, commits, pushes, or opens a pull request.
  */
-export async function runMergeWorkflowPreflight(deps, options) {
+export async function runArtifactSetPreflight(descriptor, deps) {
     // Managed paths are constants; this guards a future edit, not today's input.
-    for (const relPath of MERGE_WORKFLOW_MANAGED_RELPATHS) {
-        if (!isSafeManagedRelPath(relPath))
+    for (const artifact of descriptor.artifacts) {
+        if (!isSafeManagedRelPath(artifact.relPath))
             return { ok: false, result: fail("write_failed") };
     }
     if (!(await commandSucceeds(deps.runGit, ["--version"]))) {
@@ -253,26 +480,21 @@ export async function runMergeWorkflowPreflight(deps, options) {
         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.
+    // A clean worktree is still required, so the person is not surprised by a
+    // proposal built while their own changes are in flight.
     //
     // `--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"]);
+    // untracked directory to a single `?? .bridge/` entry. The output is read RAW
+    // (untrimmed) because the first status column is significant, and exactly one
+    // path — the install manifest, by full name — is tolerated.
+    const status = await captureRawStdout(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));
+        .map((line) => line.replace(/\r$/, ""))
+        .filter((line) => line.trim().length > 0)
+        .filter((line) => !isInstallStateLine(line));
     if (dirty.length > 0)
         return { ok: false, result: fail("worktree_not_clean") };
     deps.log("  worktree: clean");
@@ -309,135 +531,75 @@ export async function runMergeWorkflowPreflight(deps, options) {
         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;
+    if (descriptor.validateOptions) {
+        const checked = descriptor.validateOptions();
+        if (!checked.ok)
+            return { ok: false, result: fail(checked.reason) };
+        for (const line of checked.progress)
+            deps.log(line);
     }
-    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 default branch head, read from the remote. A managed branch is never
+    // the default branch; that is enforced again at push time.
+    if (descriptor.installBranch === ghDefaultBranch || descriptor.upgradeBranch === ghDefaultBranch) {
+        return { ok: false, result: fail("default_branch_unresolved") };
     }
-    // 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;
+    const defaultBranchSha = await readRemoteBranchSha(deps, remoteName, ghDefaultBranch);
+    if (defaultBranchSha === undefined)
+        return { ok: false, result: fail("remote_state_unverifiable") };
+    if (defaultBranchSha === null)
+        return { ok: false, result: fail("default_branch_unresolved") };
+    const classified = await classifyAtRemote(deps, descriptor, ghRepository, defaultBranchSha, false);
+    if (!classified.ok)
+        return { ok: false, result: classified.result };
     return {
         ok: true,
         preflight: {
             repositoryRoot: normalizedRoot,
             defaultBranch: ghDefaultBranch,
+            defaultBranchSha,
             remoteName,
             repository: ghRepository,
-            codeOwner,
-            classification: effective,
+            classification: classified.classification,
+            proposals: classified.proposals,
         },
     };
 }
 /**
- * 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.
+ * Inspect the managed pull request and branch for `branch`. Read-only.
+ * Returns `null` when the way is clear, or the outcome to report.
  */
-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,
-        };
+async function inspectManagedState(deps, descriptor, preflight, branch, upgrade) {
+    const managedPaths = descriptor.artifacts.map((a) => a.relPath);
+    const lookup = await findExistingManagedPr(deps, preflight.repository, branch);
+    if (lookup.kind === "lookup_failed")
+        return fail("remote_state_unverifiable", { branch });
+    if (lookup.kind === "found") {
+        if (!existingPrIsExpected(lookup.pr, branch, preflight.defaultBranch, managedPaths)) {
+            return fail("existing_pr_unverifiable", { branch });
+        }
+        const matches = await prContentMatchesProposal(deps, preflight.repository, lookup.pr, preflight.proposals);
+        if (matches === null)
+            return fail("existing_pr_unverifiable", { branch, prUrl: lookup.pr.url });
+        if (!matches)
+            return fail("existing_pr_differs", { branch, prUrl: lookup.pr.url });
+        return { outcome: "existing-pr", branch, prUrl: lookup.pr.url, upgrade, warnings: [] };
     }
-    catch {
-        return null;
+    // Independently of PR discovery: a pushed managed branch with no open PR.
+    const branchSha = await readRemoteBranchSha(deps, preflight.remoteName, branch);
+    if (branchSha === undefined)
+        return fail("remote_state_unverifiable", { branch });
+    if (branchSha !== null) {
+        return fail("managed_branch_without_pr", {
+            branch,
+            compareUrl: compareUrl(preflight.repository, preflight.defaultBranch, branch),
+        });
     }
-}
-/**
- * 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));
+    return null;
 }
 // ---------------------------------------------------------------------------
-// Pull request body
+// Merge-workflow descriptor
 // ---------------------------------------------------------------------------
-/** Render the pull request body. Deterministic, and free of any secret value. */
+/** Render the merge-workflow pull request body. Deterministic, and free of any secret value. */
 export function renderMergeWorkflowPrBody(codeOwner, upgrade) {
     const owner = validateMergeWorkflowCodeOwner(codeOwner);
     return [
@@ -479,159 +641,415 @@ export function renderMergeWorkflowPrBody(codeOwner, upgrade) {
         "",
     ].join("\n");
 }
+/** A companion: absent or byte-identical is fine; anything else is a conflict. */
+function companionArtifact(relPath, render) {
+    return {
+        relPath,
+        render,
+        classify: (existing) => {
+            if (existing === null)
+                return { state: "not_installed" };
+            if (existing === render())
+                return { state: "identical" };
+            return { state: "conflict", reason: "companion_artifact_conflict" };
+        },
+    };
+}
+/** The merge-workflow artifact set for one code owner. */
+export function buildMergeWorkflowArtifactSet(codeOwner) {
+    let owner = codeOwner;
+    return {
+        setName: "merge-workflow",
+        installBranch: MERGE_WORKFLOW_INSTALL_BRANCH,
+        upgradeBranch: MERGE_WORKFLOW_UPGRADE_BRANCH,
+        installCommitSubject: MERGE_WORKFLOW_INSTALL_COMMIT_SUBJECT,
+        upgradeCommitSubject: MERGE_WORKFLOW_UPGRADE_COMMIT_SUBJECT,
+        installPrTitle: MERGE_WORKFLOW_INSTALL_PR_TITLE,
+        upgradePrTitle: MERGE_WORKFLOW_UPGRADE_PR_TITLE,
+        renderPrBody: (upgrade) => renderMergeWorkflowPrBody(owner, upgrade),
+        validateOptions: () => {
+            try {
+                owner = validateMergeWorkflowCodeOwner(codeOwner);
+            }
+            catch (err) {
+                if (err instanceof MergeWorkflowCodeOwnerError)
+                    return { ok: false, reason: "codeowner_invalid" };
+                throw err;
+            }
+            return { ok: true, progress: [`  code owner: ${owner}`] };
+        },
+        consentPrompt: (plan) => `Create branch ${plan.branch}, write ${plan.artifacts.length} files, commit, push, and open a pull request? [y/N] `,
+        artifacts: [
+            {
+                relPath: MERGE_WORKFLOW_PATH,
+                render: () => renderEpicImplementerMergeWorkflow(),
+                progressLabel: "workflow",
+                classify: (existing) => {
+                    const classification = classifyMergeWorkflowContent(existing);
+                    const text = MERGE_WORKFLOW_CLASSIFICATION_TEXT[classification];
+                    if (classification === "modified_or_unrecognized") {
+                        return { state: "conflict", reason: "workflow_modified_or_unrecognized", text };
+                    }
+                    return { state: classification, text };
+                },
+            },
+            companionArtifact(MERGE_WORKFLOW_CODEOWNERS_RELPATH, () => renderMergeWorkflowCodeownersFragment(owner)),
+            companionArtifact(MERGE_WORKFLOW_GUIDANCE_RELPATH, () => renderMergeWorkflowGuidance(owner)),
+        ],
+    };
+}
+/**
+ * Run the complete read-only merge-workflow preflight. Compatibility entry point
+ * around {@link runArtifactSetPreflight}.
+ */
+export async function runMergeWorkflowPreflight(deps, options) {
+    const pre = await runArtifactSetPreflight(buildMergeWorkflowArtifactSet(options.codeOwner), deps);
+    if (!pre.ok)
+        return pre;
+    return {
+        ok: true,
+        preflight: { ...pre.preflight, codeOwner: validateMergeWorkflowCodeOwner(options.codeOwner) },
+    };
+}
 // ---------------------------------------------------------------------------
 // Orchestration
 // ---------------------------------------------------------------------------
+/** How many times consent is asked before a still-moving default branch stops the run. */
+const MAX_CONSENT_ROUNDS = 3;
+function defaultConsentPrompt(plan) {
+    return (`Create branch ${plan.branch} from ${plan.defaultBranch} in a temporary worktree, write ` +
+        `${plan.artifacts.join(", ")}, commit "${plan.commitSubject}", push to ` +
+        `${plan.remoteName}/${plan.branch}, and open a pull request into ${plan.defaultBranch}? [y/N] `);
+}
 async function consent(deps, promptText) {
     if (!deps.confirmWrite)
         return false;
     return await deps.confirmWrite(promptText);
 }
+function samePlan(a, b) {
+    if (a.classification !== b.classification)
+        return false;
+    if (a.proposals.size !== b.proposals.size)
+        return false;
+    for (const [path, content] of a.proposals)
+        if (b.proposals.get(path) !== content)
+            return false;
+    return true;
+}
+/** Refuse to write through a symlink anywhere on the path inside the worktree. */
+async function pathIsSafeInWorktree(deps, worktree, relPath) {
+    const target = resolve(worktree, relPath);
+    if (!target.startsWith(resolve(worktree) + "/"))
+        return false;
+    const lstat = deps.lstat ?? fsLstat;
+    const segments = relPath.split("/");
+    let current = resolve(worktree);
+    for (const segment of segments) {
+        current = join(current, segment);
+        try {
+            if ((await lstat(current)).isSymbolicLink())
+                return false;
+        }
+        catch (err) {
+            if (isEnoent(err))
+                return true;
+            return false;
+        }
+    }
+    return true;
+}
 /**
- * Generate the managed artifacts and open the customer's review pull request.
+ * Install one artifact set: read-only preflight, consent, then all writes in a
+ * temporary worktree, push to the managed branch, and open the 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.
+ * Progress lines go to `deps.log`; the caller reports the returned outcome and
+ * prints any `warnings` (cleanup problems) after it, on stderr.
+ * Nothing already pushed is undone on a later failure: deleting a customer's
+ * branch to tidy up 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);
+export async function installArtifactSet(descriptor, options, deps) {
+    const pre = await runArtifactSetPreflight(descriptor, deps);
     if (!pre.ok)
-        return report(pre.result);
-    const preflight = pre.preflight;
+        return pre.result;
+    let 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;
+        return { outcome: "identical", artifacts: [...preflight.proposals.keys()], warnings: [] };
     }
-    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"));
-        }
+    const managedPaths = descriptor.artifacts.map((a) => a.relPath);
+    let upgrade = false;
+    let branch = "";
+    let commitSubject = "";
+    // Consent covers one plan at one default-branch head. When the default branch
+    // moves after consent and the plan changes, the new plan is shown and consent
+    // is asked again; a branch that keeps moving stops with default_branch_moved.
+    for (let round = 0;; round += 1) {
+        upgrade = preflight.classification === "managed_version_older";
+        branch = upgrade ? descriptor.upgradeBranch : descriptor.installBranch;
+        commitSubject = upgrade ? descriptor.upgradeCommitSubject : descriptor.installCommitSubject;
+        const managed = await inspectManagedState(deps, descriptor, preflight, branch, upgrade);
+        if (managed)
+            return managed;
+        const plan = {
+            branch,
+            upgrade,
+            artifacts: managedPaths,
+            commitSubject,
+            remoteName: preflight.remoteName,
+            defaultBranch: preflight.defaultBranch,
+        };
         deps.log("");
-        deps.log(`${upgrade ? "Upgrade" : "Installation"} pull request is already open.`);
+        if (round > 0)
+            deps.log(`${preflight.defaultBranch} moved since you approved, and the plan changed.`);
+        deps.log(upgrade ? "Planned upgrade:" : "Planned installation:");
         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;
+        for (const relPath of managedPaths)
+            deps.log(`  file:   ${relPath}`);
+        deps.log(`  commit: ${commitSubject}`);
+        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 { outcome: "dry-run", branch, artifacts: managedPaths, upgrade, warnings: [] };
+        }
+        const prompt = (descriptor.consentPrompt ?? defaultConsentPrompt)(plan);
+        if (!(await consent(deps, prompt)))
+            return fail("consent_declined", { branch });
+        // --- first mutation: fetch the default branch into the remote-tracking ref --
+        const trackingRef = `refs/remotes/${preflight.remoteName}/${preflight.defaultBranch}`;
+        if (!(await commandSucceeds(deps.runGit, [
+            "fetch",
+            "--no-tags",
+            preflight.remoteName,
+            `+refs/heads/${preflight.defaultBranch}:${trackingRef}`,
+        ]))) {
+            return fail("git_failed", { branch });
+        }
+        const fetchedSha = await captureStdout(deps.runGit, ["rev-parse", "--verify", "--quiet", `${trackingRef}^{commit}`]);
+        if (!fetchedSha)
+            return fail("git_failed", { branch });
+        if (fetchedSha === preflight.defaultBranchSha)
+            break;
+        // The default branch moved: re-inspect at the fetched head. An unchanged
+        // plan proceeds from the new head under the consent already given.
+        const again = await classifyAtRemote(deps, descriptor, preflight.repository, fetchedSha, true);
+        if (!again.ok && again.result.reason === "remote_state_unverifiable")
+            return fail("remote_state_unverifiable", { branch });
+        if (!again.ok)
+            return fail("default_branch_moved", { branch });
+        const unchanged = samePlan(again, preflight);
+        preflight = { ...preflight, defaultBranchSha: fetchedSha, classification: again.classification, proposals: again.proposals };
+        if (unchanged)
+            break;
+        if (again.classification === "identical") {
+            return { outcome: "identical", artifacts: [...again.proposals.keys()], warnings: [] };
+        }
+        if (round + 1 >= MAX_CONSENT_ROUNDS)
+            return fail("default_branch_moved", { branch });
     }
-    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;
+    const makeTempDir = deps.makeTempDir ?? (() => mkdtemp(join(tmpdir(), `bridge-${descriptor.setName}-`)));
+    const removeDir = deps.removeDir ?? ((dir) => rm(dir, { recursive: true, force: true }));
+    let tempRoot;
+    try {
+        tempRoot = await makeTempDir();
     }
-    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"));
+    catch {
+        return fail("worktree_failed", { branch });
     }
-    // --- first mutation: the branch ----------------------------------------
-    if (!(await commandSucceeds(deps.runGit, ["checkout", "-b", branch]))) {
-        return report(fail("git_failed"));
+    const worktree = join(tempRoot, "worktree");
+    const warnings = [];
+    let worktreeAdded = false;
+    const run = async () => {
+        if (!(await commandSucceeds(deps.runGit, [
+            "worktree",
+            "add",
+            "--detach",
+            worktree,
+            preflight.defaultBranchSha,
+        ]))) {
+            return fail("worktree_failed", { branch });
+        }
+        worktreeAdded = true;
+        for (const artifact of descriptor.artifacts) {
+            const content = preflight.proposals.get(artifact.relPath);
+            if (!(await pathIsSafeInWorktree(deps, worktree, artifact.relPath)))
+                return fail("write_failed", { branch });
+            const absPath = joinCwd(worktree, artifact.relPath);
+            const parent = absPath.slice(0, absPath.lastIndexOf("/"));
+            try {
+                // Read-compare-write: an identical target is never rewritten.
+                let existing;
+                try {
+                    existing = await deps.readFile(absPath);
+                }
+                catch (err) {
+                    if (!isEnoent(err))
+                        throw err;
+                    existing = null;
+                }
+                if (existing !== content) {
+                    await deps.mkdir(parent, { recursive: true });
+                    await deps.writeFile(absPath, content, { encoding: "utf-8" });
+                }
+            }
+            catch {
+                return fail("write_failed", { branch });
+            }
+            try {
+                // The manifest lands in the temporary worktree and is never staged.
+                await deps.recordArtifact(worktree, artifact.relPath);
+            }
+            catch {
+                // Recording is best effort and never blocks the install.
+            }
+        }
+        // Only the explicit managed paths are staged, after `--`.
+        if (!(await commandSucceeds(deps.runGit, ["-C", worktree, "add", "--", ...managedPaths]))) {
+            return fail("git_failed", { branch });
+        }
+        if (!(await commandSucceeds(deps.runGit, ["-C", worktree, "commit", "-m", commitSubject]))) {
+            return fail("git_failed", { branch });
+        }
+        // Immediately before push: nobody else created the managed branch or PR.
+        const raced = await inspectManagedState(deps, descriptor, preflight, branch, upgrade);
+        if (raced) {
+            if (raced.outcome === "failed" && raced.reason === "remote_state_unverifiable")
+                return raced;
+            return fail("managed_state_changed", { branch });
+        }
+        if (branch === preflight.defaultBranch)
+            return fail("git_failed", { branch });
+        if (!(await commandSucceeds(deps.runGit, [
+            "-C",
+            worktree,
+            "push",
+            preflight.remoteName,
+            `HEAD:refs/heads/${branch}`,
+        ]))) {
+            return fail("git_failed", { branch });
+        }
+        const prUrl = await captureStdout(deps.runGh, [
+            "pr",
+            "create",
+            "--repo",
+            preflight.repository,
+            "--base",
+            preflight.defaultBranch,
+            "--head",
+            branch,
+            "--title",
+            upgrade ? descriptor.upgradePrTitle : descriptor.installPrTitle,
+            "--body",
+            descriptor.renderPrBody(upgrade),
+        ]);
+        if (!prUrl) {
+            return fail("pr_open_failed", {
+                branch,
+                compareUrl: compareUrl(preflight.repository, preflight.defaultBranch, branch),
+            });
+        }
+        return {
+            outcome: upgrade ? "upgrade-pr-opened" : "installed-pr-opened",
+            branch,
+            prUrl,
+            artifacts: managedPaths,
+            warnings: [],
+        };
+    };
+    let result;
+    try {
+        result = await run();
     }
-    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("/"));
+    finally {
+        let cleaned = true;
+        if (worktreeAdded && !(await commandSucceeds(deps.runGit, ["worktree", "remove", "--force", worktree]))) {
+            cleaned = false;
+        }
         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);
+            await removeDir(tempRoot);
         }
         catch {
-            return report(fail("write_failed"));
+            cleaned = false;
+        }
+        if (!cleaned) {
+            const warning = `cleanup_incomplete: the temporary worktree at ${worktree} was not fully removed. ` +
+                `Remove it with \`git worktree remove --force ${worktree}\` and delete ${tempRoot}.`;
+            // Returned, not printed: the caller prints it AFTER its own outcome, so a
+            // failure's stable reason token stays the first stderr line.
+            warnings.push(warning);
         }
-        // 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;
+    return { ...result, warnings: [...result.warnings, ...warnings] };
+}
+/**
+ * Generate the merge-workflow artifacts and open the customer's review PR.
+ *
+ * Compatibility wrapper for `install-bridge conductor --merge-workflow` around
+ * {@link installArtifactSet}. 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.
+ */
+export async function runMergeWorkflowInstall(cwd, options, deps) {
+    deps.log("Bridge merge-workflow installer");
+    deps.log("  preflight:");
+    const descriptor = buildMergeWorkflowArtifactSet(options.codeOwner);
+    const result = await installArtifactSet(descriptor, { dryRun: options.dryRun }, { ...deps, cwd });
+    const exitCode = reportMergeWorkflowResult(result, deps);
+    for (const warning of result.warnings)
+        deps.errorLog(warning);
+    return exitCode;
+}
+function reportMergeWorkflowResult(result, deps) {
+    switch (result.outcome) {
+        case "failed":
+            deps.errorLog(`${result.reason}`);
+            if (result.reason === "pr_open_failed" && result.branch) {
+                deps.errorLog(`${result.remediation} The branch ${result.branch} is pushed to origin and was left in place.`);
+            }
+            else if (result.reason === "managed_branch_without_pr" && result.branch) {
+                deps.errorLog(`${result.remediation} Managed branch: ${result.branch}.`);
+                if (result.compareUrl)
+                    deps.errorLog(`Open a pull request from it: ${result.compareUrl}`);
+            }
+            else if (result.reason === "existing_pr_differs" && result.prUrl) {
+                deps.errorLog(`${result.remediation} Pull request: ${result.prUrl}`);
+            }
+            else {
+                deps.errorLog(result.remediation);
+            }
+            return 1;
+        case "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;
+        case "existing-pr":
+            deps.log("");
+            deps.log(`${result.upgrade ? "Upgrade" : "Installation"} pull request is already open.`);
+            deps.log(`  branch: ${result.branch}`);
+            deps.log(`  pull request: ${result.prUrl}`);
+            deps.log("Review and merge it; re-running this command opens nothing new.");
+            return 0;
+        case "dry-run":
+            return 0;
+        case "installed-pr-opened":
+        case "upgrade-pr-opened":
+            deps.log("");
+            deps.log(result.outcome === "upgrade-pr-opened" ? "Upgrade pull request opened." : "Installation pull request opened.");
+            deps.log(`  branch: ${result.branch}`);
+            for (const relPath of result.artifacts)
+                deps.log(`  file:   ${relPath}`);
+            deps.log(`  pull request: ${result.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;
     }
-    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;
 }