@bridge_gpt/mcp-server 0.2.60 → 0.2.62

package/build/install-bridge-conductor.js

@@ -110,6 +110,12 @@ import { bootstrapConductorSupervisorDefaults, ConductorBridgeApiError, fetchCon
 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";
+import os from "node:os";
+import path from "node:path";
+import { readFile as readFileAsync, stat as statAsync } from "node:fs/promises";
+import { bindEpicLaunchCredential, readStoredBinding, } from "./credential-store.js";
+import { EPIC_LAUNCH_EXECUTION_MODES, EPIC_LAUNCH_PROFILE_NAME_PATTERN, EPIC_LAUNCH_PROFILE_VERSION, createNodeEpicLaunchStoreDeps, readEpicLaunchProfile, renderEpicLaunchCommand, resolveEpicLaunchTarget, writeEpicLaunchProfile, } from "./epic-launch-profile.js";
+import { DEFAULT_BAPI_BASE_URL } from "./executor/credentials.js";
 import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
 import { CLAUDE_REVIEW_WORKFLOW_RELPATH, renderClaudeReviewWorkflow, } from "./claude-review-workflow.js";
 import { formatExecutorInstallPreflight, } from "./executor/install-preflight.js";
@@ -161,6 +167,18 @@ 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",
+        "  --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).",
+        "  --base-url <url>           Explicit Bridge API target for --launch-profile.",
+        "                             Required there (or BAPI_BASE_URL): nothing defaults",
+        "                             to production; select it deliberately.",
+        "  --execution-mode <mode>    local | durable (default: durable with",
+        "                             --executor-id, otherwise local).",
+        "  --policy-file <path>       Run policy the profile references; an unattended",
+        "                             run needs notify.webhook_url reachable from the",
+        "                             API server (notify.local_sink is not enough).",
         "  --dry-run                  Diagnose and preview only. Performs NO writes:",
         "                             no POST, no file write, no host MCP config write,",
         "                             no Git hook write, no install-state or capability",
@@ -255,6 +273,10 @@ export function parseInstallBridgeConductorArgs(argv) {
     let secretName;
     let branches;
     const requiredChecks = [];
+    let launchProfile;
+    let baseUrl;
+    let executionMode;
+    let policyFile;
     const takeValue = (arg, inline, next) => {
         if (inline !== undefined) {
             if (inline.trim().length === 0)
@@ -297,7 +319,11 @@ export function parseInstallBridgeConductorArgs(argv) {
             case "--epic-run-id":
             case "--allowed-bot":
             case "--secret-name":
-            case "--branches": {
+            case "--branches":
+            case "--launch-profile":
+            case "--base-url":
+            case "--execution-mode":
+            case "--policy-file": {
                 const taken = takeValue(flag, inline, argv[i + 1]);
                 if (!taken.ok)
                     return { status: "error", message: taken.error };
@@ -322,6 +348,28 @@ export function parseInstallBridgeConductorArgs(argv) {
                     allowedBot = value;
                 else if (flag === "--secret-name")
                     secretName = value;
+                else if (flag === "--launch-profile") {
+                    if (!EPIC_LAUNCH_PROFILE_NAME_PATTERN.test(value)) {
+                        return {
+                            status: "error",
+                            message: "--launch-profile must match [a-z0-9][a-z0-9._-]{0,62}.",
+                        };
+                    }
+                    launchProfile = value;
+                }
+                else if (flag === "--base-url")
+                    baseUrl = value;
+                else if (flag === "--policy-file")
+                    policyFile = value;
+                else if (flag === "--execution-mode") {
+                    if (!EPIC_LAUNCH_EXECUTION_MODES.includes(value)) {
+                        return {
+                            status: "error",
+                            message: `Invalid --execution-mode '${value}'. Expected one of: ${EPIC_LAUNCH_EXECUTION_MODES.join(", ")}`,
+                        };
+                    }
+                    executionMode = value;
+                }
                 else if (flag === "--branches") {
                     const list = splitList(value);
                     if (list.length === 0)
@@ -404,6 +452,20 @@ export function parseInstallBridgeConductorArgs(argv) {
                 "--executor-id.",
         };
     }
+    // BAPI-1260 — the launch-profile inputs only mean something together.
+    if (launchProfile === undefined && (baseUrl !== undefined || executionMode !== undefined)) {
+        return {
+            status: "error",
+            message: "--base-url and --execution-mode configure an epic launch profile, so they require --launch-profile.",
+        };
+    }
+    if (executionMode === "durable" && executorId === undefined) {
+        return {
+            status: "error",
+            message: "--execution-mode durable requires --executor-id: a durable launch is served by a provisioned " +
+                "executor service, and this command proves its server-observed handshake before approving it.",
+        };
+    }
     return {
         status: "ok",
         options: {
@@ -421,9 +483,34 @@ export function parseInstallBridgeConductorArgs(argv) {
             executorId,
             ...(epicRunIds.length > 0 ? { epicRunIds } : {}),
             ...(repoWide ? { repoWide: true } : {}),
+            ...(launchProfile ? { launchProfile } : {}),
+            ...(baseUrl ? { baseUrl } : {}),
+            ...(launchProfile
+                ? { executionMode: executionMode ?? (executorId !== undefined ? "durable" : "local") }
+                : {}),
+            ...(policyFile ? { policyFile } : {}),
         },
     };
 }
+/** Real host-local implementations of the launch-profile seams. */
+export function createDefaultLaunchProfileDeps(env) {
+    const store = createNodeEpicLaunchStoreDeps(env);
+    return {
+        hostname: () => os.hostname(),
+        nowIso: () => new Date().toISOString(),
+        readProfile: (name) => readEpicLaunchProfile(name, store),
+        writeProfile: (profile) => writeEpicLaunchProfile(profile, store),
+        readCredentialBinding: (repoName) => readStoredBinding(`bapi:${repoName}`, {
+            env,
+            homedir: store.homedir,
+            platform: store.platform,
+            readFile: store.readFile,
+            stat: (p) => statAsync(p),
+        }),
+        bindCredential: (repoName, baseUrl) => bindEpicLaunchCredential(repoName, baseUrl, store),
+        readPolicyFile: (absolutePath) => readFileAsync(absolutePath, "utf-8"),
+    };
+}
 // ---------------------------------------------------------------------------
 // Bounded readiness observation (BAPI-779)
 // ---------------------------------------------------------------------------
@@ -948,6 +1035,265 @@ async function runConductorLocalObservabilityPhase(deps, local) {
 /**
  * Run the nested conductor installer. Returns the process exit code.
  */
+// ---------------------------------------------------------------------------
+// Epic launch profile phase (BAPI-1260)
+// ---------------------------------------------------------------------------
+/** The packaged CLI's own npm spec, used when no absolute build path resolves. */
+const LAUNCH_NPM_CHANNEL_SPEC = `${MCP_PACKAGE_NAME}@latest`;
+/**
+ * The stable invocation a profile records. A durable profile requires the
+ * absolute packaged path (the same resolver the service unit uses, which already
+ * refuses npx caches); a local one may fall back to the published package on
+ * a named channel. Never a transient `_npx` cache path.
+ */
+function resolveLaunchRuntime(executor, mode) {
+    const invocation = executor?.resolveInvocation();
+    if (invocation?.ok) {
+        const entryPath = invocation.invocation.prefixArgs[0];
+        if (typeof entryPath === "string" && entryPath.length > 0) {
+            return {
+                ok: true,
+                runtime: { kind: "packaged", executable: invocation.invocation.executable, entryPath },
+            };
+        }
+    }
+    if (mode === "durable") {
+        return {
+            ok: false,
+            error: invocation && !invocation.ok
+                ? invocation.error
+                : "no absolute packaged CLI path could be resolved for a durable launch.",
+        };
+    }
+    return { ok: true, runtime: { kind: "npm-channel", spec: LAUNCH_NPM_CHANNEL_SPEC } };
+}
+/** Loopback / link-local / private hostnames the API server cannot reach from elsewhere. */
+function isHostLocalHostname(hostname) {
+    const h = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    return (h === "localhost" ||
+        h.endsWith(".localhost") ||
+        h === "::1" ||
+        /^127\./.test(h) ||
+        /^0\.0\.0\.0$/.test(h) ||
+        /^169\.254\./.test(h));
+}
+/**
+ * Assess the policy's notification destination from the API SERVER's network
+ * perspective. Presence and reachability SHAPE only — the authoritative
+ * delivery check is the server's own `verify_notify_webhook` at approval, and a
+ * 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) {
+    if (attended) {
+        return { status: "not-applicable", detail: "the referenced policy is attended; no escalation webhook is required." };
+    }
+    const notify = policy && typeof policy.notify === "object" && policy.notify !== null
+        ? policy.notify
+        : null;
+    const url = typeof notify?.webhook_url === "string" ? notify.webhook_url.trim() : "";
+    if (url === "") {
+        return {
+            status: "missing",
+            detail: "an unattended launch needs notify.webhook_url in its --policy-file" +
+                (notify && "local_sink" in notify ? " (notify.local_sink is not an escalation channel)." : "."),
+        };
+    }
+    let webhook;
+    let target;
+    try {
+        webhook = new URL(url);
+        target = new URL(targetBaseUrl);
+    }
+    catch {
+        return { status: "missing", detail: "notify.webhook_url is not an absolute URL." };
+    }
+    if (webhook.protocol !== "https:" && webhook.protocol !== "http:") {
+        return { status: "missing", detail: "notify.webhook_url must be an http(s) URL." };
+    }
+    if (isHostLocalHostname(webhook.hostname) && !isHostLocalHostname(target.hostname)) {
+        return {
+            status: "missing",
+            detail: "notify.webhook_url points at this machine's loopback, which the API server at the selected " +
+                "target cannot reach. Use an API-reachable, durable notification service — a terminal-held " +
+                "local listener cannot establish server reachability.",
+        };
+    }
+    return {
+        status: "ok",
+        detail: "notify.webhook_url is declared and addressable from the selected API server; the server " +
+            "delivers a verification to it at approval, and a failure there holds activation.",
+    };
+}
+/**
+ * Verify every mandatory launch prerequisite at the selected target, then —
+ * and only then — persist the profile and print the one command that selects
+ * it. Any unproved prerequisite yields `incomplete-setup` with the reason, and
+ * no profile is written, so a profile's existence means setup was sufficient.
+ *
+ * Consent is READ from the server (`unattended.conductor_allowed`), never
+ * written: ordinary configuration writes cannot self-grant unattended
+ * authority, and nothing in this phase tries to.
+ */
+async function runLaunchProfilePhase(deps, options, inputs) {
+    const name = options.launchProfile;
+    const mode = options.executionMode ?? "local";
+    const lp = deps.launchProfiles ?? createDefaultLaunchProfileDeps(deps.env);
+    const repoName = inputs.access.repoName;
+    const gaps = [];
+    deps.log("");
+    deps.log(`Epic launch profile '${name}' — verification…`);
+    deps.log(`  target:     ${inputs.baseUrl}`);
+    deps.log(`  repository: ${repoName}`);
+    deps.log(`  mode:       ${mode}`);
+    // (1) Access at THIS target — only a server answer proves the key works there.
+    if (inputs.readiness === null) {
+        gaps.push("the selected target's conductor readiness could not be read with this repository's credential.");
+    }
+    // (2) The policy reference and what it implies.
+    let policy = null;
+    let policyPath = null;
+    if (options.policyFile !== undefined) {
+        policyPath = path.resolve(deps.cwd, options.policyFile);
+        try {
+            const parsed = JSON.parse(await lp.readPolicyFile(policyPath));
+            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+                policy = parsed;
+            }
+            else {
+                gaps.push("the --policy-file does not hold a JSON object.");
+            }
+        }
+        catch {
+            gaps.push("the --policy-file could not be read as JSON.");
+        }
+    }
+    const attended = policy?.posture === "attended";
+    // (3) Consent — the server's administrative authority, read not written.
+    const consent = inputs.readiness?.unattended?.conductor_allowed;
+    if (attended) {
+        deps.log("  consent:    not applicable (attended policy)");
+    }
+    else if (consent === true) {
+        deps.log("  consent:    confirmed by the server (unattended_epic_implementer_allowed)");
+    }
+    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 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);
+    deps.log(`  notify:     ${notification.status} — ${notification.detail}`);
+    if (notification.status === "missing")
+        gaps.push(notification.detail);
+    // (5) The actor that consumes the work.
+    if (mode === "durable") {
+        deps.log(`  actor:      ${inputs.actorObserved ? "server-observed executor handshake" : "NOT observed"}`);
+        if (!inputs.actorObserved) {
+            gaps.push("no executor was observed by the server for this repository; a written unit, a started " +
+                "service, or a local process is not proof. Provision it with --executor-id and let the " +
+                "bounded observation complete.");
+        }
+    }
+    else {
+        deps.log("  actor:      local — drive-epic starts this repository's plane and scoped lanes itself");
+    }
+    // (6) A stable runtime invocation.
+    if (!inputs.runtime.ok) {
+        gaps.push(`the packaged CLI invocation is not stable: ${inputs.runtime.error}`);
+    }
+    else {
+        deps.log(`  runtime:    ${inputs.runtime.runtime.kind === "packaged" ? "packaged absolute path" : inputs.runtime.runtime.spec}`);
+    }
+    // (7) The existing profile: a changed binding is re-approved explicitly.
+    const existing = await lp.readProfile(name);
+    if (existing.ok) {
+        const prior = existing.profile;
+        const changed = prior.baseUrl !== inputs.baseUrl || prior.repoName !== repoName || prior.executionMode !== mode;
+        if (changed) {
+            deps.log("");
+            deps.log(`  profile '${name}' exists with a DIFFERENT binding:`);
+            deps.log(`    current:  ${prior.baseUrl}  repo=${prior.repoName}  mode=${prior.executionMode}`);
+            deps.log(`    proposed: ${inputs.baseUrl}  repo=${repoName}  mode=${mode}`);
+            const rebind = await confirm(deps, `Re-bind profile '${name}' to the proposed target? [y/N]: `);
+            if (!rebind)
+                gaps.push(`re-binding profile '${name}' was declined; it was left unchanged.`);
+        }
+    }
+    else if (existing.kind !== "profile-missing") {
+        // Unreadable or from a newer/older schema: reported, and replaced only
+        // through the same consented write below.
+        deps.log(`  existing profile: ${existing.message}`);
+    }
+    // (8) The credential binding — the explicit one-time upgrade path.
+    if (gaps.length === 0) {
+        const bound = await lp.readCredentialBinding(repoName);
+        if (bound === inputs.baseUrl) {
+            deps.log(`  credential: bapi:${repoName} is already approved for this target`);
+        }
+        else {
+            deps.log(bound === null
+                ? `  credential: bapi:${repoName} is not yet approved for any endpoint (legacy repo-only binding)`
+                : `  credential: bapi:${repoName} is approved for a DIFFERENT endpoint`);
+            const approve = await confirm(deps, `Approve the stored credential bapi:${repoName} for ${inputs.baseUrl} only? [y/N]: `);
+            if (!approve) {
+                gaps.push("the credential binding was not approved, so a launch could not use the stored key.");
+            }
+            else {
+                const result = await lp.bindCredential(repoName, inputs.baseUrl);
+                if (!result.ok)
+                    gaps.push(`the credential binding could not be written: ${result.error}`);
+                else
+                    deps.log(`  credential: ${result.action} — approved for this target only`);
+            }
+        }
+    }
+    if (gaps.length > 0 || !inputs.runtime.ok) {
+        deps.log("");
+        deps.log(`  incomplete — profile '${name}' was NOT written:`);
+        for (const gap of gaps)
+            deps.log(`    → ${gap}`);
+        deps.log(`  re-run: npx -y ${MCP_PACKAGE_NAME} install conductor --launch-profile ${name} ` +
+            `--base-url ${inputs.baseUrl} --required-check <name> ...`);
+        return { complete: false };
+    }
+    const write = await confirm(deps, `Write epic launch profile '${name}' (references only, no secrets)? [y/N]: `);
+    if (!write) {
+        deps.log("  declined — no profile was written.");
+        return { complete: false };
+    }
+    const profile = {
+        version: EPIC_LAUNCH_PROFILE_VERSION,
+        name,
+        baseUrl: inputs.baseUrl,
+        repoName,
+        executionMode: mode,
+        host: lp.hostname(),
+        runtime: inputs.runtime.runtime,
+        policyRef: policyPath !== null ? { kind: "file", path: policyPath } : null,
+        credentialRef: { store: "bridge-credentials", target: `bapi:${repoName}` },
+        approvedAt: lp.nowIso(),
+    };
+    const written = await lp.writeProfile(profile);
+    if (!written.ok) {
+        deps.errorLog(`  profile write failed: ${written.message}`);
+        return { complete: false };
+    }
+    deps.log(`  ${written.action} ${written.path}`);
+    deps.log("");
+    deps.log("Launch command (fresh shell; no exports needed):");
+    deps.log(`  ${renderEpicLaunchCommand(profile, {
+        epicKey: options.epicKey ?? "<EPIC>",
+        planFile: options.planFile ? path.resolve(deps.cwd, options.planFile) : "<path>",
+    })
+        // Placeholders are for the operator to replace, not literal arguments.
+        .replace("'<EPIC>'", "<EPIC>")
+        .replace("'<path>'", "<path>")}`);
+    return { complete: true };
+}
 export async function runInstallBridgeConductorCli(argv, deps) {
     const parsed = parseInstallBridgeConductorArgs(argv);
     if (parsed.status === "help") {
@@ -962,12 +1308,31 @@ export async function runInstallBridgeConductorCli(argv, deps) {
     }
     const options = parsed.options;
     // ---- Base URL: normalized ONCE, confirmed BEFORE any network call ------
-    const baseUrlResult = deps.resolveBaseUrl(deps.env);
-    if (!baseUrlResult.ok) {
-        deps.errorLog(baseUrlResult.error);
-        return 1;
+    // BAPI-1260: an epic launch profile has NO production default. Its target is
+    // --base-url or BAPI_BASE_URL (they must agree), decided here before any
+    // request; the hosted default below applies to the legacy flow only.
+    let baseUrl;
+    if (options.launchProfile !== undefined) {
+        const target = resolveEpicLaunchTarget({
+            flagBaseUrl: options.baseUrl,
+            profile: null,
+            env: deps.env,
+        });
+        if (!target.ok) {
+            deps.errorLog(target.message);
+            deps.errorLog("Nothing was sent anywhere and nothing was written.");
+            return 1;
+        }
+        baseUrl = target.baseUrl;
+    }
+    else {
+        const baseUrlResult = deps.resolveBaseUrl(deps.env);
+        if (!baseUrlResult.ok) {
+            deps.errorLog(baseUrlResult.error);
+            return 1;
+        }
+        baseUrl = baseUrlResult.value;
     }
-    const baseUrl = baseUrlResult.value;
     // ---- Consent #1: the resolved base URL ---------------------------------
     // This consent gates the FIRST network request of any kind — including the
     // read-only doctor readiness GET (which carries this repository's API key)
@@ -975,6 +1340,10 @@ export async function runInstallBridgeConductorCli(argv, deps) {
     // BAPI_BASE_URL is unset, so the operator must see and confirm the target
     // before the key is sent anywhere. No TTY means no consent means abort.
     deps.log(`Bridge API base URL: ${baseUrl}`);
+    if (options.launchProfile !== undefined) {
+        deps.log(`  explicit target for epic launch profile '${options.launchProfile}'` +
+            (baseUrl === DEFAULT_BAPI_BASE_URL ? " — this is the PRODUCTION Bridge API, selected deliberately." : "."));
+    }
     const baseUrlOk = await confirm(deps, "Bootstrap against this URL? [y/N]: ");
     if (!baseUrlOk) {
         deps.log("Aborted — no network call (readiness GET or bootstrap POST) was attempted.");
@@ -1101,6 +1470,11 @@ export async function runInstallBridgeConductorCli(argv, deps) {
         else if (executor) {
             deps.log("  Executor provisioning: skipped (no --executor-id supplied)");
         }
+        if (options.launchProfile !== undefined) {
+            deps.log(`  Epic launch profile '${options.launchProfile}': would verify target access, credential ` +
+                "binding, consent, notification, and actor, and persist the profile only if all hold " +
+                "(each write behind its own consent) — nothing was read from or written to the profile store.");
+        }
         renderCapabilityMatrix(deps, firstReport.readiness);
         deps.log("");
         deps.log("complete-with-manual-steps (dry run)");
@@ -1320,6 +1694,24 @@ export async function runInstallBridgeConductorCli(argv, deps) {
         for (const action of manualActions)
             deps.log(`  → ${action}`);
     }
+    // ---- BAPI-1260: the reusable epic launch profile ------------------------
+    // Last, because it can only be approved on facts every earlier phase
+    // produced: server-observed readiness at THIS target, the executor handshake
+    // for a durable host, and the operator's consents.
+    if (options.launchProfile !== undefined) {
+        const launch = await runLaunchProfilePhase(deps, options, {
+            access,
+            baseUrl,
+            readiness: postReadiness,
+            actorObserved: observedReadiness !== null || postReadiness?.executor.ready === true,
+            runtime: resolveLaunchRuntime(executor, options.executionMode ?? "local"),
+        });
+        deps.log("");
+        if (!launch.complete) {
+            deps.log("incomplete-setup");
+            return 1;
+        }
+    }
     deps.log("");
     // The executor leg can only be true when the server observed a recent claim,
     // so a bootstrap alone can never print `complete`. The two local phases above

package/build/install-bridge.js

@@ -325,7 +325,11 @@ export const INSTALL_BRIDGE_AGENT_PROMPT = "Run /install-bridge now, with no arg
     "do' line. The server decides eligibility (repository state AND whether this caller can run the " +
     "command), so do NOT apply a role rule or a learned-state rule of your own. Do NOT run the " +
     "returned command yourself — only recommend it; running it is the human's next explicit " +
-    "invocation. For supporting context around a recommended command, use the manifest's own " +
+    "invocation. When you recommend a command and `next_step.command_context` is a non-empty " +
+    "string, print it verbatim on its own line directly under the command — it is the server's " +
+    "explanation of what the command gives the human and how long it takes; do not reword, shorten, " +
+    "or extend it, and render nothing in its place when it is empty or missing. " +
+    "For other supporting context around a recommended command, use the manifest's own " +
     "next_step.post_install_indexing and next_step.post_install_scheduler text rather than inventing " +
     "an explanation for it. " +
     "Never request, echo, or transport any credential — only ever direct the human to that " +
@@ -1943,21 +1947,34 @@ export async function resolveSignupEmail(options, deps) {
     if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
         return { ok: true, value: fromEnv.trim() };
     }
+    const entered = await promptForBoundedEmail(deps, "Email for Bridge workspace setup (required): ");
+    if (entered === undefined)
+        return { ok: false, error: "No email entered." };
+    return { ok: true, value: entered };
+}
+/**
+ * The bounded interactive email prompt shared by self-serve signup
+ * ({@link resolveSignupEmail}) and invite redemption (BAPI-1263). Two reads at
+ * most: the first answer, then ONE re-prompt after a single hint line. EOF
+ * resolves as an empty value (promptLineViaReadline resolves "" on close), which
+ * fails the shape check like any other blank answer, so it costs one re-prompt and
+ * then fails cleanly rather than hanging. Returns the trimmed (case-preserved)
+ * address, or `undefined` after two invalid answers. The answer is never echoed.
+ * The caller guarantees `deps.promptLine` exists.
+ */
+async function promptForBoundedEmail(deps, promptText) {
     const promptLine = deps.promptLine;
-    // BAPI-1171: bounded to two reads total — the first answer, then ONE re-prompt
-    // after a single hint line. EOF resolves as an empty value (promptLineViaReadline
-    // resolves "" on close), which fails the shape check like any other blank
-    // answer, so it costs one re-prompt and then fails cleanly rather than hanging.
+    if (!promptLine)
+        return undefined;
     for (let attempt = 0; attempt < 2; attempt += 1) {
-        const raw = await promptLine("Email for Bridge workspace setup (required): ");
+        const raw = await promptLine(promptText);
         const entered = String(raw ?? "").trim();
-        if (INSTALL_BRIDGE_SIGNUP_EMAIL_SHAPE.test(entered)) {
-            return { ok: true, value: entered };
-        }
+        if (INSTALL_BRIDGE_SIGNUP_EMAIL_SHAPE.test(entered))
+            return entered;
         if (attempt === 0)
             deps.log(INSTALL_BRIDGE_SIGNUP_EMAIL_HINT);
     }
-    return { ok: false, error: "No email entered." };
+    return undefined;
 }
 /**
  * Select the onboarding branch as pure logic (deterministic, no I/O, no prompt):
@@ -3428,15 +3445,21 @@ export function buildBootstrapExchangeUrl(baseUrl) {
  * POST the bootstrap-invite exchange. The token and `key_secret` travel ONLY in
  * the JSON request body (never a query string, never a header, never a log line).
  * Bounded by the same 10s timeout as the connectivity ping.
+ *
+ * BAPI-1263: an optional nonempty `email` is appended as a fourth body field, used
+ * only on the retry after an `email-required` refusal. Omitted or empty, the body is
+ * the legacy three-field one, byte for byte.
  */
-export async function exchangeBootstrapInvite(deps, baseUrl, token, repoName, keySecret) {
+export async function exchangeBootstrapInvite(deps, baseUrl, token, repoName, keySecret, email) {
     const url = buildBootstrapExchangeUrl(baseUrl);
     let resp;
     try {
         resp = await deps.fetch(url, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ token, repo_name: repoName, key_secret: keySecret }),
+            body: JSON.stringify(email
+                ? { token, repo_name: repoName, key_secret: keySecret, email }
+                : { token, repo_name: repoName, key_secret: keySecret }),
             signal: AbortSignal.timeout(10_000),
         });
     }
@@ -3490,12 +3513,42 @@ export async function exchangeBootstrapInvite(deps, baseUrl, token, repoName, ke
     if (resp.status === 401) {
         return { ok: false, kind: "invalid-invite", message: `The Bridge API rejected the bootstrap invite (HTTP ${resp.status}).` };
     }
+    if (resp.status === 426) {
+        // Only the exact `email_required` refusal is recognized; any other, absent, or
+        // unreadable 426 body stays on the generic failure path below. The message is
+        // installer-owned — nothing from the response is propagated.
+        let recognized = false;
+        try {
+            const body = (await resp.json());
+            recognized = body?.detail?.error === "email_required";
+        }
+        catch {
+            recognized = false;
+        }
+        if (recognized) {
+            return {
+                ok: false,
+                kind: "email-required",
+                message: "The Bridge API requires an email address to redeem this invite.",
+            };
+        }
+    }
     return {
         ok: false,
         kind: "failed",
         message: `The bootstrap exchange failed (HTTP ${resp.status}). Verify BAPI_BASE_URL and try again.`,
     };
 }
+/** The invite-email prompt (BAPI-1263), shown once after an `email_required` refusal. */
+const INVITE_EMAIL_PROMPT = "Email for this Bridge invite (required): ";
+/** BAPI-1263: fixed, secret-free failures for the invite email recovery. */
+export const INVITE_EMAIL_REQUIRED_NON_INTERACTIVE_MESSAGE = "Error: this invite needs an email address, and there is no interactive terminal to ask for it. " +
+    `The bootstrap invite has NOT been used. Re-run \`npx -y ${MCP_PACKAGE_NAME} install\` in an ` +
+    "interactive terminal.";
+export const INVITE_EMAIL_INVALID_ANSWERS_MESSAGE = "Error: no valid email address was entered. The bootstrap invite has NOT been used. Re-run " +
+    "install and enter an address like you@example.com.";
+export const INVITE_EMAIL_REPEATED_REFUSAL_MESSAGE = "Error: the Bridge API still requires an email address after one was entered. The bootstrap " +
+    "invite has NOT been used. Re-run install, or contact support if this repeats.";
 // ---------------------------------------------------------------------------
 // Self-serve mint (BAPI-618): email -> invite token
 // ---------------------------------------------------------------------------
@@ -6014,12 +6067,35 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             // self-serve record — once more with a freshly minted token (R4-3).
             let exchange;
             let selfServeRefreshed = false;
+            // BAPI-1263: the email typed after an `email_required` refusal. Run-local only —
+            // never persisted, logged, or written to the pending record — and carried on
+            // every later ordinary-invite exchange, including after a 409 rename.
+            let inviteEmail;
             for (;;) {
-                exchange = await exchangeBootstrapInvite(deps, baseUrl, inviteToken, repoName, keySecret);
+                exchange = await exchangeBootstrapInvite(deps, baseUrl, inviteToken, repoName, keySecret, inviteEmail);
                 // 409 repo_name_taken: the server ROLLED BACK, so the invite is NOT consumed and
                 // the SAME token can be retried under a new name — with the SAME pending secret,
-                // re-pointed to that name.
-                while (!exchange.ok && exchange.kind === "repo-name-taken") {
+                // re-pointed to that name. The same loop handles an ordinary invite's 426
+                // `email_required` (BAPI-1263), so a 409 on the email-bearing retry re-enters
+                // the rename branch without an extra exchange request.
+                while (!exchange.ok &&
+                    (exchange.kind === "repo-name-taken" ||
+                        (exchange.kind === "email-required" && !selfServeSignupMode))) {
+                    if (exchange.kind === "email-required") {
+                        if (inviteEmail !== undefined) {
+                            return fatal(INVITE_EMAIL_REPEATED_REFUSAL_MESSAGE);
+                        }
+                        if (!deps.isTTY || !deps.promptLine) {
+                            return fatal(INVITE_EMAIL_REQUIRED_NON_INTERACTIVE_MESSAGE);
+                        }
+                        const typedEmail = await promptForBoundedEmail(deps, INVITE_EMAIL_PROMPT);
+                        if (typedEmail === undefined) {
+                            return fatal(INVITE_EMAIL_INVALID_ANSWERS_MESSAGE);
+                        }
+                        inviteEmail = typedEmail;
+                        exchange = await exchangeBootstrapInvite(deps, baseUrl, inviteToken, repoName, keySecret, inviteEmail);
+                        continue;
+                    }
                     if (!deps.isTTY || !deps.promptLine) {
                         errorLog(`Error: ${exchange.message} Re-run with a different --repo (the bootstrap invite has NOT ` +
                             "been used).");
@@ -6046,7 +6122,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                     }
                     repoName = nextRepo;
                     // Same token, same key_secret — never regenerated inside the rename loop.
-                    exchange = await exchangeBootstrapInvite(deps, baseUrl, inviteToken, repoName, keySecret);
+                    exchange = await exchangeBootstrapInvite(deps, baseUrl, inviteToken, repoName, keySecret, inviteEmail);
                 }
                 if (exchange.ok)
                     break;