@bridge_gpt/mcp-server 0.2.33 → 0.2.36

package/build/install-bridge.js

@@ -1,7 +1,12 @@
 /**
  * install-bridge — the one-command Bridge API project bootstrap (BAPI-429).
  *
- *   npx -y @bridge_gpt/mcp-server@latest install-bridge [--repo <name>] [--api-key <key>] [--force] [--dry-run] [--agent <name>]
+ *   npx -y @bridge_gpt/mcp-server install [--repo <name>] [--api-key <key>] [--force] [--dry-run] [--agent <name>]
+ *
+ * The documented spelling is `install` (BAPI-714, Group E). The legacy
+ * `install-bridge` token remains a silent, permanent alias — every string this
+ * module prints names `install`, because that is the only spelling the README,
+ * the invite email, and the operator-provisioned command teach.
  *
  * Collapses the previously five-step manual setup into a single CLI subcommand.
  * It does the DETERMINISTIC work in the shell:
@@ -36,8 +41,9 @@
  *
  * then SPAWNS a fresh agent session (Step 5) for the CONFIGURE-ONLY agentic
  * remainder: `/install-bridge` config-field derivation → the read-after-write
- * concise capability report → a `/learn-repository` recommendation (BAPI-658).
- * It does NOT chain into running `/learn-repository` itself — that stays the
+ * concise capability report → whatever next step the manifest's `next_step.command`
+ * names, rendered only when it is non-empty (BAPI-658, BAPI-720).
+ * It does NOT chain into running that command itself — that stays the
  * human's next explicit invocation — and it never asks about, decides, or
  * claims anything about repository indexing: indexing is entirely automatic,
  * gated server-side by the existing readiness funnel, with no prompt on any
@@ -57,22 +63,41 @@
  * 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`).
- *
- * ORDINARY-ENTRY INVITE RECLASSIFICATION (BAPI-661) — the have-key branch's own
- * credential input (`--api-key`, `BAPI_API_KEY`, or its hidden prompt) is
- * CREDENTIAL-AGNOSTIC: it accepts a full API key OR a bootstrap-invite token,
- * because a user handed only an invite has no way to know it belongs in a
- * different flag. `classifyEnteredCredential` inspects the resolved value
- * immediately after input resolution (before repository-name resolution); a
- * `bapi_inv_…` value flips the branch's `bootstrapInviteMode`/`inviteToken` and
- * the run falls into the SAME bootstrap-invite protocol described below, verbatim.
- * Explicit `--invite`/`BAPI_INVITE` and `--email`/`BAPI_SIGNUP_EMAIL` are never
- * reclassified — they are already unambiguous and remain authoritative.
+ * deterministic from flags/env, except that a BARE interactive run is asked ONE
+ * question (BAPI-626/708): `Welcome to Bridge - do you have a token yet?`, answered
+ * `1` (yes) or `2` (no). Answering `2` is the self-serve route, which a first-time
+ * user could not otherwise discover. Answering `1` opens a single hidden,
+ * CREDENTIAL-AGNOSTIC token prompt and the route is then inferred from the pasted
+ * value's SHAPE — the user is never asked to pre-classify their own credential,
+ * because the shape checks below do that with no probe request. 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`).
+ *
+ * SHAPE-BASED ROUTING, AND THE INFERRED/DECLARED SPLIT (BAPI-661/687/708) — the
+ * have-key branch's credential input (`--api-key`, `BAPI_API_KEY`, or its hidden
+ * prompt) is CREDENTIAL-AGNOSTIC: it accepts a full API key OR a bootstrap-invite
+ * token. `classifyEnteredCredential` (prefix) and `isHighEntropyApiKeyShape`
+ * (positive 43-char canonical base64url test) inspect the resolved value
+ * immediately after input resolution, before repository-name resolution; a
+ * `bapi_inv_…` value flips `bootstrapInviteMode`/`inviteToken` and the run falls
+ * into the SAME bootstrap-invite protocol described below, verbatim.
+ *
+ * What differs is whether the user DECLARED a route:
+ *
+ *   - INFERRED — the bare interactive question was answered. This is the PRIMARY
+ *     path, not mis-paste recovery: nothing was declared, so the detected type and
+ *     destination route are ANNOUNCED and the run proceeds. There is no
+ *     confirmation prompt and no decline exit, because there is no stated intent
+ *     for the value to contradict.
+ *   - DECLARED — `--api-key`/`BAPI_API_KEY`, `--invite`/`BAPI_INVITE`, or
+ *     `--email`/`BAPI_SIGNUP_EMAIL`. BAPI-687 behavior is unchanged, asymmetry
+ *     included: an invite-shaped value on the key path auto-switches on a non-TTY
+ *     (with a notice), while an API-key-shaped value on the invite path exits
+ *     non-zero rather than silently redirecting a script.
+ *
+ * A value matching NEITHER shape is never reclassified in either direction; it
+ * stays on its route and fails there. Because the question is reachable only on a
+ * bare interactive TTY run, every non-interactive run is declared by construction.
  *
  * BOOTSTRAP-INVITE MODE (BAPI-606) — one of the exceptions to "this command
  * consumes a key, it does not create one" (the ordinary-entry reclassification
@@ -118,12 +143,17 @@ import { randomBytes as cryptoRandomBytes, createHash } from "crypto";
 import os from "os";
 import path from "path";
 import readline from "readline";
-import { runInit, buildBridgeApiEntry } from "./init.js";
+import { runInit, buildBridgeApiEntry, resolveInitScaffoldAssets, refreshBridgeApiPackageSpec, currentBridgePackageSpec, } from "./init.js";
 import { VERSION } from "./version.generated.js";
 import { validateRepoName } from "./bridge-config.js";
 import { MCP_HOST_TARGETS, HOST_PLATFORM_ORDER, allHostTargets, agentForPlatform, isHostPlatformId, detectDefaultPlatforms, } from "./mcp-host-targets.js";
 import { provisionHostTarget, createDefaultVendorProcessDeps, } from "./mcp-host-config.js";
-import { writeMcpInstallState } from "./mcp-install-state.js";
+import { recordInstalledProjectArtifact, writeMcpInstallState } from "./mcp-install-state.js";
+import { runInstallBridgeConductorCli, } from "./install-bridge-conductor.js";
+import { runConductorInstallDoctor, } from "./conductor/install-doctor.js";
+import { resolveConductorBridgeApiAccess, } from "./conductor/bridge-api-client.js";
+import { claudeReviewWorkflowPath, writeClaudeReviewWorkflow, } from "./claude-review-workflow.js";
+import { runSetupEpicCli } from "./setup-epic.js";
 import { ensureGitignored as ensureGitignoredShared, } from "./git-ignore-utils.js";
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
 import { upsertBapiCredential, getPrimaryCredentialStorePath, prepareBootstrapPendingCredential, repointBootstrapPendingCredential, promoteBootstrapPendingCredential, lookupSelfServeBootstrapPendingCredential, discardBootstrapPendingCredential, getBootstrapPendingTarget, resolveBapiCredentials, } from "./credential-store.js";
@@ -136,11 +166,17 @@ import { buildGenericAgentShellCommand, getDefaultSpawnTerminalTabForPlatform, d
 /** Redaction sentinel — the API-key value is NEVER printed; this stands in. */
 export const REDACTED_API_KEY = "<REDACTED>";
 /**
- * Always-surfaced success-path note (BAPI-451 W3, E-3). The pinned launcher's
- * FIRST cold launch can resolve/download the package inline; if the MCP client's
- * connect deadline is very short it may time out before the handshake. Pre-warming
- * (below) makes this rare, but the note is surfaced unconditionally so the
- * fail-soft backstop is always discoverable.
+ * Fail-soft backstop note (BAPI-451 W3, E-3). The pinned launcher's FIRST cold
+ * launch can resolve/download the package inline; if the MCP client's connect
+ * deadline is very short it may time out before the handshake.
+ *
+ * BAPI-708 (Part B) narrowed WHERE this is surfaced. It is no longer printed after
+ * a SUCCESSFUL pre-warm — there, the cold install the note warns about has already
+ * been paid, so the remedy addressed a problem that did not occur. It is still
+ * emitted by the pre-warm FAILURE branch, where an incomplete warm makes the
+ * remedy real, and by both `--dry-run` previews, which describe the run rather
+ * than perform it. `mcp_server/src/doctor.ts` carries an independently-worded
+ * near-duplicate for the after-the-fact diagnosis case.
  */
 export const MCP_TIMEOUT_GUIDANCE = "Note: if your MCP client has a very short connect deadline, raise MCP_TIMEOUT for the first launch " +
     "(the initial npx package resolution/download can exceed a short connect timeout).";
@@ -159,8 +195,12 @@ export function buildPrewarmCommandPreview() {
 /**
  * The natural-language prompt handed to the spawned agent session. It is
  * CONFIGURE-ONLY: it derives and applies configuration, presents the concise
- * capability report, and closes with a `/learn-repository` recommendation
- * (BAPI-658). It never chains straight into running /learn-repository itself —
+ * capability report — the availability-framed 'Available now' / 'Needs setup'
+ * pair the server authors (BAPI-719), rendered verbatim with zero local
+ * curation — and closes with the server-provided `next_step.command`
+ * when the manifest returned a non-empty one — and with nothing at all when it
+ * did not (BAPI-658, BAPI-720). The eligibility decision is the server's, not
+ * this prompt's. It never chains straight into running that command itself —
  * that remains the human's next explicit invocation — and it never asks about,
  * decides, or claims anything about repository indexing: indexing is entirely
  * automatic, gated by the existing readiness funnel
@@ -171,13 +211,32 @@ export const INSTALL_BRIDGE_AGENT_PROMPT = "Execute the /install-bridge command
     "The command chooses its own mode from the install manifest's `configured` flag — do NOT force a " +
     "mode: when `configured` is false it runs its fresh-configuration flow, and when `configured` is " +
     "true it runs JOIN MODE. In JOIN MODE the command must NOT derive, approve, apply, or offer any " +
-    "configuration and applies zero fields for any caller; a joining member's only closing interaction " +
-    "is the welcome plus the concise capability report (no /learn-repository prompt for a member). " +
+    "configuration and applies zero fields for any caller; a joining member's closing interaction " +
+    "is the welcome plus the concise capability report. " +
     "Complete the command's concise capability report: the single 'What Bridge " +
-    "can help with' section, rendered exactly as the server's concise_tool_capabilities field gives it " +
-    "(Regularly useful, then Occasionally useful, each tool's display_name only, plus each tier's " +
-    "server-computed '+N more' where non-zero). Do not render the obsolete five-section report, and do " +
-    "not locally filter, count, or fall back to the complete tool_capabilities catalog. " +
+    "can help with' section, rendered exactly as the server's concise_tool_capabilities field gives it. " +
+    "That field is exactly two availability sections in server order — 'Available now' first, then " +
+    "'Needs setup' — and each item in them carries display_name, description, how_to_use, and (in the " +
+    "'Needs setup' section only) availability_text. Render each item's display_name, its description, " +
+    "and its how_to_use verbatim when that value is a non-empty string; render availability_text " +
+    "verbatim as the setup guidance for a 'Needs setup' item, and show NO availability caveat, " +
+    "asterisk, or footnote on an 'Available now' item. An item's `kind` ('tool' or 'workflow') is " +
+    "contract metadata only — render both kinds identically, with no label, icon, or separate list, " +
+    "and never branch on it. Keep an empty section visible with a short neutral line rather than " +
+    "dropping it, and after both sections close with a pointer to the Bridge MCP server README at " +
+    "https://www.npmjs.com/package/@bridge_gpt/mcp-server for the complete tool documentation, " +
+    "including when either or both sections are empty. Do not render the obsolete five-section report, " +
+    "and do not locally filter, count, sort, regroup, infer availability, fabricate an item, or fall " +
+    "back to the complete tool_capabilities catalog or the workflows collection. If " +
+    "concise_tool_capabilities is missing or malformed, take the command's single fallback line and " +
+    "render nothing else in its place. " +
+    "In the install-spawn context Stage 6 must STILL call persist_routing_credential, but must NOT " +
+    "print or summarize its SUCCESSFUL result anywhere — no 'Stored routing credential for …' line, " +
+    "and no restatement of that target or path in any later summary or Return section — because the " +
+    "install-bridge CLI has already reported where the credential landed and a second sentence is a " +
+    "duplicate. This silence applies ONLY to success and ONLY in the install-spawn context: a Stage 6 " +
+    "FAILURE is still reported loudly and in full, and in JOIN MODE or a direct/manual /install-bridge " +
+    "invocation Stage 6 reports its success exactly as it does today. " +
     "The install-spawn skip set is exactly Stage 8, Stage 9, and Stage 10. The command-owned Stage 11 " +
     "(invite teammates) is NOT in that skip set: it is independently gated and may run only when the " +
     "caller's role is admin AND customer_type is b2b AND an interactive response is available; " +
@@ -186,11 +245,19 @@ export const INSTALL_BRIDGE_AGENT_PROMPT = "Execute the /install-bridge command
     "Do NOT ask any indexing question, call parse_repository, mention /parse-repository, or claim " +
     "indexing has started or is pending — indexing is decided entirely by the server-side readiness " +
     "funnel with no visibility from this session, so say nothing about it at all. " +
-    "After the capability report on the fresh-configuration path, recommend /learn-repository as the " +
-    "next step: explain briefly that it " +
-    "learns repository-specific architecture, review, testing, correctness, and validation-manual " +
-    "configuration by researching the actual codebase. Do NOT run /learn-repository yourself — only " +
-    "recommend it; running it is the human's next explicit invocation. " +
+    "Close with the server's own next step, which you must read at runtime rather than assume. Inspect " +
+    "the `next_step` object on the manifest response the flow already used: on the fresh-configuration " +
+    "path that is the Stage 7 post-apply read-after-write manifest, and in JOIN MODE it is the Stage 2 " +
+    "manifest (JOIN MODE performs no read-after-write). Look at `next_step.command`: when it is a " +
+    "NON-EMPTY string, recommend exactly that command, verbatim, in inline code — do not rename it or " +
+    "substitute a command you happen to know. When it is an empty string, make NO next-command " +
+    "recommendation at all and say nothing in its place: no heading, no placeholder, no 'nothing to " +
+    "do' line. The server decides eligibility (repository state AND whether this caller can run the " +
+    "command), so do NOT apply a role rule or a learned-state rule of your own. Do NOT run the " +
+    "returned command yourself — only recommend it; running it is the human's next explicit " +
+    "invocation. For supporting context around a recommended command, use the manifest's own " +
+    "next_step.post_install_indexing and next_step.post_install_scheduler text rather than inventing " +
+    "an explanation for it. " +
     "Never request, echo, or transport any credential — only ever direct the human to that " +
     "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 " +
@@ -227,16 +294,18 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
     const setupUrl = buildInstallBridgeSetupUrl(baseUrl);
     return [
         "Usage:",
-        "  npx -y @bridge_gpt/mcp-server@latest install-bridge [flags]",
+        "  npx -y @bridge_gpt/mcp-server install [flags]",
         "",
         "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 — on a TTY, only after a Y/N consent prompt — opens a",
         "fresh session in your selected tool. If the project is not yet configured it",
-        "derives the remaining config, presents a concise capability report, and",
-        "recommends /learn-repository. If the project is already configured it instead",
+        "derives the remaining config, presents a concise capability report, and shows",
+        "the next step the server returned — when it returns one.",
+        "If the project is already configured it instead",
         "joins you to it without proposing or applying any changes and just shows the",
-        "concise capability report (a b2b admin is additionally offered a teammate-invite",
+        "concise capability report plus that same conditional next step (a b2b admin is",
+        "additionally offered a teammate-invite",
         "step). So not every run applies config fields. Indexing is never asked about —",
         "it starts automatically once the repository reaches full parse readiness.",
         "",
@@ -247,16 +316,37 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "resolves your key from the credential store at runtime. A config file that",
         "cannot be parsed is left untouched, with manual-merge instructions printed.",
         "",
-        "Run it bare — `install-bridge` with no flags — in a terminal and it asks",
-        `\`${INSTALL_BRIDGE_KEY_SELECTOR_PROMPT}\` first, with three numbered choices:`,
+        "Run it bare — `install` with no flags — in a terminal and it asks",
+        `\`${INSTALL_BRIDGE_KEY_SELECTOR_PROMPT}\` first, with two numbered choices:`,
         ...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",
-        "ANY flag, setting BAPI_API_KEY, or running without an interactive terminal keeps",
-        "the existing deterministic behavior and no prompt.",
+        "There is NO default — pressing Enter selects nothing; you must type 1 or 2 (one",
+        "blank or invalid answer re-prompts once, then exits with guidance). Answering 1",
+        "opens a single hidden token prompt: paste whatever you were given and its SHAPE",
+        "picks the route — a bootstrap invite (bapi_inv_…) is redeemed to CREATE a new",
+        "project and mint your first admin key, while a Bridge API key connects to the",
+        "project that already exists. You are never asked which kind of token you hold.",
+        "Answering 2 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 ANY flag, setting BAPI_API_KEY, or running without an interactive",
+        "terminal keeps the existing deterministic behavior and no prompt.",
+        "",
+        "On that bare run the route is INFERRED, so it is only announced — the detected",
+        "credential type and where it leads are printed and the run proceeds. There is no",
+        "confirmation question and no way to decline, because you never declared a route",
+        "for the value to contradict.",
+        "",
+        "When you DO declare a route with a flag or env var, the confirmations stay, and",
+        "the two directions are deliberately asymmetric. Both are detected by SHAPE alone",
+        "— no probe request is sent — BEFORE any project-name prompt, credential write,",
+        "or network call:",
+        "  - a bootstrap invite (bapi_inv_…) passed 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 passed 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.",
+        "A value that is neither shape is left on the route you chose, and is not",
+        "announced.",
         "",
         "Inputs (the only two irreducible ones):",
         "  --api-key <key>   Bridge API key OR bootstrap invite. Falls back to the",
@@ -264,24 +354,31 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         `                    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). Passing the flag or setting the env var",
+        "                    DECLARES the key route, so that switch is confirmed on a",
+        "                    terminal; the bare run's hidden token prompt infers instead",
+        "                    and only announces. 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, answering 2",
+        "                    above, or a token that turns out to be an invite) it NAMES",
+        "                    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,13 +387,18 @@ 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 answering 2 on a",
         "                    bare run reaches. The email is NOT a",
         "                    secret (it is shown as you type), but it is never printed to",
         "                    a log. Mutually",
-        "                    exclusive with --api-key and --invite. No email verification",
-        "                    is performed and no message is sent to the address — it only",
-        "                    labels the new workspace.",
+        "                    exclusive with --api-key and --invite. The address labels the",
+        "                    new workspace AND is used for transactional invite/setup",
+        "                    delivery, so a setup message may be sent to it. Delivery is",
+        "                    asynchronous and best-effort: it is queued after signup rather",
+        "                    than awaited, so do not wait on the message to continue — this",
+        "                    command already prints everything you need. No email",
+        "                    verification is performed; the address is not confirmed before",
+        "                    the workspace is created.",
         "",
         "                    RESUMABLE: a self-serve run that fails mid-protocol saves its",
         "                    signup state under bootstrap-pending:<repo> in the credential",
@@ -312,7 +414,7 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "                    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",
+        "                    Run it WITHOUT a value — `install --invite` — and the",
         "                    token is read from an interactive prompt with echo",
         "                    suppressed, then sent only in the request body. This is the",
         "                    default and the recommended path: 'a copy/paste one-liner'",
@@ -369,6 +471,35 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "                                --agent cursor-agent still force-spawns it.",
         "  -h, --help                    Show this help.",
         "",
+        "Subcommands:",
+        "  install conductor             Bootstrap Epic Conductor v2 for this repository",
+        "                                (BAPI-679). Runs a unified READ-ONLY doctor that",
+        "                                composes the conductor, executor-preflight,",
+        "                                install-status, and executor service-unit",
+        "                                diagnostics with server-side",
+        "                                readiness (supervisor defaults, empty required-",
+        "                                check detection, GitHub App credentials and the",
+        "                                `actions` permission, reconciler tick liveness).",
+        "                                The resolved BAPI_BASE_URL is confirmed BEFORE",
+        "                                any network call — the doctor's readiness GET",
+        "                                carries the repo API key, and the URL silently",
+        "                                defaults to production when unset. A fatal",
+        "                                finding aborts BEFORE any write. A separate",
+        "                                consent immediately precedes the bootstrap POST,",
+        "                                which writes the safe project-default supervisor",
+        "                                posture in one transaction; it optionally",
+        "                                scaffolds a parameterized claude-review workflow",
+        "                                (its own separate consent), prints the capability",
+        "                                matrix, and re-runs the doctor. `--dry-run`",
+        "                                performs NO write of any kind and no write-consent",
+        "                                prompt (the base-URL confirmation still applies).",
+        "                                Executor service units are generated by",
+        "                                `executor install-service`; starting one stays",
+        "                                operator-managed, so a run reports",
+        "                                `complete-with-manual-steps` until a live",
+        "                                executor is actually observed. See",
+        "                                `install conductor --help`.",
+        "",
         "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_SIGNUP_EMAIL supplies the self-serve signup email non-interactively (it is",
@@ -503,7 +634,7 @@ export function parseInstallBridgeArgs(argv) {
         }
         return {
             status: "error",
-            message: `Unexpected positional argument: '${arg}'. install-bridge does not accept positional arguments.`,
+            message: `Unexpected positional argument: '${arg}'. install does not accept positional arguments.`,
         };
     }
     // Mutually exclusive by construction: bootstrap-invite mode CREATES the key, so
@@ -635,7 +766,7 @@ export const INSTALL_BRIDGE_CONNECT_GITHUB_COMMAND = "npx -y @bridge_gpt/mcp-ser
 export const INSTALL_BRIDGE_GITHUB_OFFER_CONTEXT = [
     "",
     "Step 4b — optional: connect GitHub.",
-    "  This installs the Bridge GitHub App so pull requests and code review work. It opens",
+    "  This installs the Bridge GitHub App so you can implement and review tickets with Bridge. It opens",
     "  github.com in your browser; no GitHub credential is shared with Bridge.",
     `  You can do this later instead: ${INSTALL_BRIDGE_CONNECT_GITHUB_COMMAND}`,
 ];
@@ -838,6 +969,55 @@ export function createDefaultInstallBridgeDeps() {
             if (process.env.BAPI_INSTALL_DEBUG)
                 console.error(m);
         },
+        // ---- Nested `install-bridge conductor` seams (BAPI-679) ----
+        conductorRunDoctor: (params) => runConductorInstallDoctor({
+            access: params.access,
+            accessError: params.accessError,
+            fetch: params.fetch,
+            reviewPolicySource: params.reviewPolicySource,
+            readWorkflowFile: () => params.readFile(claudeReviewWorkflowPath(params.cwd)),
+            installDoctorDeps: {
+                env: params.env,
+                cwd: params.cwd,
+                platform: process.platform,
+                homedir: os.homedir,
+                readFile: params.readFile,
+                stat: (p) => stat(p),
+                fetch: (...args) => fetch(...args),
+            },
+        }),
+        conductorResolveAccess: async (repoName, baseUrl, mergedDeps) => {
+            const result = await resolveConductorBridgeApiAccess({
+                env: { ...mergedDeps.env, BAPI_BASE_URL: baseUrl },
+                cwd: mergedDeps.cwd,
+                homedir: mergedDeps.homedir,
+                platform: mergedDeps.platform,
+                readFile: mergedDeps.readFile,
+                stat: (p) => mergedDeps.stat(p),
+                repoName,
+            });
+            // Never surface the resolver's secret-bearing internals — it already
+            // guarantees a secret-free `error`, which is forwarded verbatim.
+            return result.ok ? { ok: true, access: result.access } : { ok: false, error: result.error };
+        },
+        conductorWriteWorkflow: (cwd, content, options, mergedDeps) => writeClaudeReviewWorkflow(cwd, content, {
+            readFile: mergedDeps.readFile,
+            mkdir: (p, o) => mergedDeps.mkdir(p, o),
+            writeFile: (p, data) => mergedDeps.writeFile(p, data),
+        }, options),
+        conductorRecordArtifact: async (cwd, relPath, mergedDeps) => {
+            const result = await recordInstalledProjectArtifact(cwd, relPath, {
+                readFile: mergedDeps.readFile,
+                writeFile: (p, data) => mergedDeps.writeFile(p, data),
+                rename: mergedDeps.rename,
+                mkdir: (p, o) => mergedDeps.mkdir(p, o),
+                unlink: mergedDeps.unlink,
+            });
+            return result.ok ? { ok: true } : { ok: false, error: result.error };
+        },
+        conductorRunSetupEpicDryRun: async (argv) => ({
+            exitCode: await runSetupEpicCli(argv),
+        }),
     };
 }
 /**
@@ -865,7 +1045,11 @@ export async function resolveApiKey(options, deps) {
         return { ok: true, value: fromEnv.trim(), source: "env" };
     }
     if (deps.isTTY && deps.promptSecret) {
-        const entered = (await deps.promptSecret("Bridge API key or invite (input hidden): ")).trim();
+        // BAPI-708 (A-3): the prompt no longer asks the user to pre-classify their own
+        // credential ("Bridge API key or invite"). Classification is done from SHAPE
+        // downstream with no probe request, so the only thing worth asking for is the
+        // token itself.
+        const entered = (await deps.promptSecret("Paste your Bridge token (input hidden): ")).trim();
         if (entered.length > 0) {
             return { ok: true, value: entered, source: "prompt" };
         }
@@ -874,12 +1058,12 @@ export async function resolveApiKey(options, deps) {
         // and it named no route usable by someone who has no key at all.
         return {
             ok: false,
-            error: `No Bridge API key or invite entered. ${INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE}`,
+            error: `No Bridge token entered. ${INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE}`,
         };
     }
     return {
         ok: false,
-        error: "A Bridge API key or invite is required (no interactive terminal is available to prompt " +
+        error: "A Bridge token is required (no interactive terminal is available to prompt " +
             `for it). ${INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE}`,
     };
 }
@@ -919,7 +1103,7 @@ export async function resolveInviteToken(options, deps) {
         error: "A bootstrap invite token is required. Pass --invite <token> or set the BAPI_INVITE " +
             "environment variable (no interactive terminal is available to prompt for it). Note that " +
             "both forms expose the token to your shell history and process list — prefer running " +
-            "'install-bridge --invite' interactively.",
+            "'install --invite' interactively.",
     };
 }
 /**
@@ -986,27 +1170,38 @@ export function resolveInstallBridgeOnboardingBranch(options, env) {
     return { kind: "have-key" };
 }
 /**
- * The bare-TTY onboarding chooser (BAPI-667), replacing the BAPI-626/661 Y/n
- * question. The old prompt defaulted a bare Enter to "yes" and dropped the newest
- * users — the ones with no key, no invite, and no account — into a hidden API-key
- * prompt they could not answer, then exited. The self-serve path built for exactly
- * that user was never named. The chooser names all three routes and has NO default,
- * so Enter can no longer route anyone into a prompt they cannot satisfy.
+ * The bare-TTY onboarding question (BAPI-708, Part A), replacing the BAPI-667/687
+ * three-option chooser.
+ *
+ * The three-option form asked the user to make a distinction the CODE can already
+ * make for itself: whether the string in their clipboard is an invite or an API
+ * key. `classifyEnteredCredential` + `isHighEntropyApiKeyShape` decide that from
+ * SHAPE alone, with no probe request — so the only thing a first-time user
+ * genuinely knows, and the only thing worth asking, is whether they have a token
+ * at all. Hence a yes/no question, with the route inferred afterwards.
+ *
+ * Interaction contract is unchanged from BAPI-667/687 and remains load-bearing:
+ * render the heading and the numbered options exactly once, accept ONE strict
+ * line, no default (a bare Enter selects nothing), bounded to a single re-prompt
+ * after one hint, and EOF resolves as an empty answer so it can never hang.
+ */
+export const INSTALL_BRIDGE_KEY_SELECTOR_PROMPT = "Welcome to Bridge - do you have a token yet?";
+/**
+ * The question's numbered options, in render order. Index + 1 is the accepted
+ * token, exactly as before — only the option SET narrowed from three to two.
  *
- * Interaction contract mirrors the BAPI-663 tool picker: render the heading and the
- * numbered options once, accept ONE strict line.
+ * "Token" is deliberately credential-agnostic: an invite and an API key are both
+ * tokens as far as this question is concerned, and answering "Yes" leads to ONE
+ * hidden prompt whose value selects the route by shape.
  */
-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. */
 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. Yes, I have received a token",
+    "2. No, I need one",
 ];
 /** The single-line answer prompt drawn after the options (no bracketed default). */
-export const INSTALL_BRIDGE_ONBOARDING_CHOICE_PROMPT = "Enter 1, 2, or 3: ";
+export const INSTALL_BRIDGE_ONBOARDING_CHOICE_PROMPT = "Enter 1 or 2: ";
 /** The one hint line printed after a blank/invalid answer, before the single re-prompt. */
-export const INSTALL_BRIDGE_ONBOARDING_CHOICE_HINT = "Enter 1, 2, or 3.";
+export const INSTALL_BRIDGE_ONBOARDING_CHOICE_HINT = "Enter 1 or 2.";
 /**
  * The one place the "no usable credential" copy lives (BAPI-667, U1-3).
  *
@@ -1015,10 +1210,10 @@ export const INSTALL_BRIDGE_ONBOARDING_CHOICE_HINT = "Enter 1, 2, or 3.";
  * advised "try the hidden prompt again" — false, because the process has already
  * exited by the time the user reads it. All three now name the SAME three routes.
  */
-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 " +
-    "sign up with just an email.";
+export const INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE = "Re-run install: on a bare interactive run answer 1 if you already have a token " +
+    "(an invite or an API key — either one is accepted at the hidden prompt) or 2 to sign up " +
+    "with just an email. Non-interactively, pass --api-key <key> (or set BAPI_API_KEY) for an " +
+    "existing project, --invite if you were sent an invite token, or --email <addr> to sign up.";
 /**
  * Interactive wrapper around {@link resolveInstallBridgeOnboardingBranch}.
  *
@@ -1042,20 +1237,37 @@ 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-708 (Part A) narrowed those three options to a token yes/no question. The
+ * chooser was asking the user to pre-classify their own credential, which the
+ * shape checks downstream already do without a probe request. Every interaction
+ * property above survives verbatim — heading + options rendered once, one strict
+ * line, no default, one hint, one re-prompt, EOF-as-empty — and so does every
+ * bypass. Only the option SET and the dispatch changed.
+ *
+ * PROVENANCE. This function is the SOLE authority on `credentialIntent`, and that
+ * is deliberate: the route-switch arms downstream must not re-derive provenance
+ * from `argv`, because a second derivation is exactly the drift BAPI-708 exists to
+ * fix. `"inferred"` is returned ONLY when the question was actually answered — a
+ * state reachable on a bare interactive TTY run and nowhere else. Every other exit
+ * is `"declared"`, so 100% of non-interactive runs stay on declared paths and the
+ * documented directional asymmetry (invite-on-key auto-switches on a non-TTY;
+ * key-on-invite exits non-zero) is preserved BY CONSTRUCTION. Do not "unify" the
+ * two.
  */
 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 };
+        return { ok: true, branch, credentialIntent: "declared" };
     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 };
+        return { ok: true, branch, credentialIntent: "declared" };
     }
     const promptLine = deps.promptLine;
     try {
@@ -1070,15 +1282,20 @@ 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).
+            // BAPI-708 (A-1): the accepted tokens are now exactly 1/2 (no letters, no
+            // aliases), preserving the one-strict-line contract. "Yes" routes to the
+            // have-key branch's credential-agnostic prompt, whose value is classified by
+            // SHAPE — so a user holding an invite still lands in the redemption protocol
+            // without ever having been asked which kind of token they hold.
             if (answer === "1")
-                return { ok: true, branch: { kind: "have-key" } };
+                return { ok: true, branch: { kind: "have-key" }, credentialIntent: "inferred" };
             if (answer === "2") {
-                return { ok: true, branch: { kind: "need-key", method: "bootstrap-invite" } };
+                return {
+                    ok: true,
+                    branch: { kind: "need-key", method: "self-serve" },
+                    credentialIntent: "inferred",
+                };
             }
-            if (answer === "3")
-                return { ok: true, branch: { kind: "need-key", method: "self-serve" } };
             if (attempt === 0)
                 deps.log(INSTALL_BRIDGE_ONBOARDING_CHOICE_HINT);
         }
@@ -1112,23 +1329,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 +1361,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 +1386,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 };
     }
@@ -1417,13 +1644,21 @@ export function buildManualInstallBridgeContinuation(kind, toolLabels) {
     if (kind === "empty-selection") {
         return [
             "No AI coding tools were configured, so nothing was set up for this project.",
-            "Re-run install-bridge and select at least one tool to configure it.",
+            "Re-run install and select at least one tool to configure it.",
         ].join("\n");
     }
     const toolPhrase = formatToolLabelPhrase(toolLabels);
+    // BAPI-708 (B-c): the reload clause lives here so the requirement survives on
+    // every NO-SPAWN terminal path (declined consent, non-TTY suppression, no
+    // launchable tool, chooser failure, failed spawn). A written project MCP config
+    // is not a live connection until the host reloads and its trust prompt is
+    // approved — the single most common place a fresh install looks broken. The
+    // spawn path states the same requirement in its own handoff.
     return [
         `To finish configuring this project, open it in ${toolPhrase} that has the`,
         "Bridge MCP server configured, start a new session, and run /install-bridge.",
+        "Restart or reload the tool first if it is already running — the newly written",
+        "MCP server is not live until it reloads and you approve it if prompted.",
         "Until the project is configured, your Bridge MCP tools stay limited.",
     ].join("\n");
 }
@@ -1747,6 +1982,22 @@ async function requestTrackedConfigConsent(deps, relPath) {
     const normalized = (answer ?? "").trim().toLowerCase();
     return normalized === "y" || normalized === "yes";
 }
+/**
+ * Overlay a freshly built Bridge entry onto whatever is already registered,
+ * preserving the EXISTING launcher args composition (BAPI-714, Group C).
+ *
+ * Only the package-spec token is refreshed on an existing entry, so a legacy bare
+ * launcher stays bare and an already-`serve`-bearing launcher keeps `serve`
+ * exactly once. When there is no existing entry — or its args are a shape we
+ * cannot recognize — the new template args (which DO include `serve`) are used
+ * verbatim. `command` and `env` always come from the freshly built entry: this
+ * helper governs launcher-token migration only, never credentials.
+ */
+export function preserveExistingLauncherArgs(existing, entry) {
+    const existingArgs = asRecord(existing)?.args;
+    const preserved = refreshBridgeApiPackageSpec(existingArgs, currentBridgePackageSpec());
+    return preserved ? { ...entry, args: preserved } : entry;
+}
 /**
  * Write the `bridge-api` entry into each host config via read-merge-write,
  * preserving unrelated servers and top-level keys (BAPI-666). Per target:
@@ -1807,7 +2058,13 @@ async function writeHostConfigs(deps, targets, entries, trackedState, ctx) {
         // never initialized before its tracked-state consent is resolved.
         const config = read.state === "parsed" ? read.config : {};
         const topLevel = asRecord(config[target.topLevelKey]) ?? {};
-        topLevel["bridge-api"] = entry;
+        // BAPI-714 (Group C): a PRE-EXISTING Bridge entry keeps its own launcher args
+        // composition — only the package-spec token is refreshed — so the installer
+        // never migrates a legacy bare launcher to `serve`. A newly created entry gets
+        // the full template args, `serve` included. The rule is identical for the
+        // real-key and secret-free variants: credential safety must not decide whether
+        // a launcher is migrated.
+        topLevel["bridge-api"] = preserveExistingLauncherArgs(topLevel["bridge-api"], entry);
         config[target.topLevelKey] = topLevel;
         await deps.mkdir(path.dirname(fullPath), { recursive: true });
         await deps.writeFile(fullPath, JSON.stringify(config, null, 2) + "\n", {
@@ -1986,6 +2243,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 +2440,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 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 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`;
@@ -2253,7 +2639,7 @@ export const BOOTSTRAP_INVITE_LOST_SECRET_MESSAGE = [
     "",
     "Ask your Bridge API operator to recover it for you: they revoke the orphaned key",
     "(DELETE /setup/keys/{id}) and issue a replacement key for the EXISTING project",
-    "(POST /setup/keys), then send you that key. Run install-bridge with --api-key <that key>.",
+    "(POST /setup/keys), then send you that key. Run install with --api-key <that key>.",
 ].join("\n");
 /**
  * The 401 message for a run that REUSED an existing pending secret — the replay
@@ -2282,8 +2668,8 @@ export const BOOTSTRAP_SELF_SERVE_EXPIRED_MESSAGE = "The Bridge API rejected the
  */
 export function buildBootstrapRetryAdvice(selfServeSignupMode) {
     return selfServeSignupMode
-        ? "Re-run install-bridge and choose the email option — your previous attempt will resume."
-        : "Re-run install-bridge with the same bootstrap invite — the redemption will replay and " +
+        ? "Re-run install and choose the email option — your previous attempt will resume."
+        : "Re-run install with the same bootstrap invite — the redemption will replay and " +
             "return the same key.";
 }
 /**
@@ -2332,6 +2718,69 @@ export async function resolveCredentialConflictConsent(prepared, ctx) {
     ctx.grantConsent();
     return ctx.retry();
 }
+/**
+ * The secret-free install-state file. Gitignored before it is written, so it is
+ * named here once and fed to BOTH the gitignore call and the commit-notice
+ * exclusion set — a single definition site keeps the two from drifting apart.
+ */
+export const INSTALL_BRIDGE_INSTALL_STATE_PATH = ".bridge/install-state.json";
+/** Heading printed above the commit-your-assets list. Shared with the tests. */
+export const INSTALL_BRIDGE_COMMIT_ASSETS_HEADING = "Commit these generated files so your team inherits the same Bridge setup:";
+/**
+ * Format the commit-your-assets notice (BAPI-708, Part C).
+ *
+ * THIS IS A CORRECTNESS BOUNDARY, NOT COPY. Several files this install writes are
+ * deliberately gitignored because they can carry a real `BAPI_API_KEY` — the
+ * per-host MCP configs above all — and `.bridge/install-state.json` is gitignored
+ * too. A generic "commit your Bridge assets" is exactly how a live key reaches a
+ * public remote. So the notice is built by SUBTRACTION as well as selection: every
+ * path this run handed to `ensureGitignoredShared` is removed from the candidate
+ * list, which means the safe set cannot silently acquire a gitignored target if
+ * the host-target registry grows a new entry later.
+ *
+ * SECRET DISCIPLINE: parameters are project-relative scaffold paths only. The
+ * credential-store path is never passed in — it lives outside the repository and
+ * holds the key, so it is excluded by never being a candidate at all, not by
+ * filtering.
+ *
+ * Returns `""` when nothing survives, so a caller can skip an empty notice.
+ */
+export function buildCommitGeneratedAssetsNotice(safePaths, gitignoredPaths) {
+    // POSIX-normalized, trailing slash preserved (it marks a directory), so
+    // "./a/b" and "a//b" compare equal to "a/b" on both sides of the exclusion.
+    const normalize = (value) => {
+        const trailingSlash = /\/+$/.test(value.trim());
+        const collapsed = value.trim().replace(/\\/g, "/").replace(/\/+/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+        return trailingSlash ? `${collapsed}/` : collapsed;
+    };
+    const excluded = new Set();
+    for (const raw of gitignoredPaths) {
+        const normalized = normalize(raw);
+        if (normalized.length === 0)
+            continue;
+        // Match a gitignored file whether the candidate names it with or without a
+        // trailing slash, so a registry entry can never slip through on formatting.
+        excluded.add(normalized);
+        excluded.add(normalized.replace(/\/+$/, ""));
+        excluded.add(`${normalized.replace(/\/+$/, "")}/`);
+    }
+    const seen = new Set();
+    const lines = [];
+    for (const raw of safePaths) {
+        const normalized = normalize(raw);
+        if (normalized.length === 0)
+            continue;
+        if (excluded.has(normalized))
+            continue;
+        if (seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        lines.push(`  ${normalized}`);
+    }
+    if (lines.length === 0)
+        return "";
+    return [INSTALL_BRIDGE_COMMIT_ASSETS_HEADING, ...lines].join("\n");
+}
 /**
  * Render the --dry-run preview lines. Every secret is ALWAYS redacted — the
  * spawnCommand, config preview, and (in bootstrap-invite mode) the exchange body
@@ -2344,10 +2793,15 @@ export function buildDryRunPreview(plan) {
     if (plan.bootstrapInvite)
         return buildBootstrapDryRunPreview(plan);
     return [
-        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)" : ""}`,
+        // 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 --dry-run (one read-only repository-resolution GET may already have occurred; no writes, no state-changing requests, no spawns)"
+            : "install --dry-run (no writes, no network, no spawns)",
+        `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)}`,
@@ -2364,9 +2818,25 @@ 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}`,
+        ...buildCommitAssetsPreviewLines(plan),
         ...buildLaunchStepPreview(plan),
     ];
 }
+/**
+ * The commit-assets notice as preview lines (BAPI-708, Part C). A `--dry-run`
+ * returns before the live emission point, and this module's convention is that a
+ * preview never advertises different behavior — so the same notice, built from the
+ * same resolved manifest, appears here too. The gitignored exclusion set is the
+ * plan's own `configTargets` plus the install-state file, exactly as the live path
+ * computes it.
+ */
+function buildCommitAssetsPreviewLines(plan) {
+    const notice = buildCommitGeneratedAssetsNotice(plan.commitSafeAssets ?? [], [
+        ...plan.configTargets,
+        INSTALL_BRIDGE_INSTALL_STATE_PATH,
+    ]);
+    return notice.length > 0 ? ["", notice] : [];
+}
 /**
  * One-line description of the planned launch agent for the dry-run header (BAPI-657).
  * Never claims an unconditional Claude spawn: it reflects the discriminated launch
@@ -2407,8 +2877,10 @@ function buildLaunchStepPreview(plan) {
         "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 '${INSTALL_BRIDGE_GITHUB_CONNECT_PROMPT.replace(/:\s*$/, "")}' before the agent session starts.`,
-        "          It installs the Bridge GitHub App so pull requests and code review work, opens",
-        "          github.com in your browser, and shares no GitHub credential with Bridge; it",
+        // BAPI-708: the purpose sentence is kept on ONE line in both copies so the
+        // no-drift test can compare the whole phrase rather than a wrapped fragment.
+        "          It installs the Bridge GitHub App so you can implement and review tickets with Bridge.",
+        "          It opens github.com in your browser, and shares no GitHub credential with Bridge; it",
         `          defaults to No and can be run later instead: ${INSTALL_BRIDGE_CONNECT_GITHUB_COMMAND}`,
     ];
     if (plan.launch.kind === "spawn") {
@@ -2452,8 +2924,8 @@ function buildBootstrapDryRunPreview(plan) {
     // 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)";
+        ? "install --email --dry-run (no writes, no network, no spawns, no account created, no secret generated)"
+        : "install --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)`;
@@ -2493,6 +2965,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)`,
+        ...buildCommitAssetsPreviewLines(plan),
         ...buildLaunchStepPreview(plan),
     ];
 }
@@ -2542,6 +3015,28 @@ export function manualEditorNames(editors) {
 export function formatNeedKeyCredentialStoreLine(repoName, credentialStorePath) {
     return `Your API key is stored at ${credentialStorePath} under "bapi:${repoName}" — copy BAPI_API_KEY from there.`;
 }
+/**
+ * Where THIS run's routing credential landed (BAPI-708, B-b) — the single Step 4
+ * result line, printed on the have-key and need-key arms alike.
+ *
+ * It replaces both `stored routing credential for … at …` lines, and it is also
+ * what makes Part B-a honest: `.mcp.json` is an MCP SERVER REGISTRATION, not a
+ * credentials file, so the one place a credential is reported must name the
+ * credential store instead.
+ *
+ * Distinct from {@link formatNeedKeyCredentialStoreLine}, which stays for the
+ * MANUAL-EDITOR context — its "copy BAPI_API_KEY from there" instruction only
+ * makes sense when the user has a global config to paste into.
+ *
+ * SECRET DISCIPLINE (hard constraint, same as its sibling): this formatter accepts
+ * NO key material. Its parameters are a repo name and a filesystem path, both
+ * printable; it must never be handed `apiKey`, `inviteToken`, `keySecret`, a signup
+ * email, or a credential record. The arity is pinned by test precisely so a third
+ * parameter cannot be added without that test failing.
+ */
+export function formatProjectCredentialStoreLine(repoName, credentialStorePath) {
+    return `We wrote your project credentials to: ${credentialStorePath} (target "bapi:${repoName}")`;
+}
 /**
  * Build the manual-instruction block for the DETECTED global-config editors only
  * (key always redacted). Returns `null` when neither Windsurf nor Codex is
@@ -2686,7 +3181,7 @@ function readInstallBridgeDebugValue(read) {
  */
 export function buildInstallBridgeFailureLines(error, context) {
     const lines = [
-        `Error: install-bridge failed at: ${context.step}`,
+        `Error: install failed at: ${context.step}`,
         `  cause: ${classifyInstallBridgeFailure(error)}`,
         `  ${INSTALL_BRIDGE_DOCTOR_POINTER}`,
     ];
@@ -2753,6 +3248,14 @@ export function resolveInstallBridgeBaseUrl(env) {
  * Every printed Step 1–5 label, defined once. `runInstallBridgeCli` uses each
  * constant BOTH when logging the step AND when recording the current step, so a
  * failure can never be attributed to a label the user did not just see.
+ *
+ * BAPI-708 (Part D) removed the separate `promoteCredential` entry: promotion is
+ * not a step the user does anything about, and printing it as its own numbered
+ * step told them the bootstrap two-phase commit exists without giving them a way
+ * to act on it. Both credential arms now log `persistCredential`. Attribution is
+ * NOT lost — the promotion-failure fatal is highly specific about what failed and
+ * what state the user is left in. The step COUNT is unchanged at 5; nothing is
+ * renumbered.
  */
 export const INSTALL_BRIDGE_STEP_LABELS = {
     scaffold: "Step 1/5 — scaffolding project (commands, agents, pipelines, config placeholders)…",
@@ -2760,7 +3263,6 @@ export const INSTALL_BRIDGE_STEP_LABELS = {
     inviteRedeem: "Step 2/5 — redeeming the bootstrap invite…",
     verifyConnectivity: "Step 2/5 — verifying connectivity…",
     writeHostConfigs: "Step 3/5 — writing per-host MCP config…",
-    promoteCredential: "Step 4/5 — promoting the bootstrap credential…",
     persistCredential: "Step 4/5 — persisting routing credential…",
 };
 /**
@@ -2792,7 +3294,7 @@ export const INSTALL_BRIDGE_NO_GIT_WARNING = "This doesn't look like a project r
 /** Default-No confirmation shown only on a TTY when `.git` is absent. */
 export const INSTALL_BRIDGE_NO_GIT_PROMPT = `${INSTALL_BRIDGE_NO_GIT_WARNING} — continue? [y/N]: `;
 /** Printed on decline. Paired with exit code 0 — a cancel is not an error. */
-export const INSTALL_BRIDGE_NO_GIT_ABORT = "Aborted — run install-bridge from your project root, or re-run and confirm to continue.";
+export const INSTALL_BRIDGE_NO_GIT_ABORT = "Aborted — run install from your project root, or re-run and confirm to continue.";
 /** The non-TTY form: same finding, stated as a warning, then the run continues. */
 export const INSTALL_BRIDGE_NO_GIT_NONINTERACTIVE_WARNING = `Warning: ${INSTALL_BRIDGE_NO_GIT_WARNING} — continuing (non-interactive).`;
 /**
@@ -2858,6 +3360,63 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // A rejected value cannot be interpolated into guidance, so usage falls back to
     // the documented default — the run is about to fail on it anyway.
     const usageBaseUrl = baseUrlResult.ok ? baseUrlResult.value : DEFAULT_BAPI_BASE_URL;
+    // ---- BAPI-679: nested `install-bridge conductor` -----------------------
+    // Intercepted HERE, before `parseInstallBridgeArgs`, because that parser
+    // rejects ALL positional arguments — a bare `conductor` token would otherwise
+    // be an argument error. Deliberately after the deps merge and the base-URL
+    // resolution above, so the nested command inherits the same final merged deps
+    // (including a test's `fetch` override) and the same normalized base URL.
+    // Note this is `install-bridge conductor`; the bare top-level `conductor`
+    // subcommand still routes to `runConductorCli` (the local event ledger) and is
+    // untouched.
+    if (argv[0] === "conductor") {
+        if (!baseUrlResult.ok) {
+            errorLog(baseUrlResult.error);
+            return 1;
+        }
+        const conductorBaseUrl = baseUrlResult.value;
+        const conductorDeps = {
+            env: deps.env,
+            cwd: deps.cwd,
+            log: deps.log,
+            errorLog: deps.errorLog,
+            promptLine: deps.promptLine,
+            resolveBaseUrl: () => ({ ok: true, value: conductorBaseUrl }),
+            resolveAccess: (repoName, resolvedBaseUrl) => (deps.conductorResolveAccess ??
+                (async () => ({ ok: false, error: "conductor access seam unavailable" })))(repoName, resolvedBaseUrl, deps),
+            fetchJson: deps.fetch,
+            postJson: deps.fetch,
+            runDoctor: (params) => (deps.conductorRunDoctor ??
+                (async () => ({
+                    legacyConductor: null,
+                    legacyExecutorPreflight: null,
+                    legacyInstallChecks: null,
+                    executorService: null,
+                    readiness: null,
+                    sections: [
+                        {
+                            id: "conductor-doctor",
+                            label: "Conductor install doctor",
+                            status: "fatal",
+                            detail: "the unified doctor seam is unavailable",
+                        },
+                    ],
+                })))({
+                ...params,
+                fetch: deps.fetch,
+                cwd: deps.cwd,
+                env: deps.env,
+                readFile: deps.readFile,
+            }),
+            writeWorkflow: (cwd, content, options) => (deps.conductorWriteWorkflow ??
+                (async () => ({ ok: false, error: "workflow seam unavailable" })))(cwd, content, options, deps),
+            recordArtifact: (cwd, relPath) => (deps.conductorRecordArtifact ??
+                (async () => ({ ok: false, error: "install-state seam unavailable" })))(cwd, relPath, deps),
+            runSetupEpicDryRun: (setupArgv) => (deps.conductorRunSetupEpicDryRun ??
+                (async () => ({ exitCode: 1 })))(setupArgv),
+        };
+        return runInstallBridgeConductorCli(argv.slice(1), conductorDeps);
+    }
     const parsed = parseInstallBridgeArgs(argv);
     if (parsed.status === "help") {
         log(getInstallBridgeUsage(usageBaseUrl));
@@ -2927,12 +3486,24 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         return 1;
     }
     const branch = branchResult.branch;
+    // BAPI-708 (A-5): provenance comes from the branch resolver and NOWHERE else. It
+    // is deliberately NOT re-derived from `argv`/`env` here — the resolver owns that
+    // logic, and a second derivation is exactly the drift this ticket removes.
+    const credentialIntent = branchResult.credentialIntent;
     // Mutable (BAPI-661): an ordinary have-key credential that classifies as a
     // bootstrap invite (see the have-key arm below) flips `bootstrapInviteMode` to
     // true AFTER branch selection, before repository-name resolution — everything
     // 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 +3536,47 @@ 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);
+            // BAPI-708 (A-4): DO NOT UNIFY THESE TWO BRANCHES. On an INFERRED route the
+            // announcement above is purely informational — the user never declared the
+            // invite path, so there is no stated intent for the value to contradict and a
+            // confirmation would ask them to ratify a decision they never made. On a
+            // DECLARED route the confirmation is byte-for-byte BAPI-687 behavior,
+            // including the intentional non-TTY asymmetry: an API-key-shaped value on the
+            // declared invite path exits non-zero rather than silently redirecting a
+            // script away from the project-creating run it asked for.
+            if (credentialIntent === "declared") {
+                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 +3590,28 @@ 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.
+            log(INSTALL_BRIDGE_INVITE_ON_KEY_PATH_NOTICE);
+            // BAPI-708 (A-4): DO NOT UNIFY THESE TWO BRANCHES — see the matching comment
+            // on the invite-path arm above. INFERRED means the user answered "yes, I have
+            // a token" and pasted it; they never claimed it was an API key, so the notice
+            // is an announcement and the run simply proceeds. DECLARED keeps BAPI-687
+            // verbatim, asymmetry included: a TTY gets the default-No confirmation, while
+            // a non-TTY still auto-switches (a script that worked yesterday must not gain
+            // a prompt) and prints the notice so the transcript explains itself.
+            if (credentialIntent === "declared") {
+                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;
@@ -2987,6 +3621,16 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             apiKeySource = undefined;
         }
         else {
+            // BAPI-708 (A-4): on the INFERRED path the route decision is announced even
+            // when nothing switches, so a bare run always says which credential type it
+            // detected and where that leads. Reuses the existing notice because it names
+            // only the credential TYPE and the destination ROUTE — never the value.
+            // Guarded on the POSITIVE shape test: a value matching neither shape is not
+            // reclassified AND not announced; it stays on this route and fails here
+            // exactly as it does today. Declared paths announce nothing new.
+            if (credentialIntent === "inferred" && isHighEntropyApiKeyShape(keyResult.value.trim())) {
+                log(INSTALL_BRIDGE_KEY_ON_INVITE_PATH_NOTICE);
+            }
             apiKey = keyResult.value;
             apiKeySource = keyResult.source;
         }
@@ -2997,13 +3641,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 +3682,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}`);
@@ -3090,12 +3750,24 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     else {
         planLaunch = { kind: "manual", reason: launchDecision.reason };
     }
+    // BAPI-708 (Part C): resolved from THIS invocation's cwd + env, so the notice
+    // names only what this run actually scaffolds — `.cursor/commands/` only when
+    // Cursor was detected, `.github/agents/` only when VS Code was, and the pipelines
+    // / instructions entries under whatever `BAPI_PIPELINES_DIR` resolved to. It is
+    // deliberately independent of which MCP HOSTS were selected: a scaffolded command
+    // directory is committed whether or not its editor got an MCP registration.
+    const scaffoldAssets = await resolveInitScaffoldAssets({
+        cwd: deps.cwd,
+        env: deps.env,
+        stat: deps.stat,
+    });
     const plan = {
         repoName,
         baseUrl,
         docsDir,
         launch: planLaunch,
         configTargets: targets.map((t) => t.relPath),
+        commitSafeAssets: scaffoldAssets.commitSafePaths,
         manualEditors: manualEditorNames(manualEditors),
         credentialTarget: `bapi:${repoName}`,
         credentialStorePath,
@@ -3105,7 +3777,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,
@@ -3330,7 +4004,11 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 }
                 keySecret = prep.keySecret;
                 reusedPendingSecret = prep.reused;
-                log(`  saved the pending credential for ${prep.target} (fsynced before the exchange)`);
+                // BAPI-708 (Part D): the pending write is NOT narrated on the happy path.
+                // The target name and the fsync ordering are implementation detail the user
+                // cannot act on; they remain fully described in --dry-run and in the failure
+                // messages, which name the pending record and what it means for a retry. The
+                // MECHANISM above is untouched — see the LOAD-BEARING ORDERING block below.
                 return true;
             };
             // ---- Self-serve signup (BAPI-618): mint the invite token from the email ----
@@ -3415,7 +4093,8 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 }
                 keySecret = prepared.keySecret;
                 reusedPendingSecret = prepared.reused;
-                log(`  saved the pending credential for ${prepared.target} (fsynced before the exchange)`);
+                // BAPI-708 (Part D): happy-path narration removed; the mechanism above is
+                // unchanged. See the matching comment on the self-serve arm.
             }
             // The exchange REPLACES the pre-flight ping: in invite mode there is no key to
             // ping with — this call is what mints it.
@@ -3472,7 +4151,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                     !selfServeRefreshed) {
                     if (!deps.isTTY || !deps.promptLine) {
                         return fatal(BOOTSTRAP_SELF_SERVE_EXPIRED_MESSAGE, `The saved attempt at ${getBootstrapPendingTarget(repoName)} in ${credentialStorePath} ` +
-                            "has been left untouched. Re-run install-bridge on an interactive terminal to " +
+                            "has been left untouched. Re-run install on an interactive terminal to " +
                             "discard it and start a fresh signup.");
                     }
                     errorLog(BOOTSTRAP_SELF_SERVE_EXPIRED_MESSAGE);
@@ -3605,8 +4284,14 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             trackedState.set(target.relPath, await isTrackedProjectConfig(deps, target.relPath));
         }
         const writeResult = await writeHostConfigs(deps, targets, { real: entry, secretFree: secretFreeEntry }, trackedState, { repoName, credentialStorePath });
+        // BAPI-708 (B-a): these files are the MCP SERVER REGISTRATION (BAPI_REPO_NAME,
+        // BAPI_BASE_URL, BAPI_DOCS_DIR, BAPI_PROJECT_ROOT, and the version-pinned npx
+        // launcher) — calling them a credentials file was simply inaccurate. Where the
+        // credential actually landed is reported once, at Step 4.
         for (const { relPath, mode } of writeResult.written) {
-            log(mode === "secret-free" ? `  wrote ${relPath} (secret-free — key resolved at runtime)` : `  wrote ${relPath}`);
+            log(mode === "secret-free"
+                ? `  registered the Bridge MCP server in ${relPath} (secret-free — key resolved at runtime)`
+                : `  registered the Bridge MCP server in ${relPath}`);
         }
         for (const { relPath } of writeResult.skipped) {
             log(`  skipped ${relPath} — existing config could not be parsed safely; left untouched`);
@@ -3642,16 +4327,16 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             log("  Note: Claude Code uses the project .mcp.json while GitHub Copilot CLI uses only its " +
                 "global ~/.copilot/mcp-config.json — the two are configured separately.");
         }
-        // BAPI-635 (Step 7): Claude trust reminder — a written project MCP config is
-        // not a live connection until approved in Claude Code's trust dialog.
-        if (selectedPlatforms.includes("claude-code")) {
-            log("  Claude Code: the project MCP server is pending approval in Claude Code's trust dialog; " +
-                "restart or reload an already-running session for it to take effect.");
-        }
+        // BAPI-708 (B-c): the Claude trust reminder that used to print here was
+        // RELOCATED, not dropped — the reload requirement is genuinely actionable (the
+        // server does not work until the host reloads), but at Step 3 it duplicated the
+        // spawn handoff. It now survives on EVERY terminal path: the spawn handoff
+        // already carries it, and `buildManualInstallBridgeContinuation("configured")`
+        // carries it for the declined, non-TTY, and failed-spawn paths.
         // BAPI-635 (Step 8 + Step 3): persist the secret-free install state, ignoring
         // it before the write. Project-local paths only; global paths are never in it.
         try {
-            await ensureGitignoredShared(deps.cwd, ".bridge/install-state.json", gitignoreDeps);
+            await ensureGitignoredShared(deps.cwd, INSTALL_BRIDGE_INSTALL_STATE_PATH, gitignoreDeps);
             // writeMcpInstallState catches its own I/O errors and returns { ok: false }
             // (it does NOT throw), so the failure warning must inspect the return value —
             // a try/catch alone would silently swallow a real persistence failure.
@@ -3684,7 +4369,11 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             // resolve. Promotion removes the pending record and writes the credential in one
             // durable replacement; on failure the pending record survives so a re-run replays
             // the same redemption. The agent session is NOT spawned until this succeeds.
-            currentStep = INSTALL_BRIDGE_STEP_LABELS.promoteCredential;
+            // BAPI-708 (Part D): the SHARED Step 4 label — identical on both arms, so a
+            // successful run prints exactly one Step 4 line and never narrates promotion
+            // as a step of its own. Still assigned before the log, preserving the
+            // log == record invariant the failure attribution depends on.
+            currentStep = INSTALL_BRIDGE_STEP_LABELS.persistCredential;
             log(currentStep);
             const promoted = await deps.promoteBootstrapPending({ repoName, inviteFingerprint, allowOverwriteExistingCredential: overwriteConsent }, credentialWriteDeps);
             if (!promoted.ok) {
@@ -3694,7 +4383,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                     `(${promoted.kind}). ${promoted.error} Your key is still saved locally as a pending ` +
                     `record. ${buildBootstrapRetryAdvice(selfServeSignupMode)}`);
             }
-            log(`  stored routing credential for ${promoted.target} at ${promoted.path}`);
+            log(formatProjectCredentialStoreLine(repoName, promoted.path));
         }
         else {
             // ---- persist routing credential (non-blocking / fail-open) ----
@@ -3703,13 +4392,13 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             try {
                 const result = await deps.upsertCredential(repoName, apiKey, credentialWriteDeps);
                 if (result.ok) {
-                    log(`  stored routing credential for ${result.target} at ${result.path}`);
+                    log(formatProjectCredentialStoreLine(repoName, result.path));
                 }
                 else {
                     log(`  warning: could not persist the routing credential (${result.kind}). ` +
                         `start-tickets model routing may not resolve the key for bapi:${repoName} ` +
                         "and will fail open to the premium/Opus tier (the most expensive) — " +
-                        "set BAPI_API_KEY in the shell or re-run install-bridge, then verify with " +
+                        "set BAPI_API_KEY in the shell or re-run install, then verify with " +
                         "'npx -y @bridge_gpt/mcp-server doctor'.");
                 }
             }
@@ -3722,6 +4411,21 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                     "'npx -y @bridge_gpt/mcp-server doctor'.");
             }
         }
+        // ---- commit-your-assets notice (BAPI-708, Part C) ----
+        // Emitted AFTER the credential step and BEFORE the GitHub offer and the Step 5
+        // consent/spawn block, so every terminal path — spawn, decline, non-TTY, and
+        // spawn-failure alike — receives it exactly once. The exclusion set is computed
+        // from what this run actually gitignored (the selected project host targets and
+        // the install-state file), not a hand-copied literal, so a future host-registry
+        // entry is excluded automatically. `credentialStorePath` is never a candidate.
+        const commitAssetsNotice = buildCommitGeneratedAssetsNotice(scaffoldAssets.commitSafePaths, [
+            ...targets.map((t) => t.relPath),
+            INSTALL_BRIDGE_INSTALL_STATE_PATH,
+        ]);
+        if (commitAssetsNotice.length > 0) {
+            log("");
+            log(commitAssetsNotice);
+        }
         // ---- 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
@@ -3737,8 +4441,11 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         if (prewarmPromise) {
             const prewarm = await prewarmPromise;
             if (prewarm.ok) {
-                log("  launcher bucket warmed (the first MCP launch will not pay a cold install).");
-                log(`  ${MCP_TIMEOUT_GUIDANCE}`);
+                // BAPI-708 (Part B): a SUCCESSFUL pre-warm is silent. Both lines described
+                // an internal optimization that worked and a remedy for a problem that did
+                // not occur. The failure branch below — where the remedy is real — keeps
+                // the MCP_TIMEOUT guidance verbatim, and both dry-run previews still carry
+                // it, so it stays discoverable exactly where it is actionable.
             }
             else {
                 // Escalate to a stronger, still secret-free warning when pre-warm didn't
@@ -3780,8 +4487,9 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 // raw agent binary name — computed once so all three sentences agree.
                 const handoffToolLabel = toolLabelForLaunchAgent(finalAgentName);
                 log("");
-                log(`install-bridge setup steps complete. A fresh ${handoffToolLabel} session is now applying ` +
-                    "configuration, presenting the concise capability report, and recommending /learn-repository.");
+                log(`install setup steps complete. A fresh ${handoffToolLabel} session is now applying ` +
+                    "configuration, presenting the concise capability report, and showing any next step the " +
+                    "server provides.");
                 // The trust dialog is the single most common place a spawned session stalls:
                 // the tab opens, nothing is approved, and the install looks hung.
                 log(`In the new tab: approve the workspace and the 'bridge-api' MCP server if ${handoffToolLabel} ` +