@bridge_gpt/mcp-server 0.2.32 → 0.2.34

package/build/install-bridge.js

@@ -252,36 +252,52 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         ...INSTALL_BRIDGE_ONBOARDING_CHOICES.map((choice) => `  ${choice}`),
         "There is NO default — pressing Enter selects nothing; you must type 1, 2, or 3",
         "(one blank or invalid answer re-prompts once, then exits with guidance). Option 1",
-        "is the existing-key flow below, option 2 is the bootstrap-invite flow, and option 3",
-        "prompts for an email and creates a brand-new Bridge workspace for you (the",
-        "self-serve flow). That question is asked ONLY for a bare interactive run: passing",
+        "is the bootstrap-invite flow, option 2 prompts for an email and creates a",
+        "brand-new Bridge workspace for you (the self-serve flow), and option 3 is the",
+        "existing-project API-key flow below. The project-CREATING routes lead",
+        "deliberately. That question is asked ONLY for a bare interactive run: passing",
         "ANY flag, setting BAPI_API_KEY, or running without an interactive terminal keeps",
         "the existing deterministic behavior and no prompt.",
         "",
+        "Entered the wrong kind of credential? Both directions are detected by SHAPE",
+        "alone — no probe request is sent — and neither switches routes in silence:",
+        "  - a bootstrap invite (bapi_inv_…) entered as an API key is announced, then",
+        "    confirmed on a terminal before it is redeemed; a non-interactive run keeps",
+        "    today's automatic switch but prints the notice.",
+        "  - an API-key-shaped value entered as an invite is announced and may switch in",
+        "    place only after you confirm on a terminal — non-interactive runs exit with",
+        "    guidance instead, so a script is never silently redirected. The check runs",
+        "    BEFORE any project-name prompt, credential write, or network call.",
+        "A value that is neither shape is left on the route you chose.",
+        "",
         "Inputs (the only two irreducible ones):",
         "  --api-key <key>   Bridge API key OR bootstrap invite. Falls back to the",
         "                    BAPI_API_KEY env var, then an interactive (no-echo) prompt.",
         `                    Generate a key at ${setupUrl} (Security page) — this`,
         "                    command consumes a key, it does not create one. A value",
         "                    detected as a bootstrap invite (bapi_inv_…), from any of the",
-        "                    three sources above, is instead redeemed to CREATE a new",
-        "                    project and its first admin key — the same as --invite —",
-        "                    so it skips repository lookup entirely (--email and --invite",
-        "                    remain the explicit, preferred entry points for a new project).",
-        "                    NEVER printed or logged.",
+        "                    three sources above, is announced and instead redeemed to",
+        "                    CREATE a new project and its first admin key — the same as",
+        "                    --invite — so it skips repository lookup entirely (--email",
+        "                    and --invite remain the explicit, preferred entry points for",
+        "                    a new project). NEVER printed or logged.",
         "  --repo <name>     Repository name. --repo and BAPI_REPO_NAME still take",
         "                    priority and short-circuit before any network call. When",
         "                    neither is set, a compatible server resolves the unique",
-        "                    repository from your existing API key automatically; if the",
-        "                    server is older, the key is unresolvable, or resolution",
-        "                    fails, it falls back to an inferred default you confirm",
-        "                    interactively (and to a required --repo when stdin is",
-        "                    non-interactive). In the existing-key flow it MUST match the",
-        "                    server-side repo registration (it keys the credential store",
-        "                    as bapi:<repo>). In either new-project flow (--email,",
-        "                    --invite, or chooser option 2 or 3 above) it",
-        "                    instead NAMES the project this run creates, so you are asked",
-        "                    to name a new project rather than match an existing one; the",
+        "                    repository from your existing API key automatically. If the",
+        "                    key does not identify exactly one project, the run STOPS —",
+        "                    it never guesses — and asks you to re-run with --repo <name>,",
+        `                    or to rotate the key at ${setupUrl} (Security page).`,
+        "                    If instead the server is older or resolution fails",
+        "                    transiently, you are asked to type the registered name, with",
+        "                    NO pre-filled default (and",
+        "                    --repo is required when stdin is non-interactive). In the",
+        "                    existing-project flow it MUST match the server-side repo",
+        "                    registration (it keys the credential store as bapi:<repo>).",
+        "                    In either new-project flow (--email, --invite, or chooser",
+        "                    option 1 or 2 above) it instead NAMES the project this run",
+        "                    creates, so you are asked to name a new project — with a",
+        "                    suggested default — rather than match an existing one; the",
         "                    name must be globally unique.",
         "",
         "Self-serve onboarding (no account, no API key, no pre-issued invite):",
@@ -290,7 +306,7 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "                    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 chooser option 3 on a",
+        "                    interactive prompt — which is also what chooser option 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",
@@ -997,11 +1013,24 @@ export function resolveInstallBridgeOnboardingBranch(options, env) {
  * numbered options once, accept ONE strict line.
  */
 export const INSTALL_BRIDGE_KEY_SELECTOR_PROMPT = "How would you like to connect to Bridge API?";
-/** The chooser's numbered options, in render order. Index + 1 is the accepted token. */
+/**
+ * The chooser's numbered options, in render order. Index + 1 is the accepted token.
+ *
+ * BAPI-687 (A-1) put the two PROJECT-CREATING routes first. The previous order led
+ * with the existing-project key path, labelled only "I have a Bridge API key" — which
+ * reads as the default for anyone holding any credential, so a user with a valid
+ * invite picked it and dead-ended at a repo-not-registered 403 with no route to the
+ * path that would have created their project. Position was doing the opposite of the
+ * intended routing.
+ *
+ * Option 3's label carries its own scope ("for an existing project") rather than
+ * relying on position (A-3): a stale screenshot or a habituated user must still be
+ * able to read the right choice off the label itself.
+ */
 export const INSTALL_BRIDGE_ONBOARDING_CHOICES = [
-    "1. I have a Bridge API key",
-    "2. I have an invite token",
-    "3. I'm new — set me up with just my email",
+    "1. I have an invite token",
+    "2. I'm new — set me up with just my email",
+    "3. I have an API key for an existing project",
 ];
 /** The single-line answer prompt drawn after the options (no bracketed default). */
 export const INSTALL_BRIDGE_ONBOARDING_CHOICE_PROMPT = "Enter 1, 2, or 3: ";
@@ -1017,7 +1046,7 @@ export const INSTALL_BRIDGE_ONBOARDING_CHOICE_HINT = "Enter 1, 2, or 3.";
  */
 export const INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE = "Re-run install-bridge and choose an option: pass --api-key <key> if you have a Bridge API " +
     "key (or set BAPI_API_KEY), --invite if you were sent an invite token, or --email <addr> " +
-    "to sign up with just an email — on a bare interactive run, re-run and choose option 3 to " +
+    "to sign up with just an email — on a bare interactive run, re-run and choose option 2 to " +
     "sign up with just an email.";
 /**
  * Interactive wrapper around {@link resolveInstallBridgeOnboardingBranch}.
@@ -1042,10 +1071,16 @@ export const INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE = "Re-run install-bridge and cho
  *
  * BAPI-667 replaced the Y/n question with a three-option chooser. Two properties
  * are load-bearing: there is NO default (a bare Enter can no longer route a
- * brand-new user into the hidden key prompt), and option 3 names the self-serve
- * route explicitly so it is discoverable without reading `--help`. Validation is
+ * brand-new user into the hidden key prompt), and the self-serve route is named
+ * explicitly so it is discoverable without reading `--help`. Validation is
  * bounded to ONE re-prompt — an unanswerable prompt that loops is the same
  * dead-end in a different costume.
+ *
+ * BAPI-687 reordered the options so the project-CREATING routes lead (1 = invite,
+ * 2 = self-serve email, 3 = existing-project API key). Only the labels and the
+ * dispatch moved: the heading, the `Enter 1, 2, or 3: ` prompt, the accepted-token
+ * set, the no-default rule, EOF handling, and every flag/env/non-TTY bypass are
+ * byte-for-byte unchanged.
  */
 export async function resolveInstallBridgeOnboardingBranchForRun(options, deps, argv) {
     const branch = resolveInstallBridgeOnboardingBranch(options, deps.env);
@@ -1070,15 +1105,18 @@ export async function resolveInstallBridgeOnboardingBranchForRun(options, deps,
         // it can never hang or silently select a branch.
         for (let attempt = 0; attempt < 2; attempt += 1) {
             const answer = (await promptLine(INSTALL_BRIDGE_ONBOARDING_CHOICE_PROMPT)).trim();
-            // Option 1 stays credential-agnostic: a `bapi_inv_…` value pasted into the
-            // hidden key prompt is still reclassified downstream (BAPI-661).
-            if (answer === "1")
-                return { ok: true, branch: { kind: "have-key" } };
-            if (answer === "2") {
+            // BAPI-687 (A-2): the dispatch moved WITH the labels — the accepted tokens are
+            // still exactly 1/2/3 (no letters, no aliases), so the one-strict-line input
+            // contract BAPI-667 established is unchanged. Either branch stays
+            // credential-agnostic: a value pasted onto the wrong path is detected and
+            // re-routed downstream rather than silently accepted (B-2 / B-3).
+            if (answer === "1") {
                 return { ok: true, branch: { kind: "need-key", method: "bootstrap-invite" } };
             }
-            if (answer === "3")
+            if (answer === "2")
                 return { ok: true, branch: { kind: "need-key", method: "self-serve" } };
+            if (answer === "3")
+                return { ok: true, branch: { kind: "have-key" } };
             if (attempt === 0)
                 deps.log(INSTALL_BRIDGE_ONBOARDING_CHOICE_HINT);
         }
@@ -1112,23 +1150,30 @@ export function resolveConfiguredRepoName(options, env) {
     return undefined;
 }
 /**
- * Resolve the repo name: `--repo` → `BAPI_REPO_NAME` env → inferred default
- * (from .bridge/config, else the cwd basename) confirmed interactively. Fails
- * fast (no inference) when neither is supplied and stdin is non-interactive —
- * the repo identity keys the credential store, so it is never silently inferred
+ * Resolve the repo name: `--repo` → `BAPI_REPO_NAME` env → an interactive prompt.
+ * Fails fast when neither is supplied and stdin is non-interactive — the repo
+ * identity keys the credential store, so it is never silently inferred
  * non-interactively.
  *
- * `mode` selects only the WORDING (prompt and non-interactive error); resolution
- * order, inference, and validation are identical in both. It defaults to
- * `existing-registration` to preserve the behaviour of pre-BAPI-626 callers.
+ * `mode` selects the WORDING **and, since BAPI-687 (C-3), whether a default is
+ * inferred at all**:
+ *
+ *   - `new-project` — unchanged. The project does not exist yet, so a suggested
+ *     name (from `.bridge/config`, else the cwd basename) is genuinely helpful and
+ *     a bare Enter accepts it.
+ *   - `existing-registration` — NO inference and NO bracketed default. The name
+ *     must match a registration the user already has server-side, where the cwd
+ *     basename is essentially never right; BAPI-661 already tried warning harder
+ *     and the 2026-07-21 run shows the user accepted the guess anyway, then took a
+ *     403 two steps later. A pre-filled wrong answer is the defect, so the user now
+ *     types the registered name deliberately.
  */
 export async function resolveRepoName(options, deps, mode = "existing-registration") {
     const configured = resolveConfiguredRepoName(options, deps.env);
     if (configured !== undefined) {
         return { ok: true, value: configured };
     }
-    // Non-interactive: fail fast and require --repo. Inference is an interactive
-    // convenience only (the user must confirm it).
+    // Non-interactive: fail fast and require --repo.
     if (!deps.isTTY || !deps.promptLine) {
         return {
             ok: false,
@@ -1137,10 +1182,19 @@ export async function resolveRepoName(options, deps, mode = "existing-registrati
                     "variable (no interactive terminal is available to confirm an inferred name). It " +
                     "names the new Bridge project this run creates and must be globally unique."
                 : "A repo name is required. Pass --repo or set the BAPI_REPO_NAME environment variable " +
-                    "(no interactive terminal is available to confirm an inferred name). It must match the " +
-                    "server-side repository registration.",
+                    "(no interactive terminal is available to prompt for it). It must match the " +
+                    "server-side repository registration exactly.",
         };
     }
+    // BAPI-687 (C-3): only the new-project mode infers. The existing-registration
+    // prompt is rendered with NO bracketed default, so a bare Enter cannot commit a
+    // guess the user never chose.
+    if (mode !== "new-project") {
+        const answer = (await deps.promptLine("Repo name (must match server-side registration): ")).trim();
+        if (answer.length > 0)
+            return { ok: true, value: answer };
+        return { ok: false, error: "No repo name provided." };
+    }
     // Infer a sensible default: existing .bridge/config, else the cwd basename.
     let inferred = await resolveStartTicketsRepoName({
         env: deps.env,
@@ -1153,19 +1207,13 @@ export async function resolveRepoName(options, deps, mode = "existing-registrati
             inferred = validated.value;
     }
     if (inferred) {
-        const promptText = mode === "new-project"
-            ? `Name your new Bridge project [${inferred}]: `
-            : `Repo name [${inferred}] (must match server-side registration): `;
-        const answer = (await deps.promptLine(promptText)).trim();
+        const answer = (await deps.promptLine(`Name your new Bridge project [${inferred}]: `)).trim();
         const chosen = answer.length > 0 ? answer : inferred;
         if (chosen.length > 0)
             return { ok: true, value: chosen };
     }
     else {
-        const promptText = mode === "new-project"
-            ? "Name your new Bridge project: "
-            : "Repo name (must match server-side registration): ";
-        const answer = (await deps.promptLine(promptText)).trim();
+        const answer = (await deps.promptLine("Name your new Bridge project: ")).trim();
         if (answer.length > 0)
             return { ok: true, value: answer };
     }
@@ -1986,6 +2034,23 @@ export async function verifyConnectivity(deps, baseUrl, repoName, apiKey, apiKey
         message: `Connectivity check failed (HTTP ${resp.status}). Verify your repo, API key, and BAPI_BASE_URL.`,
     };
 }
+/**
+ * The `unresolved` (409) hard stop (BAPI-687, C-2). Names both recoveries; the
+ * caller appends the address-bearing rotation line so this string stays a constant.
+ * Secret-free: no key, no HTTP status, no server detail.
+ */
+export const INSTALL_BRIDGE_UNRESOLVED_KEY_ERROR = "Error: that API key does not identify exactly one Bridge project, so the repository could " +
+    "not be resolved from it. Re-run with --repo <name> (or set BAPI_REPO_NAME) to name the " +
+    "registered project explicitly.";
+/**
+ * The surviving `not-deployed` (404) / `error` fallback notice (BAPI-687, C-5).
+ *
+ * Re-worded for a path that no longer OFFERS a name: the old copy said the CLI was
+ * "falling back to a guessed name" and told the user to confirm it against the setup
+ * UI, which is now false in both halves — there is nothing pre-filled to confirm.
+ */
+export const INSTALL_BRIDGE_RESOLUTION_UNAVAILABLE_NOTICE = "Automatic repository resolution isn't available for this run. Enter the name your project " +
+    "is registered under (or re-run with --repo <name>).";
 /** The resolve endpoint: `<base>/setup/resolve-repo`. No query string — ever. */
 export function buildResolveRepoUrl(baseUrl) {
     return `${baseUrl.replace(/\/+$/, "")}/setup/resolve-repo`;
@@ -2166,6 +2231,118 @@ export const BOOTSTRAP_INVITE_TOKEN_PREFIX = "bapi_inv_";
 export function classifyEnteredCredential(value) {
     return value.trim().startsWith(BOOTSTRAP_INVITE_TOKEN_PREFIX) ? "invite" : "api-key";
 }
+// ---------------------------------------------------------------------------
+// Cross-credential detection (BAPI-687, Part B)
+// ---------------------------------------------------------------------------
+/** The exact encoded length of `secrets.token_urlsafe(32)`: 32 bytes, unpadded base64url. */
+export const USER_ACCESS_KEY_ENCODED_LENGTH = 43;
+/** The exact decoded length the encoded form must yield. */
+export const USER_ACCESS_KEY_DECODED_BYTES = 32;
+/** Strict base64url alphabet, anchored to the exact issuance length. */
+const USER_ACCESS_KEY_SHAPE_PATTERN = new RegExp(`^[A-Za-z0-9_-]{${USER_ACCESS_KEY_ENCODED_LENGTH}}$`);
+/**
+ * POSITIVE test for the project's API-key shape — the TypeScript port of the
+ * server's `is_high_entropy_user_access_key_shape`
+ * (`src/python/library/auth/user_access_lookup.py`). Detection had to become
+ * positive: "is an API key" was previously only the NEGATIVE of the `bapi_inv_`
+ * prefix check, which would confidently mis-announce a typo'd invite as an API key.
+ *
+ * Admits ONLY `secrets.token_urlsafe(32)`: exactly 43 characters from the strict
+ * base64url alphabet, decoding to exactly 32 bytes, AND canonical — the input must
+ * equal the unpadded base64url re-encoding of those bytes. The canonical check is
+ * not decoration: the final 6-bit group of a 32-byte value carries 2 unused low
+ * bits, so several distinct 43-character strings decode to the same 32 bytes and
+ * length-only validation would admit the aliases. It deliberately does NOT admit
+ * shorter legacy keys — a legacy credential misses detection rather than being
+ * re-routed on a guess.
+ *
+ * Pure and total: no logging, no trimming (the caller owns normalization), no
+ * throw, and the input is never placed in a returned or thrown value. Every
+ * failure path returns `false`.
+ */
+export function isHighEntropyApiKeyShape(value) {
+    if (typeof value !== "string" || !USER_ACCESS_KEY_SHAPE_PATTERN.test(value))
+        return false;
+    let decoded;
+    try {
+        // The alphabet was already validated above, so this decode cannot silently
+        // discard characters the way a lenient base64url decode otherwise would.
+        decoded = Buffer.from(value, "base64url");
+    }
+    catch {
+        return false;
+    }
+    if (decoded.length !== USER_ACCESS_KEY_DECODED_BYTES)
+        return false;
+    return decoded.toString("base64url") === value;
+}
+/**
+ * Notice printed when a bootstrap invite is detected on the API-key path (B-2).
+ *
+ * The reclassification itself is not new (BAPI-661) — the SILENCE was. A user who
+ * called their value an "API key" was branch-switched with no indication, which is
+ * half of why the reported run was opaque to everyone reading the transcript.
+ *
+ * Secret discipline: names the credential TYPE and the destination ROUTE only.
+ * No part of the value — no prefix excerpt, no length, no fingerprint.
+ */
+export const INSTALL_BRIDGE_INVITE_ON_KEY_PATH_NOTICE = "That looks like a bootstrap invite token, not a Bridge API key. An invite CREATES a new " +
+    "Bridge project and mints your first admin key, instead of connecting to a project that " +
+    "already exists.";
+/** TTY confirmation for the invite-detected-on-the-key-path switch. Default No. */
+export const INSTALL_BRIDGE_INVITE_ON_KEY_PATH_PROMPT = "Redeem it as an invite and create a new project? [y/N]: ";
+/** Non-TTY form: the switch still happens automatically, but it is announced (B-2). */
+export const INSTALL_BRIDGE_INVITE_ON_KEY_PATH_AUTO_NOTICE = "Redeeming it as a bootstrap invite (non-interactive — no confirmation is possible here).";
+/** Printed on decline. Names the other route rather than leaving the user stranded. */
+export const INSTALL_BRIDGE_INVITE_ON_KEY_PATH_DECLINED = "Error: cancelled — nothing was created. Re-run install-bridge with an API key for an " +
+    "existing project (--api-key <key>, or BAPI_API_KEY), or re-run and confirm to redeem the " +
+    "invite and create a new project.";
+/**
+ * Notice printed when an API-key-shaped value is detected on the invite path (B-3).
+ *
+ * This direction had NO detection at all, and the cost of that was severe: the run
+ * prompted for a new project name, fsynced a durable `bootstrap-pending:<repo>`
+ * record, POSTed the exchange, took a 401, and printed the "you cannot recover it
+ * yourself — ask your Bridge API operator" message. For a wrong-credential-type
+ * paste. The orphaned pending record then blocked the next attempt.
+ *
+ * Secret discipline: credential TYPE and destination ROUTE only.
+ */
+export const INSTALL_BRIDGE_KEY_ON_INVITE_PATH_NOTICE = "That looks like a Bridge API key, not a bootstrap invite token. An API key connects to a " +
+    "project that already exists, instead of creating a new one.";
+/** TTY confirmation for the key-detected-on-the-invite-path switch. Default No. */
+export const INSTALL_BRIDGE_KEY_ON_INVITE_PATH_PROMPT = "Use it to connect to your existing project instead? [y/N]: ";
+/**
+ * Printed when the switch is declined, unconfirmable, or non-interactive.
+ *
+ * Non-TTY does NOT auto-switch here, and the asymmetry is deliberate: the invite
+ * direction merely continues a path BAPI-661 already established, while this
+ * direction would silently redirect a script away from the project-creating run it
+ * asked for. A script gets a non-zero exit and the exact flag it should have passed.
+ */
+export const INSTALL_BRIDGE_KEY_ON_INVITE_PATH_DECLINED = "Error: cancelled — nothing was created and no invite was spent. Re-run install-bridge with " +
+    "--api-key <key> (or BAPI_API_KEY) to connect to your existing project, or supply a bootstrap " +
+    "invite token (bapi_inv_…) to create a new one.";
+/**
+ * Shared default-No confirmation for a cross-credential route switch (B-2 / B-3).
+ *
+ * Accepts only an explicit `y`/`yes` (case-insensitive, trimmed); EVERY other
+ * answer — including a prompt that throws or an EOF-resolved empty line — is a
+ * decline, because an unreadable prompt is not consent. The credential value is
+ * never passed in, so neither the prompt text nor a caught exception can carry it.
+ */
+export async function requestCredentialRouteSwitchConfirmation(deps, promptText) {
+    if (!deps.isTTY || !deps.promptLine)
+        return false;
+    try {
+        const answer = (await deps.promptLine(promptText)).trim().toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    catch {
+        // Secret-free by construction: the caught value is never surfaced or inspected.
+        return false;
+    }
+}
 /** The self-serve mint endpoint: `<base>/setup/bootstrap/self-serve`. No query string — ever. */
 export function buildSelfServeMintUrl(baseUrl) {
     return `${baseUrl.replace(/\/+$/, "")}/setup/bootstrap/self-serve`;
@@ -2344,10 +2521,15 @@ export function buildDryRunPreview(plan) {
     if (plan.bootstrapInvite)
         return buildBootstrapDryRunPreview(plan);
     return [
-        plan.attemptedServerResolution
+        // Any defined status means the read-only GET really happened, so the header is
+        // truthful for every outcome — but ONLY `resolved` may claim the name came back
+        // from the server (BAPI-687, C-4).
+        plan.serverRepoResolutionStatus !== undefined
             ? "install-bridge --dry-run (one read-only repository-resolution GET may already have occurred; no writes, no state-changing requests, no spawns)"
             : "install-bridge --dry-run (no writes, no network, no spawns)",
-        `Repo name:        ${plan.repoName}${plan.attemptedServerResolution ? " (resolved server-side from your API key)" : ""}`,
+        `Repo name:        ${plan.repoName}${plan.serverRepoResolutionStatus === "resolved"
+            ? " (resolved server-side from your API key)"
+            : ""}`,
         `Base URL (ping):  ${plan.baseUrl}`,
         `Docs dir:         ${plan.docsDir}`,
         `Agent:            ${describePlannedLaunchAgent(plan.launch)}`,
@@ -2933,6 +3115,14 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // downstream that branches on these two flags then follows the existing
     // bootstrap-invite protocol automatically. Explicit `--invite`/`BAPI_INVITE` and
     // `--email`/`BAPI_SIGNUP_EMAIL` never pass through this reclassification.
+    //
+    // BAPI-687 (Part B) makes the reclassification BIDIRECTIONAL and, in both
+    // directions, ANNOUNCED. The two directions are deliberately asymmetric on a
+    // non-TTY: an invite found on the key path still switches automatically (a script
+    // that worked yesterday must not gain a prompt) but now prints a notice, whereas
+    // an API key found on the invite path exits non-zero, because auto-switching there
+    // would silently redirect a script away from the project-creating run it asked
+    // for. Detection is by SHAPE ONLY — no probe request, no credential-store read.
     let bootstrapInviteMode = branch.kind === "need-key";
     let selfServeSignupMode = branch.kind === "need-key" && branch.method === "self-serve";
     // ---- Resolve inputs (may prompt when interactive) ----
@@ -2965,6 +3155,37 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             return 1;
         }
         inviteToken = inviteResult.value;
+        // BAPI-687 (B-3/B-4): an API-key-shaped value pasted onto the invite path is
+        // caught HERE — before the project-name prompt, before `prepareBootstrapPending`
+        // writes a durable `bootstrap-pending:<repo>` record, and before any fetch. That
+        // ordering IS the fix: today's failure leaves exactly that debris behind, and the
+        // orphaned pending record is what turns a wrong-credential paste into an
+        // unrecoverable "ask your Bridge API operator" message plus a `pending-conflict`
+        // on the next attempt.
+        //
+        // Guarded by BOTH conditions (B-5): not `bapi_inv_`-prefixed AND a positive
+        // API-key shape. A value that is neither — a typo'd invite, say — is not
+        // reclassified in either direction; it stays on the branch the user chose and
+        // fails there exactly as it does today.
+        if (classifyEnteredCredential(inviteToken) !== "invite" &&
+            isHighEntropyApiKeyShape(inviteToken)) {
+            log(INSTALL_BRIDGE_KEY_ON_INVITE_PATH_NOTICE);
+            const switchToKeyPath = await requestCredentialRouteSwitchConfirmation(deps, INSTALL_BRIDGE_KEY_ON_INVITE_PATH_PROMPT);
+            if (!switchToKeyPath) {
+                // Decline, an unreadable prompt, and a non-TTY run all land here — nothing
+                // has been prompted for, written, or sent, so the exit costs the user only
+                // the re-run named in the guidance.
+                errorLog(INSTALL_BRIDGE_KEY_ON_INVITE_PATH_DECLINED);
+                return 1;
+            }
+            apiKey = inviteToken;
+            inviteToken = "";
+            bootstrapInviteMode = false;
+            selfServeSignupMode = false;
+            // Deliberately unattributed: the value came through the INVITE input seam, so
+            // naming `--api-key` or `BAPI_API_KEY` on a later 401 would simply be false.
+            apiKeySource = undefined;
+        }
     }
     else {
         const keyResult = await resolveApiKey(options, deps);
@@ -2978,6 +3199,22 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         // resolution is what lets the rest of the function reuse the existing
         // bootstrap-invite protocol verbatim.
         if (classifyEnteredCredential(keyResult.value) === "invite") {
+            // BAPI-687 (B-2): the switch survives, the SILENCE does not. The user is told
+            // which credential type was detected and what it will do, and on a TTY is
+            // asked to confirm before the branch changes. A non-TTY run keeps today's
+            // automatic switch — a script must not gain a prompt — but still prints the
+            // notice, so the transcript explains itself.
+            log(INSTALL_BRIDGE_INVITE_ON_KEY_PATH_NOTICE);
+            if (deps.isTTY && deps.promptLine) {
+                const switchToInvite = await requestCredentialRouteSwitchConfirmation(deps, INSTALL_BRIDGE_INVITE_ON_KEY_PATH_PROMPT);
+                if (!switchToInvite) {
+                    errorLog(INSTALL_BRIDGE_INVITE_ON_KEY_PATH_DECLINED);
+                    return 1;
+                }
+            }
+            else {
+                log(INSTALL_BRIDGE_INVITE_ON_KEY_PATH_AUTO_NOTICE);
+            }
             inviteToken = keyResult.value.trim();
             apiKey = "";
             bootstrapInviteMode = true;
@@ -2997,13 +3234,25 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // ---- Resolve the repository name ----
     // Need-key (invite or self-serve): choose-a-name for the project this run is
     // about to create, so the prompt says exactly that. Have-key:
-    // `--repo`/`BAPI_REPO_NAME` short-circuit deterministically; otherwise resolve
-    // it server-side from the API key (BAPI-616), and on ANY non-resolution outcome
-    // (unresolved / not-deployed / error) fall back to the existing local
-    // prompt/inference — never a hard failure. That fallback keeps the
-    // existing-registration wording: there the name must match a real project.
+    // `--repo`/`BAPI_REPO_NAME` short-circuit deterministically; otherwise resolve it
+    // server-side from the API key (BAPI-616).
+    //
+    // BAPI-687 (C-2) TIERS the non-`resolved` outcomes instead of collapsing them:
+    //
+    //   - `unresolved` (409) → HARD STOP. The key does not identify exactly one
+    //     project, and that answer is real rather than a deployment artifact:
+    //     `user_access.api_key_lookup` cannot be backfilled offline, but
+    //     `verify_repo_access` lazily populates it on any successful authentication,
+    //     so the permanently-unresolvable population is only pre-migration keys that
+    //     have never authenticated since — small and shrinking. Guessing a name here
+    //     buys nothing but a 403 two steps later.
+    //   - `not-deployed` (404) / `error` → still recoverable, and must stay that way:
+    //     404 is the BAPI-616 feature-detect for an older or self-hosted server, and
+    //     `error` covers a transient network failure or a 401. Collapsing these into
+    //     the hard stop would make a blip unrecoverable.
     let repoName;
-    let attemptedServerResolution = false;
+    /** The resolver's OUTCOME (C-4), or undefined when it was never called. */
+    let serverRepoResolutionStatus;
     if (bootstrapInviteMode) {
         const repoResult = await resolveRepoName(options, deps, "new-project");
         if (!repoResult.ok) {
@@ -3026,20 +3275,24 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             repoName = configured;
         }
         else {
-            attemptedServerResolution = true;
             log("Resolving repository…");
             const resolution = await deps.resolveRepoViaServer(baseUrl, apiKey);
+            serverRepoResolutionStatus = resolution.status;
             if (resolution.status === "resolved") {
                 repoName = resolution.repoName;
             }
+            else if (resolution.status === "unresolved") {
+                // C-2: a 409 means the key does not identify exactly one project. Stop here,
+                // before any prompt, ping, scaffold, persist, or spawn — and name BOTH
+                // recoveries rather than inferring anything.
+                return fatal(INSTALL_BRIDGE_UNRESOLVED_KEY_ERROR, `  Or rotate the key at ${setupUrl} (Security page) if it should identify exactly one project.`);
+            }
             else {
-                // Feature-detect + degrade: 404 (old server), 409 (unresolved/ambiguous/
-                // client-scoped), and network/other errors all fall back to the existing
-                // local resolution — WITHOUT a cause-specific message or leaked detail, but
-                // (BAPI-661) WITH a visible signal that the fallback is happening, so a
-                // guessed name is never confirmed silently as if it had been verified.
-                log("Couldn't auto-resolve your repo from the key; falling back to a guessed name — confirm " +
-                    `it matches ${setupUrl} (setup UI).`);
+                // Feature-detect + degrade: 404 (old server) and network/other errors keep
+                // the local fallback prompt — WITHOUT a cause-specific message or leaked
+                // detail. C-3/C-5: it no longer offers a name, so it no longer says
+                // "guessed" or asks the user to confirm a value against the setup UI.
+                log(INSTALL_BRIDGE_RESOLUTION_UNAVAILABLE_NOTICE);
                 const repoResult = await resolveRepoName(options, deps, "existing-registration");
                 if (!repoResult.ok) {
                     errorLog(`Error: ${repoResult.error}`);
@@ -3105,7 +3358,9 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             ? { bootstrapInvite: true, exchangeUrl: buildBootstrapExchangeUrl(baseUrl) }
             : {}),
         ...(selfServeSignupMode ? { selfServeSignup: true } : {}),
-        ...(attemptedServerResolution ? { attemptedServerResolution: true } : {}),
+        ...(serverRepoResolutionStatus !== undefined
+            ? { serverRepoResolutionStatus }
+            : {}),
     };
     // ---- --dry-run: preview every step, strictly no side effects ----
     // Positioned BEFORE the CSPRNG, the pending write, the exchange, the scaffold,