@bridge_gpt/mcp-server 0.2.62 → 0.2.66

package/build/init.js

@@ -10,6 +10,7 @@
  * effects and depends only on leaf modules.
  */
 import { writeFile, mkdir, readFile, stat } from "fs/promises";
+import { execFile } from "child_process";
 import path from "path";
 import os from "os";
 import { COMMANDS } from "./commands.generated.js";
@@ -19,7 +20,7 @@ import { AGENTS } from "./agents.generated.js";
 import { DOCS } from "./docs.generated.js";
 import { VERSION, LAUNCHER_ARGS } from "./version.generated.js";
 import { reconstructAgentMarkdown, translateAgentToCopilot, translateCommandToCopilot, } from "./agent-utils.js";
-import { validateRepoName, resolveRepoNameForProjectRoot } from "./bridge-config.js";
+import { BRIDGE_CONFIG_TEAMMATE_NOTICE_LINES, validateBridgeConfigRepoNameRepresentability, validateRepoName, resolveRepoNameForProjectRoot, } from "./bridge-config.js";
 import { ensureGitignored as ensureGitignoredShared } from "./git-ignore-utils.js";
 import { resolveBapiCredentials } from "./credential-store.js";
 import { describeLauncherReason, DUPLICATE_REGISTRATION_GUIDANCE, inspectLauncherConfigs, isPrerequisiteFailure, } from "./launcher-config-inspection.js";
@@ -133,6 +134,8 @@ export function buildBridgeConfigManifest(repoName) {
         "# Inherited by every git worktree; start-tickets worktree provisioning reads it",
         "# to decide which Bridge API MCP registrations to write. Do not add credentials,",
         "# connection URLs, or machine-specific paths here — those are resolved at runtime.",
+        "#",
+        ...BRIDGE_CONFIG_TEAMMATE_NOTICE_LINES,
         "",
         `repo_name = "${repoName}"`,
         "",
@@ -389,6 +392,65 @@ export class InitPreflightError extends Error {
         this.failures = failures;
     }
 }
+/**
+ * Classify `git ls-files --error-unmatch -- <relPath>` from its exit code: 0 is
+ * tracked, 1 is untracked, anything else is undetermined. Shared by `runInit`
+ * and install so both reach the same verdict from the same probe.
+ */
+export function classifyTrackedProbeExitCode(exitCode) {
+    if (exitCode === 0)
+        return "tracked";
+    if (exitCode === 1)
+        return "untracked";
+    return "undetermined";
+}
+/**
+ * Default tracked-config probe for `runInit`: runs git with an ARGUMENT LIST,
+ * never a shell string, in `cwd`. Any failure is `undetermined`, which callers
+ * treat as untracked — the probe fails OPEN, so a missing git or a non-repo
+ * folder still gets today's `BAPI_PROJECT_ROOT = cwd` rewrite.
+ */
+export function defaultIsTrackedConfig(cwd) {
+    return (relPath) => new Promise((resolve) => {
+        try {
+            execFile("git", ["ls-files", "--error-unmatch", "--", relPath], { cwd, windowsHide: true, timeout: 10_000 }, (error) => {
+                if (!error)
+                    return resolve("tracked");
+                const code = error.code;
+                resolve(classifyTrackedProbeExitCode(typeof code === "number" ? code : null));
+            });
+        }
+        catch {
+            resolve("undetermined");
+        }
+    });
+}
+/**
+ * Decide the `BAPI_PROJECT_ROOT` an EXISTING Bridge entry should carry (BAPI-1318).
+ * A git-tracked config keeps its existing non-blank value exactly: the runtime
+ * check in `project-root.ts` makes a committed path harmless for teammates, and
+ * rewriting it would put this machine's path into everyone's diff. Untracked and
+ * undetermined configs, and blank or absent values, get `cwd` as before.
+ *
+ * `warnReplaced` is true only when the probe was undetermined AND a different,
+ * non-blank value is being replaced — the one case where a tracked path may have
+ * been rewritten without the protection applying.
+ */
+export function decideExistingProjectRoot(existing, cwd, tracked) {
+    const current = typeof existing === "string" ? existing : "";
+    const blank = current.trim().length === 0;
+    if (tracked === "tracked" && !blank)
+        return { value: current, warnReplaced: false };
+    return {
+        value: cwd,
+        warnReplaced: tracked === "undetermined" && !blank && current !== cwd,
+    };
+}
+/** The one secret-safe warning for an undetermined probe that replaced a root. */
+export function formatUndeterminedRootReplacedWarning(relPath) {
+    return (`  Warning: could not tell whether ${relPath} is tracked by git, so its BAPI_PROJECT_ROOT ` +
+        "was rewritten to this folder. Review its diff before committing.");
+}
 /**
  * Resolve the non-secret identity a NEW Bridge entry should carry.
  *
@@ -518,6 +580,20 @@ export async function runInit(cwd, options = {}) {
     const targetSpec = `${MCP_PACKAGE_NAME}@${targetVersion}`;
     const say = options.stdout ?? ((m) => console.log(m));
     const warn = options.stderr ?? ((m) => console.error(m));
+    const trackedProbe = options.isTrackedConfig ?? defaultIsTrackedConfig(cwd);
+    const probeTracked = async (relPath) => {
+        try {
+            const verdict = await trackedProbe(relPath);
+            if (verdict === true)
+                return "tracked";
+            if (verdict === false)
+                return "untracked";
+            return verdict === "tracked" || verdict === "untracked" ? verdict : "undetermined";
+        }
+        catch {
+            return "undetermined";
+        }
+    };
     // ---- Phase 1: IDE Detection ----
     // BAPI-708: detection lives in `detectInitIdes` so the commit-safe asset
     // manifest resolves the SAME conditional targets this scaffolder writes.
@@ -701,7 +777,17 @@ export async function runInit(cwd, options = {}) {
         entry.args = refreshed;
         if (!entry.env)
             entry.env = {};
-        entry.env.BAPI_PROJECT_ROOT = cwd;
+        // BAPI-1318: a git-tracked config keeps its committed BAPI_PROJECT_ROOT.
+        // The probe runs only when there is a non-blank value to preserve.
+        const existingRoot = entry.env.BAPI_PROJECT_ROOT;
+        let trackedVerdict = "untracked";
+        if (typeof existingRoot === "string" && existingRoot.trim().length > 0 && existingRoot !== cwd) {
+            trackedVerdict = await probeTracked(target.path);
+        }
+        const rootDecision = decideExistingProjectRoot(existingRoot, cwd, trackedVerdict);
+        entry.env.BAPI_PROJECT_ROOT = rootDecision.value;
+        if (rootDecision.warnReplaced)
+            warn(formatUndeterminedRootReplacedWarning(target.path));
         await io.writeFile(fullPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
         const kind = found.action === "already-current"
             ? "already-current"
@@ -1094,9 +1180,24 @@ says to serialize structured output.
     // the credential landed and which generated assets are safe to commit. Removed
     // outright rather than behind an output-mode flag — parameterizing would change
     // the injected `deps.runInit` seam signature for no user-visible gain.
+    // BAPI-1318: a caller that already resolved the project name (install) is
+    // authoritative, so the manifest agrees with the MCP entry. `--init` and
+    // `upgrade` pass no creation context and keep the folder-name default.
+    let bridgeConfigCreated = false;
+    let bridgeConfigRepoName;
     if (!bridgeConfigExists) {
-        await mkdir(path.dirname(bridgeConfigPath), { recursive: true });
-        await writeFile(bridgeConfigPath, buildBridgeConfigManifest(chooseScaffoldRepoName(cwd)), "utf-8");
+        const scaffoldName = options.creationContext?.repoName ?? chooseScaffoldRepoName(cwd);
+        const representable = validateBridgeConfigRepoNameRepresentability(scaffoldName);
+        if (representable.ok) {
+            await mkdir(path.dirname(bridgeConfigPath), { recursive: true });
+            await writeFile(bridgeConfigPath, buildBridgeConfigManifest(representable.value), "utf-8");
+            bridgeConfigCreated = true;
+            bridgeConfigRepoName = representable.value;
+        }
+        else {
+            warn("  Warning: .bridge/config was not created because this project name cannot be written " +
+                `there (${representable.error}). Worktrees and shell tools will fall back to the git folder name.`);
+        }
     }
     // BAPI-728: authoritative, secret-free outcome. `ok` is false whenever any
     // entry authenticates as nobody, so no caller can report full success over a
@@ -1106,5 +1207,7 @@ says to serialize structured output.
         configActions: structuredActions,
         readinessWarnings,
         targetVersion,
+        bridgeConfigCreated,
+        ...(bridgeConfigRepoName !== undefined ? { bridgeConfigRepoName } : {}),
     };
 }

package/build/install-bridge-conductor.js

@@ -106,7 +106,7 @@
  * The command does NOT persist a repository-level review policy: that is
  * BAPI-694's. The policy selected here is per-run and is reported as such.
  */
-import { bootstrapConductorSupervisorDefaults, ConductorBridgeApiError, fetchConductorReadiness, } from "./conductor/bridge-api-client.js";
+import { bootstrapConductorSupervisorDefaults, classifySupervisorBootstrapFailure, fetchConductorReadiness, previewConductorSupervisorBootstrap, } from "./conductor/bridge-api-client.js";
 import { CONDUCTOR_OPERATOR_RUNBOOK_POINTER, EXECUTOR_PROVISIONING_GUIDANCE, conductorInstallDoctorExitCode, conductorInstallDoctorHasFatal, formatConductorInstallDoctorReport, } from "./conductor/install-doctor.js";
 import { describeNativeLedgerAvailability, } from "./conductor/doctor.js";
 import { CONDUCTOR_BIN_UNRESOLVED_ERROR, MANAGED_HOOK_NAMES, } from "./conductor/git-hooks.js";
@@ -167,13 +167,20 @@ export function getInstallBridgeConductorUsage() {
         "  --secret-name <NAME>       claude-review workflow: OAuth token secret NAME",
         "  --branches a,b             claude-review workflow: PR branch triggers",
         "  --skip-workflow            Never offer the claude-review workflow",
+        "  --replace-done-gate        Replace an EXISTING done gate with the CI-only gate",
+        "                             built from --required-check. Without it, a repeat",
+        "                             install keeps the stored gate and only adds missing",
+        "                             checks. Any requirement a replacement would remove",
+        "                             is previewed and needs its own exact approval.",
         "  --launch-profile <name>    (BAPI-1260) Opt in to the reusable epic launch: after",
         "                             every mandatory prerequisite is verified, persist a",
         "                             host-local profile and print the ONE drive-epic",
         "                             command that selects it (runs in a fresh shell).",
+        "                             Optional for production — drive-epic targets it with",
+        "                             no profile. Needed for local or durable-host targets.",
         "  --base-url <url>           Explicit Bridge API target for --launch-profile.",
-        "                             Required there (or BAPI_BASE_URL): nothing defaults",
-        "                             to production; select it deliberately.",
+        "                             Required there (or BAPI_BASE_URL): guided setup",
+        "                             approves one named server and has no default.",
         "  --execution-mode <mode>    local | durable (default: durable with",
         "                             --executor-id, otherwise local).",
         "  --policy-file <path>       Run policy the profile references; an unattended",
@@ -262,6 +269,7 @@ export function parseInstallBridgeConductorArgs(argv) {
     let repo;
     let dryRun = false;
     let skipWorkflow = false;
+    let replaceDoneGate = false;
     let reviewPolicy = DEFAULT_CONDUCTOR_REVIEW_POLICY;
     let reviewPolicyExplicit = false;
     let epicKey;
@@ -304,6 +312,11 @@ export function parseInstallBridgeConductorArgs(argv) {
                     return { status: "error", message: "--skip-workflow takes no value" };
                 skipWorkflow = true;
                 break;
+            case "--replace-done-gate":
+                if (inline !== undefined)
+                    return { status: "error", message: "--replace-done-gate takes no value" };
+                replaceDoneGate = true;
+                break;
             case "--repo-wide":
                 if (inline !== undefined)
                     return { status: "error", message: "--repo-wide takes no value" };
@@ -480,6 +493,7 @@ export function parseInstallBridgeConductorArgs(argv) {
             secretName,
             branches,
             skipWorkflow,
+            ...(replaceDoneGate ? { replaceDoneGate: true } : {}),
             executorId,
             ...(epicRunIds.length > 0 ? { epicRunIds } : {}),
             ...(repoWide ? { repoWide: true } : {}),
@@ -582,6 +596,89 @@ export async function observeExecutorReadiness(access, fetchJson, deps, options
 // Runner
 // ---------------------------------------------------------------------------
 const CONSENT_YES = new Set(["y", "yes"]);
+/** Fixed, value-free operator text for each bootstrap failure (BAPI-1288). */
+const BOOTSTRAP_FAILURE_TEXT = Object.freeze({
+    "unsupported-protocol": "the Bridge API server does not support the gate-change preview protocol " +
+        "(it predates BAPI-1288) or answered a response this installer cannot verify. " +
+        "Upgrade the server before re-running; this installer never falls back to the " +
+        "older bootstrap that replaced configured gates.",
+    "approval-required": "the server requires an approved preview for this change. Re-run to preview it again.",
+    "stale-preview": "the project defaults changed since the preview, or the approval expired. " +
+        "Re-run to preview the current state again.",
+    "unknown-stored-state": "a stored project-default row cannot be read with certainty, so no change to it " +
+        "can be evaluated. See the account-settings operator runbook " +
+        "(unknown_stored_state) before re-running.",
+    "non-relaxable": "the change would turn auto-merge on or drop the human merge-approval requirement, " +
+        "which no gate-change approval can authorize.",
+    "invalid-proposal": "the server rejected the proposed configuration as unreadable.",
+    "state-unavailable": "the server could not read or lock the project defaults right now. Retry shortly.",
+    unauthorized: "the API key was rejected, or it is not an admin key for this repository.",
+    network: "the Bridge API could not be reached.",
+    timeout: "the Bridge API did not answer in time.",
+    server: "the Bridge API reported an internal error.",
+    rejected: "the Bridge API rejected the request.",
+});
+function reportBootstrapFailure(deps, stage, kind) {
+    const label = stage === "preview" ? "Bootstrap preview failed" : "Bootstrap failed";
+    deps.errorLog(`${label} (${kind}): ${BOOTSTRAP_FAILURE_TEXT[kind]}`);
+    deps.errorLog(stage === "preview"
+        ? "No server write was attempted. No workflow or verification step was run."
+        : "Every configured requirement is unchanged. No workflow or verification step was run.");
+}
+/** Obligation tokens rendered as short fixed phrases — never server free text. */
+const OBLIGATION_LABELS = Object.freeze({
+    ci_check_green: "required CI check green",
+    sticky_verdict_approved: "claude-review sticky verdict approved",
+    native_review_approved: "native GitHub review approved",
+    approval_minimum: "minimum approval count",
+    verdictless_review_parks: "verdictless review parks for a human",
+});
+function formatObligations(tokens) {
+    return tokens.length === 0 ? "none" : tokens.map((t) => OBLIGATION_LABELS[t] ?? t).join(", ");
+}
+function renderGateChangeEffect(deps, effect) {
+    deps.log(`    - ${effect.row} ${effect.requirement}: ${effect.change}`);
+    deps.log(`      ${effect.description}`);
+    deps.log(`      removes: ${formatObligations(effect.removed_obligations)}`);
+    if (effect.replacement_obligations.length > 0) {
+        deps.log(`      replaced by: ${formatObligations(effect.replacement_obligations)}`);
+    }
+    if (effect.removed_ci_check_count > 0) {
+        const refs = effect.removed_ci_check_refs.join(", ");
+        deps.log(`      CI checks no longer required: ${effect.removed_ci_check_count}` +
+            (refs ? ` (refs: ${refs})` : ""));
+    }
+    if (effect.stored_min_approvals !== null || effect.proposed_min_approvals !== null) {
+        deps.log(`      approval minimum: ${effect.stored_min_approvals ?? "none"} → ` +
+            `${effect.proposed_min_approvals ?? "none"}`);
+    }
+}
+function renderBootstrapPreview(deps, preview) {
+    deps.log("  Server preview (nothing written yet):");
+    deps.log(`    supervisor setup:  ${preview.setup_outcome}`);
+    deps.log(`    supervisor config: ${preview.config_outcome}`);
+    if (preview.changed_field_names.length > 0) {
+        deps.log(`    fields that would change: ${preview.changed_field_names.join(", ")}`);
+    }
+    else {
+        deps.log("    nothing would change — the configured project defaults are already in place.");
+    }
+    if (preview.approval_required) {
+        deps.log("");
+        deps.log("  This change REMOVES or WEAKENS configured requirements:");
+        for (const effect of preview.effects)
+            renderGateChangeEffect(deps, effect);
+        deps.log("  CI check refs are opaque; compare them with GET /jira/epic-runs/supervisor-setup/defaults/.");
+    }
+}
+function renderBootstrapOutcome(deps, response) {
+    const describe = (outcome) => outcome === "preserved" ? "preserved (nothing written)" : String(outcome);
+    deps.log(`  supervisor setup:  ${describe(response.setup_outcome)}`);
+    deps.log(`  supervisor config: ${describe(response.config_outcome)}`);
+    if (response.audited_field_names.length > 0) {
+        deps.log(`  committed fields: ${response.audited_field_names.join(", ")}`);
+    }
+}
 async function confirm(deps, promptText) {
     // A missing prompt seam means no TTY. Silence is NOT consent.
     if (!deps.promptLine)
@@ -847,6 +944,13 @@ export const CONDUCTOR_PROFILE_EMPTY_MERGE_REMEDIATION = `run \`npx ${MCP_PACKAG
 /** Remediation printed whenever the managed conductor hooks were not installed. */
 export const CONDUCTOR_HOOKS_MANUAL_REMEDIATION = "re-run `install conductor` and accept the local-observability consent, or run " +
     "`epic-implementer install-git-hooks` directly.";
+/**
+ * Remediation for a non-fatal hook refusal (BAPI-1290): the hooks need a
+ * persistent install to embed, and the repair is to create one and reinstall.
+ */
+export const CONDUCTOR_HOOKS_DURABLE_REMEDIATION = `install the CLI persistently (\`npm i -g ${MCP_PACKAGE_NAME}\`), then run ` +
+    "`epic-implementer install-git-hooks` (or re-run `install conductor` and accept the " +
+    "local-observability consent).";
 /**
  * Phase: tool visibility.
  *
@@ -947,11 +1051,33 @@ async function runConductorLocalObservabilityPhase(deps, local) {
             // `reason` is already a sanitized sentence. This one IS a command failure —
             // a hook that cannot resolve its binary is a dead hook, and the whole point
             // of that ticket is that it no longer gets written silently.
+            // BAPI-1290: the refusal names its fixed classification (e.g.
+            // `ephemeral-cache` for an npx-cache runtime) or its per-hook planning
+            // reasons. It is an OPTIONAL-hook installation refusal — distinct from a
+            // setup-permission stop and from engine admission, which it never gates.
             deps.errorLog(result.error === CONDUCTOR_BIN_UNRESOLVED_ERROR
-                ? `  hook installation refused — ${result.reason}`
-                : "  hook installation refused.");
-            manualActions.push(`local observability: ${CONDUCTOR_HOOKS_MANUAL_REMEDIATION}`);
-            fatal = true;
+                ? `  hook installation refused (${result.classification}) — ${result.reason}`
+                : `  hook installation refused — ${result.reason}`);
+            deps.errorLog("  existing hooks were left unchanged; optional local hook delivery is unavailable " +
+                "(engine admission is unaffected).");
+            // Only BAPI-772's broken-package case stays fatal: the executing artifact
+            // ships no hook binary at all. Every other refusal — an npx-cache runtime
+            // (the documented `npx … install conductor` path), an unqualified or
+            // unloadable runtime, an unsafe existing hook — is a manual action, and
+            // the installer continues to setup-epic verification and executor
+            // provisioning. Optional hooks must never stop the phases that do gate
+            // a run.
+            // A refusal without a classification (an older or injected result shape)
+            // is read as `missing` — fail-closed to BAPI-772's fatal contract.
+            const brokenPackage = result.error === CONDUCTOR_BIN_UNRESOLVED_ERROR &&
+                (result.classification ?? "missing") === "missing";
+            if (brokenPackage) {
+                manualActions.push(`local observability: ${CONDUCTOR_HOOKS_MANUAL_REMEDIATION}`);
+                fatal = true;
+            }
+            else {
+                manualActions.push(`local observability: ${CONDUCTOR_HOOKS_DURABLE_REMEDIATION}`);
+            }
         }
         else if (result !== null && result.ok) {
             if (!result.is_worktree) {
@@ -969,6 +1095,9 @@ async function runConductorLocalObservabilityPhase(deps, local) {
                         ? `  ${hook.name}: ${hook.action}`
                         : `  ${hook.name}: ${hook.action} — warning: ${hook.warning}`);
                 }
+                if (result.partial) {
+                    deps.log("  the hook update is PARTIAL — one managed hook was published and the other was not.");
+                }
                 // Sanitized: the installer's own warnings are secret-free sentences, and
                 // hook CONTENT, env, and caught errors are never rendered.
                 for (const warning of result.warnings)
@@ -979,11 +1108,21 @@ async function runConductorLocalObservabilityPhase(deps, local) {
                 // provisioned observability, and the missing reference-transaction hook
                 // is precisely the one that stops half the events from ever being
                 // emitted.
+                //
+                // BAPI-1290: each hook's `usable` is the installer's shared verdict —
+                // published over a matching snapshot, executable, and backed by the
+                // qualified persistent runtime — and the installer's own `complete`
+                // flag must agree. Anything less is not recorded.
                 const usable = (name) => {
                     const hook = result.installed.find((h) => h.name === name);
-                    return hook !== undefined && hook.action !== "skipped" && hook.warning === undefined;
+                    return (hook !== undefined &&
+                        hook.usable === true &&
+                        hook.action !== "skipped" &&
+                        hook.warning === undefined);
                 };
-                const complete = MANAGED_HOOK_NAMES.every((name) => usable(name)) && result.warnings.length === 0;
+                const complete = result.complete === true &&
+                    MANAGED_HOOK_NAMES.every((name) => usable(name)) &&
+                    result.warnings.length === 0;
                 if (complete) {
                     const recorded = await local.recordCapability("conductor_local_observability");
                     if (!recorded.ok) {
@@ -1084,7 +1223,7 @@ function isHostLocalHostname(hostname) {
  * failure there holds activation. A launcher-local listener can never pass
  * here for a remote target: the server cannot reach this machine's loopback.
  */
-function assessNotification(policy, attended, targetBaseUrl) {
+function assessNotification(policy, attended, targetBaseUrl, readiness) {
     if (attended) {
         return { status: "not-applicable", detail: "the referenced policy is attended; no escalation webhook is required." };
     }
@@ -1093,9 +1232,20 @@ function assessNotification(policy, attended, targetBaseUrl) {
         : null;
     const url = typeof notify?.webhook_url === "string" ? notify.webhook_url.trim() : "";
     if (url === "") {
+        // BAPI-1274 — with no webhook declared, the account's email address is the
+        // escalation channel when the server reports one is present (never the
+        // address itself). A declared webhook stays authoritative and is assessed
+        // below exactly as before; `notify.local_sink` still satisfies nothing.
+        if (readiness?.unattended?.escalation_email_available === true) {
+            return {
+                status: "ok",
+                detail: "No webhook declared; escalation alerts will be emailed to the account's email address",
+            };
+        }
         return {
             status: "missing",
-            detail: "an unattended launch needs notify.webhook_url in its --policy-file" +
+            detail: "an unattended launch needs notify.webhook_url in its --policy-file, or an email " +
+                "address on the account so escalation alerts can be emailed" +
                 (notify && "local_sink" in notify ? " (notify.local_sink is not an escalation channel)." : "."),
         };
     }
@@ -1180,12 +1330,13 @@ async function runLaunchProfilePhase(deps, options, inputs) {
     else {
         deps.log(`  consent:    ${consent === false ? "NOT granted" : "could not be verified"}`);
         gaps.push(consent === false
-            ? "unattended consent is not granted for this repository; an administrator sets it " +
-                "(docs/claude/account-settings-operator-runbook.md) — this command never writes it."
+            ? "unattended consent is off for this repository; turn on 'Allow unattended Epic " +
+                "Implementer runs' on the repository's Setup page in the Bridge admin panel " +
+                "(if it is already on, contact Bridge support) — this command never writes it."
             : "unattended consent could not be verified at the selected target (older server or unreadable report).");
     }
     // (4) Notification, from the server's network perspective.
-    const notification = assessNotification(policy, attended, inputs.baseUrl);
+    const notification = assessNotification(policy, attended, inputs.baseUrl, inputs.readiness);
     deps.log(`  notify:     ${notification.status} — ${notification.detail}`);
     if (notification.status === "missing")
         gaps.push(notification.detail);
@@ -1428,16 +1579,19 @@ export async function runInstallBridgeConductorCli(argv, deps) {
     if (options.dryRun) {
         deps.log("");
         deps.log("Dry run — no writes will be performed.");
-        deps.log("  Would POST /jira/epic-runs/supervisor-bootstrap with field NAMES:");
+        deps.log("  Would PREVIEW, then POST /jira/epic-runs/supervisor-bootstrap with field NAMES:");
         // Field NAMES and a COUNT only — never the check values, which are
         // configuration content, and never the API key.
         deps.log("    - done_gate_config.required_checks " +
             `(${options.requiredChecks.length} check(s))`);
-        deps.log("    - review_source");
         if (options.reviewPolicyExplicit)
             deps.log("    - review_policy");
+        if (options.replaceDoneGate)
+            deps.log("    - replace_done_gate");
         deps.log("    - auto_merge_enabled");
         deps.log("    - merge_approval_required");
+        deps.log("  Existing project defaults would be KEPT: missing checks are added, nothing is " +
+            "removed without a previewed, separately approved change.");
         deps.log(`  Would target base URL: ${baseUrl}`);
         deps.log(options.skipWorkflow || options.reviewPolicy !== "verdict_protocol"
             ? "  Workflow scaffold: skipped (not applicable for this policy)"
@@ -1480,6 +1634,40 @@ export async function runInstallBridgeConductorCli(argv, deps) {
         deps.log("complete-with-manual-steps (dry run)");
         return 0;
     }
+    if (!access) {
+        // Unreachable in practice (a null access produces a fatal doctor section
+        // above), but the type must be narrowed before the preview.
+        deps.errorLog("Bridge API access could not be resolved; aborting before the write.");
+        return 1;
+    }
+    // ---- Phase 2: bootstrap — preview, consent, exact approval, apply -------
+    // BAPI-1288. The server decides what this bootstrap would do to the stored
+    // project defaults; this command only shows that decision and asks. It never
+    // evaluates gate strength itself, and it never falls back to the old
+    // replacing bootstrap when the server cannot preview.
+    deps.log("");
+    deps.log("Phase 2/8 — bootstrapping supervisor project defaults…");
+    const bootstrapRequest = {
+        required_checks: options.requiredChecks,
+        // BAPI-694 — the narrow ReviewPolicy object, sent ONLY on an explicit
+        // selection. `review_source` is deliberately NOT sent: on an existing
+        // repository an omitted field keeps its stored value, and a new repository
+        // receives the server's `verdict_protocol` default either way.
+        ...(options.reviewPolicyExplicit
+            ? { review_policy: { source: options.reviewPolicy } }
+            : {}),
+        merge_approval_required: "true",
+        ...(options.replaceDoneGate ? { replace_done_gate: true } : {}),
+    };
+    let preview;
+    try {
+        preview = await previewConductorSupervisorBootstrap(access, bootstrapRequest, deps.postJson);
+    }
+    catch (err) {
+        reportBootstrapFailure(deps, "preview", classifySupervisorBootstrapFailure(err));
+        return 1;
+    }
+    renderBootstrapPreview(deps, preview);
     // ---- Consent #2: the bootstrap write itself ----------------------------
     // Deliberately separate from the base-URL consent above (which was given
     // before any network call). Confirming WHERE to write is not consent TO write.
@@ -1489,36 +1677,36 @@ export async function runInstallBridgeConductorCli(argv, deps) {
         deps.log("Aborted — no server write was attempted.");
         return 0;
     }
-    if (!access) {
-        // Unreachable in practice (a null access produces a fatal doctor section
-        // above), but the type must be narrowed before the POST.
-        deps.errorLog("Bridge API access could not be resolved; aborting before the write.");
-        return 1;
+    // ---- Consent #3: the EXACT gate change, only when the preview needs it ---
+    // Never inferred from consent #2: agreeing to install is not agreeing to
+    // remove a configured requirement. A missing prompt seam is a refusal.
+    let applyRequest = bootstrapRequest;
+    if (preview.approval_required) {
+        deps.log("");
+        const gateChangeOk = await confirm(deps, "Approve EXACTLY the gate changes listed above? [y/N]: ");
+        if (!gateChangeOk || !preview.approval_token) {
+            deps.errorLog("Gate change not approved — no server write was attempted, and every configured " +
+                "requirement is unchanged.");
+            return 1;
+        }
+        applyRequest = {
+            ...bootstrapRequest,
+            approval: { approve: true, approval_token: preview.approval_token },
+        };
     }
-    // ---- Phase 2: bootstrap ------------------------------------------------
-    deps.log("");
-    deps.log("Phase 2/8 — bootstrapping supervisor project defaults…");
     let bootstrapResponse;
     try {
-        bootstrapResponse = await bootstrapConductorSupervisorDefaults(access, {
-            required_checks: options.requiredChecks,
-            review_source: "verdict_protocol",
-            // BAPI-694 — the narrow ReviewPolicy object, sent ONLY on an explicit
-            // selection. `review_source` above is deliberately left alone: it is the
-            // WIDER done-gate vocabulary and the two are not interchangeable, so
-            // neither value is coerced into the other.
-            ...(options.reviewPolicyExplicit
-                ? { review_policy: { source: options.reviewPolicy } }
-                : {}),
-            merge_approval_required: "true",
-        }, deps.postJson);
+        bootstrapResponse = await bootstrapConductorSupervisorDefaults(access, applyRequest, deps.postJson);
     }
     catch (err) {
-        const kind = err instanceof ConductorBridgeApiError ? err.kind : "network";
-        deps.errorLog(`Bootstrap failed (${kind}). No workflow or verification step was run.`);
+        reportBootstrapFailure(deps, "apply", classifySupervisorBootstrapFailure(err));
+        return 1;
+    }
+    if (bootstrapResponse.setup_outcome === null || bootstrapResponse.config_outcome === null) {
+        reportBootstrapFailure(deps, "apply", "unsupported-protocol");
         return 1;
     }
-    deps.log(`  wrote supervisor setup + config (fields: ${bootstrapResponse.audited_field_names.join(", ")})`);
+    renderBootstrapOutcome(deps, bootstrapResponse);
     // ---- Phase 3: optional workflow scaffold -------------------------------
     deps.log("");
     deps.log("Phase 3/8 — claude-review workflow…");
@@ -1609,8 +1797,10 @@ export async function runInstallBridgeConductorCli(argv, deps) {
         manualActions.push("local observability: run the packaged `install conductor` command, or " +
             "`epic-implementer install-git-hooks`, to install the managed conductor Git hooks.");
     }
-    // The fail-loud hook-binary refusal exits 1 — but only AFTER the phase's
-    // read-only ledger report has been printed, which the phase guarantees.
+    // The fail-loud hook-binary refusal (a package that ships no hook binary)
+    // exits 1 — but only AFTER the phase's read-only ledger report has been
+    // printed, which the phase guarantees. BAPI-1290: qualification refusals are
+    // manual actions, not fatal, so they reach the phases below.
     if (observabilityFatal)
         return 1;
     // ---- Phase 6: setup-epic verification (conditional) --------------------