@bridge_gpt/mcp-server 0.2.59 → 0.2.60

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";
@@ -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" };
@@ -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))),
     };
@@ -4030,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 ?? []) : []),
     ];
 }
 /**
@@ -4142,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.",
     ];
 }
@@ -4233,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 ?? []) : []),
     ];
 }
 /**
@@ -4659,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;
@@ -4783,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") {
@@ -4809,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 {
@@ -6088,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") {

package/build/mcp-install-state.js

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