@bridge_gpt/mcp-server 0.2.58 → 0.2.60

package/build/install-bridge.js

@@ -162,12 +162,17 @@ 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";
-import { runConductorInstallDoctor, CONDUCTOR_PROFILE_TOKEN, } from "./conductor/install-doctor.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";
 // BAPI-941: read-only workflow-lineage probe, wired into the conductor install
@@ -300,7 +305,7 @@ export const INSTALL_BRIDGE_AGENT_PROMPT = "Run /install-bridge now, with no arg
     "duplicate. This silence applies ONLY to success and ONLY in the install-spawn context: a Stage 6 " +
     "FAILURE is still reported loudly and in full, and in JOIN MODE or a direct/manual /install-bridge " +
     "invocation Stage 6 reports its success exactly as it does today. " +
-    "The install-spawn skip set is exactly Stage 8, Stage 9, and Stage 10. The command-owned Stage 11 " +
+    "The install-spawn skip set is exactly Stage 8 and Stage 9. The command-owned Stage 11 " +
     "(invite teammates) is NOT in that skip set: it is independently gated and may run only when the " +
     "caller's role is admin AND customer_type is b2b AND an interactive response is available; " +
     "otherwise it is skipped silently. If Stage 11 mints a teammate key, show that plaintext key " +
@@ -572,7 +577,7 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "                                (its own separate consent), then closes the local",
         "                                out-of-the-box gap in two more phases, each behind",
         "                                its OWN consent: tool visibility adds the",
-        "                                `conductor` token to existing .mcp.json /",
+        "                                `epic_implementer` token to existing .mcp.json /",
         "                                .vscode/mcp.json / .cursor/mcp.json entries (never",
         "                                Codex or Copilot, and never creating a file) and",
         "                                prints the MCP-client restart advisory; local",
@@ -589,6 +594,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 +985,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 +1053,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 +1085,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 +1151,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" };
@@ -1123,9 +1210,9 @@ export function buildAgentNotesSummaryLine(offer, result, writeFailed, unsupport
  * Exported so `index.ts`'s `--init` can share the exact same prompt mechanics
  * as `install`'s missing-project-root confirmation (BAPI-818, R1).
  */
-export function promptLineViaReadline(promptText) {
+export function promptLineViaReadline(promptText, input = process.stdin, output = process.stderr) {
     return new Promise((resolve) => {
-        const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+        const rl = readline.createInterface({ input, output });
         // See promptSecretViaReadline: EOF must resolve rather than deadlock the
         // top-level await, and `answered` guards the synchronous `close` from
         // discarding a real answer.
@@ -1374,6 +1461,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 +1634,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 +1668,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 +1692,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))),
     };
@@ -1454,8 +1736,8 @@ function buildConductorExecutorDeps(deps, baseUrl) {
  */
 function buildConductorLocalDeps(deps) {
     return {
-        mergeProfileToken: () => mergeBridgeApiProfileToken(deps.cwd, CONDUCTOR_PROFILE_TOKEN),
-        inspectProfileToken: () => inspectBridgeApiProfileToken(deps.cwd, CONDUCTOR_PROFILE_TOKEN, {
+        mergeProfileToken: () => mergeBridgeApiProfileToken(deps.cwd, EPIC_IMPLEMENTER_PROFILE_TOKEN),
+        inspectProfileToken: () => inspectBridgeApiProfileToken(deps.cwd, EPIC_IMPLEMENTER_PROFILE_TOKEN, {
             readFile: deps.readFile,
         }),
         // The repository root is this command's cwd, which is what the hook
@@ -2013,6 +2295,174 @@ export function promptMultiSelectViaReadline(promptText, options, input = proces
         prompt();
     });
 }
+/**
+ * Subscription display name for the three platforms whose maximize-posture
+ * option-three wording names the actual tool, keyed by the SAME
+ * `HostPlatformId` `resolveSelectedHostPlatforms` returns. Deliberately does
+ * NOT project `MCP_HOST_TARGETS[id].label` — that registry label reads
+ * "OpenAI Codex", which is not this feature's approved wording.
+ */
+const OPTIMIZATION_POSTURE_SUBSCRIPTION_NAMES = {
+    "claude-code": "Claude Code",
+    codex: "Codex",
+    cursor: "Cursor",
+};
+/**
+ * `"{name} subscription"` for the three eligible platforms, and the generic
+ * `"coding subscription"` for every other input — Copilot, Windsurf, an
+ * unrecognized id, or no primary platform at all (empty tool selection).
+ */
+export function optimizationPostureSubscriptionNounPhrase(primaryPlatform) {
+    const mapped = primaryPlatform ? OPTIMIZATION_POSTURE_SUBSCRIPTION_NAMES[primaryPlatform] : undefined;
+    return mapped ? `${mapped} subscription` : "coding subscription";
+}
+/** Option three's exact wording, platform-aware (BAPI-1221 Step 2). */
+function buildOptimizationPostureOptionThree(primaryPlatform) {
+    return `Get the most out of your ${optimizationPostureSubscriptionNounPhrase(primaryPlatform)}?`;
+}
+/** The neutral single-line correction reprompted for any malformed answer. */
+const OPTIMIZATION_POSTURE_CORRECTION = "Enter a single number from 1 to 3.";
+/**
+ * Bounds the picker's correction reprompts, mirroring this file's existing
+ * {@link INSTALL_BRIDGE_MAX_CODE_REJECTIONS} convention. A real interactive
+ * user always reaches a terminal answer well inside this many tries — Enter
+ * (blank) or Ctrl+D (EOF) both resolve immediately — so this cap exists only
+ * to stop a `promptLine` seam that NEVER produces a digit or a blank answer
+ * from reprompting forever. Set comfortably above the widest malformed-input
+ * sweep this picker is tested against (a comma list, a range, signed and
+ * decimal values, `0`, `4`, blank-with-more-input, and arbitrary text).
+ */
+const OPTIMIZATION_POSTURE_MAX_CORRECTIONS = 20;
+/**
+ * Render the one-time posture menu and its input instruction. Exactly three
+ * vertically ordered numbered options; option three is platform-aware. Plain,
+ * wrap-safe text — no color-only state, icons, or decorative framing.
+ */
+function buildOptimizationPostureMenu(primaryPlatform) {
+    return ("How should Bridge optimize its work on this repository?\n" +
+        "  1. Quality\n" +
+        "  2. Speed\n" +
+        `  3. ${buildOptimizationPostureOptionThree(primaryPlatform)}\n` +
+        `${OPTIMIZATION_POSTURE_CORRECTION} `);
+}
+/**
+ * The purpose-built, strict single-select optimization-posture picker
+ * (BAPI-1221 Step 2). Renders the three-option menu exactly once and loops
+ * ONLY the neutral correction line on a malformed answer — never
+ * `promptMultiSelectViaReadline()`, whose comma-separated contract this
+ * picker deliberately does not share.
+ *
+ * Accepts only a trimmed single digit `1`, `2`, or `3`; every other answer
+ * (a comma list, a range, a signed or decimal value, blank text, or
+ * unrelated text) is malformed and reprompted. EOF, an unavailable
+ * `deps.promptLine` seam, or a genuinely blank/no-answer result all resolve
+ * `null` rather than looping indefinitely — `promptLineViaReadline` itself
+ * already collapses real EOF and an empty typed answer to the same `""`, so
+ * there is no seam-level way (or need) to tell them apart here.
+ */
+export async function promptOptimizationPosture(deps, primaryPlatform) {
+    if (!deps.isTTY || !deps.promptLine)
+        return null;
+    const promptLine = deps.promptLine;
+    try {
+        let answer = (await promptLine(buildOptimizationPostureMenu(primaryPlatform))).trim();
+        for (let attempts = 0;; attempts++) {
+            if (answer === "1")
+                return "quality";
+            if (answer === "2")
+                return "speed";
+            if (answer === "3")
+                return "maximize_subscription";
+            if (answer === "")
+                return null;
+            if (attempts >= OPTIMIZATION_POSTURE_MAX_CORRECTIONS)
+                return null;
+            answer = (await promptLine(`${OPTIMIZATION_POSTURE_CORRECTION} `)).trim();
+        }
+    }
+    catch {
+        // Prompt/stream exception at the posture-step boundary: fail open to a
+        // no-answer outcome rather than aborting an otherwise-complete install.
+        return null;
+    }
+}
+/** Build the posture config-field URL, matching {@link buildPingUrl}'s normalization. */
+function buildOptimizationPostureUrl(baseUrl) {
+    return `${baseUrl.replace(/\/+$/, "")}/jira/config-field/optimization_posture`;
+}
+/**
+ * Persist the captured posture through the existing, generic configuration
+ * endpoint (BAPI-1221 Step 4) — the SAME `PUT /jira/config-field/{field_name}`
+ * every other config-field write uses; this ticket adds no new endpoint,
+ * model, or migration. Fail-open by design: a missing repo identity, a
+ * forbidden write, any other non-OK response, or a network/timeout failure
+ * all return a coarse outcome rather than throwing, and none of them retries
+ * or blocks the rest of installation. The response body is never read or
+ * logged, and the API key never appears in the URL, body, or any returned
+ * message.
+ */
+export async function persistOptimizationPosture(deps, baseUrl, apiKey, repoName, value) {
+    if (!repoName || repoName.trim().length === 0) {
+        return { kind: "missing-repo-identity" };
+    }
+    let resp;
+    try {
+        resp = await deps.fetch(buildOptimizationPostureUrl(baseUrl), {
+            method: "PUT",
+            headers: { "X-API-Key": apiKey, "Content-Type": "application/json" },
+            body: JSON.stringify({ repo_name: repoName, value }),
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    catch {
+        return { kind: "request-failed" };
+    }
+    if (resp.ok)
+        return { kind: "success" };
+    if (resp.status === 403)
+        return { kind: "forbidden" };
+    return { kind: "http-error", status: resp.status };
+}
+/** Confirmation noun phrase used in the deferred-activation success message. */
+function optimizationPostureConfirmationPhrase(value, primaryPlatform) {
+    if (value === "quality")
+        return "quality";
+    if (value === "speed")
+        return "speed";
+    return `getting the most out of your ${optimizationPostureSubscriptionNounPhrase(primaryPlatform)}`;
+}
+/** Printed immediately after a successful posture write, on its own line. */
+const OPTIMIZATION_POSTURE_BLOG_URL = "https://bridgegpt.ai/blog/how-we-optimize-your-setup";
+const OPTIMIZATION_POSTURE_REMEDIATION = "Update it later with /teach-bridge or the optimization_posture setting in the web UI.";
+/**
+ * The generic, secret-free fail-open message shared by every non-success,
+ * non-forbidden outcome — an interactive no-answer/prompt-exception (no PUT
+ * was ever attempted) and a missing-repo-identity/HTTP-error/network failure
+ * (a PUT was attempted and did not take). States plainly that the current
+ * server value is unchanged; a new repository merely READS as Quality via
+ * the BAPI-1220 server-side default, so this never claims every repository
+ * IS now Quality.
+ */
+const OPTIMIZATION_POSTURE_UNCHANGED_MESSAGE = `  Optimization posture was not changed; new repositories use Quality by default. ${OPTIMIZATION_POSTURE_REMEDIATION}`;
+/**
+ * Report the outcome of the optional posture capture/persistence step
+ * (BAPI-1221 Step 5) — called only when an explicit interactive selection was
+ * captured and the PUT helper actually ran.
+ */
+function reportOptimizationPostureOutcome(log, result, value, primaryPlatform) {
+    if (result.kind === "success") {
+        log(`  Preference saved for later activation — we'll optimize for ${optimizationPostureConfirmationPhrase(value, primaryPlatform)}.`);
+        log(`  ${OPTIMIZATION_POSTURE_BLOG_URL}`);
+        return;
+    }
+    if (result.kind === "forbidden") {
+        log(`  Optimization posture was not changed (an admin API key is required). ${OPTIMIZATION_POSTURE_REMEDIATION}`);
+        return;
+    }
+    // missing-repo-identity, http-error, request-failed: none carries
+    // user-actionable detail beyond "it didn't take."
+    log(OPTIMIZATION_POSTURE_UNCHANGED_MESSAGE);
+}
 /**
  * Resolve the selected host platforms with strict precedence (BAPI-635):
  *   1. explicit `--tools` (including an explicit EMPTY selection — never falls
@@ -3862,7 +4312,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 ?? []) : []),
     ];
 }
 /**
@@ -3974,14 +4424,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.",
     ];
 }
@@ -4065,7 +4522,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 ?? []) : []),
     ];
 }
 /**
@@ -4491,6 +4948,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;
@@ -4615,6 +5106,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") {
@@ -4641,7 +5133,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 {
@@ -4948,6 +5441,18 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // global (Codex) or manual (Windsurf) target is provisioned by the
     // registry-driven emitter after the connectivity check.
     const selectedPlatforms = await resolveSelectedHostPlatforms(deps, options);
+    // ---- BAPI-1221 (S2): capture the optimization-posture preference ----
+    // Asked immediately after tool selection, on every otherwise-eligible
+    // interactive install (including reinstalls and an explicit empty
+    // selection) — a prior posture is never read first. `--dry-run` already
+    // returns long before this point (see the NOTE below), so this gate is
+    // belt-and-suspenders, not the sole guard. The primary platform is
+    // `selectedPlatforms[0]` exclusively, relying on the resolver's own
+    // `HOST_PLATFORM_ORDER` normalization even when several tools were chosen.
+    const optimizationPostureEligible = deps.isTTY && Boolean(deps.promptLine) && !options.dryRun;
+    const optimizationPostureSelection = optimizationPostureEligible
+        ? await promptOptimizationPosture(deps, selectedPlatforms[0])
+        : null;
     if (options.codexProfile && !selectedPlatforms.includes("codex")) {
         errorLog("Error: --codex-profile requires Codex in --tools or the interactive selection.");
         return 1;
@@ -5648,6 +6153,18 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 : `Error: ${ping.message}`);
         }
         log("  connectivity OK");
+        // ---- BAPI-1221 (S2): persist the captured posture, now that connectivity
+        // is validated and `repoName`/`apiKey` are both final. Overwrites any
+        // existing value unconditionally — the old value is never read first. A
+        // no-answer (or a prompt/stream exception the picker already absorbed)
+        // reports the same fail-open remediation without ever attempting a write.
+        if (optimizationPostureSelection) {
+            const postureResult = await persistOptimizationPosture(deps, baseUrl, apiKey, repoName, optimizationPostureSelection);
+            reportOptimizationPostureOutcome(log, postureResult, optimizationPostureSelection, selectedPlatforms[0]);
+        }
+        else if (optimizationPostureEligible) {
+            log(OPTIMIZATION_POSTURE_UNCHANGED_MESSAGE);
+        }
         const entry = buildInstallBridgeServerEntry(deps.cwd, repoName, apiKey, baseUrl, docsDir);
         // BAPI-666: the secret-free variant (no BAPI_API_KEY) is written instead of the
         // real entry into any git-tracked project config the user did not explicitly
@@ -5896,7 +6413,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") {