@bridge_gpt/mcp-server 0.2.59 → 0.2.62

package/build/install-bridge.js

@@ -162,11 +162,16 @@ import { resolveAgentNotesTargets, writeAgentNotes, } from "./agent-notes.js";
 // `executor install-service` as a subprocess, which would lose the typed plan,
 // the write outcome, and the unit path this flow has to record.
 import { collectExecutorInstallPreflight, } from "./executor/install-preflight.js";
-import { inspectExecutorServiceState, startExecutorService, } from "./executor/service-lifecycle.js";
-import { executorLaunchdLabelForId, executorSystemdUnitNameForId, executorLaunchdPlistPathForId, executorSystemdUnitPathForId, resolvePackagedExecutorInvocation, writeExecutorServicePlan, } from "./executor/service-unit.js";
+import { inspectExecutorServiceDurability, inspectExecutorServiceState, startExecutorService, } from "./executor/service-lifecycle.js";
+import { executorLaunchdLabelForId, executorSystemdUnitNameForId, executorLaunchdPlistPathForId, executorSystemdUnitPathForId, resolvePackagedExecutorInvocation, writeExecutorServicePlan, EXECUTOR_SERVICE_UNIT_FILE_MODE, } from "./executor/service-unit.js";
 import { collectConductorNativeLedgerSafe, } from "./conductor/doctor.js";
 import { installConductorGitHooks, } from "./conductor/git-hooks.js";
 import { runInstallBridgeConductorCli, } from "./install-bridge-conductor.js";
+// BAPI-1136: the merge-workflow generate-and-PR installer. Domain logic lives in
+// its own module; this file supplies the parser and the process seams.
+import { runMergeWorkflowInstall, } from "./merge-workflow-install.js";
+import { MERGE_WORKFLOW_REMEDY_COMMAND, } from "./conductor/merge-execution-contract.js";
+import { MERGE_WORKFLOW_API_KEY_SECRET_NAME, } from "./merge-workflow-config.js";
 import { runConductorInstallDoctor, EPIC_IMPLEMENTER_PROFILE_TOKEN, } from "./conductor/install-doctor.js";
 import { resolveConductorBridgeApiAccess, } from "./conductor/bridge-api-client.js";
 import { claudeReviewWorkflowPath, writeClaudeReviewWorkflow, } from "./claude-review-workflow.js";
@@ -320,7 +325,11 @@ export const INSTALL_BRIDGE_AGENT_PROMPT = "Run /install-bridge now, with no arg
     "do' line. The server decides eligibility (repository state AND whether this caller can run the " +
     "command), so do NOT apply a role rule or a learned-state rule of your own. Do NOT run the " +
     "returned command yourself — only recommend it; running it is the human's next explicit " +
-    "invocation. For supporting context around a recommended command, use the manifest's own " +
+    "invocation. When you recommend a command and `next_step.command_context` is a non-empty " +
+    "string, print it verbatim on its own line directly under the command — it is the server's " +
+    "explanation of what the command gives the human and how long it takes; do not reword, shorten, " +
+    "or extend it, and render nothing in its place when it is empty or missing. " +
+    "For other supporting context around a recommended command, use the manifest's own " +
     "next_step.post_install_indexing and next_step.post_install_scheduler text rather than inventing " +
     "an explanation for it. " +
     "Never request, echo, or transport any credential — only ever direct the human to that " +
@@ -589,6 +598,26 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "                                executor is actually observed. See",
         "                                `install conductor --help`.",
         "",
+        "  install conductor --merge-workflow --codeowner <@org/team|@user>",
+        "                                Generate the Epic Implementer merge workflow",
+        "                                plus its CODEOWNERS fragment and repository-rule",
+        "                                guidance, commit them on a managed branch, push",
+        "                                with your own git, and open a pull request with",
+        "                                your own `gh` (BAPI-1136). It NEVER merges that",
+        "                                pull request and Bridge performs no repository",
+        "                                write. A complete read-only preflight runs before",
+        "                                the first branch, file, commit, push, or pull",
+        "                                request. Re-running reports one of four states —",
+        "                                not installed, managed version is older,",
+        "                                identical, or modified/unrecognized — and an",
+        "                                already-open installation or upgrade pull request",
+        "                                is reported rather than duplicated. A modified or",
+        "                                unrecognized workflow is never overwritten. No",
+        "                                credential is ever accepted, prompted for, or",
+        "                                written: the repository Actions secret is named",
+        "                                only, and you create it yourself afterwards.",
+        "                                `--dry-run` performs NO write of any kind.",
+        "",
         "Environment: BAPI_BASE_URL (default https://bridgegpt-api.com) and BAPI_DOCS_DIR",
         "(default docs/tmp) are read from the environment with the shown fallbacks.",
         "BAPI_SIGNUP_EMAIL supplies the self-serve signup email non-interactively (it is",
@@ -960,6 +989,10 @@ export const INSTALL_BRIDGE_BITBUCKET_OFFER_CONTEXT = [
     "Step 4b — optional: connect Bitbucket.",
     "  This installs the Bridge Bitbucket Forge app so you can implement and review tickets with Bridge.",
     "  It opens Bitbucket in your browser; no Bitbucket credential is shared with Bridge.",
+    // BAPI-1247: name the destination precisely. "Admin panel" sent people looking for a
+    // page that does not exist under that name — the app lives under the workspace's own
+    // settings, and saying so is the difference between a 20-second step and a hunt.
+    '  You finish by pasting a printed code into Workspace settings → Apps → "Connect Bitbucket to Bridge API".',
     `  You can do this later instead: ${INSTALL_BRIDGE_CONNECT_BITBUCKET_COMMAND}`,
 ];
 /** Default-No Bitbucket offer prompt. Mirrors {@link INSTALL_BRIDGE_GITHUB_CONNECT_PROMPT}. */
@@ -1024,10 +1057,30 @@ export async function offerBitbucketConnection(repoName, baseUrl, deps, log, ses
         if (answer !== "y" && answer !== "yes")
             return; // declining is a normal outcome
         const connectDeps = createDefaultConnectBitbucketDeps();
-        const code = await runBitbucketConnectionFlow(connectDeps, api, repoName);
-        if (code !== 0) {
-            log("  note: Bitbucket was not connected. Your install is complete — connect Bitbucket later with " +
-                `'npx -y ${MCP_PACKAGE_NAME}@latest connect-bitbucket --repo ${repoName}'.`);
+        const result = await runBitbucketConnectionFlow(connectDeps, api, repoName, {
+            // The install path has no workspace slug to give: a workspace is only discoverable
+            // AFTER redemption stages candidates, which is later than this. The connection flow
+            // falls back to its textual navigation path rather than guessing a link.
+            workspace: undefined,
+            // The Step 4b prompt just above IS the approval for the first mint. Asking again
+            // inside the flow would be a second confirmation for one decision.
+            initialMintApproved: true,
+        });
+        if (result.kind === "connected") {
+            // BAPI-1171, mirroring offerGithubConnection: only a CONFIRMED success marks the
+            // run's VCS provider as connected.
+            session.vcsConnected = true;
+        }
+        else {
+            // BAPI-1247: close Bitbucket out loud before Step 4c starts. Step 4c is about
+            // agent notes and has nothing to do with Bitbucket, so without this line a user
+            // who declined a renewal sees the install move on and cannot tell whether the
+            // Bitbucket step succeeded, failed, or is still going.
+            log("  note: Bitbucket connection was not completed. Your install is complete and will continue — " +
+                // Single-quoted repo name, matching the connect command's own resume form, so
+                // a name with spaces or shell metacharacters is inert when pasted.
+                `connect Bitbucket later with npx -y ${MCP_PACKAGE_NAME}@latest connect-bitbucket --repo '${repoName}' ` +
+                "(this issues a new code).");
         }
     }
     catch {
@@ -1036,21 +1089,59 @@ export async function offerBitbucketConnection(repoName, baseUrl, deps, log, ses
             `Bitbucket later with 'npx -y ${MCP_PACKAGE_NAME}@latest connect-bitbucket --repo ${repoName}'.`);
     }
 }
-/** Default-No agent-notes offer prompt. Mirrors {@link INSTALL_BRIDGE_GITHUB_CONNECT_PROMPT}. */
-export const INSTALL_BRIDGE_AGENT_NOTES_PROMPT = "Add cross-platform agent notes? [y/N]: ";
+/**
+ * The exact agent-notes consent-prompt prefix, shared with tests so the copy
+ * cannot drift. Mirrors {@link INSTALL_BRIDGE_LAUNCH_CONSENT_PROMPT_PREFIX}: the
+ * prefix is pinned, the platform tail varies with the selection.
+ */
+export const INSTALL_BRIDGE_AGENT_NOTES_PROMPT_PREFIX = "Write guidance so ";
+/**
+ * Describe the selected notes platforms for the offer copy: a naturally joined
+ * subject and whether it is plural (so a verb can agree). `platformLabels` are
+ * the display names of the SELECTED platforms that resolve to a writable notes
+ * target (Windsurf, which has no convention, never appears). An empty list —
+ * not reached while a live offer runs, since the offer self-gates on a writable
+ * target — falls back to a generic, singular "your coding agent".
+ */
+function describeAgentNotesPlatforms(platformLabels) {
+    if (platformLabels.length === 0)
+        return { subject: "your coding agent", plural: false };
+    return { subject: joinLabelsWithAnd(platformLabels), plural: platformLabels.length > 1 };
+}
+/** Join labels for prose: "A", "A and B", or "A, B, and C". */
+function joinLabelsWithAnd(labels) {
+    if (labels.length <= 1)
+        return labels[0] ?? "";
+    if (labels.length === 2)
+        return `${labels[0]} and ${labels[1]}`;
+    return `${labels.slice(0, -1).join(", ")}, and ${labels[labels.length - 1]}`;
+}
+/**
+ * The default-No agent-notes consent prompt (BAPI-1207; payoff-led, platform-named
+ * copy per the BAPI-1239 install-issue #4 follow-up). Leads with WHY — teaching
+ * the agent how to use Bridge's MCP tools — and NAMES the selected platform(s)
+ * rather than the old generic "cross-platform" phrasing.
+ */
+export function buildAgentNotesPrompt(platformLabels) {
+    const { subject, plural } = describeAgentNotesPlatforms(platformLabels);
+    return `${INSTALL_BRIDGE_AGENT_NOTES_PROMPT_PREFIX}${subject} know${plural ? "" : "s"} how to use the Bridge MCP? [y/N]: `;
+}
 /**
  * The offer-context lines printed immediately before the agent-notes prompt
- * (BAPI-1207). Names the applicable file(s) and states the marker-scoped,
- * non-destructive contract up front — mirrors the GitHub/Bitbucket offers'
- * "explain before asking" convention.
+ * (BAPI-1207). Leads with the payoff — teaching the named platform(s) WHEN to
+ * reach for Bridge's MCP tools — then states the marker-scoped, non-destructive
+ * contract as a secondary line, mirroring the GitHub/Bitbucket offers' "explain
+ * before asking" convention.
  */
-export function buildAgentNotesOfferContext(targets) {
+export function buildAgentNotesOfferContext(targets, platformLabels) {
+    const { subject, plural } = describeAgentNotesPlatforms(platformLabels);
     return [
         "",
-        "Step 4c — optional: cross-platform agent notes.",
-        `  This creates or refreshes a Bridge-owned region in ${targets.join(" and ")} with situation-`,
-        "  to-tool guidance for a few Bridge MCP tools. Only that marked region is created or",
-        "  refreshed — any existing content in the file, inside or outside it, is otherwise preserved.",
+        `Step 4c — optional: Bridge MCP guidance for ${subject}.`,
+        `  Write guidance so ${subject} know${plural ? "" : "s"} when to reach for Bridge's MCP tools`,
+        "  during a task — for project standards, a second opinion, a council, or a ticket review.",
+        `  It writes a Bridge-owned region to ${targets.join(" and ")}; only that marked region is`,
+        "  created or refreshed — any existing content, inside or outside it, is otherwise preserved.",
     ];
 }
 /**
@@ -1064,16 +1155,16 @@ export function buildAgentNotesOfferContext(targets) {
  * actual write via {@link writeAgentNotes}, so a `--dry-run` (which never
  * reaches this call) and the live path share exactly one write path.
  */
-export async function offerAgentGuidanceNotes(deps, log, targets) {
+export async function offerAgentGuidanceNotes(deps, log, targets, platformLabels) {
     if (targets.length === 0)
         return { kind: "not-applicable" };
     // No prompt surface → no offer. Never assume consent on a non-interactive run.
     if (!deps.isTTY || !deps.promptLine)
         return { kind: "headless-skip" };
     try {
-        for (const line of buildAgentNotesOfferContext(targets))
+        for (const line of buildAgentNotesOfferContext(targets, platformLabels))
             log(line);
-        const answer = (await deps.promptLine(INSTALL_BRIDGE_AGENT_NOTES_PROMPT)).trim().toLowerCase();
+        const answer = (await deps.promptLine(buildAgentNotesPrompt(platformLabels))).trim().toLowerCase();
         // Only an explicit yes proceeds — blank input, EOF, "n", and anything malformed
         // all decline without writing.
         return answer === "y" || answer === "yes" ? { kind: "consented" } : { kind: "declined" };
@@ -1374,6 +1465,160 @@ function defaultShellFreeRunner(executable, args) {
         child.on("close", (code) => resolve({ exitCode: code ?? 1, stdout, stderr }));
     });
 }
+export function parseMergeWorkflowInstallArgs(argv) {
+    if (!argv.some((a) => a === "--merge-workflow" || a.startsWith("--merge-workflow="))) {
+        return { status: "not-selected" };
+    }
+    let codeOwner;
+    let dryRun = false;
+    let error = null;
+    const setError = (message) => {
+        if (error === null)
+            error = message;
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const raw = argv[i];
+        const eq = raw.indexOf("=");
+        const flag = eq === -1 ? raw : raw.slice(0, eq);
+        const inline = eq === -1 ? undefined : raw.slice(eq + 1);
+        switch (flag) {
+            case "--merge-workflow":
+                if (inline !== undefined)
+                    setError("--merge-workflow takes no value");
+                break;
+            case "--dry-run":
+                if (inline !== undefined)
+                    setError("--dry-run takes no value");
+                dryRun = true;
+                break;
+            case "--codeowner": {
+                const next = argv[i + 1];
+                if (inline !== undefined) {
+                    if (inline.trim().length === 0)
+                        setError("--codeowner requires a value");
+                    else
+                        codeOwner = inline.trim();
+                }
+                else if (next === undefined || next.startsWith("-") || next.trim().length === 0) {
+                    setError("--codeowner requires a value");
+                }
+                else {
+                    codeOwner = next.trim();
+                    i++;
+                }
+                break;
+            }
+            default:
+                setError(`Unknown option: ${flag}`);
+        }
+    }
+    if (error === null && codeOwner === undefined) {
+        error = "--codeowner <@org/team|@user> is required with --merge-workflow";
+    }
+    return {
+        status: "selected",
+        error,
+        options: { codeOwner: codeOwner ?? "", dryRun },
+    };
+}
+/** Usage text for the merge-workflow installer. */
+export function getMergeWorkflowInstallUsage() {
+    return [
+        `Usage: ${MERGE_WORKFLOW_REMEDY_COMMAND} --codeowner <@org/team|@user> [--dry-run]`,
+        "",
+        "Generate the Epic Implementer merge workflow plus its CODEOWNERS fragment and",
+        "repository-rule guidance, commit them on a managed branch, push with your own",
+        "git identity, and open a pull request with your own `gh`.",
+        "",
+        "Options:",
+        "  --merge-workflow           Select this command.",
+        "  --codeowner <@owner>       REQUIRED. The one @user or @org/team that should own",
+        "                             review of the workflow path. Not inferred.",
+        "  --dry-run                  Print the plan and perform NO write: no branch, no",
+        "                             file, no install-state write, no commit, no push,",
+        "                             and no pull request.",
+        "",
+        "It never merges the pull request and never asks for a credential. The Bridge",
+        `API key is named only (${MERGE_WORKFLOW_API_KEY_SECRET_NAME}); create that`,
+        "repository Actions secret yourself after the pull request lands.",
+    ].join("\n");
+}
+/**
+ * Build the installer's seams from the final merged installer deps.
+ *
+ * `git` and `gh` run through {@link defaultShellFreeRunner} — argument arrays,
+ * `shell: false` — and `gh` additionally receives the non-interactive pins so a
+ * prompt can never hang an install. The resulting environment is never printed.
+ */
+export function buildMergeWorkflowInstallDeps(deps, log, errorLog) {
+    const toResult = (r) => ({
+        status: r.exitCode,
+        stdout: r.stdout,
+        stderr: r.stderr,
+    });
+    return {
+        cwd: deps.cwd,
+        log,
+        errorLog,
+        readFile: deps.readFile,
+        writeFile: deps.writeFile,
+        mkdir: deps.mkdir,
+        runGit: deps.mergeWorkflowRunGit ??
+            (async (args) => toResult(await defaultShellFreeRunner("git", args))),
+        runGh: deps.mergeWorkflowRunGh ??
+            (async (args) => toResult(await defaultShellFreeRunnerWithEnv("gh", args, {
+                GH_PROMPT_DISABLED: "1",
+                GH_NO_UPDATE_NOTIFIER: "1",
+            }))),
+        confirmWrite: deps.isTTY && deps.promptLine
+            ? async (promptText) => {
+                const answer = (await deps.promptLine(promptText)).trim().toLowerCase();
+                return answer === "y" || answer === "yes";
+            }
+            : undefined,
+        recordArtifact: (cwd, relPath) => recordInstalledProjectArtifact(cwd, relPath, {
+            readFile: deps.readFile,
+            writeFile: (p, data) => deps.writeFile(p, data),
+            rename: deps.rename,
+            mkdir: (p, o) => deps.mkdir(p, o),
+            unlink: deps.unlink,
+        }),
+    };
+}
+/**
+ * {@link defaultShellFreeRunner} with extra environment entries overlaid.
+ *
+ * Kept separate rather than widening the shared runner's signature: every other
+ * caller wants the inherited environment exactly as it is, and an optional
+ * parameter that only one caller passes is an invitation to pass it wrongly.
+ *
+ * NOTE ON THE INHERITED ENVIRONMENT (BAPI-1136). This spread is deliberate and
+ * is NOT the ambient-identity pattern this ticket removes from the merge path.
+ * The two are opposites: a merge must authenticate as one explicitly configured
+ * credential, because it performs a privileged write on Bridge's behalf; this
+ * `gh` opens a pull request AS THE CUSTOMER, using their own login, which is
+ * exactly what makes the resulting review theirs. `conductor/local-merge.ts`'s
+ * allowlisted child environment is where the other rule lives.
+ */
+function defaultShellFreeRunnerWithEnv(executable, args, extraEnv) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(executable, args, {
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: { ...process.env, ...extraEnv },
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString("utf-8");
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf-8");
+        });
+        child.on("error", reject);
+        child.on("close", (code) => resolve({ exitCode: code ?? 1, stdout, stderr }));
+    });
+}
 /** Presence probe: `<tool> --version` exiting 0 means the tool resolves on PATH. */
 async function defaultExecutablePresenceProbe(name) {
     try {
@@ -1393,7 +1638,18 @@ async function defaultExecutablePresenceProbe(name) {
  * stays in `install-bridge-conductor.ts`; moving it into this dispatch layer
  * would put policy in the place least able to test it.
  */
-function buildConductorExecutorDeps(deps, baseUrl) {
+/**
+ * Compose the executor-provisioning bundle from the FINAL merged deps.
+ *
+ * EXPORTED for testing (BAPI-1137). The bundle's seams are only reachable
+ * through the nested conductor runner after two consents and a successful
+ * start, so driving the whole CLI to assert "the durability probe got the
+ * injected uid" turns a one-line property into an end-to-end rehearsal. Every
+ * entry here is a thin adapter over an implementation that is tested elsewhere;
+ * what this function decides is only WHICH seam each one is wired to, and that
+ * is exactly what a direct test can check.
+ */
+export function buildConductorExecutorDeps(deps, baseUrl) {
     const homeDir = deps.homedir();
     const lookupExecutable = deps.lookupExecutable ?? defaultExecutablePresenceProbe;
     const runLifecycleCommand = deps.runLifecycleCommand ?? defaultShellFreeRunner;
@@ -1416,7 +1672,14 @@ function buildConductorExecutorDeps(deps, baseUrl) {
         writeUnit: (plan) => writeExecutorServicePlan(plan, {
             stat: (filePath) => deps.stat(filePath),
             mkdir: (dirPath, options) => deps.mkdir(dirPath, options),
-            writeFile: (filePath, content) => deps.writeFile(filePath, content),
+            // BAPI-1137: the write mode is passed through EXPLICITLY rather than
+            // left to the process umask — a unit names the repositories and endpoint
+            // this host serves, and how readable it ends up must not depend on the
+            // shell that happened to run the installer.
+            writeFile: (filePath, content, options) => deps.writeFile(filePath, content, options ?? { encoding: "utf-8", mode: EXECUTOR_SERVICE_UNIT_FILE_MODE }),
+            // The permission seam, so an ALREADY-PRESENT unit's mode is corrected
+            // too: `writeFile`'s mode only applies at creation.
+            chmod: deps.chmod,
             // Supplying `readFile` is what enables the `unchanged` outcome, so a
             // re-run against an identical unit reports the truth instead of an
             // unnecessary rewrite.
@@ -1433,6 +1696,29 @@ function buildConductorExecutorDeps(deps, baseUrl) {
             return result.ok ? { ok: true } : { ok: false, error: result.error };
         },
         startService: (plan) => startExecutorService(plan, runLifecycleCommand),
+        // BAPI-1137 — both new seams are THIN adapters over `service-lifecycle.ts`,
+        // exactly like `startService` above. No probe is built here, no command
+        // string is assembled here, and no policy about what a state means lives
+        // here: this file stays a dispatch layer, and the module that owns
+        // launchctl/systemctl/loginctl keeps owning them.
+        inspectServiceState: (plan) => inspectExecutorServiceState({
+            platform: plan.platform,
+            unitPath: plan.unitPath,
+            serviceIdentifier: plan.serviceIdentifier,
+            // The same injected `getuid` seam the start plan uses — the launchd
+            // domain target needs it, and reading it here rather than inside the
+            // lifecycle module keeps that module free of ambient process state.
+            uid: deps.getuid ? deps.getuid() : null,
+        }, runLifecycleCommand),
+        inspectDurability: (plan) => inspectExecutorServiceDurability({
+            platform: plan.platform,
+            unitPath: plan.unitPath,
+            serviceIdentifier: plan.serviceIdentifier,
+            // Linux lingering is a property of the USER (`loginctl show-user
+            // <uid>`) and the macOS login domain is `gui/<uid>`, so both probes
+            // need the numeric uid from this same seam.
+            uid: deps.getuid ? deps.getuid() : null,
+        }, runLifecycleCommand),
         now: deps.monotonicNow ?? (() => Number(process.hrtime.bigint() / 1000000n)),
         sleep: deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
     };
@@ -1661,21 +1947,34 @@ export async function resolveSignupEmail(options, deps) {
     if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
         return { ok: true, value: fromEnv.trim() };
     }
+    const entered = await promptForBoundedEmail(deps, "Email for Bridge workspace setup (required): ");
+    if (entered === undefined)
+        return { ok: false, error: "No email entered." };
+    return { ok: true, value: entered };
+}
+/**
+ * The bounded interactive email prompt shared by self-serve signup
+ * ({@link resolveSignupEmail}) and invite redemption (BAPI-1263). Two reads at
+ * most: the first answer, then ONE re-prompt after a single hint line. EOF
+ * resolves as an empty value (promptLineViaReadline resolves "" on close), which
+ * fails the shape check like any other blank answer, so it costs one re-prompt and
+ * then fails cleanly rather than hanging. Returns the trimmed (case-preserved)
+ * address, or `undefined` after two invalid answers. The answer is never echoed.
+ * The caller guarantees `deps.promptLine` exists.
+ */
+async function promptForBoundedEmail(deps, promptText) {
     const promptLine = deps.promptLine;
-    // BAPI-1171: bounded to two reads total — the first answer, then ONE re-prompt
-    // after a single hint line. EOF resolves as an empty value (promptLineViaReadline
-    // resolves "" on close), which fails the shape check like any other blank
-    // answer, so it costs one re-prompt and then fails cleanly rather than hanging.
+    if (!promptLine)
+        return undefined;
     for (let attempt = 0; attempt < 2; attempt += 1) {
-        const raw = await promptLine("Email for Bridge workspace setup (required): ");
+        const raw = await promptLine(promptText);
         const entered = String(raw ?? "").trim();
-        if (INSTALL_BRIDGE_SIGNUP_EMAIL_SHAPE.test(entered)) {
-            return { ok: true, value: entered };
-        }
+        if (INSTALL_BRIDGE_SIGNUP_EMAIL_SHAPE.test(entered))
+            return entered;
         if (attempt === 0)
             deps.log(INSTALL_BRIDGE_SIGNUP_EMAIL_HINT);
     }
-    return { ok: false, error: "No email entered." };
+    return undefined;
 }
 /**
  * Select the onboarding branch as pure logic (deterministic, no I/O, no prompt):
@@ -3146,15 +3445,21 @@ export function buildBootstrapExchangeUrl(baseUrl) {
  * POST the bootstrap-invite exchange. The token and `key_secret` travel ONLY in
  * the JSON request body (never a query string, never a header, never a log line).
  * Bounded by the same 10s timeout as the connectivity ping.
+ *
+ * BAPI-1263: an optional nonempty `email` is appended as a fourth body field, used
+ * only on the retry after an `email-required` refusal. Omitted or empty, the body is
+ * the legacy three-field one, byte for byte.
  */
-export async function exchangeBootstrapInvite(deps, baseUrl, token, repoName, keySecret) {
+export async function exchangeBootstrapInvite(deps, baseUrl, token, repoName, keySecret, email) {
     const url = buildBootstrapExchangeUrl(baseUrl);
     let resp;
     try {
         resp = await deps.fetch(url, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ token, repo_name: repoName, key_secret: keySecret }),
+            body: JSON.stringify(email
+                ? { token, repo_name: repoName, key_secret: keySecret, email }
+                : { token, repo_name: repoName, key_secret: keySecret }),
             signal: AbortSignal.timeout(10_000),
         });
     }
@@ -3208,12 +3513,42 @@ export async function exchangeBootstrapInvite(deps, baseUrl, token, repoName, ke
     if (resp.status === 401) {
         return { ok: false, kind: "invalid-invite", message: `The Bridge API rejected the bootstrap invite (HTTP ${resp.status}).` };
     }
+    if (resp.status === 426) {
+        // Only the exact `email_required` refusal is recognized; any other, absent, or
+        // unreadable 426 body stays on the generic failure path below. The message is
+        // installer-owned — nothing from the response is propagated.
+        let recognized = false;
+        try {
+            const body = (await resp.json());
+            recognized = body?.detail?.error === "email_required";
+        }
+        catch {
+            recognized = false;
+        }
+        if (recognized) {
+            return {
+                ok: false,
+                kind: "email-required",
+                message: "The Bridge API requires an email address to redeem this invite.",
+            };
+        }
+    }
     return {
         ok: false,
         kind: "failed",
         message: `The bootstrap exchange failed (HTTP ${resp.status}). Verify BAPI_BASE_URL and try again.`,
     };
 }
+/** The invite-email prompt (BAPI-1263), shown once after an `email_required` refusal. */
+const INVITE_EMAIL_PROMPT = "Email for this Bridge invite (required): ";
+/** BAPI-1263: fixed, secret-free failures for the invite email recovery. */
+export const INVITE_EMAIL_REQUIRED_NON_INTERACTIVE_MESSAGE = "Error: this invite needs an email address, and there is no interactive terminal to ask for it. " +
+    `The bootstrap invite has NOT been used. Re-run \`npx -y ${MCP_PACKAGE_NAME} install\` in an ` +
+    "interactive terminal.";
+export const INVITE_EMAIL_INVALID_ANSWERS_MESSAGE = "Error: no valid email address was entered. The bootstrap invite has NOT been used. Re-run " +
+    "install and enter an address like you@example.com.";
+export const INVITE_EMAIL_REPEATED_REFUSAL_MESSAGE = "Error: the Bridge API still requires an email address after one was entered. The bootstrap " +
+    "invite has NOT been used. Re-run install, or contact support if this repeats.";
 // ---------------------------------------------------------------------------
 // Self-serve mint (BAPI-618): email -> invite token
 // ---------------------------------------------------------------------------
@@ -4030,7 +4365,7 @@ export function buildDryRunPreview(ctx) {
         ...credentialStep,
         ...buildCommitAssetsPreviewLines(ctx.commitSafeAssets, ctx.host.kind === "explicit" ? ctx.host.configTargets : []),
         ...(ctx.host.kind === "explicit" ? buildLaunchStepPreview(ctx.host.launch) : buildDeferredLaunchStepPreview()),
-        ...(ctx.host.kind === "explicit" ? buildAgentNotesPreviewLines(ctx.host.notesTargets ?? []) : []),
+        ...(ctx.host.kind === "explicit" ? buildAgentNotesPreviewLines(ctx.host.notesTargets ?? [], ctx.host.notesPlatformLabels ?? []) : []),
     ];
 }
 /**
@@ -4142,14 +4477,21 @@ function buildDeferredLaunchStepPreview() {
  * no writable target (e.g. Windsurf-only), mirroring how the GitHub offer
  * lines are unconditional but this offer's applicability is not.
  */
-function buildAgentNotesPreviewLines(notesTargets) {
+function buildAgentNotesPreviewLines(notesTargets, platformLabels) {
     if (notesTargets.length === 0)
         return [];
+    const { subject, plural } = describeAgentNotesPlatforms(platformLabels);
     return [
-        "Step 4c — optional: cross-platform agent notes (SKIPPED in --dry-run): if the terminal is",
-        `          interactive, offer to create or refresh a Bridge-owned marker region in ${notesTargets.join(" and ")}`,
-        "          with situation-to-tool guidance for a few Bridge MCP tools; defaults to No, and",
-        "          existing content outside that region is always preserved. No notes files are",
+        // BAPI-1247: state the sequencing explicitly. A real run reaches this point only
+        // after Step 4b has ended one way or the other, and the live run now says so out
+        // loud, so the preview says so too rather than leaving the order implied.
+        "Step 4c — reached only after the Step 4b VCS connect offer has completed or been",
+        "          explicitly deferred (a declined or incomplete connect is announced first,",
+        "          with the command to finish it later, and never blocks this step).",
+        `Step 4c — optional: Bridge MCP guidance for ${subject} (SKIPPED in --dry-run): if the`,
+        `          terminal is interactive, offer to write guidance so ${subject} know${plural ? "" : "s"} when to reach`,
+        `          for Bridge's MCP tools, in a Bridge-owned marker region in ${notesTargets.join(" and ")}; defaults`,
+        "          to No, and existing content outside that region is always preserved. No notes files are",
         "          written in --dry-run.",
     ];
 }
@@ -4233,7 +4575,7 @@ function buildBootstrapDryRunPreview(ctx) {
         ...promoteStep,
         ...buildCommitAssetsPreviewLines(ctx.commitSafeAssets, ctx.host.kind === "explicit" ? ctx.host.configTargets : []),
         ...(ctx.host.kind === "explicit" ? buildLaunchStepPreview(ctx.host.launch) : buildDeferredLaunchStepPreview()),
-        ...(ctx.host.kind === "explicit" ? buildAgentNotesPreviewLines(ctx.host.notesTargets ?? []) : []),
+        ...(ctx.host.kind === "explicit" ? buildAgentNotesPreviewLines(ctx.host.notesTargets ?? [], ctx.host.notesPlatformLabels ?? []) : []),
     ];
 }
 /**
@@ -4659,6 +5001,40 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // `epic-implementer` name. This nested `install-bridge conductor` surface is
     // untouched by that rename.
     if (argv[0] === "conductor") {
+        // ---- BAPI-1136: `install-bridge conductor --merge-workflow` ----------
+        //
+        // Intercepted ahead of `parseInstallBridgeConductorArgs` on purpose. That
+        // parser REQUIRES at least one `--required-check` because an empty done gate
+        // passes unconditionally — a rule that is right for the bootstrap phase and
+        // meaningless for this one, which writes three files and opens a pull
+        // request and has no done gate at all. Routing here keeps the bootstrap
+        // parser's invariant intact instead of weakening it for a sibling command.
+        //
+        // It also runs BEFORE any MCP server construction or connection, and before
+        // the base-URL resolution below, because this command makes no Bridge API
+        // call whatsoever: it talks only to the customer's own git and `gh`.
+        const mergeWorkflowArgs = parseMergeWorkflowInstallArgs(argv.slice(1));
+        if (mergeWorkflowArgs.status === "selected") {
+            if (mergeWorkflowArgs.error) {
+                errorLog(`Error: ${mergeWorkflowArgs.error}`);
+                errorLog("");
+                errorLog(getMergeWorkflowInstallUsage());
+                return 1;
+            }
+            try {
+                return await runMergeWorkflowInstall(deps.cwd, mergeWorkflowArgs.options, buildMergeWorkflowInstallDeps(deps, log, errorLog));
+            }
+            catch {
+                // Containment. A domain or subprocess exception escaping here would
+                // print an unbounded message that can carry a remote URL with an
+                // embedded token; the named reason plus a remediation sentence is the
+                // only operator-facing surface this command has.
+                errorLog("merge_workflow_install_failed");
+                errorLog("The merge-workflow installer stopped unexpectedly. Re-run it; anything already " +
+                    "created was left in place.");
+                return 1;
+            }
+        }
         if (!baseUrlResult.ok) {
             errorLog(baseUrlResult.error);
             return 1;
@@ -4783,6 +5159,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         let host;
         if (dryRunPlatforms !== undefined) {
             const dryRunTargets = hostConfigTargetsForPlatforms(dryRunPlatforms);
+            const dryRunNotesPlan = resolveAgentNotesTargets(dryRunPlatforms);
             const launchDecision = resolveInstallBridgeLaunchDecision(dryRunPlatforms, options.agentName);
             let launch;
             if (launchDecision.kind === "spawn") {
@@ -4809,7 +5186,8 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 configTargets: dryRunTargets.map((t) => t.relPath),
                 manualEditors: manualEditorNames(await detectManualEditors(deps)),
                 launch,
-                notesTargets: resolveAgentNotesTargets(dryRunPlatforms).targets,
+                notesTargets: dryRunNotesPlan.targets,
+                notesPlatformLabels: labelsForPlatforms(dryRunNotesPlan.supportedPlatforms),
             };
         }
         else {
@@ -5689,12 +6067,35 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             // self-serve record — once more with a freshly minted token (R4-3).
             let exchange;
             let selfServeRefreshed = false;
+            // BAPI-1263: the email typed after an `email_required` refusal. Run-local only —
+            // never persisted, logged, or written to the pending record — and carried on
+            // every later ordinary-invite exchange, including after a 409 rename.
+            let inviteEmail;
             for (;;) {
-                exchange = await exchangeBootstrapInvite(deps, baseUrl, inviteToken, repoName, keySecret);
+                exchange = await exchangeBootstrapInvite(deps, baseUrl, inviteToken, repoName, keySecret, inviteEmail);
                 // 409 repo_name_taken: the server ROLLED BACK, so the invite is NOT consumed and
                 // the SAME token can be retried under a new name — with the SAME pending secret,
-                // re-pointed to that name.
-                while (!exchange.ok && exchange.kind === "repo-name-taken") {
+                // re-pointed to that name. The same loop handles an ordinary invite's 426
+                // `email_required` (BAPI-1263), so a 409 on the email-bearing retry re-enters
+                // the rename branch without an extra exchange request.
+                while (!exchange.ok &&
+                    (exchange.kind === "repo-name-taken" ||
+                        (exchange.kind === "email-required" && !selfServeSignupMode))) {
+                    if (exchange.kind === "email-required") {
+                        if (inviteEmail !== undefined) {
+                            return fatal(INVITE_EMAIL_REPEATED_REFUSAL_MESSAGE);
+                        }
+                        if (!deps.isTTY || !deps.promptLine) {
+                            return fatal(INVITE_EMAIL_REQUIRED_NON_INTERACTIVE_MESSAGE);
+                        }
+                        const typedEmail = await promptForBoundedEmail(deps, INVITE_EMAIL_PROMPT);
+                        if (typedEmail === undefined) {
+                            return fatal(INVITE_EMAIL_INVALID_ANSWERS_MESSAGE);
+                        }
+                        inviteEmail = typedEmail;
+                        exchange = await exchangeBootstrapInvite(deps, baseUrl, inviteToken, repoName, keySecret, inviteEmail);
+                        continue;
+                    }
                     if (!deps.isTTY || !deps.promptLine) {
                         errorLog(`Error: ${exchange.message} Re-run with a different --repo (the bootstrap invite has NOT ` +
                             "been used).");
@@ -5721,7 +6122,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                     }
                     repoName = nextRepo;
                     // Same token, same key_secret — never regenerated inside the rename loop.
-                    exchange = await exchangeBootstrapInvite(deps, baseUrl, inviteToken, repoName, keySecret);
+                    exchange = await exchangeBootstrapInvite(deps, baseUrl, inviteToken, repoName, keySecret, inviteEmail);
                 }
                 if (exchange.ok)
                     break;
@@ -6088,7 +6489,8 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         // selected set. `writeAgentNotes` never touches `writeMcpInstallState` or any
         // other persisted install-state contract — consent is re-evaluated every run.
         const notesPlan = resolveAgentNotesTargets(selectedPlatforms);
-        const notesOffer = await offerAgentGuidanceNotes(deps, log, notesPlan.targets);
+        const notesPlatformLabels = labelsForPlatforms(notesPlan.supportedPlatforms);
+        const notesOffer = await offerAgentGuidanceNotes(deps, log, notesPlan.targets, notesPlatformLabels);
         let notesResult;
         let notesWriteFailed = false;
         if (notesOffer.kind === "consented") {