@bridge_gpt/mcp-server 0.2.23 → 0.2.25

package/build/install-bridge.js

@@ -6,6 +6,12 @@
  * Collapses the previously five-step manual setup into a single CLI subcommand.
  * It does the DETERMINISTIC work in the shell:
  *
+ *   Step 0  Resolve the repository name. `--repo` / `BAPI_REPO_NAME` short-circuit
+ *           deterministically; otherwise, on the consume-an-existing-key flow, a
+ *           compatible server resolves the unique repo from the API key via a
+ *           read-only `GET <base>/setup/resolve-repo` (BAPI-616) BEFORE the
+ *           connectivity check. An old server / unresolvable key / failure falls
+ *           back to the existing local prompt/inference — never a hard failure.
  *   Step 1  Scaffold via `runInit` (commands, agents, pipelines, secret-free
  *           per-host MCP config placeholders, .bridge/config).
  *   Step 2  Verify connectivity over HTTP (`GET <base>/jira/ping?repo_name=…`
@@ -22,14 +28,34 @@
  *           (`~/.config/bridge/credentials.json`, target `bapi:<repo>`) via
  *           `upsertBapiCredential`. Non-blocking (fail-open) — mirrors Stage 6.
  *
- * then SPAWNS a fresh agent session (Step 5) for the agentic remainder
- * (`/install-bridge` config-field derivation, then `/learn-repository`). The
+ * then SPAWNS a fresh agent session (Step 5) for the CONFIGURE-ONLY agentic
+ * remainder: `/install-bridge` config-field derivation → the read-after-write
+ * capability report → a single optional indexing-consent question. It does NOT
+ * chain `/learn-repository` and does NOT index without explicit consent. The
  * fresh session is required because a CLI cannot force the running editor to
  * reload the just-written `.mcp.json`, and field derivation needs an agent
  * runtime the shell does not have.
  *
- * BOOTSTRAP-INVITE MODE (BAPI-606) — the one exception to "this command consumes
- * a key, it does not create one". With `--invite` (or `BAPI_INVITE`) there is no
+ * That spawn command embeds the entire agent prompt and runs to multiple KB, which
+ * no macOS terminal will accept as one typed line. So it is never typed: the full
+ * command is written to a restricted (0600) launch script and only a short
+ * `. '<path>'` runner is spawned (BAPI-626, via `materializeWorkerLaunchCommand`).
+ * Materialization happens BEFORE any install side effect, because a command that
+ * cannot be launched is a whole-run failure, not a Step 5 warning.
+ *
+ * ONBOARDING BRANCHES — `have-key` (consume an existing key) vs. `need-key` (this
+ * command creates the project AND its first admin key). There are two need-key
+ * methods, differing only in how the first token is obtained: `bootstrap-invite`
+ * (BAPI-606) redeems a pre-issued invite; `self-serve` (BAPI-618) mints one from an
+ * email. Both then feed the SAME redemption protocol. Selection is pure and
+ * deterministic from flags/env, except that a BARE interactive run is asked which
+ * branch it wants (BAPI-626) — without that question a first-time user cannot
+ * discover self-serve at all. Either need-key method NAMES a new project, so the
+ * repository prompt asks for a new project name rather than an existing
+ * registration (see `RepoNamePromptMode`).
+ *
+ * BOOTSTRAP-INVITE MODE (BAPI-606) — one of the two exceptions to "this command
+ * consumes a key, it does not create one". With `--invite` (or `BAPI_INVITE`) there is no
  * API key yet, so the pre-flight ping of Step 2 CANNOT be made: the exchange is
  * what mints the key, and it REPLACES that ping. The order becomes:
  *
@@ -63,9 +89,13 @@ import { runInit, buildBridgeApiEntry } from "./init.js";
 import { VERSION } from "./version.generated.js";
 import { validateRepoName } from "./bridge-config.js";
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
-import { upsertBapiCredential, getPrimaryCredentialStorePath, prepareBootstrapPendingCredential, repointBootstrapPendingCredential, promoteBootstrapPendingCredential, } from "./credential-store.js";
+import { upsertBapiCredential, getPrimaryCredentialStorePath, prepareBootstrapPendingCredential, repointBootstrapPendingCredential, promoteBootstrapPendingCredential, 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";
+import { createDefaultConnectGithubDeps, runGithubConnectionFlow } from "./connect-github.js";
 import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
-import { buildGenericAgentShellCommand, getDefaultSpawnTerminalTabForPlatform, detectTerminal, createDefaultStartTicketsDeps, } from "./start-tickets.js";
+import { buildGenericAgentShellCommand, getDefaultSpawnTerminalTabForPlatform, detectTerminal, createDefaultStartTicketsDeps, materializeWorkerLaunchCommand, MAX_TERMINAL_COMMAND_BYTES, } from "./start-tickets.js";
 /** Redaction sentinel — the API-key value is NEVER printed; this stands in. */
 export const REDACTED_API_KEY = "<REDACTED>";
 /**
@@ -85,15 +115,46 @@ export function buildPrewarmArgs() {
 export function buildPrewarmCommandPreview() {
     return `npx ${buildPrewarmArgs().join(" ")}`;
 }
-/** The natural-language sequential prompt handed to the spawned agent session. */
-export const INSTALL_BRIDGE_AGENT_PROMPT = "Please execute the /install-bridge command. Once it completes successfully, execute the " +
-    "/learn-repository command. After /learn-repository completes, ask the user for consent to start " +
-    "repository indexing; with consent, call the parse_repository MCP tool once and report that the " +
-    "job was queued (progress is checked with get_parse_status — do not poll it to completion). " +
-    "When you are done, end with an explicit summary line stating how " +
-    "many config fields the apply_install_manifest call applied (e.g. 'Applied 8 of 9 derived " +
-    "fields') and whether indexing was queued — if 0 fields were applied, say so loudly and explain " +
-    "what is still pending.";
+/**
+ * The natural-language prompt handed to the spawned agent session. It is
+ * CONFIGURE-ONLY: it derives and applies configuration, presents the capability
+ * report, and ends with exactly one indexing-consent question. It never chains
+ * /learn-repository and never indexes before explicit consent.
+ *
+ * The index-consent beat is AGENT-OWNED (asked inside this spawned session), not
+ * parent-CLI-owned, because `spawnTerminalTab()` opens an asynchronous terminal
+ * session: the parent CLI returns immediately and cannot reliably ask a question
+ * that must appear AFTER the spawned session's capability report. Asking it via
+ * the parent's `deps.promptLine` would display the question before the report
+ * even exists. `deps.promptLine` therefore stays the owner of the parent-CLI
+ * prompts (repository / overwrite / invite confirmation) and is intentionally
+ * NOT used for this post-report question.
+ */
+export const INSTALL_BRIDGE_AGENT_PROMPT = "Execute the /install-bridge command in the install-spawn context (tell the command it is running " +
+    "in the install-spawn context so it SKIPS its Stage 8 and Stage 9 offers — this session's only " +
+    "closing interaction is the single indexing question below). Do NOT run /learn-repository. Do NOT " +
+    "call parse_repository (or otherwise start indexing) before the capability report and explicit " +
+    "consent below. " +
+    "Complete the command's read-after-write five-section capability report first: 'Connected ✓', " +
+    "'Not yet connected ✗', 'Tools you can use now', 'Tools you'll unlock', and 'Recommended next " +
+    "step + why'. " +
+    "Only AFTER that report is fully presented, ask exactly one question using this visible prompt: " +
+    "'[Y/n] Index repository now?'. Only an explicit affirmative answer (e.g. 'y'/'yes') starts " +
+    "indexing; a blank answer, a negative answer, EOF, an unavailable interaction, and any " +
+    "non-interactive/headless run all resolve to NO. " +
+    "On an affirmative answer: call the parse_repository MCP tool exactly once, describe the accepted " +
+    "job as QUEUED, and direct later progress checks to get_parse_status or /check-parse-status " +
+    "(do NOT poll it to completion). If parse_repository returns a blocking refusal or error, do NOT " +
+    "claim the job was queued — report the sanitized result and leave indexing pending. " +
+    "On NO (or any unavailable/non-interactive resolution): do not index; print the exact copy-paste " +
+    "continuation command '/parse-repository' on its own line and state that indexing remains pending. " +
+    "Never request, echo, or transport any credential — only ever direct the human to that " +
+    "integration's own configure_in pointer, verbatim. The pointer is per-integration and is NOT " +
+    "always the setup UI: GitHub's is a terminal command (connect-github), while Jira, SFCC, and " +
+    "Bitbucket point at the setup UI. Follow whatever the report says rather than assuming. " +
+    "End with an explicit summary line stating how many config fields the apply_install_manifest call " +
+    "applied (e.g. 'Applied 8 of 9 derived fields') and whether indexing was queued or left pending — " +
+    "if 0 fields were applied, say so loudly and explain what is still pending.";
 /** Default base URL when `BAPI_BASE_URL` is unset (mirrors index.ts). */
 export const DEFAULT_BAPI_BASE_URL = "https://bridgegpt-api.com";
 /** Default docs dir when `BAPI_DOCS_DIR` is unset (mirrors index.ts). */
@@ -107,27 +168,56 @@ export function getInstallBridgeUsage() {
         "One-command Bridge API project bootstrap. Scaffolds the project, writes the",
         "per-host MCP config with your credentials, verifies connectivity, persists the",
         "routing credential, then opens a fresh agent session to derive the remaining",
-        "config and run /learn-repository.",
+        "config, present a capability report, and offer optional repository indexing.",
+        "",
+        "Run it bare — `install-bridge` with no flags — in a terminal and it asks",
+        `\`${INSTALL_BRIDGE_KEY_SELECTOR_PROMPT.trim()}\` first. Answer yes (or press Enter) for the`,
+        "existing-key flow below; answer no and it asks for an email and creates a new",
+        "Bridge workspace for you (the self-serve flow). 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.",
         "",
         "Inputs (the only two irreducible ones):",
         "  --api-key <key>   Bridge API key. Falls back to the BAPI_API_KEY env var,",
         "                    then an interactive (no-echo) prompt. Generate one in the",
         "                    Bridge API web UI Security page — this command consumes a",
-        "                    key, it does not create one (--invite is the one exception:",
-        "                    it CREATES the project and its first admin key). NEVER",
-        "                    printed or logged.",
-        "  --repo <name>     Repository name. Falls back to BAPI_REPO_NAME, then an",
-        "                    inferred default you confirm interactively. MUST match the",
-        "                    server-side repo registration (it keys the credential",
-        "                    store as bapi:<repo>). Required (no inference) when stdin",
-        "                    is non-interactive. With --invite it is the name your NEW",
-        "                    project is created under (globally unique).",
+        "                    key, it does not create one (--email and --invite are the",
+        "                    exceptions: they CREATE the project and its first admin key).",
+        "                    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 a negative answer to the key question 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",
+        "                    name must be globally unique.",
+        "",
+        "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 a negative answer to",
+        "                    the bare-run key question above 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. No email verification",
+        "                    is performed and no message is sent to the address — it only",
+        "                    labels the new workspace.",
         "",
         "Bootstrap-invite onboarding (no web UI, no pre-existing key):",
-        "  --invite [token]  Redeem a bootstrap invite: creates the project and mints",
-        "                    your own admin API key in one command. Mutually exclusive",
-        "                    with --api-key (in this mode the key is created, not",
-        "                    consumed).",
+        "  --invite [token]  Redeem a bootstrap invite you were already given: creates",
+        "                    the project and mints your own admin API key in one command.",
+        "                    Mutually exclusive with --api-key and --email (in this mode",
+        "                    the key is created, not consumed).",
         "",
         "                    Run it WITHOUT a value — `install-bridge --invite` — and the",
         "                    token is read from an interactive prompt with echo",
@@ -157,8 +247,10 @@ export function getInstallBridgeUsage() {
         "",
         "Environment: BAPI_BASE_URL (default https://bridgegpt-api.com) and BAPI_DOCS_DIR",
         "(default docs/tmp) are read from the environment with the shown fallbacks.",
-        "BAPI_INVITE supplies the bootstrap-invite token non-interactively (scripting",
-        "only — it is exposed to shell history; prefer the prompt).",
+        "BAPI_SIGNUP_EMAIL supplies the self-serve signup email non-interactively (it is",
+        "visible input, not a secret). BAPI_INVITE supplies the bootstrap-invite token",
+        "non-interactively (scripting only — it is exposed to shell history; prefer the",
+        "prompt).",
     ].join("\n");
 }
 /**
@@ -178,10 +270,12 @@ export function parseInstallBridgeArgs(argv) {
     let dryRun = false;
     let agentName = DEFAULT_AGENT_NAME;
     let invite;
+    let email;
     // Track SUPPLIED-ness separately from the values: `--invite` is legitimately
     // valueless (prompt path) and `--api-key ""` is still a contradiction with it.
     let inviteSupplied = false;
     let apiKeySupplied = false;
+    let emailSupplied = false;
     /** Read a `--flag value` or `--flag=value` value, advancing the index. */
     const readValue = (arg, flag, i) => {
         if (arg.startsWith(`${flag}=`)) {
@@ -228,6 +322,21 @@ export function parseInstallBridgeArgs(argv) {
             }
             continue;
         }
+        if (arg === "--email" || arg.startsWith("--email=")) {
+            // REQUIRED-value flag (unlike --invite): the email is what selects and drives
+            // the self-serve mint, so a bare or blank `--email` is a hard error rather
+            // than a prompt trigger. The value is NOT echoed in any error message.
+            const r = readValue(arg, "--email", i);
+            if ("error" in r)
+                return { status: "error", message: r.error };
+            if (r.value.trim().length === 0) {
+                return { status: "error", message: "--email requires a non-empty value." };
+            }
+            email = r.value.trim();
+            emailSupplied = true;
+            i = r.nextIndex;
+            continue;
+        }
         if (arg === "--repo" || arg.startsWith("--repo=")) {
             const r = readValue(arg, "--repo", i);
             if ("error" in r)
@@ -267,9 +376,26 @@ export function parseInstallBridgeArgs(argv) {
                 "it does not consume an existing one.",
         };
     }
+    // --email selects self-serve mode, which CREATES the key — so it conflicts with
+    // both consuming an existing one (--api-key) and redeeming a pre-issued invite
+    // (--invite). Names the flags only — never the email or token values (BAPI-618).
+    if (emailSupplied && apiKeySupplied) {
+        return {
+            status: "error",
+            message: "--email and --api-key are mutually exclusive: self-serve signup creates your API key, " +
+                "it does not consume an existing one.",
+        };
+    }
+    if (emailSupplied && inviteSupplied) {
+        return {
+            status: "error",
+            message: "--email and --invite are mutually exclusive: use --email for self-serve signup (no " +
+                "pre-issued invite), or --invite to redeem an invite you already have.",
+        };
+    }
     return {
         status: "ok",
-        options: { apiKey, repo, force, dryRun, agentName, invite, inviteMode: inviteSupplied },
+        options: { apiKey, repo, force, dryRun, agentName, invite, inviteMode: inviteSupplied, email },
     };
 }
 /**
@@ -330,6 +456,66 @@ export function promptSecretViaReadline(promptText, input = process.stdin, outpu
         muted = true;
     });
 }
+/**
+ * Offer to connect GitHub, if it is not already connected (BAPI-631).
+ *
+ * Entirely best-effort and non-destructive: by the time this runs the install itself is
+ * already complete and durable, so nothing here may fail the run. Every branch that is
+ * not "the user said yes and it worked" simply proceeds to the agent session.
+ *
+ * Reuses the shared connect-github flow rather than duplicating the API, polling,
+ * browser, or picker logic — there is exactly one implementation of that handshake.
+ */
+async function offerGithubConnection(repoName, deps, log) {
+    // No prompt surface → no offer. Never assume consent on a non-interactive run.
+    if (!deps.isTTY || !deps.promptLine)
+        return;
+    try {
+        const credDeps = {
+            env: deps.env,
+            homedir: deps.homedir,
+            platform: deps.platform,
+            readFile: deps.readFile,
+            stat: deps.stat,
+            stderr: () => { },
+        };
+        // Resolve through the shared resolver rather than reusing an in-memory key from
+        // this run: the offered flow is the same shell-spawned surface the standalone
+        // command uses, and it must resolve credentials the same way (project MCP config
+        // env is NOT visible to a spawned shell).
+        const cred = await resolveBapiCredentials(repoName, credDeps);
+        if (!cred.ok)
+            return;
+        const api = {
+            fetch: deps.fetch,
+            baseUrl: deps.env.BAPI_BASE_URL?.trim() || DEFAULT_BAPI_BASE_URL,
+            apiKey: cred.credentials.apiKey,
+        };
+        const state = await fetchGithubConfigurationState(api, repoName);
+        if (state === "configured")
+            return;
+        if (state === "unavailable") {
+            // Do NOT fabricate "unconfigured" from a probe that simply failed — offering to
+            // connect an already-connected repo is worse than staying quiet.
+            log("  note: could not read GitHub configuration status; skipping the GitHub offer.");
+            return;
+        }
+        const answer = (await deps.promptLine("Connect GitHub? (Y/n): ")).trim().toLowerCase();
+        if (answer === "n" || answer === "no")
+            return; // declining is a normal outcome
+        const connectDeps = createDefaultConnectGithubDeps();
+        const code = await runGithubConnectionFlow(connectDeps, api, repoName);
+        if (code !== 0) {
+            log("  note: GitHub was not connected. Your install is complete — connect GitHub later with " +
+                `'npx -y @bridge_gpt/mcp-server@latest connect-github --repo ${repoName}'.`);
+        }
+    }
+    catch {
+        // The install is already durable; a failure here is never fatal to it.
+        log("  note: the GitHub connection offer could not run. Your install is complete — connect " +
+            `GitHub later with 'npx -y @bridge_gpt/mcp-server@latest connect-github --repo ${repoName}'.`);
+    }
+}
 /** Echoed single-line prompt on stderr (used for repo confirmation / value). */
 function promptLineViaReadline(promptText) {
     return new Promise((resolve) => {
@@ -358,13 +544,25 @@ function promptLineViaReadline(promptText) {
  * Always resolves (never rejects): a spawn error / non-zero exit / timeout becomes
  * `{ ok: false, warning }` with secret-free warning text.
  */
+/**
+ * The env clone handed to the pre-warm child, with every credential/PII variable
+ * removed: `BAPI_API_KEY` and the bootstrap-invite token (`BAPI_INVITE`) are
+ * secrets that must never reach an npm lifecycle script, and the self-serve signup
+ * email (`BAPI_SIGNUP_EMAIL`, BAPI-618) is invitee PII with no business in a
+ * `--version` probe. Extracted as a pure, exported helper so the strip is directly
+ * unit-testable (the default spawner below uses the real `spawn`, which is not
+ * injectable).
+ */
+export function sanitizePrewarmEnv(env) {
+    const sanitized = { ...env };
+    delete sanitized.BAPI_API_KEY;
+    delete sanitized.BAPI_INVITE;
+    delete sanitized.BAPI_SIGNUP_EMAIL;
+    return sanitized;
+}
 function spawnPrewarmDefault(command, args, env) {
     return new Promise((resolve) => {
-        const sanitizedEnv = { ...env };
-        delete sanitizedEnv.BAPI_API_KEY;
-        // The bootstrap-invite token is likewise never needed by a `--version` probe
-        // and must not reach an npm lifecycle script.
-        delete sanitizedEnv.BAPI_INVITE;
+        const sanitizedEnv = sanitizePrewarmEnv(env);
         try {
             const child = spawn(command, args, {
                 shell: false,
@@ -393,6 +591,11 @@ function spawnPrewarmDefault(command, args, env) {
 /** Build default deps from the live process. */
 export function createDefaultInstallBridgeDeps() {
     const isTTY = Boolean(process.stdin.isTTY);
+    // One production fetch, reused for both the `fetch` seam and the default
+    // resolver, so a direct caller of this factory gets a resolver bound to the
+    // same client. (runInstallBridgeCli re-binds the resolver to the FINAL merged
+    // fetch when the caller did not override the resolver — see below.)
+    const productionFetch = (...args) => fetch(...args);
     return {
         env: process.env,
         cwd: process.cwd(),
@@ -417,7 +620,8 @@ export function createDefaultInstallBridgeDeps() {
         randomBytes: (size) => cryptoRandomBytes(size),
         promptSecret: isTTY ? promptSecretViaReadline : undefined,
         promptLine: isTTY ? promptLineViaReadline : undefined,
-        fetch: (...args) => fetch(...args),
+        fetch: productionFetch,
+        resolveRepoViaServer: (baseUrl, apiKey) => resolveRepoViaServer(productionFetch, baseUrl, apiKey),
         spawnPrewarm: spawnPrewarmDefault,
         runInit,
         upsertCredential: upsertBapiCredential,
@@ -496,28 +700,174 @@ export async function resolveInviteToken(options, deps) {
     };
 }
 /**
- * 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 and must match server-side
- * registration, so it is never silently inferred non-interactively.
+ * Resolve the SELF-SERVE signup email: `--email <addr>` → `BAPI_SIGNUP_EMAIL` env →
+ * interactive VISIBLE prompt (BAPI-618). Fails (secret-free) when none is available
+ * and stdin is non-interactive.
+ *
+ * The precedence mirrors {@link resolveInviteToken}, but the input is NOT a secret:
+ * an email is not a credential, so it uses the ECHOED {@link InstallBridgeDeps.promptLine}
+ * — never `promptSecret`. (It IS invitee PII, so like every value in this module it
+ * is never written to a log line; it is only ever echoed as the user's own keystrokes
+ * and placed in the mint request body.)
+ *
+ * No email-format validation is performed here — only surrounding whitespace is
+ * trimmed, matching the other CLI input seams and the server's deliberately
+ * permissive "stored unvalidated" contract (D-2). The entered value is never echoed
+ * back in an error message.
  */
-export async function resolveRepoName(options, deps) {
-    if (typeof options.repo === "string" && options.repo.trim().length > 0) {
-        return { ok: true, value: options.repo.trim() };
+export async function resolveSignupEmail(options, deps) {
+    if (typeof options.email === "string" && options.email.trim().length > 0) {
+        return { ok: true, value: options.email.trim() };
     }
-    const fromEnv = deps.env.BAPI_REPO_NAME;
+    const fromEnv = deps.env.BAPI_SIGNUP_EMAIL;
     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." };
+    }
+    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).",
+    };
+}
+/**
+ * Select the onboarding branch as pure logic (deterministic, no I/O, no prompt):
+ *
+ *   - `--invite` (with or without a value) or a non-empty `BAPI_INVITE` selects
+ *     the `bootstrap-invite` need-key branch.
+ *   - otherwise, `--email` or a non-empty `BAPI_SIGNUP_EMAIL` selects the
+ *     `self-serve` need-key branch (BAPI-618).
+ *   - every other invocation selects `have-key`.
+ *
+ * Precedence is explicit: an invite input wins over an email input (both are
+ * need-key, but a pre-issued invite is the more specific intent), and any
+ * need-key input wins over the have-key default. The parser already rejects
+ * `--email` alongside `--api-key`/`--invite`, so a flag-level conflict never
+ * reaches here; the precedence only disambiguates env-var combinations.
+ */
+export function resolveInstallBridgeOnboardingBranch(options, env) {
+    const inviteMode = options.inviteMode === true || (env.BAPI_INVITE ?? "").trim().length > 0;
+    if (inviteMode)
+        return { kind: "need-key", method: "bootstrap-invite" };
+    const emailMode = (options.email ?? "").trim().length > 0 ||
+        (env.BAPI_SIGNUP_EMAIL ?? "").trim().length > 0;
+    if (emailMode)
+        return { kind: "need-key", method: "self-serve" };
+    return { kind: "have-key" };
+}
+/** The exact visible text of the bare-TTY onboarding selector (BAPI-626). */
+export const INSTALL_BRIDGE_KEY_SELECTOR_PROMPT = "Do you have a Bridge API key? [Y/n] ";
+/**
+ * Interactive wrapper around {@link resolveInstallBridgeOnboardingBranch}.
+ *
+ * The pure resolver defaults every un-signalled invocation to `have-key`, which is
+ * correct for a script but wrong for a human: a first-time user with nothing yet
+ * runs a bare `install-bridge`, gets the hidden API-key prompt, and has no way to
+ * discover that the self-serve email path exists. So a BARE INTERACTIVE run — and
+ * only that — is asked which branch it wants.
+ *
+ * "Bare" is deliberately strict. Any of these keeps the existing deterministic
+ * behaviour with NO prompt:
+ *
+ *   - stdin is not a TTY, or no `promptLine` seam is available (scripts, CI);
+ *   - any CLI argument was supplied (the user already stated an intent);
+ *   - a non-blank `BAPI_API_KEY` is present (that IS the existing-key intent);
+ *   - the pure resolver already chose a need-key branch explicitly.
+ *
+ * A prompt failure becomes a typed, secret-free failure rather than an exception:
+ * the caller turns it into an exit code, and terminal/internal error text never
+ * reaches the user.
+ */
+export async function resolveInstallBridgeOnboardingBranchForRun(options, deps, argv) {
+    const branch = resolveInstallBridgeOnboardingBranch(options, deps.env);
+    // An explicit need-key intent is already unambiguous — never re-ask it.
+    if (branch.kind === "need-key")
+        return { ok: true, branch };
+    const hasEnvApiKey = (deps.env.BAPI_API_KEY ?? "").trim().length > 0;
+    const isBareInvocation = argv.length === 0;
+    if (!deps.isTTY || !deps.promptLine || !isBareInvocation || hasEnvApiKey) {
+        return { ok: true, branch };
+    }
+    const promptLine = deps.promptLine;
+    try {
+        // Bounded so a prompt seam that returns the same invalid value forever (a
+        // misbehaving pipe that passes the TTY check) cannot spin indefinitely.
+        for (let attempt = 0; attempt < 5; attempt += 1) {
+            const answer = (await promptLine(INSTALL_BRIDGE_KEY_SELECTOR_PROMPT)).trim().toLowerCase();
+            // Blank = accept the bracketed default (Y), matching the prompt's own contract.
+            if (answer.length === 0 || answer === "y" || answer === "yes") {
+                return { ok: true, branch: { kind: "have-key" } };
+            }
+            if (answer === "n" || answer === "no") {
+                return { ok: true, branch: { kind: "need-key", method: "self-serve" } };
+            }
+            deps.log("Please answer y or n (press Enter for yes).");
+        }
+        return {
+            ok: false,
+            error: "No valid answer to the Bridge API key question. Re-run and answer y or n.",
+        };
+    }
+    catch {
+        // Secret-free by construction: the caught value is never surfaced.
+        return {
+            ok: false,
+            error: "Could not read your answer from the terminal. Re-run with --api-key <key> if you have a " +
+                "Bridge API key, or --email <addr> to create a new Bridge workspace.",
+        };
+    }
+}
+/**
+ * Return the explicitly configured repository name (`--repo`, then
+ * `BAPI_REPO_NAME`), trimmed, or `undefined` when neither is supplied. Pure: no
+ * prompting, no inference, no I/O. `--repo` takes priority over the environment.
+ * This is the deterministic short-circuit that runs BEFORE any server resolution.
+ */
+export function resolveConfiguredRepoName(options, env) {
+    if (typeof options.repo === "string" && options.repo.trim().length > 0) {
+        return options.repo.trim();
+    }
+    const fromEnv = env.BAPI_REPO_NAME;
+    if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
+        return fromEnv.trim();
+    }
+    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
+ * 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.
+ */
+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).
     if (!deps.isTTY || !deps.promptLine) {
         return {
             ok: false,
-            error: "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.",
+            error: mode === "new-project"
+                ? "A project name is required. Pass --repo or set the BAPI_REPO_NAME environment " +
+                    "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.",
         };
     }
     // Infer a sensible default: existing .bridge/config, else the cwd basename.
@@ -532,13 +882,19 @@ export async function resolveRepoName(options, deps) {
             inferred = validated.value;
     }
     if (inferred) {
-        const answer = (await deps.promptLine(`Repo name [${inferred}] (must match server-side registration): `)).trim();
+        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 chosen = answer.length > 0 ? answer : inferred;
         if (chosen.length > 0)
             return { ok: true, value: chosen };
     }
     else {
-        const answer = (await deps.promptLine("Repo name (must match server-side registration): ")).trim();
+        const promptText = mode === "new-project"
+            ? "Name your new Bridge project: "
+            : "Repo name (must match server-side registration): ";
+        const answer = (await deps.promptLine(promptText)).trim();
         if (answer.length > 0)
             return { ok: true, value: answer };
     }
@@ -668,11 +1024,13 @@ export async function verifyConnectivity(deps, baseUrl, repoName, apiKey) {
             signal: AbortSignal.timeout(10_000),
         });
     }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+    catch {
+        // The caught exception message is NOT interpolated: some fetch/undici errors
+        // echo request detail (which carries the X-API-Key header) into the message,
+        // so a fixed, secret-free string is used instead (BAPI-616).
         return {
             ok: false,
-            message: `Could not reach the Bridge API at ${baseUrl} (${msg}). Check BAPI_BASE_URL and your network.`,
+            message: `Could not reach the Bridge API at ${baseUrl}. Check BAPI_BASE_URL and your network.`,
         };
     }
     if (resp.ok)
@@ -697,6 +1055,54 @@ export async function verifyConnectivity(deps, baseUrl, repoName, apiKey) {
         message: `Connectivity check failed (HTTP ${resp.status}). Verify your repo, API key, and BAPI_BASE_URL.`,
     };
 }
+/** The resolve endpoint: `<base>/setup/resolve-repo`. No query string — ever. */
+export function buildResolveRepoUrl(baseUrl) {
+    return `${baseUrl.replace(/\/+$/, "")}/setup/resolve-repo`;
+}
+/**
+ * Resolve the repository name server-side from an existing API key. The key
+ * travels ONLY in the `X-API-Key` header (never the URL, never the body), bounded
+ * by the same 10s timeout as {@link verifyConnectivity}.
+ *
+ * Status mapping is the whole compatibility story: `404` → `not-deployed` (old
+ * server), `409` → `unresolved` (ambiguous/shared/client-scoped/legacy), every
+ * other non-OK (`401`, `403`, `5xx`, unexpected) → `error`, and any
+ * network/timeout/malformed-body failure → `error`. A caught exception or a
+ * response body is NEVER read into the result.
+ */
+export async function resolveRepoViaServer(fetchImpl, baseUrl, apiKey) {
+    const url = buildResolveRepoUrl(baseUrl);
+    let resp;
+    try {
+        resp = await fetchImpl(url, {
+            headers: { "X-API-Key": apiKey },
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    catch {
+        // Network failure / timeout. The exception may echo the request (and thus the
+        // X-API-Key header), so it is never inspected or propagated.
+        return { status: "error" };
+    }
+    if (resp.status === 404)
+        return { status: "not-deployed" };
+    if (resp.status === 409)
+        return { status: "unresolved" };
+    if (!resp.ok)
+        return { status: "error" };
+    let body;
+    try {
+        body = await resp.json();
+    }
+    catch {
+        return { status: "error" };
+    }
+    const repoName = body?.repo_name;
+    const validated = validateRepoName(repoName);
+    if (!validated.ok)
+        return { status: "error" };
+    return { status: "resolved", repoName: validated.value };
+}
 // ---------------------------------------------------------------------------
 // Bootstrap-invite exchange (BAPI-606) — replaces the pre-flight ping in invite mode
 // ---------------------------------------------------------------------------
@@ -796,6 +1202,76 @@ export async function exchangeBootstrapInvite(deps, baseUrl, token, repoName, ke
         message: `The bootstrap exchange failed (HTTP ${resp.status}). Verify BAPI_BASE_URL and try again.`,
     };
 }
+// ---------------------------------------------------------------------------
+// Self-serve mint (BAPI-618): email -> invite token
+// ---------------------------------------------------------------------------
+/**
+ * The self-serve invite-token prefix, mirroring the server's
+ * ``BOOTSTRAP_INVITE_TOKEN_PREFIX`` (``bapi_inv_``). A well-formed token
+ * self-identifies with this prefix; a success response whose token does not is
+ * treated as a `failed` mint rather than fed into the redemption path.
+ */
+export const BOOTSTRAP_INVITE_TOKEN_PREFIX = "bapi_inv_";
+/** 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`;
+}
+/**
+ * POST the self-serve mint: an email in, an invite token out. Mirrors
+ * {@link exchangeBootstrapInvite}'s fetch/timeout/secret-free-result discipline.
+ *
+ * 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.
+ */
+export async function mintSelfServeInvite(deps, baseUrl, email) {
+    const url = buildSelfServeMintUrl(baseUrl);
+    let resp;
+    try {
+        resp = await deps.fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ invitee_email: email }),
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    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 token;
+        try {
+            const body = (await resp.json());
+            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" ||
+            token.trim().length === 0 ||
+            !token.startsWith(BOOTSTRAP_INVITE_TOKEN_PREFIX)) {
+            return { ok: false, category: "failed" };
+        }
+        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) {
+        return { ok: false, category: "rate-limited" };
+    }
+    if (resp.status === 400 || resp.status === 422) {
+        return { ok: false, category: "invalid" };
+    }
+    return { ok: false, category: "failed" };
+}
 /**
  * The 401 message for a run that had to GENERATE a fresh secret — i.e. no local
  * pending record existed. Besides a simply-wrong token, this is exactly what a lost
@@ -844,8 +1320,10 @@ export function buildDryRunPreview(plan) {
     if (plan.bootstrapInvite)
         return buildBootstrapDryRunPreview(plan);
     return [
-        "install-bridge --dry-run (no writes, no network, no spawns)",
-        `Repo name:        ${plan.repoName}`,
+        plan.attemptedServerResolution
+            ? "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)" : ""}`,
         `Base URL (ping):  ${plan.baseUrl}`,
         `Docs dir:         ${plan.docsDir}`,
         `Agent:            ${plan.agentName}`,
@@ -860,7 +1338,29 @@ export function buildDryRunPreview(plan) {
         `Step 3b — pre-warm the version-pinned launcher bucket (fail-open, env sanitized — BAPI_API_KEY removed): ${plan.prewarmCommand}`,
         MCP_TIMEOUT_GUIDANCE,
         `Step 4 — persist routing credential: target ${plan.credentialTarget} at ${plan.credentialStorePath}`,
-        `Step 5 — spawn agent session: ${plan.spawnCommand}`,
+        ...buildLaunchStepPreview(plan),
+    ];
+}
+/**
+ * The Step 5 preview lines, shared by both previews so the launch description
+ * cannot drift between the have-key and need-key flows.
+ *
+ * A --dry-run never writes the launch script, so the preview describes the
+ * materialization rather than performing it — but it still shows the full command,
+ * because the command is what the user is previewing and it is secret-free.
+ */
+function buildLaunchStepPreview(plan) {
+    return [
+        // BAPI-631: described, never performed in --dry-run — a preview must not open a
+        // browser or reach the network. It is also strictly optional, so it carries no step
+        // number of its own and never changes the 5-step count.
+        "Step 4b — optional GitHub connect (SKIPPED in --dry-run): read GitHub's configured state",
+        "          via the install manifest and, only when it is unconfigured and the terminal is",
+        "          interactive, offer 'Connect GitHub? (Y/n)' before the agent session starts.",
+        "Step 5 — spawn agent session: the full command below is stored in a restricted launch script",
+        "          (mode 0600, under the system temp dir) and only a short sourced runner is spawned",
+        "          (the script itself is NOT written in --dry-run):",
+        `          ${plan.spawnCommand}`,
     ];
 }
 /**
@@ -872,14 +1372,35 @@ export function buildDryRunPreview(plan) {
  */
 function buildBootstrapDryRunPreview(plan) {
     const pendingTarget = `bootstrap-pending:${plan.repoName}`;
+    // Self-serve signup (BAPI-618): the ONLY structural difference from a pre-issued
+    // invite is a mint-from-email step (Step 2·pre) that turns an email into the
+    // invite token before the unchanged redemption below. The preview states plainly
+    // that in --dry-run that signup/mint is previewed-and-skipped: no account is
+    // created, no mint request is sent, no email leaves the machine. The email and
+    // any synthetic token are deliberately absent from this output.
+    const header = plan.selfServeSignup
+        ? "install-bridge --email --dry-run (no writes, no network, no spawns, no account created, no secret generated)"
+        : "install-bridge --invite --dry-run (no writes, no network, no spawns, no secret generated)";
+    const repoLine = plan.selfServeSignup
+        ? `Repo name:        ${plan.repoName} (created by the self-serve exchange; globally unique)`
+        : `Repo name:        ${plan.repoName} (created by the exchange; globally unique)`;
+    const selfServeStep = plan.selfServeSignup
+        ? [
+            "Step 2·pre — self-serve signup (PREVIEWED, SKIPPED in --dry-run): no Bridge workspace",
+            "          signup is requested, no mint call is made, and no email is sent or transmitted;",
+            "          a real run would request a fresh workspace for your email and receive an invite",
+            "          token, which then feeds the SAME redemption protocol below.",
+        ]
+        : [];
     return [
-        "install-bridge --invite --dry-run (no writes, no network, no spawns, no secret generated)",
-        `Repo name:        ${plan.repoName} (created by the exchange; globally unique)`,
+        header,
+        repoLine,
         `Base URL:         ${plan.baseUrl}`,
         `Docs dir:         ${plan.docsDir}`,
         `Agent:            ${plan.agentName}`,
         "",
         "Step 1 — scaffold (runInit): commands, agents, pipelines, .bridge/config, secret-free MCP placeholders.",
+        ...selfServeStep,
         `Step 2a — generate key_secret (32 CSPRNG bytes) and fsync it to ${pendingTarget} at ${plan.credentialStorePath}`,
         "          BEFORE the exchange. If that write fails the run ABORTS and no invite is spent.",
         `Step 2b — redeem the bootstrap invite (replaces the pre-flight ping — there is no key yet):`,
@@ -894,7 +1415,7 @@ function buildBootstrapDryRunPreview(plan) {
         `Step 3b — pre-warm the version-pinned launcher bucket (fail-open, env sanitized — BAPI_API_KEY / BAPI_INVITE removed): ${plan.prewarmCommand}`,
         MCP_TIMEOUT_GUIDANCE,
         `Step 4 — promote ${pendingTarget} → ${plan.credentialTarget} at ${plan.credentialStorePath} (only after the exchange succeeds)`,
-        `Step 5 — spawn agent session: ${plan.spawnCommand}`,
+        ...buildLaunchStepPreview(plan),
     ];
 }
 /**
@@ -962,6 +1483,12 @@ function buildManualHostInstructions(entry, editors) {
  */
 export async function runInstallBridgeCli(argv, overrides = {}) {
     const deps = { ...createDefaultInstallBridgeDeps(), ...overrides };
+    // When the caller overrode only `fetch` (the common test seam), bind the
+    // default resolver to the FINAL merged fetch so server resolution still routes
+    // through the override. An explicit `resolveRepoViaServer` override is honored.
+    if (!overrides.resolveRepoViaServer) {
+        deps.resolveRepoViaServer = (baseUrl, apiKey) => resolveRepoViaServer(deps.fetch, baseUrl, apiKey);
+    }
     const { log, errorLog } = deps;
     const parsed = parseInstallBridgeArgs(argv);
     if (parsed.status === "help") {
@@ -975,18 +1502,42 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         return 1;
     }
     const options = parsed.options;
-    // Bootstrap-invite mode: `--invite` (with or without a value), or a non-empty
-    // BAPI_INVITE. Everything below branches on this ONE flag; an invocation without
-    // it is the unchanged consume-a-key flow.
-    const bootstrapInviteMode = options.inviteMode === true || (deps.env.BAPI_INVITE ?? "").trim().length > 0;
+    // Onboarding branch: have-key vs. a need-key method (`bootstrap-invite` = redeem
+    // a pre-issued invite, `self-serve` = mint one from an email, BAPI-618). BOTH
+    // need-key methods share the downstream redemption protocol, so
+    // `bootstrapInviteMode` is true for both; `selfServeSignupMode` discriminates the
+    // one extra step (mint-from-email) the self-serve path adds.
+    //
+    // The selection is pure and deterministic for every explicit, env-driven, and
+    // non-TTY invocation; only a BARE interactive run is asked which branch it wants
+    // (BAPI-626 — otherwise a first-time user can never reach self-serve).
+    const branchResult = await resolveInstallBridgeOnboardingBranchForRun(options, deps, argv);
+    if (!branchResult.ok) {
+        errorLog(`Error: ${branchResult.error}`);
+        return 1;
+    }
+    const branch = branchResult.branch;
+    const bootstrapInviteMode = branch.kind === "need-key";
+    const selfServeSignupMode = branch.kind === "need-key" && branch.method === "self-serve";
     // ---- Resolve inputs (may prompt when interactive) ----
-    // Resolve the credential input first so a fully-empty non-interactive invocation
-    // fails with the (more security-relevant) missing-secret message before the repo
-    // one. In bootstrap-invite mode there is no API key to resolve — the exchange
-    // MINTS it — so resolveApiKey is skipped entirely.
+    // Resolve the credential/entry input first so a fully-empty non-interactive
+    // invocation fails with the (more relevant) missing-input message before the repo
+    // one. In either need-key mode there is no API key to resolve — the exchange
+    // MINTS it. Self-serve resolves the email here (up-front, before the dry-run
+    // guard) so a missing email fails fast; the actual MINT happens later, strictly
+    // after the dry-run return, so a preview neither mints nor sends anything.
     let apiKey = "";
     let inviteToken = "";
-    if (bootstrapInviteMode) {
+    let signupEmail = "";
+    if (selfServeSignupMode) {
+        const emailResult = await resolveSignupEmail(options, deps);
+        if (!emailResult.ok) {
+            errorLog(`Error: ${emailResult.error}`);
+            return 1;
+        }
+        signupEmail = emailResult.value;
+    }
+    else if (bootstrapInviteMode) {
         const inviteResult = await resolveInviteToken(options, deps);
         if (!inviteResult.ok) {
             errorLog(`Error: ${inviteResult.error}`);
@@ -1002,25 +1553,61 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         }
         apiKey = keyResult.value;
     }
-    const repoResult = await resolveRepoName(options, deps);
-    if (!repoResult.ok) {
-        errorLog(`Error: ${repoResult.error}`);
-        return 1;
-    }
-    let repoName = repoResult.value;
-    // Invite mode creates the project, so the name must be valid BEFORE any pending
-    // state or exchange. (Normal mode's name is already registered server-side, so
-    // its behavior is deliberately left untouched.)
+    // baseUrl is resolved BEFORE repository input because the have-key branch needs
+    // it for the server-resolution request.
+    const baseUrl = deps.env.BAPI_BASE_URL ?? DEFAULT_BAPI_BASE_URL;
+    const docsDir = deps.env.BAPI_DOCS_DIR ?? DEFAULT_BAPI_DOCS_DIR;
+    // ---- 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.
+    let repoName;
+    let attemptedServerResolution = false;
     if (bootstrapInviteMode) {
-        const validated = validateRepoName(repoName);
+        const repoResult = await resolveRepoName(options, deps, "new-project");
+        if (!repoResult.ok) {
+            errorLog(`Error: ${repoResult.error}`);
+            return 1;
+        }
+        // Invite mode creates the project, so the name must be valid BEFORE any
+        // pending state or exchange.
+        const validated = validateRepoName(repoResult.value);
         if (!validated.ok) {
             errorLog(`Error: invalid repo name — ${validated.error}.`);
             return 1;
         }
         repoName = validated.value;
     }
-    const baseUrl = deps.env.BAPI_BASE_URL ?? DEFAULT_BAPI_BASE_URL;
-    const docsDir = deps.env.BAPI_DOCS_DIR ?? DEFAULT_BAPI_DOCS_DIR;
+    else {
+        const configured = resolveConfiguredRepoName(options, deps.env);
+        if (configured !== undefined) {
+            // Deterministic short-circuit: no server round-trip when the name is known.
+            repoName = configured;
+        }
+        else {
+            attemptedServerResolution = true;
+            log("Resolving repository…");
+            const resolution = await deps.resolveRepoViaServer(baseUrl, apiKey);
+            if (resolution.status === "resolved") {
+                repoName = resolution.repoName;
+            }
+            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.
+                const repoResult = await resolveRepoName(options, deps, "existing-registration");
+                if (!repoResult.ok) {
+                    errorLog(`Error: ${repoResult.error}`);
+                    return 1;
+                }
+                repoName = repoResult.value;
+            }
+        }
+    }
     const agent = resolveAgentSpec(options.agentName) ?? resolveAgentSpec(DEFAULT_AGENT_NAME);
     const spawnCommand = deps.buildShellCommand(agent, INSTALL_BRIDGE_AGENT_PROMPT, deps.cwd, deps.platform);
     const credentialStorePath = getPrimaryCredentialStorePath({
@@ -1045,6 +1632,8 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         ...(bootstrapInviteMode
             ? { bootstrapInvite: true, exchangeUrl: buildBootstrapExchangeUrl(baseUrl) }
             : {}),
+        ...(selfServeSignupMode ? { selfServeSignup: true } : {}),
+        ...(attemptedServerResolution ? { attemptedServerResolution: true } : {}),
     };
     // ---- --dry-run: preview every step, strictly no side effects ----
     // Positioned BEFORE the CSPRNG, the pending write, the exchange, the scaffold,
@@ -1055,6 +1644,31 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             log(line);
         return 0;
     }
+    // ---- Materialize the Step 5 launch command BEFORE any install side effect ----
+    // `spawnCommand` embeds the whole INSTALL_BRIDGE_AGENT_PROMPT and is multiple KB
+    // — far past what osascript can type into a Terminal/iTerm tab, which is why the
+    // spawn silently delivered a truncated line. It must travel via a launch script.
+    //
+    // This runs HERE, before the scaffold/mint/credential/config writes, because a
+    // command that cannot be launched safely is a whole-run failure, not a Step 5
+    // warning: the deterministic setup would otherwise complete and leave the user
+    // in the "configured but never configured by the agent" state the warning below
+    // explicitly calls out. Failing first means nothing is half-done.
+    const materialized = await materializeWorkerLaunchCommand(deps.startTicketsDeps, "install", spawnCommand);
+    if (!materialized.ok) {
+        errorLog(`Error: ${materialized.error}`);
+        return 1;
+    }
+    const launchCommand = materialized.command;
+    // Independent final guard on the line ACTUALLY handed to the terminal — not on
+    // the original command. It catches the two ways a "successful" materialization
+    // can still be unlaunchable: no writer seam (inline command preserved verbatim),
+    // and a runner whose script path is unexpectedly long.
+    if (Buffer.byteLength(launchCommand, "utf8") >= MAX_TERMINAL_COMMAND_BYTES) {
+        errorLog("Error: the agent session command is too long to send to the terminal safely. " +
+            "Check that the system temporary directory is writable so the launch script can be used.");
+        return 1;
+    }
     const credentialWriteDeps = {
         env: deps.env,
         homedir: deps.homedir,
@@ -1091,6 +1705,32 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // ---- Step 2 — mint (invite mode) or verify (normal mode) the credential ----
     let inviteFingerprint = "";
     if (bootstrapInviteMode) {
+        // ---- Self-serve signup (BAPI-618): mint the invite token from the email ----
+        // This is the ONE step that precedes the unchanged BAPI-606 redemption below.
+        // It sits AFTER the --dry-run return above, so a preview never mints, never
+        // sends the email, and never writes a pending secret. On success the minted
+        // token is assigned to `inviteToken` and the flow falls into the existing
+        // persist-before-exchange block VERBATIM — identical to a --invite token from
+        // here on. On failure we return BEFORE any CSPRNG/pending write, so nothing is
+        // persisted. The email and the token are never logged.
+        if (selfServeSignupMode) {
+            log("Step 2/5 — requesting Bridge self-serve setup…");
+            const mint = await mintSelfServeInvite(deps, baseUrl, signupEmail);
+            if (!mint.ok) {
+                if (mint.category === "rate-limited") {
+                    errorLog("Error: Self-serve setup is temporarily rate limited. Try again later.");
+                }
+                else if (mint.category === "invalid") {
+                    errorLog("Error: Self-serve setup could not be requested. Check the email value and try again.");
+                }
+                else {
+                    errorLog("Error: Unable to complete self-serve setup. Check connectivity and retry.");
+                }
+                return 1;
+            }
+            // Treated identically to a manually supplied invite token from here on.
+            inviteToken = mint.token;
+        }
         // ===================================================================
         // LOAD-BEARING ORDERING — NOT DEFENSIVE POLISH. DO NOT "TIDY" THIS.
         //
@@ -1318,10 +1958,17 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 "'npx -y @bridge_gpt/mcp-server doctor'.");
         }
     }
+    // ---- optional GitHub connect offer (BAPI-631) ----
+    // Placed AFTER the credential is durable (the flow needs a resolvable key) and BEFORE
+    // the agent spawn, for two reasons: the spawned session's capability report should
+    // observe GitHub as configured if the user connects it here, and running it after the
+    // spawn would put two prompts on the same terminal at once.
+    await offerGithubConnection(repoName, deps, log);
     // ---- Step 5 — spawn a fresh agent session for the agentic remainder ----
-    log(`Step 5/5 — opening a ${agent.name} session for /install-bridge + /learn-repository…`);
+    log(`Step 5/5 — opening a ${agent.name} session for /install-bridge configuration + capability report…`);
     const terminal = detectTerminal(undefined, deps.env);
-    const spawnResult = await deps.spawnTerminalTab(deps.startTicketsDeps, terminal, spawnCommand, {
+    // Only the validated short runner reaches the terminal — never the inline prompt.
+    const spawnResult = await deps.spawnTerminalTab(deps.startTicketsDeps, terminal, launchCommand, {
         key: "install",
         worktreePath: deps.cwd,
     });
@@ -1332,16 +1979,17 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         // user can run the agentic remainder by hand. Mirrors start-tickets treating a
         // spawn failure as non-fatal to the run.
         errorLog(`Warning: setup steps completed, but the agent session could not be opened (${spawnResult.error}). ` +
-            "The project is NOT configured yet — run /install-bridge then /learn-repository manually " +
-            "in this project to derive and apply the config fields.");
+            "The project is NOT configured yet — run /install-bridge manually in this project to derive " +
+            "and apply the config fields and see the capability report, then choose whether to run " +
+            "/parse-repository to index the repository.");
         return 0;
     }
     log("");
-    log(`install-bridge setup steps complete. A fresh ${agent.name} session is now running ` +
-        "/install-bridge then /learn-repository.");
+    log(`install-bridge setup steps complete. A fresh ${agent.name} session is now applying ` +
+        "configuration, presenting the capability report, and ending with one indexing-consent question.");
     log("NOTE: the install is not finished until that session's apply reports applied fields — " +
-        "it will pause to ask you to approve the project description. Verify afterwards on the " +
-        "project's Get Started page (install status panel) or via the session's " +
-        "'Applied N of M' summary.");
+        "it will pause to ask you to approve the project description, and it will close by asking " +
+        "'[Y/n] Index repository now?'. Verify afterwards on the project's Get Started page " +
+        "(install status panel) or via the session's 'Applied N of M' summary.");
     return 0;
 }