@bridge_gpt/mcp-server 0.2.36 → 0.2.38

package/build/install-bridge.js

@@ -156,7 +156,7 @@ import { claudeReviewWorkflowPath, writeClaudeReviewWorkflow, } from "./claude-r
 import { runSetupEpicCli } from "./setup-epic.js";
 import { ensureGitignored as ensureGitignoredShared, } from "./git-ignore-utils.js";
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
-import { upsertBapiCredential, getPrimaryCredentialStorePath, prepareBootstrapPendingCredential, repointBootstrapPendingCredential, promoteBootstrapPendingCredential, lookupSelfServeBootstrapPendingCredential, discardBootstrapPendingCredential, getBootstrapPendingTarget, resolveBapiCredentials, } from "./credential-store.js";
+import { upsertBapiCredential, getPrimaryCredentialStorePath, prepareBootstrapPendingCredential, repointBootstrapPendingCredential, promoteBootstrapPendingCredential, lookupSelfServeBootstrapPendingCredential, prepareSelfServeBootstrapChallenge as prepareSelfServeBootstrapChallengeCredential, discardBootstrapPendingCredential, getBootstrapPendingTarget, resolveBapiCredentials, } from "./credential-store.js";
 // BAPI-631: the optional GitHub connect offer reuses the standalone command's flow and
 // API primitives verbatim — no duplicated polling, browser, or picker logic here.
 import { fetchGithubConfigurationState } from "./connect-github-api.js";
@@ -384,29 +384,34 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "Self-serve onboarding (no account, no API key, no pre-issued invite):",
         "  --email <addr>    Create a brand-new Bridge workspace from just an email —",
         "                    the primary path for a first-time user with nothing yet.",
-        "                    It requests a fresh workspace for that email, then creates",
-        "                    the project and mints your own admin API key in one command.",
         "                    Falls back to the BAPI_SIGNUP_EMAIL env var, then a visible",
         "                    interactive prompt — which is also what answering 2 on a",
-        "                    bare run reaches. The email is NOT a",
-        "                    secret (it is shown as you type), but it is never printed to",
-        "                    a log. Mutually",
-        "                    exclusive with --api-key and --invite. The address labels the",
-        "                    new workspace AND is used for transactional invite/setup",
-        "                    delivery, so a setup message may be sent to it. Delivery is",
-        "                    asynchronous and best-effort: it is queued after signup rather",
-        "                    than awaited, so do not wait on the message to continue — this",
-        "                    command already prints everything you need. No email",
-        "                    verification is performed; the address is not confirmed before",
-        "                    the workspace is created.",
+        "                    bare run reaches. The email is NOT a secret (it is shown as",
+        "                    you type), but it is never printed to a log. Mutually",
+        "                    exclusive with --api-key and --invite.",
+        "",
+        "                    VERIFIED: Bridge emails a 6-digit code to that address and",
+        "                    this command prompts you for it. Nothing is created until",
+        "                    the code is entered — no workspace, no project, no API key.",
+        "                    Delivery is asynchronous, so the message arrives shortly",
+        "                    after you are prompted rather than instantly. The code",
+        "                    expires 60 minutes after it is requested, and you can ask",
+        "                    for a new one if it does not arrive; earlier codes keep",
+        "                    working until one is accepted.",
+        "",
+        "                    REQUIRES A TERMINAL: there is no flag or environment",
+        "                    variable for the code — either would put a live credential",
+        "                    into your shell history and process list. For unattended",
+        "                    setup use --api-key <key> or --invite <token> instead.",
         "",
-        "                    RESUMABLE: a self-serve run that fails mid-protocol saves its",
+        "                    RESUMABLE: a self-serve run that is interrupted saves its",
         "                    signup state under bootstrap-pending:<repo> in the credential",
-        "                    store. Re-running the self-serve flow RESUMES that attempt —",
-        "                    it does not sign up again — so a retry never creates a second",
-        "                    workspace. Never copy, display, or hand-remove that record; if",
-        "                    the saved invite has genuinely expired the CLI asks before",
-        "                    discarding it.",
+        "                    store. Re-running RESUMES that attempt — at the code prompt",
+        "                    if the code has not been entered yet, or at the exchange if",
+        "                    it has — so a retry never sends a second code and never",
+        "                    creates a second workspace. The code itself is never saved.",
+        "                    Never copy, display, or hand-remove that record; if the saved",
+        "                    invite has genuinely expired the CLI asks before discarding it.",
         "",
         "Bootstrap-invite onboarding (no web UI, no pre-existing key):",
         "  --invite [token]  Redeem a bootstrap invite you were already given: creates",
@@ -956,6 +961,8 @@ export function createDefaultInstallBridgeDeps() {
         repointBootstrapPending: repointBootstrapPendingCredential,
         promoteBootstrapPending: promoteBootstrapPendingCredential,
         lookupSelfServeBootstrapPending: lookupSelfServeBootstrapPendingCredential,
+        prepareSelfServeBootstrapChallenge: prepareSelfServeBootstrapChallengeCredential,
+        now: () => Date.now(),
         discardBootstrapPending: discardBootstrapPendingCredential,
         buildShellCommand: buildGenericAgentShellCommand,
         spawnTerminalTab: getDefaultSpawnTerminalTabForPlatform(process.platform),
@@ -1123,6 +1130,16 @@ export async function resolveInviteToken(options, deps) {
  * back in an error message.
  */
 export async function resolveSignupEmail(options, deps) {
+    // BAPI-757 (R-3 / AC-9): self-serve signup now REQUIRES an interactive terminal,
+    // and the check runs FIRST — before `--email` and before `BAPI_SIGNUP_EMAIL` —
+    // so an unattended run fails before any request is made, no verification email
+    // is sent, and no challenge row is created. Supplying the address was never the
+    // hard part; entering a code that only arrives by email is, and there is
+    // deliberately no `--code` flag and no environment variable to supply it (a live
+    // code must never reach shell history or a process list).
+    if (!deps.isTTY || !deps.promptLine) {
+        return { ok: false, error: INSTALL_BRIDGE_SIGNUP_REQUIRES_TTY };
+    }
     if (typeof options.email === "string" && options.email.trim().length > 0) {
         return { ok: true, value: options.email.trim() };
     }
@@ -1130,19 +1147,11 @@ export async function resolveSignupEmail(options, deps) {
     if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
         return { ok: true, value: fromEnv.trim() };
     }
-    if (deps.isTTY && deps.promptLine) {
-        const entered = (await deps.promptLine("Email for Bridge workspace setup: ")).trim();
-        if (entered.length > 0) {
-            return { ok: true, value: entered };
-        }
-        return { ok: false, error: "No email entered." };
+    const entered = (await deps.promptLine("Email for Bridge workspace setup: ")).trim();
+    if (entered.length > 0) {
+        return { ok: true, value: entered };
     }
-    return {
-        ok: false,
-        error: "An email is required to create a Bridge workspace. Pass --email <addr> or set the " +
-            "BAPI_SIGNUP_EMAIL environment variable (no interactive terminal is available to prompt " +
-            "for it).",
-    };
+    return { ok: false, error: "No email entered." };
 }
 /**
  * Select the onboarding branch as pure logic (deterministic, no I/O, no prompt):
@@ -2556,23 +2565,234 @@ export async function requestCredentialRouteSwitchConfirmation(deps, promptText)
 export function buildSelfServeMintUrl(baseUrl) {
     return `${baseUrl.replace(/\/+$/, "")}/setup/bootstrap/self-serve`;
 }
+// ===================================================================
+// BAPI-757 — the verification checkpoint's user-facing copy.
+//
+// Every string below is a module constant rather than an inline literal, for two
+// reasons: the static-contract suite pins several of them, and a uniform outcome
+// stated in one place cannot drift into four subtly different sentences that
+// together disclose which failure occurred.
+// ===================================================================
+/** Digits in a verification code. Mirrors the server's protocol constant. */
+export const SIGNUP_VERIFICATION_CODE_LENGTH = 6;
+/** The one prompt label. The E2E harness and the static contract both pin it. */
+export const INSTALL_BRIDGE_CODE_PROMPT = "Email verification code: ";
+/** Shown when a stored, unexpired challenge is picked up on a later run. */
+export const INSTALL_BRIDGE_RESUME_VERIFICATION_HEADING = "Resume email verification";
+/**
+ * The non-interactive refusal (AC-9 / R-3).
+ *
+ * Names BOTH unattended alternatives, because the whole point of the message is
+ * that the user is running in a context where no prompt can be answered — telling
+ * them only what does not work would leave them stuck.
+ */
+export const INSTALL_BRIDGE_SIGNUP_REQUIRES_TTY = [
+    "Creating a Bridge workspace requires verifying your email address, and that needs an",
+    "interactive terminal to enter the emailed code. There is deliberately no flag or",
+    "environment variable for the code — either would put a live credential into your shell",
+    "history and process list.",
+    "",
+    "Two onboarding paths still work unattended:",
+    "  • An existing API key:      install --api-key <key>   (or set BAPI_API_KEY)",
+    "  • A pre-issued invite:      install --invite <token>  (or set BAPI_INVITE)",
+    "",
+    "To sign up from scratch, re-run this command in an interactive terminal.",
+].join("\n");
+/**
+ * The UNIFORM recovery message for a rejected verification.
+ *
+ * The server answers a wrong code, an expired code, an unknown handle, and an
+ * exhausted challenge with one identical response — and this message is the client
+ * half of that property. It must never be specialized per case, and it must never
+ * speculate ("maybe it expired?"): a message that narrowed the possibilities would
+ * hand back exactly the signal the uniform response withholds.
+ */
+export const INSTALL_BRIDGE_VERIFICATION_REJECTED = [
+    "That code was not accepted.",
+    "",
+    "Check the most recent verification email and try again, or request a new code. If the",
+    "signup attempt is too old, re-run this command to start a fresh one.",
+].join("\n");
+/** Resend success. States plainly that earlier codes still work — see R-5. */
+export const INSTALL_BRIDGE_RESEND_SENT = "A new code is on its way. Any code from an earlier email for this signup still works too.";
+/** Cooldown. Non-accusatory, and silent about which limiter applied. */
+export const INSTALL_BRIDGE_RESEND_COOLDOWN = "A verification email was sent moments ago — give it a minute to arrive before requesting another.";
+/** Send ceiling. Names no bucket: not the address, not the source, not the global cap. */
+export const INSTALL_BRIDGE_RESEND_THROTTLED = "Bridge is not sending another verification email for this signup right now. Try again later, or use the code from an email you already received.";
+/**
+ * A throttle that arrives from the VERIFY call, i.e. after a code was submitted.
+ *
+ * Deliberately NOT {@link INSTALL_BRIDGE_RESEND_THROTTLED}. That message tells the
+ * user to fall back on a code they already have — which is backwards here: the
+ * server throttles verification at the invite-mint ceiling, so their code may have
+ * been perfectly correct and there is nothing to fall back to. Re-running is the
+ * remedy, and the code stays valid until it expires.
+ */
+export const INSTALL_BRIDGE_VERIFY_THROTTLED = "Bridge is at capacity and could not finish creating your workspace just now. Nothing was created — wait a few minutes and re-run this command; the code already emailed to you stays valid until it expires.";
+/**
+ * A transient server failure during verification.
+ *
+ * Separate from {@link INSTALL_BRIDGE_SIGNUP_UPGRADE_REQUIRED} because a 5xx means
+ * the server understood this CLI perfectly and simply failed. Telling the user to
+ * upgrade would send them to the one recovery step that cannot help, and would
+ * hide a real outage behind a version-skew story.
+ */
+export const INSTALL_BRIDGE_VERIFY_SERVER_ERROR = "Error: Bridge could not complete verification right now. Nothing was created — wait a few minutes and re-run this command; the code already emailed to you stays valid until it expires.";
+/**
+ * Local cap on rejected verification attempts before the CLI stops re-prompting.
+ *
+ * AC-4 makes "wrong code" and "this challenge is dead" byte-identical on purpose,
+ * so the CLI genuinely cannot tell them apart. Without a cap, a user who exhausts
+ * the server's attempt budget is re-prompted forever against a challenge that can
+ * never succeed, with Ctrl-C as the only exit.
+ *
+ * Set ABOVE the server's default attempt budget (5) so a legitimately mistyping
+ * user is never cut off before the server itself would refuse — the cap exists to
+ * end a hopeless loop, not to add a second, tighter budget the user cannot see.
+ */
+export const INSTALL_BRIDGE_MAX_CODE_REJECTIONS = 6;
+/** Printed when the rejection cap is reached. Still state-neutral (AC-4). */
+export const INSTALL_BRIDGE_VERIFICATION_GIVING_UP = [
+    "Error: that signup could not be verified.",
+    "",
+    "Nothing has been created. Re-run this command to start a fresh signup — it will email",
+    "a new code to the same address.",
+].join("\n");
+/** The fail-closed enqueue failure (R-4). No suggestion that verification is skippable. */
+export const INSTALL_BRIDGE_SIGNUP_UNAVAILABLE = "Error: Bridge could not send a verification email, so no workspace was created. Nothing has been set up — try again in a few minutes.";
 /**
- * POST the self-serve mint: an email in, an invite token out. Mirrors
- * {@link exchangeBootstrapInvite}'s fetch/timeout/secret-free-result discipline.
+ * R-2's hard break, rendered for a server that no longer speaks this client's
+ * protocol — or a client that no longer speaks the server's.
  *
- * The email travels 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 exchange and
- * the connectivity ping. On any non-success status the failure body is NOT read —
- * the status alone decides the category — because an untrusted upstream body could
- * echo the email or carry internals. A caught fetch exception is likewise never
- * inspected or interpolated; some fetch impls embed the request (and thus the
- * email) in the message.
+ * Deliberately NOT the old generic "Check connectivity and retry": connectivity is
+ * fine, and sending a user to debug their network for a protocol change is the
+ * failure mode this constant exists to prevent.
  */
-export async function mintSelfServeInvite(deps, baseUrl, email) {
-    const url = buildSelfServeMintUrl(baseUrl);
+export const INSTALL_BRIDGE_SIGNUP_UPGRADE_REQUIRED = [
+    "Error: this Bridge server's signup flow does not match this CLI.",
+    "",
+    "Signup now verifies your email address with a code before creating a workspace. Upgrade",
+    "and re-run:",
+    "",
+    "  npx -y @bridge_gpt/mcp-server@latest install --email <addr>",
+].join("\n");
+/**
+ * Mask an address for display: first character, then the domain.
+ *
+ * `ada@example.com` renders as `a***@example.com`. Enough for the user to confirm
+ * they typed the right mailbox, without putting a full address into a terminal
+ * transcript that may be pasted into an issue or captured by CI. Anything that
+ * does not look like a mailbox is reduced to a fixed placeholder rather than
+ * echoed — an unparseable value is exactly the one most likely to be a typo worth
+ * not repeating.
+ */
+export function maskSignupEmail(email) {
+    const trimmed = (email ?? "").trim();
+    const at = trimmed.lastIndexOf("@");
+    if (at <= 0 || at === trimmed.length - 1)
+        return "your email address";
+    return `${trimmed[0]}***${trimmed.slice(at)}`;
+}
+/**
+ * Render a challenge's remaining lifetime in calm, approximate language.
+ *
+ * Whole minutes, rounded down, and never a countdown: the exact number does not
+ * change what the user does, and a precise timer turns a routine wait into a
+ * deadline. A challenge already past its expiry says so plainly rather than
+ * rendering a negative number.
+ */
+export function formatChallengeRemaining(expiresAtIso, nowMs) {
+    const expiresMs = Date.parse(expiresAtIso);
+    if (Number.isNaN(expiresMs))
+        return "";
+    const minutes = Math.floor((expiresMs - nowMs) / 60_000);
+    if (minutes <= 0)
+        return "This code has expired.";
+    if (minutes === 1)
+        return "This code is valid for about another minute.";
+    return `This code is valid for about another ${minutes} minutes.`;
+}
+/**
+ * Prompt for the verification code, validating its shape LOCALLY before any
+ * network call.
+ *
+ * Local validation is a courtesy, not a security control — the server re-validates
+ * everything — but it keeps a mistyped code from consuming one of the five attempts
+ * that permanently kill a challenge. The user gets the prompt back instead.
+ *
+ * Pasted input is trimmed: copying a code out of a mail client routinely brings
+ * whitespace with it, and refusing that would be an avoidable dead end.
+ *
+ * The entered value is returned and never echoed, never logged, and never written
+ * to disk. `null` means the user gave up (an empty line, or an unreadable prompt).
+ */
+export async function promptForVerificationCode(deps, log, maxAttempts = 3) {
+    if (!deps.promptLine)
+        return null;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        let entered;
+        try {
+            entered = (await deps.promptLine(INSTALL_BRIDGE_CODE_PROMPT)).trim();
+        }
+        catch {
+            // Secret-free by construction: the caught value is never surfaced or
+            // inspected, because a readline failure can carry the partial input.
+            return null;
+        }
+        if (entered.length === 0)
+            return null;
+        if (new RegExp(`^[0-9]{${SIGNUP_VERIFICATION_CODE_LENGTH}}$`).test(entered)) {
+            return entered;
+        }
+        // Describes the SHAPE, never the value the user typed.
+        log(`  That does not look like a code — it is ${SIGNUP_VERIFICATION_CODE_LENGTH} digits.`);
+    }
+    return null;
+}
+/*
+ * `mintSelfServeInvite` and `SelfServeMintResult` were REMOVED in BAPI-757.
+ *
+ * They read `token` from the request phase's success body. Under R-2 that field
+ * no longer exists for any client version, and a helper that still looked for it
+ * would be a live path back to an unverified signup — so it is deleted rather than
+ * deprecated. The replacement is the three-phase client immediately below.
+ */
+// ===================================================================
+// BAPI-757 — the three-phase self-serve signup client.
+//
+// The server no longer returns a token from the request phase, for ANY client
+// version (R-2). These three helpers replace the single-shot mint above:
+//
+//   requestSelfServeChallenge  → POST /setup/bootstrap/self-serve
+//   verifySelfServeChallenge   → POST /setup/bootstrap/self-serve/verify
+//   resendSelfServeChallenge   → POST /setup/bootstrap/self-serve/resend
+//
+// All three keep the discipline the deleted single-shot mint established, and that
+// `exchangeBootstrapInvite` still follows: the same 10s timeout, a COARSE result
+// category on failure, and a failure body that is never read — an untrusted
+// upstream body could echo the email or the code, and some fetch implementations
+// embed the request (and therefore the code) in a thrown error's message, so caught
+// exceptions are never inspected either. The one exception is the resend 429, which
+// reads a FIXED server-controlled detail string carrying no request value.
+// ===================================================================
+/** The challenge REQUEST endpoint: `<base>/setup/bootstrap/self-serve`. */
+export function buildSelfServeVerifyUrl(baseUrl) {
+    return `${baseUrl.replace(/\/+$/, "")}/setup/bootstrap/self-serve/verify`;
+}
+/** The challenge RESEND endpoint: `<base>/setup/bootstrap/self-serve/resend`. */
+export function buildSelfServeResendUrl(baseUrl) {
+    return `${baseUrl.replace(/\/+$/, "")}/setup/bootstrap/self-serve/resend`;
+}
+/**
+ * POST the challenge REQUEST: an email in, a handle out. Never a token.
+ *
+ * The email travels ONLY in the JSON body — never a query string, never a header,
+ * never a log line.
+ */
+export async function requestSelfServeChallenge(deps, baseUrl, email) {
     let resp;
     try {
-        resp = await deps.fetch(url, {
+        resp = await deps.fetch(buildSelfServeMintUrl(baseUrl), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ invitee_email: email }),
@@ -2580,8 +2800,57 @@ export async function mintSelfServeInvite(deps, baseUrl, email) {
         });
     }
     catch (err) {
-        // The message may contain the request (some fetch impls echo it), so it is
-        // deliberately NOT inspected or interpolated here.
+        void err;
+        return { ok: false, category: "failed" };
+    }
+    if (resp.ok) {
+        let handle;
+        let expiresAt;
+        try {
+            const body = (await resp.json());
+            handle = body?.handle;
+            expiresAt = body?.expires_at;
+        }
+        catch {
+            return { ok: false, category: "failed" };
+        }
+        if (typeof handle !== "string" ||
+            handle.trim().length === 0 ||
+            typeof expiresAt !== "string" ||
+            expiresAt.trim().length === 0) {
+            // A success body without challenge metadata is not something this client can
+            // act on. It is also what an OLD server (pre-BAPI-757, still returning a
+            // token) looks like — and continuing from one would mean skipping
+            // verification entirely, so it is refused rather than tolerated.
+            return { ok: false, category: "failed" };
+        }
+        return { ok: true, handle: handle.trim(), expiresAt: expiresAt.trim() };
+    }
+    if (resp.status === 429)
+        return { ok: false, category: "rate-limited" };
+    if (resp.status === 503)
+        return { ok: false, category: "unavailable" };
+    if (resp.status === 400 || resp.status === 422)
+        return { ok: false, category: "invalid" };
+    return { ok: false, category: "failed" };
+}
+/**
+ * POST the VERIFY phase: a handle and a code in, the invite token out.
+ *
+ * The code is sent once, in the body, and is never echoed back into terminal
+ * output or into any error this returns.
+ */
+export async function verifySelfServeChallenge(deps, baseUrl, handle, code) {
+    let resp;
+    try {
+        resp = await deps.fetch(buildSelfServeVerifyUrl(baseUrl), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ handle, code }),
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    catch (err) {
         void err;
         return { ok: false, category: "failed" };
     }
@@ -2592,7 +2861,6 @@ export async function mintSelfServeInvite(deps, baseUrl, email) {
             token = body?.token;
         }
         catch {
-            // An unreadable success body is not actionable and must not be exposed.
             return { ok: false, category: "failed" };
         }
         if (typeof token !== "string" ||
@@ -2602,14 +2870,83 @@ export async function mintSelfServeInvite(deps, baseUrl, email) {
         }
         return { ok: true, token };
     }
-    // Non-success: the status alone decides the category. The failure body is NEVER
-    // read — it is untrusted and could echo the email or leak internals.
-    if (resp.status === 429) {
+    // 401 is the server's uniform invalid-challenge outcome. It covers a wrong code,
+    // an expired code, an unknown handle, and an exhausted challenge, and the client
+    // deliberately cannot tell them apart — so neither can a caller watching the
+    // client's output.
+    if (resp.status === 401)
+        return { ok: false, category: "rejected" };
+    if (resp.status === 429)
         return { ok: false, category: "rate-limited" };
+    // A 5xx is the server failing, not the protocol disagreeing. Kept distinct so the
+    // caller can say "try again" instead of "upgrade the CLI".
+    if (resp.status >= 500)
+        return { ok: false, category: "server-error" };
+    return { ok: false, category: "failed" };
+}
+/**
+ * POST the RESEND phase: the handle alone, timing metadata out.
+ *
+ * No email field — accepting one would let a caller request mail for an address
+ * they hold no challenge for, which is the abuse the per-email budget bounds.
+ */
+export async function resendSelfServeChallenge(deps, baseUrl, handle) {
+    let resp;
+    try {
+        resp = await deps.fetch(buildSelfServeResendUrl(baseUrl), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ handle }),
+            signal: AbortSignal.timeout(10_000),
+        });
     }
-    if (resp.status === 400 || resp.status === 422) {
-        return { ok: false, category: "invalid" };
+    catch (err) {
+        void err;
+        return { ok: false, category: "failed" };
+    }
+    if (resp.ok) {
+        let expiresAt;
+        let resendsRemaining;
+        try {
+            const body = (await resp.json());
+            expiresAt = body?.expires_at;
+            resendsRemaining = body?.resends_remaining;
+        }
+        catch {
+            return { ok: false, category: "failed" };
+        }
+        if (typeof expiresAt !== "string" || expiresAt.trim().length === 0) {
+            return { ok: false, category: "failed" };
+        }
+        return {
+            ok: true,
+            expiresAt: expiresAt.trim(),
+            resendsRemaining: typeof resendsRemaining === "number" && Number.isFinite(resendsRemaining)
+                ? resendsRemaining
+                : 0,
+        };
     }
+    // Cooldown and the send ceilings are BOTH 429 and are distinguished only by the
+    // fixed detail string. Reading it is safe here precisely because it is fixed and
+    // server-controlled — it carries no request value — and the distinction lets the
+    // CLI say "wait a moment" instead of "try again later". Any parse problem falls
+    // through to the more conservative `rate-limited`.
+    if (resp.status === 429) {
+        let detail = "";
+        try {
+            const body = (await resp.json());
+            detail = typeof body?.detail === "string" ? body.detail : "";
+        }
+        catch {
+            detail = "";
+        }
+        return {
+            ok: false,
+            category: detail.toLowerCase().includes("very recently") ? "cooldown" : "rate-limited",
+        };
+    }
+    if (resp.status === 401)
+        return { ok: false, category: "rejected" };
     return { ok: false, category: "failed" };
 }
 /**
@@ -3905,7 +4242,14 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         // ---- Step 1 — scaffold (secret-free placeholders only) ----
         currentStep = INSTALL_BRIDGE_STEP_LABELS.scaffold;
         log(currentStep);
-        await deps.runInit(deps.cwd);
+        // BAPI-728: hand init the identity this run already resolved and validated.
+        // `credentialAvailable: true` is a statement about THIS flow, not a lookup:
+        // Step 2 mints/verifies the key and Step 4 persists it, so a placeholder
+        // warning here would be a false alarm about a config the installer is
+        // actively configuring. The key value itself never crosses this boundary.
+        await deps.runInit(deps.cwd, {
+            creationContext: { repoName, baseUrl, credentialAvailable: true },
+        });
         // ---- Step 2 — mint (invite mode) or verify (normal mode) the credential ----
         let inviteFingerprint = "";
         if (bootstrapInviteMode) {
@@ -3923,13 +4267,18 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             let resumedSelfServeReplay = false;
             let keySecret = "";
             let reusedPendingSecret = false;
+            // BAPI-757: a LIVE challenge found by the lookup below. When set, the run
+            // resumes at the code prompt and MUST NOT request or resend — the emailed
+            // code is still valid, and asking again would spend one of the user's own
+            // per-address sends for nothing.
+            let liveChallenge = null;
             if (selfServeSignupMode) {
-                const lookup = await deps.lookupSelfServeBootstrapPending({ repoName }, credentialWriteDeps);
+                const lookup = await deps.lookupSelfServeBootstrapPending({ repoName, now: deps.now() }, credentialWriteDeps);
                 if (!lookup.ok) {
-                    // Fail BEFORE the mint endpoint is called and leave the stored record
-                    // untouched — an ordinary-invite record, a malformed record, and an
-                    // unreadable store are all states where minting again would compound the
-                    // problem rather than recover from it.
+                    // Fail BEFORE any endpoint is called and leave the stored record
+                    // untouched — an ordinary-invite record, a malformed record, a partial
+                    // challenge record, and an unreadable store are all states where
+                    // starting over would compound the problem rather than recover from it.
                     return fatal(`Error: ${lookup.error}`);
                 }
                 if (lookup.state === "resumable") {
@@ -3943,37 +4292,176 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                     reusedPendingSecret = true;
                     log(`  resuming your previous signup attempt for ${repoName}`);
                 }
+                else if (lookup.state === "challenge") {
+                    liveChallenge = {
+                        handle: lookup.challengeHandle,
+                        expiresAt: lookup.challengeExpiresAt,
+                        email: lookup.signupEmail,
+                    };
+                }
+                // `challenge-expired` and `none` both fall through to a fresh request.
             }
             /**
-             * Mint a self-serve invite and durably store it WITH a fresh `key_secret`.
+             * Run the self-serve signup through request → verify, then durably store the
+             * resulting invite token WITH a fresh `key_secret` (BAPI-757).
              *
-             * Shared by the initial signup and the consented refresh below — the only two
-             * places a self-serve token is ever created. The ordering inside is the same
-             * load-bearing protocol described below: mint the token, durably store the
-             * token plus the `key_secret`, and only THEN exchange. Logs its own
-             * (secret-free) failure and returns false; the caller exits non-zero.
+             * Three phases, in this order, and the order is the protocol:
+             *
+             *   1. **Request** (skipped when resuming a live challenge). The server
+             *      creates a challenge and queues an email. No tenant, no invitation, and
+             *      nothing billable exists yet.
+             *   2. **Persist the challenge, THEN prompt.** The email has already been
+             *      sent and the user's per-address send budget already charged by this
+             *      point, so the handle reaches disk before anything can interrupt the
+             *      run. A terminal closed at the prompt resumes the SAME challenge with
+             *      the SAME code.
+             *   3. **Verify**, which is what actually mints — and hands back the very
+             *      `inviteToken` the untouched persist-before-exchange region below
+             *      already expected.
+             *
+             * The verification code is prompted for, submitted once, and never written to
+             * disk, never logged, and never echoed.
+             *
+             * Logs its own (secret-free) failure and returns false; the caller exits
+             * non-zero.
              */
             const mintAndPrepareSelfServe = async () => {
-                const mint = await mintSelfServeInvite(deps, baseUrl, signupEmail);
-                if (!mint.ok) {
-                    if (mint.category === "rate-limited") {
-                        // BAPI-668 (R12-1): the limiter is a single GLOBAL per-hour signup bucket,
-                        // not a per-IP/per-email one — so "temporarily rate limited" read as "you
-                        // did something wrong" when nothing on the user's machine is at fault.
-                        // Message-only: the return value and the caller's exit code are unchanged.
-                        reportFatal("Error: Bridge's self-serve signup capacity for this hour is exhausted (this is a " +
-                            "global service limit, not a problem with your machine). Try again in about an hour.");
+                let challengeHandle;
+                let challengeExpiresAt;
+                let challengeEmail;
+                if (liveChallenge) {
+                    // Phase 1 SKIPPED. Resuming an unexpired challenge: no request call, no
+                    // resend call, and no second email.
+                    challengeHandle = liveChallenge.handle;
+                    challengeExpiresAt = liveChallenge.expiresAt;
+                    challengeEmail = liveChallenge.email;
+                    log(`  ${INSTALL_BRIDGE_RESUME_VERIFICATION_HEADING}`);
+                    log(`  We already emailed a code to ${maskSignupEmail(challengeEmail)}.`);
+                }
+                else {
+                    const requested = await requestSelfServeChallenge(deps, baseUrl, signupEmail);
+                    if (!requested.ok) {
+                        if (requested.category === "rate-limited") {
+                            // Deliberately does NOT name a limiter bucket. The server refuses to
+                            // say which ceiling was reached, and repeating a guess here would
+                            // undo that.
+                            reportFatal(`Error: ${INSTALL_BRIDGE_RESEND_THROTTLED}`);
+                        }
+                        else if (requested.category === "unavailable") {
+                            // R-4's fail-closed branch: nothing was created, and there is no
+                            // suggestion anywhere that verification can be skipped.
+                            reportFatal(INSTALL_BRIDGE_SIGNUP_UNAVAILABLE);
+                        }
+                        else if (requested.category === "invalid") {
+                            reportFatal("Error: Self-serve setup could not be requested. Check the email value and try again.");
+                        }
+                        else {
+                            // R-2: a malformed or tokenless-unexpected response is a PROTOCOL
+                            // mismatch, not a network problem. Saying "check connectivity" here
+                            // was the old behavior and is exactly what this ticket replaces.
+                            reportFatal(INSTALL_BRIDGE_SIGNUP_UPGRADE_REQUIRED);
+                        }
+                        return false;
                     }
-                    else if (mint.category === "invalid") {
-                        reportFatal("Error: Self-serve setup could not be requested. Check the email value and try again.");
+                    challengeHandle = requested.handle;
+                    challengeExpiresAt = requested.expiresAt;
+                    challengeEmail = signupEmail;
+                    // Phase 2, first half — durable BEFORE the prompt. A failure here stops
+                    // the run: continuing would prompt for a code whose challenge could not
+                    // be resumed if anything interrupted the terminal.
+                    const recorded = await deps.prepareSelfServeBootstrapChallenge({
+                        repoName,
+                        signupEmail: challengeEmail,
+                        challengeHandle,
+                        challengeExpiresAt,
+                    }, credentialWriteDeps);
+                    if (!recorded.ok) {
+                        reportFatal(`Error: could not record the signup attempt (${recorded.kind}). ${recorded.error} ` +
+                            "No workspace has been set up — fix the problem and re-run.");
+                        return false;
                     }
-                    else {
-                        reportFatal("Error: Unable to complete self-serve setup. Check connectivity and retry.");
+                    log(`  We emailed a code to ${maskSignupEmail(challengeEmail)}.`);
+                }
+                log(`  Enter the ${SIGNUP_VERIFICATION_CODE_LENGTH}-digit code to finish setting up your workspace.`);
+                const remaining = formatChallengeRemaining(challengeExpiresAt, deps.now());
+                if (remaining)
+                    log(`  ${remaining}`);
+                // Phase 2, second half, and phase 3. One resend is offered on the recovery
+                // path only — never proactively — so the budget is spent on the user's
+                // explicit request rather than by the CLI's own retry logic.
+                let resendOffered = false;
+                // BOUNDED, not `for (;;)`. AC-4 makes a wrong code and a dead challenge
+                // byte-identical, so the CLI cannot detect that a challenge has been killed
+                // — an unbounded loop would re-prompt forever against something that can
+                // never succeed, with Ctrl-C as the only way out.
+                let rejections = 0;
+                for (;;) {
+                    const code = await promptForVerificationCode(deps, log);
+                    if (code === null) {
+                        reportFatal("Error: No verification code entered — nothing has been set up. Re-run this command " +
+                            "to continue; the code already emailed to you stays valid until it expires.");
+                        return false;
+                    }
+                    const verified = await verifySelfServeChallenge(deps, baseUrl, challengeHandle, code);
+                    if (verified.ok) {
+                        inviteToken = verified.token;
+                        break;
+                    }
+                    if (verified.category === "rate-limited") {
+                        // NOT the resend wording: a throttle here comes from the invite-mint
+                        // ceiling and can fire AFTER a perfectly correct code, so telling the
+                        // user to fall back on an email they already have is backwards.
+                        reportFatal(`Error: ${INSTALL_BRIDGE_VERIFY_THROTTLED}`);
+                        return false;
+                    }
+                    if (verified.category === "server-error") {
+                        reportFatal(INSTALL_BRIDGE_VERIFY_SERVER_ERROR);
+                        return false;
+                    }
+                    if (verified.category === "failed") {
+                        // Only a genuine protocol mismatch reaches here now: a malformed body,
+                        // a missing token, a network error, or a 4xx this client does not
+                        // expect. R-2's upgrade instruction is the right answer for those.
+                        reportFatal(INSTALL_BRIDGE_SIGNUP_UPGRADE_REQUIRED);
+                        return false;
+                    }
+                    // `rejected` — the server's UNIFORM outcome. One message, no speculation
+                    // about which of the four states it was.
+                    rejections += 1;
+                    if (rejections >= INSTALL_BRIDGE_MAX_CODE_REJECTIONS) {
+                        // Still state-neutral: this says the attempt is over, never WHY.
+                        reportFatal(INSTALL_BRIDGE_VERIFICATION_GIVING_UP);
+                        return false;
+                    }
+                    errorLog(INSTALL_BRIDGE_VERIFICATION_REJECTED);
+                    if (!resendOffered && deps.isTTY && deps.promptLine) {
+                        resendOffered = true;
+                        const answer = await requestCredentialRouteSwitchConfirmation(deps, "Send a new code? [y/N]: ");
+                        if (answer) {
+                            const resent = await resendSelfServeChallenge(deps, baseUrl, challengeHandle);
+                            if (resent.ok) {
+                                log(`  ${INSTALL_BRIDGE_RESEND_SENT}`);
+                            }
+                            else if (resent.category === "cooldown") {
+                                log(`  ${INSTALL_BRIDGE_RESEND_COOLDOWN}`);
+                            }
+                            else if (resent.category === "rate-limited") {
+                                log(`  ${INSTALL_BRIDGE_RESEND_THROTTLED}`);
+                            }
+                            else if (resent.category === "rejected") {
+                                // The challenge is no longer eligible — the same uniform outcome
+                                // verification reports. Stop rather than loop on a dead challenge.
+                                reportFatal(`Error: ${INSTALL_BRIDGE_VERIFICATION_REJECTED}`);
+                                return false;
+                            }
+                            else {
+                                log(`  ${INSTALL_BRIDGE_RESEND_THROTTLED}`);
+                            }
+                        }
                     }
-                    return false;
                 }
-                // Treated identically to a manually supplied invite token from here on.
-                inviteToken = mint.token;
+                // From here on the token is treated identically to a manually supplied
+                // invite — the load-bearing region below is completely unchanged.
                 inviteFingerprint = fingerprintBootstrapInvite(inviteToken);
                 const prepareSelfServePending = (allowOverwrite) => deps.prepareBootstrapPending({
                     repoName,