@bridge_gpt/mcp-server 0.2.67 → 0.2.69

package/build/install-bridge.js

@@ -1,3 +1,6 @@
+import { validateBootstrapDisplayName, validateBootstrapServerIdentity } from "./bootstrap-project-identity.js";
+import { lookupModernBootstrapRecord, mutateModernBootstrapRecord, prepareModernBootstrapInvite, prepareModernBootstrapSignup, transitionModernBootstrapSignup, lookupLegacyBootstrapInvite, checkpointModernBootstrapIdentity, promoteModernBootstrapCredential } from "./credential-store.js";
+import { collectFirstBuildAdvisory, formatFirstBuildAdvisory } from "./first-build-advisory.js";
 /**
  * install-bridge — the one-command Bridge API project bootstrap (BAPI-429).
  *
@@ -64,9 +67,9 @@
  * (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 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,
+ * question (BAPI-626/708/1448): `Email (or press Enter if you already have a
+ * token): `. A valid email is the self-serve route, which a first-time user could
+ * not otherwise discover. A blank answer 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
@@ -137,7 +140,7 @@
  * 0600, fsync'd pending record as the `key_secret`, purely so the signup can be
  * replayed, and it is discarded when that record is promoted.
  */
-import { readFile, writeFile, mkdir, stat, rename, chmod, unlink, open } from "fs/promises";
+import { readFile, writeFile, mkdir, stat, rename, chmod, unlink, open, realpath } from "fs/promises";
 import { spawn } from "child_process";
 import { randomBytes as cryptoRandomBytes, createHash } from "crypto";
 import os from "os";
@@ -152,7 +155,7 @@ import { MCP_HOST_TARGETS, HOST_PLATFORM_ORDER, allHostTargets, agentForPlatform
 import { provisionHostTarget, createDefaultVendorProcessDeps, inspectBridgeApiProfileToken, } from "./mcp-host-config.js";
 import { adaptBridgeEntryForHostTarget, } from "./mcp-host-entry-adapter.js";
 import { MCP_SERVER_NAME, MCP_PACKAGE_NAME, resolveRegistrationKey, } from "./mcp-identity.js";
-import { DUPLICATE_REGISTRATION_GUIDANCE } from "./launcher-config-inspection.js";
+import { DUPLICATE_REGISTRATION_GUIDANCE, discoverClaudeCodeEffectivePin } from "./launcher-config-inspection.js";
 import { codexHome, configureBridgeCodexProfile, inspectBridgeCodexProfile } from "./codex-bridge-profile.js";
 import { recordInstalledConductorCapability, recordInstalledExecutorServiceUnit, recordInstalledProjectArtifact, writeMcpInstallState, } from "./mcp-install-state.js";
 // BAPI-1207: opt-in cross-platform agent notes (AGENTS.md / CLAUDE.md).
@@ -168,9 +171,13 @@ import { executorLaunchdLabelForId, executorSystemdUnitNameForId, executorLaunch
 import { collectConductorNativeLedgerSafe, } from "./conductor/doctor.js";
 import { installConductorGitHooks, } from "./conductor/git-hooks.js";
 import { runInstallBridgeConductorCli, } from "./install-bridge-conductor.js";
+import { createQualificationExecutorRunner, } from "./install-bridge-conductor-gate.js";
+import { createNodeGateDiscoveryFs } from "./conductor/gate-discovery.js";
+import { runExecutorCli } from "./executor/cli.js";
+import { runExecutor } from "./executor/runner.js";
 // BAPI-1136: the merge-workflow generate-and-PR installer. Domain logic lives in
 // its own module; this file supplies the parser and the process seams.
-import { runMergeWorkflowInstall, } from "./merge-workflow-install.js";
+import { parseGithubRemote, runMergeWorkflowInstall, } from "./merge-workflow-install.js";
 import { MERGE_WORKFLOW_CODEOWNER_INSTRUCTION, MERGE_WORKFLOW_REMEDY_COMMAND, } from "./conductor/merge-execution-contract.js";
 import { MERGE_WORKFLOW_API_KEY_SECRET_NAME, } from "./merge-workflow-config.js";
 import { runConductorInstallDoctor, EPIC_IMPLEMENTER_PROFILE_TOKEN, } from "./conductor/install-doctor.js";
@@ -180,15 +187,17 @@ import { claudeReviewWorkflowPath, writeClaudeReviewWorkflow, } from "./claude-r
 // doctor's optional drift seam below.
 import { probeClaudeReviewWorkflowDrift, resolveCurrentBranch, resolveRepositoryDefaultBranch, } from "./claude-review-workflow-drift-probe.js";
 import { runSetupEpicCli } from "./setup-epic.js";
+import { runBridgePermissionsInstallStep, runBridgePermissionsRemoval, } from "./bridge-permissions.js";
 import { ensureGitignored as ensureGitignoredShared, } from "./git-ignore-utils.js";
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
 import { upsertBapiCredential, getPrimaryCredentialStorePath, prepareBootstrapPendingCredential, repointBootstrapPendingCredential, promoteBootstrapPendingCredential, lookupSelfServeBootstrapPendingCredential, prepareSelfServeBootstrapChallenge as prepareSelfServeBootstrapChallengeCredential, discardBootstrapPendingCredential, getBootstrapPendingTarget, resolveBapiCredentials, } from "./credential-store.js";
 // BAPI-631: the optional GitHub connect offer reuses the standalone command's flow and
 // API primitives verbatim — no duplicated polling, browser, or picker logic here.
-import { fetchGithubConfigurationState } from "./connect-github-api.js";
+import { fetchGithubConfigurationDetails, fetchGithubConfigurationState, } from "./connect-github-api.js";
 import { createDefaultConnectGithubDeps, runGithubConnectionFlow } from "./connect-github.js";
 import { fetchBitbucketConfigurationState } from "./connect-bitbucket-api.js";
 import { createDefaultConnectBitbucketDeps, runBitbucketConnectionFlow } from "./connect-bitbucket.js";
+import { defaultGitRemoteRunner, resolveBitbucketWorkspace, } from "./bitbucket-workspace-remote.js";
 import { resolveAgentSpec, isAgentName, formatValidAgentNames, resolveModelAlias, } from "./agent-registry.js";
 import { buildGenericAgentShellCommand, getDefaultSpawnTerminalTabForPlatform, detectTerminal, createDefaultStartTicketsDeps, materializeWorkerLaunchCommand, MAX_TERMINAL_COMMAND_BYTES, validateResolvedModelAliasForAgent, } from "./start-tickets.js";
 import { defaultNpmEntryFileExists, resolveNpmEntry } from "./windows-npm-entry.js";
@@ -265,7 +274,7 @@ export const INSTALL_BRIDGE_AGENT_PROMPT = "Run /install-bridge now, with no arg
     "'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, " +
+    "verbatim as the setup guidance for a 'Needs setup' item — except when that section carries a non-empty string heading: print it verbatim as the section's sub-heading instead of its name and print NO item's availability_text; with no usable heading, render each availability_text as usual — 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 " +
@@ -294,7 +303,7 @@ export const INSTALL_BRIDGE_AGENT_PROMPT = "Run /install-bridge now, with no arg
     "short, plain-language sentence covering what is happening and why it matters to the person running " +
     "this install, rather than in internal shorthand. Narration you compose yourself must never name an " +
     "internal stage number, this command's contract version, a raw internal MCP tool identifier (like " +
-    "get_install_manifest, apply_install_manifest, or invite_member), or a manifest field key (like " +
+    "get_install_manifest or apply_install_manifest), or a manifest field key (like " +
     "command_contract_version, next_step, or configured) — describe what is actually happening instead. " +
     "This restriction is scoped to narration you author: it does not apply to a user-invocable command " +
     "name you must give the human verbatim (/install-bridge, /learn-repository, connect-github, " +
@@ -308,11 +317,7 @@ export const INSTALL_BRIDGE_AGENT_PROMPT = "Run /install-bridge now, with no arg
     "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 and Stage 9. 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; " +
-    "otherwise it is skipped silently. If Stage 11 mints a teammate key, show that plaintext key " +
-    "exactly once and never repeat it in any summary, retry, or diagnostic. " +
+    "The install-spawn skip set is exactly Stage 8 and Stage 9. " +
     "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. " +
@@ -385,9 +390,8 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "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 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 —",
+        "concise capability report plus that same conditional next step.",
+        "So not every run applies config fields. Indexing is never asked about —",
         "it starts automatically once the repository reaches full parse readiness.",
         "",
         "Your API key is written to a project MCP config only when that file is safe: a",
@@ -397,17 +401,15 @@ 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` 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 or 2 (one",
-        "blank or invalid answer re-prompts once, then exits with guidance). Answering 1",
-        "prompts for an email and creates a brand-new Bridge workspace for you (the",
-        "self-serve flow). Answering 2 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. That question is asked ONLY for a",
+        "Run it bare — `install` with no flags — in a terminal and it asks one question:",
+        `\`${INSTALL_BRIDGE_EMAIL_OR_TOKEN_PROMPT.trim()}\``,
+        "Type your email to create a brand-new Bridge workspace for you (the self-serve",
+        "flow). Press Enter if you already have a token: a single hidden token prompt",
+        "opens, and whatever you paste has its SHAPE pick 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. One",
+        "malformed answer re-prompts once, then exits with guidance. You are",
+        "never asked which kind of token you hold. The 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.",
         "",
@@ -443,7 +445,10 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "                    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",
+        "  --display-name <label> Friendly creation label; required for non-TTY modern invites.",
+        "                    Do not combine with --repo or BAPI_REPO_NAME. Existing keys use canonical selectors.",
+        "                    Self-serve verification still requires an interactive terminal.",
+        "  --repo <name>     Canonical selector for reconnect or explicit legacy creation. --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",
@@ -520,9 +525,11 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "                                --tools claude-code,codex are accepted. On an",
         "                                interactive terminal WITHOUT this flag you get a",
         "                                numbered picker: enter one or more tool numbers,",
-        "                                comma-separated (e.g. 1,3), and press Enter once —",
-        "                                no tool is pre-selected (not even Claude Code) and",
-        "                                you must select at least one. A non-interactive",
+        "                                comma-separated (e.g. 1,3), and press Enter once.",
+        "                                Tools Bridge detects on this machine are pre-ticked:",
+        "                                a bare Enter accepts them, and typed numbers",
+        "                                replace them. With none detected you must select",
+        "                                at least one. A non-interactive",
         "                                (non-TTY) run without",
         "                                --tools writes the legacy automatic set (Claude",
         "                                Code plus any detected Cursor / Copilot VS Code)",
@@ -551,6 +558,8 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "                                session — it always wins, and there is NO Claude",
         "                                default. Without it the launch tool is derived",
         "                                from your selection: Claude Code opens `claude`.",
+        "                                With more than one launchable tool selected, the",
+        "                                first one is used and no question is asked.",
         "                                Cursor is NOT auto-opened (its cursor-agent CLI",
         "                                first-run workspace-trust prompt collapses a spawned",
         "                                session); selecting Cursor writes .cursor/mcp.json",
@@ -561,6 +570,13 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "                                --agent cursor-agent still force-spawns it. Codex",
         "                                is accepted only for manual continuation: neither",
         "                                this bootstrap nor start-tickets launches it yet.",
+        "  --remove-bridge-permissions   Remove ONLY the permission rules and autoMode",
+        "                                entries Bridge wrote for /drive-epic-run",
+        "                                (recorded in .bridge/bridge-permissions.json)",
+        "                                from .claude/settings.local.json and",
+        "                                ~/.claude/settings.json. Must be used alone.",
+        "                                Entries you added yourself stay. Runs nothing",
+        "                                else: no onboarding, no credential, no network.",
         "  -h, --help                    Show this help.",
         "",
         "Subcommands:",
@@ -642,6 +658,7 @@ export function parseInstallBridgeArgs(argv) {
     }
     let apiKey;
     let repo;
+    let displayName;
     let force = false;
     let dryRun = false;
     // Undefined until `--agent` is explicitly supplied — install-bridge never falls
@@ -667,8 +684,32 @@ export function parseInstallBridgeArgs(argv) {
         }
         return { value: argv[i + 1], nextIndex: i + 1 };
     };
+    // BAPI-1398: the removal flag selects a different, narrow action, so it is
+    // accepted only on its own — combining it with an install flag is ambiguous.
+    if (argv.includes("--remove-bridge-permissions")) {
+        if (argv.length !== 1) {
+            return {
+                status: "error",
+                message: "--remove-bridge-permissions must be used alone; it removes Bridge's permission rules and does nothing else.",
+            };
+        }
+        return { status: "ok", options: { force: false, dryRun: false, removeBridgePermissions: true } };
+    }
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
+        if (arg === "--display-name" || arg.startsWith("--display-name=")) {
+            const result = readValue(arg, "--display-name", i);
+            if ("error" in result)
+                return { status: "error", message: result.error };
+            try {
+                displayName = validateBootstrapDisplayName(result.value);
+            }
+            catch {
+                return { status: "error", message: "--display-name requires a safe label of 1–255 Unicode characters." };
+            }
+            i = result.nextIndex;
+            continue;
+        }
         if (arg === "--force") {
             force = true;
             continue;
@@ -797,7 +838,7 @@ export function parseInstallBridgeArgs(argv) {
     }
     return {
         status: "ok",
-        options: { apiKey, repo, force, dryRun, agentName, invite, inviteMode: inviteSupplied, email, tools, codexProfile },
+        options: { apiKey, repo, displayName, force, dryRun, agentName, invite, inviteMode: inviteSupplied, email, tools, codexProfile },
     };
 }
 /**
@@ -918,6 +959,8 @@ export async function offerGithubConnection(repoName, baseUrl, deps, log, sessio
     // No prompt surface → no offer. Never assume consent on a non-interactive run.
     if (!deps.isTTY || !deps.promptLine)
         return;
+    let attempted = false;
+    const fallbackContext = "  This attempt did not establish a successful Bridge GitHub link. Bitbucket may be offered next as an optional alternative; you can decline it and retry GitHub later.";
     try {
         const credDeps = {
             env: deps.env,
@@ -961,6 +1004,7 @@ export async function offerGithubConnection(repoName, baseUrl, deps, log, sessio
         if (answer !== "y" && answer !== "yes")
             return; // declining is a normal outcome
         const connectDeps = createDefaultConnectGithubDeps();
+        attempted = true;
         const code = await runGithubConnectionFlow(connectDeps, api, repoName);
         if (code === 0) {
             // BAPI-1171: only a CONFIRMED success suppresses the Bitbucket offer below —
@@ -968,12 +1012,15 @@ export async function offerGithubConnection(repoName, baseUrl, deps, log, sessio
             session.vcsConnected = true;
         }
         else {
+            log(fallbackContext);
             log("  note: GitHub was not connected. Your install is complete — connect GitHub later with " +
                 `'npx -y ${MCP_PACKAGE_NAME}@latest connect-github --repo ${repoName}'.`);
         }
     }
     catch {
         // The install is already durable; a failure here is never fatal to it.
+        if (attempted)
+            log(fallbackContext);
         log("  note: the GitHub connection offer could not run. Your install is complete — connect " +
             `GitHub later with 'npx -y ${MCP_PACKAGE_NAME}@latest connect-github --repo ${repoName}'.`);
     }
@@ -995,7 +1042,10 @@ export const INSTALL_BRIDGE_BITBUCKET_OFFER_CONTEXT = [
     // BAPI-1247: name the destination precisely. "Admin panel" sent people looking for a
     // page that does not exist under that name — the app lives under the workspace's own
     // settings, and saying so is the difference between a 20-second step and a hunt.
-    '  You finish by pasting a printed code into Workspace settings → Apps → "Connect Bitbucket to Bridge API".',
+    // BAPI-1401: say up front that there are two steps. Bitbucket's install screen gives no
+    // sign that a second one exists.
+    "  There are two steps: (1) install the app, then (2) approve the request on the app's page",
+    '  under Workspace settings → Forge Apps → "Connect Bitbucket to Bridge API".',
     `  You can do this later instead: ${INSTALL_BRIDGE_CONNECT_BITBUCKET_COMMAND}`,
 ];
 /** Default-No Bitbucket offer prompt. Mirrors {@link INSTALL_BRIDGE_GITHUB_CONNECT_PROMPT}. */
@@ -1060,11 +1110,13 @@ export async function offerBitbucketConnection(repoName, baseUrl, deps, log, ses
         if (answer !== "y" && answer !== "yes")
             return; // declining is a normal outcome
         const connectDeps = createDefaultConnectBitbucketDeps();
+        // BAPI-1401: the workspace comes from the project's origin remote, the same way the
+        // standalone command infers it. With one, the flow mints an approval-mode request
+        // (and prints the direct link when the server has a template); without one it falls
+        // back to the code flow and its textual navigation path.
+        const workspace = await resolveBitbucketWorkspace(undefined, deps.cwd, deps.runGit ?? defaultGitRemoteRunner, log);
         const result = await runBitbucketConnectionFlow(connectDeps, api, repoName, {
-            // The install path has no workspace slug to give: a workspace is only discoverable
-            // AFTER redemption stages candidates, which is later than this. The connection flow
-            // falls back to its textual navigation path rather than guessing a link.
-            workspace: undefined,
+            workspace,
             // The Step 4b prompt just above IS the approval for the first mint. Asking again
             // inside the flow would be a second confirmation for one decision.
             initialMintApproved: true,
@@ -1092,12 +1144,6 @@ export async function offerBitbucketConnection(repoName, baseUrl, deps, log, ses
             `Bitbucket later with 'npx -y ${MCP_PACKAGE_NAME}@latest connect-bitbucket --repo ${repoName}'.`);
     }
 }
-/**
- * The exact agent-notes consent-prompt prefix, shared with tests so the copy
- * cannot drift. Mirrors {@link INSTALL_BRIDGE_LAUNCH_CONSENT_PROMPT_PREFIX}: the
- * prefix is pinned, the platform tail varies with the selection.
- */
-export const INSTALL_BRIDGE_AGENT_NOTES_PROMPT_PREFIX = "Write guidance so ";
 /**
  * Describe the selected notes platforms for the offer copy: a naturally joined
  * subject and whether it is plural (so a verb can agree). `platformLabels` are
@@ -1120,64 +1166,30 @@ function joinLabelsWithAnd(labels) {
     return `${labels.slice(0, -1).join(", ")}, and ${labels[labels.length - 1]}`;
 }
 /**
- * The default-No agent-notes consent prompt (BAPI-1207; payoff-led, platform-named
- * copy per the BAPI-1239 install-issue #4 follow-up). Leads with WHY — teaching
- * the agent how to use Bridge's MCP tools — and NAMES the selected platform(s)
- * rather than the old generic "cross-platform" phrasing.
- */
-export function buildAgentNotesPrompt(platformLabels) {
-    const { subject, plural } = describeAgentNotesPlatforms(platformLabels);
-    return `${INSTALL_BRIDGE_AGENT_NOTES_PROMPT_PREFIX}${subject} know${plural ? "" : "s"} how to use the Bridge MCP? [y/N]: `;
-}
-/**
- * The offer-context lines printed immediately before the agent-notes prompt
- * (BAPI-1207). Leads with the payoff — teaching the named platform(s) WHEN to
- * reach for Bridge's MCP tools — then states the marker-scoped, non-destructive
- * contract as a secondary line, mirroring the GitHub/Bitbucket offers' "explain
- * before asking" convention.
- */
-export function buildAgentNotesOfferContext(targets, platformLabels) {
-    const { subject, plural } = describeAgentNotesPlatforms(platformLabels);
-    return [
-        "",
-        `Step 4c — optional: Bridge MCP guidance for ${subject}.`,
-        `  Write guidance so ${subject} know${plural ? "" : "s"} when to reach for Bridge's MCP tools`,
-        "  during a task — for project standards, a second opinion, a council, or a ticket review.",
-        `  It writes a Bridge-owned region to ${targets.join(" and ")}; only that marked region is`,
-        "  created or refreshed — any existing content, inside or outside it, is otherwise preserved.",
-    ];
-}
-/**
- * Offer to create or refresh the cross-platform agent notes, if the selected
- * platforms resolve to at least one writable target (BAPI-1207).
+ * Decide whether to create or refresh the cross-platform agent notes, if the
+ * selected platforms resolve to at least one writable target (BAPI-1207).
+ *
+ * BAPI-1448: an interactive run consents by default — the question is gone, with
+ * the product sign-off recorded in the install notes. The write is still bounded to
+ * Bridge's marked region (see {@link writeAgentNotes}) and reported afterwards with
+ * a removal hint. A non-interactive run keeps `headless-skip`: it never writes
+ * guidance on its own.
  *
- * Entirely best-effort and non-destructive, mirroring
- * {@link offerGithubConnection}: by the time this runs the install itself is
- * already complete and durable, so nothing here may fail the run. This
- * function only resolves the CONSENT decision — the caller performs the
- * actual write via {@link writeAgentNotes}, so a `--dry-run` (which never
- * reaches this call) and the live path share exactly one write path.
+ * Entirely best-effort and non-destructive: by the time this runs the install
+ * itself is already complete and durable, so nothing here may fail the run. This
+ * function only resolves the CONSENT decision — the caller performs the actual
+ * write via {@link writeAgentNotes}, so a `--dry-run` (which never reaches this
+ * call) and the live path share exactly one write path.
  */
-export async function offerAgentGuidanceNotes(deps, log, targets, platformLabels) {
+export function offerAgentGuidanceNotes(deps, targets) {
     if (targets.length === 0)
         return { kind: "not-applicable" };
-    // No prompt surface → no offer. Never assume consent on a non-interactive run.
-    if (!deps.isTTY || !deps.promptLine)
+    if (!deps.isTTY)
         return { kind: "headless-skip" };
-    try {
-        for (const line of buildAgentNotesOfferContext(targets, platformLabels))
-            log(line);
-        const answer = (await deps.promptLine(buildAgentNotesPrompt(platformLabels))).trim().toLowerCase();
-        // Only an explicit yes proceeds — blank input, EOF, "n", and anything malformed
-        // all decline without writing.
-        return answer === "y" || answer === "yes" ? { kind: "consented" } : { kind: "declined" };
-    }
-    catch {
-        // The install is already durable; a failure here is never fatal to it.
-        log("  note: the agent-notes offer could not run. No notes files were written.");
-        return { kind: "declined" };
-    }
+    return { kind: "consented" };
 }
+/** The one-line removal hint printed after guidance was actually written (BAPI-1448). */
+export const INSTALL_BRIDGE_AGENT_NOTES_REMOVAL_HINT = "To remove it, delete the lines from <!-- BEGIN BRIDGE MCP GUIDANCE --> to <!-- END BRIDGE MCP GUIDANCE -->.";
 /**
  * One secret-free summary line for the final install output (BAPI-1207). Never
  * reveals guidance content, file bytes, or a credential — only which files
@@ -1192,11 +1204,13 @@ export function buildAgentNotesSummaryLine(offer, result, writeFailed, unsupport
         return unsupportedPlatforms.length > 0 ? `Agent notes: not written${unsupportedNote}.` : undefined;
     }
     if (offer.kind === "headless-skip") {
-        return `Agent notes: skipped (non-interactive session)${unsupportedNote}.`;
+        return `Agent notes: skipped (non-interactive session or submission provenance unavailable)${unsupportedNote}.`;
     }
     if (offer.kind === "declined") {
-        return `Agent notes: skipped (declined)${unsupportedNote}.`;
+        return `Agent notes: skipped (declined or no submitted consent)${unsupportedNote}.`;
     }
+    if (offer.kind === "prompt-error")
+        return undefined;
     if (writeFailed || !result) {
         return `Agent notes: could not be written (unexpected error)${unsupportedNote}.`;
     }
@@ -1212,6 +1226,47 @@ export function buildAgentNotesSummaryLine(offer, result, writeFailed, unsupport
         parts.push(`failed for ${failed.join(", ")}`);
     return `Agent notes: ${parts.join("; ")}${unsupportedNote}.`;
 }
+const OPTIMIZATION_POSTURE_SUMMARY_LABELS = {
+    quality: "Quality",
+    speed: "Speed",
+    maximize_subscription: "Token Efficiency",
+};
+/**
+ * The aligned "defaults Bridge chose" block printed once, right before the launch
+ * consent question. Pure: it formats what the run already knows and performs no I/O.
+ *
+ * Layout: a header, then two rows of two cells. Both rows are indented two spaces and
+ * the left cells are padded to the longer left cell plus three spaces, so the right
+ * cells line up. The Ticket keys cell is omitted entirely when the server supplied no
+ * valid prefix; the prefix is printed as given and never derived locally.
+ */
+export function buildInstallBridgeDefaultsSummary(input) {
+    const optimization = input.persistedPosture
+        ? OPTIMIZATION_POSTURE_SUMMARY_LABELS[input.persistedPosture]
+        : input.isNewProject
+            ? "Quality"
+            : "unchanged";
+    const guidanceLabel = input.claudeCodeSelected ? "Claude Code guidance" : "Agent guidance";
+    const guidanceValue = input.guidance.written.length > 0
+        ? `added to ${input.guidance.written.join(", ")}`
+        : input.guidance.unchanged.length > 0
+            ? "already up to date"
+            : "not written";
+    const leftTop = `Project name: ${input.displayName}`;
+    const leftBottom = `Optimization: ${optimization}`;
+    const rightTop = input.ticketPrefix
+        ? `Ticket keys: ${input.ticketPrefix}-1, ${input.ticketPrefix}-2, …`
+        : undefined;
+    const rightBottom = `${guidanceLabel}: ${guidanceValue}`;
+    const width = Math.max(leftTop.length, leftBottom.length) + 3;
+    const rowTop = rightTop === undefined ? `  ${leftTop}` : `  ${leftTop.padEnd(width)}${rightTop}`;
+    const rowBottom = `  ${leftBottom.padEnd(width)}${rightBottom}`;
+    return [
+        "Bridge chose these defaults — change them later on the Setup page, or ask your agent:",
+        rowTop,
+        rowBottom,
+    ].join("\n");
+}
 /**
  * Echoed single-line prompt on stderr (used for repo confirmation / value).
  * Exported so `index.ts`'s `--init` can share the exact same prompt mechanics
@@ -1328,6 +1383,7 @@ export function createDefaultInstallBridgeDeps() {
     return {
         env: process.env,
         cwd: process.cwd(),
+        realpath: async (folder) => realpath(folder),
         platform: process.platform,
         homedir: os.homedir,
         isTTY,
@@ -1349,7 +1405,9 @@ export function createDefaultInstallBridgeDeps() {
         randomBytes: (size) => cryptoRandomBytes(size),
         promptSecret: isTTY ? promptSecretViaReadline : undefined,
         promptLine: isTTY ? promptLineViaReadline : undefined,
-        promptMultiSelect: isTTY ? promptMultiSelectViaReadline : undefined,
+        promptMultiSelect: isTTY
+            ? (promptText, options, preselected) => promptMultiSelectViaReadline(promptText, options, process.stdin, process.stderr, preselected)
+            : undefined,
         vendor: createDefaultVendorProcessDeps(spawn),
         fetch: productionFetch,
         resolveRepoViaServer: (baseUrl, apiKey) => resolveRepoViaServer(productionFetch, baseUrl, apiKey),
@@ -1643,6 +1701,77 @@ function defaultShellFreeRunnerWithEnv(executable, args, extraEnv) {
         child.on("close", (code) => resolve({ exitCode: code ?? 1, stdout, stderr }));
     });
 }
+/**
+ * BAPI-1405 — the owner's own `gh`, shell-free, for the epic-branch CI step.
+ *
+ * Same inherited environment as {@link defaultShellFreeRunnerWithEnv} (the
+ * customer's own login is the point), plus an optional stdin body so a ruleset
+ * update can use `gh api --input -` and keep JSON out of argv. A spawn failure
+ * (no `gh` on PATH) resolves as exit 127 rather than throwing.
+ */
+export function defaultUserGhRunner(args, opts) {
+    return new Promise((resolve) => {
+        const child = spawn("gh", args, {
+            shell: false,
+            stdio: [opts?.input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+            env: { ...process.env, GH_PROMPT_DISABLED: "1", GH_NO_UPDATE_NOTIFIER: "1" },
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString("utf-8");
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf-8");
+        });
+        child.on("error", () => resolve({ exitCode: 127, stdout: "", stderr: "gh could not be started" }));
+        child.on("close", (code) => resolve({ exitCode: code ?? 1, stdout, stderr }));
+        if (opts?.input !== undefined) {
+            child.stdin?.on("error", () => undefined);
+            child.stdin?.end(opts.input);
+        }
+    });
+}
+/**
+ * BAPI-1405 — the production epic-branch CI seams for one repository root.
+ *
+ * Provider detection reads `origin` with the owner's own git; only a canonical
+ * github.com remote counts as GitHub (the same parser the merge-workflow
+ * installer uses). The example epic branch is a local remote-tracking
+ * `origin/epic/*` ref when one exists — a cheap, offline read — and otherwise
+ * the gate module's never-created probe name.
+ */
+export function buildEpicBranchCiDeps(cwd) {
+    const git = async (args) => {
+        try {
+            const r = await defaultShellFreeRunner("git", ["-C", cwd, ...args]);
+            return r.exitCode === 0 ? r.stdout.trim() : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    return {
+        fs: createNodeGateDiscoveryFs(cwd),
+        runGh: defaultUserGhRunner,
+        detectProvider: async () => {
+            const remoteUrl = await git(["remote", "get-url", "origin"]);
+            if (!remoteUrl)
+                return { kind: "unknown" };
+            const ownerRepo = parseGithubRemote(remoteUrl);
+            return ownerRepo ? { kind: "github", ownerRepo } : { kind: "not_github" };
+        },
+        findExampleEpicBranch: async () => {
+            const ref = await git([
+                "for-each-ref",
+                "--count=1",
+                "--format=%(refname:strip=3)",
+                "refs/remotes/origin/epic/",
+            ]);
+            return ref ? ref.split("\n")[0].trim() || null : null;
+        },
+    };
+}
 /** Presence probe: `<tool> --version` exiting 0 means the tool resolves on PATH. */
 async function defaultExecutablePresenceProbe(name) {
     try {
@@ -1954,9 +2083,17 @@ const INSTALL_BRIDGE_SIGNUP_EMAIL_SHAPE = /^[^@\s]+@[^@\s]+$/;
 /** The one hint line printed after a blank/malformed email, before the single re-prompt. */
 export const INSTALL_BRIDGE_SIGNUP_EMAIL_HINT = "Enter a valid email address (e.g. you@example.com).";
 export function buildInstallBridgeSignupPrivacyNotice(baseUrl) {
-    return `Privacy Policy: ${baseUrl.replace(/\/+$/, "")}/privacy`;
+    return `Your email is used to verify signup and set up your Bridge workspace. Privacy Policy — how data is handled: ${baseUrl.replace(/\/+$/, "")}/privacy`;
+}
+export function buildInstallBridgeMaintenanceHint() {
+    return [
+        `Bridge MCP installer package: ${MCP_PACKAGE_NAME}@${VERSION}`,
+        "From the project root, use /upgrade-bridge or run:",
+        `npx -y ${MCP_PACKAGE_NAME}@latest --upgrade`,
+        "Persistent host registrations remain pinned until an explicit upgrade; the editor may need to reconnect to use the new server.",
+    ];
 }
-export async function resolveSignupEmail(options, deps, baseUrl = DEFAULT_BAPI_BASE_URL) {
+export async function resolveSignupEmail(options, deps, baseUrl = DEFAULT_BAPI_BASE_URL, onboarding) {
     // BAPI-757 (R-3 / AC-9): self-serve signup now REQUIRES an interactive terminal,
     // and the check runs FIRST — before `--email` and before `BAPI_SIGNUP_EMAIL` —
     // so an unattended run fails before any request is made, no verification email
@@ -1967,6 +2104,13 @@ export async function resolveSignupEmail(options, deps, baseUrl = DEFAULT_BAPI_B
     if (!deps.isTTY || !deps.promptLine) {
         return { ok: false, error: INSTALL_BRIDGE_SIGNUP_REQUIRES_TTY };
     }
+    // BAPI-1448: an email already answered at the merged entry prompt is consumed the
+    // way `--email` is, with no second question and no second privacy notice.
+    if (onboarding) {
+        if (!onboarding.privacyNoticeShown)
+            deps.log(buildInstallBridgeSignupPrivacyNotice(baseUrl));
+        return { ok: true, value: onboarding.email };
+    }
     deps.log(buildInstallBridgeSignupPrivacyNotice(baseUrl));
     if (typeof options.email === "string" && options.email.trim().length > 0) {
         return { ok: true, value: options.email.trim() };
@@ -2030,49 +2174,24 @@ export function resolveInstallBridgeOnboardingBranch(options, env) {
     return { kind: "have-key" };
 }
 /**
- * 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. BAPI-1171 swapped the order so the self-serve, need-a-token path is
- * option 1 — first-time signup is the common case and now leads.
- *
- * "Token" is deliberately credential-agnostic: an invite and an API key are both
- * tokens as far as this question is concerned, and answering "2" leads to ONE
- * hidden prompt whose value selects the route by shape.
+ * The bare-TTY entry prompt (BAPI-1448). One question replaces the BAPI-708 "do you
+ * have a token yet? 1/2" chooser: a typed email selects self-serve signup, and a
+ * blank answer selects the have-key branch, whose value is read ONLY through the
+ * hidden `Paste your Bridge token (input hidden): ` prompt downstream.
  */
-export const INSTALL_BRIDGE_ONBOARDING_CHOICES = [
-    "1. I need a token",
-    "2. I already have a token",
-];
-/** The single-line answer prompt drawn after the options (no bracketed default). */
-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 or 2.";
+export const INSTALL_BRIDGE_EMAIL_OR_TOKEN_PROMPT = "Email (or press Enter if you already have a token): ";
+/** The one hint line printed after a non-blank malformed answer, before the single re-prompt. */
+export const INSTALL_BRIDGE_EMAIL_OR_TOKEN_HINT = "Enter an email address, or press Enter if you already have a token.";
 /**
  * The one place the "no usable credential" copy lives (BAPI-667, U1-3).
  *
- * Centralized because the chooser failure and {@link resolveApiKey}'s two failure
+ * Centralized because the entry-prompt failure and {@link resolveApiKey}'s two failure
  * branches previously drifted: only one of them mentioned self-serve, and one
  * 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: on a bare interactive run answer 1 to request a new token or 2 if you " +
-    "already have one (an invite or an API key — either one is accepted at the hidden prompt). " +
+export const INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE = "Re-run install: on a bare interactive run, type your email to sign up, or press Enter if you " +
+    "already have a token (an invite or an API key — either one is accepted at the hidden prompt). " +
     "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.";
 /**
@@ -2120,7 +2239,7 @@ export const INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE = "Re-run install: on a bare int
  * key-on-invite exits non-zero) is preserved BY CONSTRUCTION. Do not "unify" the
  * two.
  */
-export async function resolveInstallBridgeOnboardingBranchForRun(options, deps, argv) {
+export async function resolveInstallBridgeOnboardingBranchForRun(options, deps, argv, baseUrl = DEFAULT_BAPI_BASE_URL) {
     const branch = resolveInstallBridgeOnboardingBranch(options, deps.env);
     // An explicit need-key intent is already unambiguous — never re-ask it.
     if (branch.kind === "need-key")
@@ -2132,38 +2251,35 @@ export async function resolveInstallBridgeOnboardingBranchForRun(options, deps,
     }
     const promptLine = deps.promptLine;
     try {
-        // Render the heading + options EXACTLY once; a re-prompt after an invalid
-        // answer re-asks the question without redrawing the list (BAPI-663 contract).
-        deps.log(INSTALL_BRIDGE_KEY_SELECTOR_PROMPT);
-        for (const choice of INSTALL_BRIDGE_ONBOARDING_CHOICES)
-            deps.log(choice);
+        // The answer may be an email, so the privacy notice comes first and prints once.
+        deps.log(buildInstallBridgeSignupPrivacyNotice(baseUrl));
         // Bounded to two reads total: the first answer, then ONE re-prompt after a
         // single hint line. EOF resolves as an empty answer (promptLineViaReadline
-        // resolves "" on close), so it costs one re-prompt and then fails cleanly —
-        // it can never hang or silently select a branch.
+        // resolves "" on close), which selects the have-key branch rather than hanging.
         for (let attempt = 0; attempt < 2; attempt += 1) {
-            const answer = (await promptLine(INSTALL_BRIDGE_ONBOARDING_CHOICE_PROMPT)).trim();
-            // BAPI-708 (A-1): the accepted tokens are exactly 1/2 (no letters, no
-            // aliases), preserving the one-strict-line contract. BAPI-1171 swapped the
-            // order so "1" is the self-serve need-key branch and "2" 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") {
+            const answer = String((await promptLine(INSTALL_BRIDGE_EMAIL_OR_TOKEN_PROMPT)) ?? "").trim();
+            // Blank (or EOF): the user has a token; it is read only by the hidden prompt.
+            if (answer.length === 0) {
+                return { ok: true, branch: { kind: "have-key" }, credentialIntent: "inferred" };
+            }
+            // A typed value is accepted ONLY as a signup email. It is never classified as a
+            // credential, logged, or persisted here; a token-shaped value fails the shape
+            // check and gets the hint.
+            if (INSTALL_BRIDGE_SIGNUP_EMAIL_SHAPE.test(answer)) {
                 return {
                     ok: true,
                     branch: { kind: "need-key", method: "self-serve" },
                     credentialIntent: "inferred",
+                    onboardingEmail: answer,
+                    privacyNoticeShown: true,
                 };
             }
-            if (answer === "2")
-                return { ok: true, branch: { kind: "have-key" }, credentialIntent: "inferred" };
             if (attempt === 0)
-                deps.log(INSTALL_BRIDGE_ONBOARDING_CHOICE_HINT);
+                deps.log(INSTALL_BRIDGE_EMAIL_OR_TOKEN_HINT);
         }
         return {
             ok: false,
-            error: `No option was selected. ${INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE}`,
+            error: `No email or token choice was made. ${INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE}`,
         };
     }
     catch {
@@ -2272,22 +2388,31 @@ const SELECTION_TOKEN_PATTERN = /^[1-9][0-9]*$/;
  * Interactive single-shot numbered picker on stderr (TTY only). Renders the
  * heading and each option exactly once, then accepts ONE strict
  * comma-separated line of one-based numbers and resolves immediately — there
- * is no preselected/toggle state and no separate confirmation step (BAPI-663).
+ * is no toggle state and no separate confirmation step (BAPI-663).
  *
- * A blank line or a line containing any invalid token (non-numeric, zero,
- * signed, leading-zero, decimal, out-of-range) is rejected atomically — the
- * whole line is discarded, one error line is printed, and the picker
- * re-prompts without re-rendering the option list. A valid line is
- * deduplicated and returned in `options` order regardless of entry order.
+ * BAPI-1448: when `preselected` names at least one offered option, those rows
+ * render as `[x]` (the rest as `[ ]`) and a blank line accepts the ticked set.
+ * Typed numbers REPLACE the ticked set; they never toggle it. With nothing
+ * pre-ticked the original behaviour is unchanged: a blank line is rejected with
+ * "Select at least one tool."
+ *
+ * A line containing any invalid token (non-numeric, zero, signed,
+ * leading-zero, decimal, out-of-range) is rejected atomically — the whole line
+ * is discarded, one error line is printed, and the picker re-prompts without
+ * re-rendering the option list, so the ticks stay as first shown. A valid line
+ * is deduplicated and returned in `options` order regardless of entry order.
  *
  * Resolves to `[]` on EOF / synchronous close before any line has been
  * committed, so a readline regression can never hang. Returns `[]`
  * immediately, without creating a readline interface, when `options` is
  * empty.
  */
-export function promptMultiSelectViaReadline(promptText, options, input = process.stdin, output = process.stderr) {
+export function promptMultiSelectViaReadline(promptText, options, input = process.stdin, output = process.stderr, preselected = []) {
     if (options.length === 0)
         return Promise.resolve([]);
+    // Canonical option order, restricted to options actually offered.
+    const ticked = options.filter((o) => preselected.includes(o.id)).map((o) => o.id);
+    const hasTicks = ticked.length > 0;
     return new Promise((resolve) => {
         const rl = readline.createInterface({ input, output });
         let settled = false;
@@ -2304,13 +2429,20 @@ export function promptMultiSelectViaReadline(promptText, options, input = proces
         rl.on("close", () => finish([]));
         output.write(`\n${promptText}\n`);
         options.forEach((opt, idx) => {
-            output.write(`  ${idx + 1}. ${opt.label}\n`);
+            const box = hasTicks ? `${ticked.includes(opt.id) ? "[x]" : "[ ]"} ` : "";
+            output.write(`  ${idx + 1}. ${box}${opt.label}\n`);
         });
-        output.write("Enter the number(s) of the tools you use (e.g. 1,3), then Enter.\n");
+        output.write(hasTicks
+            ? "Press Enter to use the ticked tools, or type the numbers you use (e.g. 1,3).\n"
+            : "Enter the number(s) of the tools you use (e.g. 1,3), then Enter.\n");
         const prompt = () => {
             rl.question("> ", (answer) => {
                 const trimmed = answer.trim();
                 if (trimmed.length === 0) {
+                    if (hasTicks) {
+                        finish(ticked);
+                        return;
+                    }
                     output.write("Select at least one tool.\n");
                     prompt();
                     return;
@@ -2361,10 +2493,6 @@ export function optimizationPostureSubscriptionNounPhrase(primaryPlatform) {
     const mapped = primaryPlatform ? OPTIMIZATION_POSTURE_SUBSCRIPTION_NAMES[primaryPlatform] : undefined;
     return mapped ? `${mapped} subscription` : "coding subscription";
 }
-/** Option three's exact wording, platform-aware (BAPI-1221 Step 2). */
-function buildOptimizationPostureOptionThree(primaryPlatform) {
-    return `Get the most out of your ${optimizationPostureSubscriptionNounPhrase(primaryPlatform)}?`;
-}
 /** The neutral single-line correction reprompted for any malformed answer. */
 const OPTIMIZATION_POSTURE_CORRECTION = "Enter a single number from 1 to 3.";
 /**
@@ -2380,15 +2508,21 @@ const OPTIMIZATION_POSTURE_CORRECTION = "Enter a single number from 1 to 3.";
 const OPTIMIZATION_POSTURE_MAX_CORRECTIONS = 20;
 /**
  * Render the one-time posture menu and its input instruction. Exactly three
- * vertically ordered numbered options; option three is platform-aware. Plain,
- * wrap-safe text — no color-only state, icons, or decorative framing.
+ * vertically ordered numbered options; option three names the user's own
+ * subscription. Plain, wrap-safe text (every line within 80 columns) — no
+ * color-only state, icons, or decorative framing.
  */
 function buildOptimizationPostureMenu(primaryPlatform) {
-    return ("How should Bridge optimize its work on this repository?\n" +
-        "  1. Quality\n" +
-        "  2. Speed\n" +
-        `  3. ${buildOptimizationPostureOptionThree(primaryPlatform)}\n` +
-        `${OPTIMIZATION_POSTURE_CORRECTION} `);
+    return ("How should Bridge balance quality and cost on this project?\n" +
+        "  1. Quality — Bridge plans and reviews each ticket in full depth; slowest and\n" +
+        "     uses the most credits, but catches the most problems.\n" +
+        "  2. Speed — Bridge plans in one pass and reviews once; faster and cheaper, but\n" +
+        "     may miss things on some tickets.\n" +
+        "  3. Token Efficiency — Bridge will use Speed settings and hand simpler tickets\n" +
+        "     to smaller models more often, which stretches your\n" +
+        `     ${optimizationPostureSubscriptionNounPhrase(primaryPlatform)} the furthest.\n` +
+        "Press Enter to keep Quality (or your saved choice).\n" +
+        "Enter 1, 2, or 3: ");
 }
 /**
  * The purpose-built, strict single-select optimization-posture picker
@@ -2478,7 +2612,7 @@ function optimizationPostureConfirmationPhrase(value, primaryPlatform) {
 }
 /** Printed immediately after a successful posture write, on its own line. */
 const OPTIMIZATION_POSTURE_BLOG_URL = "https://bridgegpt.ai/blog/how-we-optimize-your-setup";
-const OPTIMIZATION_POSTURE_REMEDIATION = "Update it later with /teach-bridge or the optimization_posture setting in the web UI.";
+const OPTIMIZATION_POSTURE_REMEDIATION = "Change it later by running /teach-bridge in your agent.";
 /**
  * The generic, secret-free fail-open message shared by every non-success,
  * non-forbidden outcome — an interactive no-answer/prompt-exception (no PUT
@@ -2496,7 +2630,7 @@ const OPTIMIZATION_POSTURE_UNCHANGED_MESSAGE = `  Optimization posture was not c
  */
 function reportOptimizationPostureOutcome(log, result, value, primaryPlatform) {
     if (result.kind === "success") {
-        log(`  Preference saved for later activation — we'll optimize for ${optimizationPostureConfirmationPhrase(value, primaryPlatform)}.`);
+        log(`  Preference saved — we'll optimize for ${optimizationPostureConfirmationPhrase(value, primaryPlatform)}.`);
         log(`  ${OPTIMIZATION_POSTURE_BLOG_URL}`);
         return;
     }
@@ -2512,8 +2646,9 @@ function reportOptimizationPostureOutcome(log, result, value, primaryPlatform) {
  * Resolve the selected host platforms with strict precedence (BAPI-635):
  *   1. explicit `--tools` (including an explicit EMPTY selection — never falls
  *      back to detection),
- *   2. interactive multi-select on a TTY (AC-2: no row pre-selected — the picker
- *      starts empty and requires an explicit ≥1 selection),
+ *   2. interactive multi-select on a TTY, pre-ticked with the detected tools
+ *      (BAPI-1448 reverses the BAPI-635 AC-2 empty picker; with nothing detected
+ *      the picker still requires an explicit ≥1 selection),
  *   3. the legacy non-TTY automatic set: Claude Code plus only the currently
  *      detected Copilot VS Code and Cursor automatic targets (never Codex just
  *      because a global directory exists).
@@ -2523,11 +2658,12 @@ export async function resolveSelectedHostPlatforms(deps, options) {
     if (options.tools !== undefined) {
         return options.tools;
     }
-    // 2. Interactive single-shot numbered picker on a TTY. No row is pre-selected
-    // — the picker has no default state and requires an explicit selection.
+    // 2. Interactive single-shot numbered picker on a TTY, seeded with the locally
+    // detected tools (BAPI-1448): Enter accepts them, typed numbers replace them.
     if (deps.isTTY && deps.promptMultiSelect) {
         const optionList = allHostTargets().map((t) => ({ id: t.id, label: t.label }));
-        const chosen = await deps.promptMultiSelect(INSTALL_BRIDGE_TOOL_SELECTOR_PROMPT, optionList);
+        const detected = detectDefaultPlatforms(await buildDetectionContext(deps));
+        const chosen = await deps.promptMultiSelect(INSTALL_BRIDGE_TOOL_SELECTOR_PROMPT, optionList, detected);
         return HOST_PLATFORM_ORDER.filter((id) => chosen.includes(id));
     }
     // 3. Legacy non-TTY automatic set: Claude + detected Cursor / Copilot VS Code.
@@ -2645,42 +2781,6 @@ export function toolLabelForLaunchAgent(agent) {
     const target = allHostTargets().find((t) => t.launchAgent === agent);
     return target?.label ?? UNKNOWN_LAUNCH_TOOL_LABEL;
 }
-/**
- * Interactive numbered chooser for when MORE THAN ONE launchable tool was selected
- * (AC-11). Mirrors the connect-github picker: prints each candidate by its host-tool
- * label, asks for an exact numeric choice with NO default, validates the range, and
- * returns the chosen agent. Returns `null` — never a silent first-candidate default —
- * for every unavailable/invalid path: non-TTY, a missing `promptLine` seam, blank/EOF
- * input, an out-of-range or malformed answer, or a prompt that throws. Single-purpose:
- * it must run only AFTER the multi-select promise has resolved and closed its readline
- * interface so two readers never contend for stdin.
- */
-export async function chooseInstallBridgeLaunchAgent(agents, deps) {
-    if (!deps.isTTY || !deps.promptLine)
-        return null;
-    const promptLine = deps.promptLine;
-    try {
-        deps.log("");
-        deps.log("More than one selected tool can host the configuration session:");
-        agents.forEach((agent, i) => {
-            deps.log(`  ${String(i + 1).padStart(2, " ")}. ${toolLabelForLaunchAgent(agent)}`);
-        });
-        // No default: a stray Enter must not silently pick a tool.
-        const answer = (await promptLine(`Which tool should open? [1-${agents.length}]: `)).trim();
-        const index = Number(answer);
-        if (!/^\d+$/.test(answer) ||
-            !Number.isInteger(index) ||
-            index < 1 ||
-            index > agents.length) {
-            return null;
-        }
-        return agents[index - 1];
-    }
-    catch {
-        // Never surface caught exception text; an unavailable chooser is a no-spawn.
-        return null;
-    }
-}
 /**
  * Shared, copy-pasteable "we didn't open a session for you" guidance so every
  * no-spawn path (no-launchable selection, non-TTY suppression, chooser failure,
@@ -3386,6 +3486,7 @@ async function removeUnprovenBridgeConfig(deps, createdText) {
  * ONCE for the whole batch, so selecting both does not print it twice.
  */
 async function provisionSelectedGlobalTargets(deps, platforms, entry, needKey) {
+    let complete = true;
     const logLines = [];
     const duplicateRegistrations = [];
     let anyManualRequired = false;
@@ -3418,14 +3519,17 @@ async function provisionSelectedGlobalTargets(deps, platforms, entry, needKey) {
                 logLines.push(`  configured ${target.label} (${outcome.displayPath})`);
                 break;
             case "manual-required":
+                complete = false;
                 anyManualRequired = true;
                 logLines.push(`  ${target.label}: add the ${MCP_SERVER_NAME} MCP server manually to ${outcome.displayPath} ` +
                     "(the API key is redacted in printed instructions).");
                 break;
             case "skipped-invalid":
+                complete = false;
                 logLines.push(`  ${target.label}: skipped ${outcome.displayPath} — existing config is not valid; left untouched.`);
                 break;
             case "skipped-duplicate-registration":
+                complete = false;
                 // BAPI-807: NOT an ordinary vendor-fallback condition. The target was
                 // left byte-identical and the caller must fail loudly rather than report
                 // a configured host.
@@ -3433,6 +3537,7 @@ async function provisionSelectedGlobalTargets(deps, platforms, entry, needKey) {
                 logLines.push(`  ${target.label}: skipped ${outcome.displayPath} — ${outcome.detail}`);
                 break;
             case "failed":
+                complete = false;
                 logLines.push(`  ${target.label}: could not be configured automatically; configure it manually.`);
                 break;
         }
@@ -3440,7 +3545,7 @@ async function provisionSelectedGlobalTargets(deps, platforms, entry, needKey) {
     if (needKey && anyManualRequired) {
         logLines.push(`  ${formatNeedKeyCredentialStoreLine(needKey.repoName, needKey.credentialStorePath)}`);
     }
-    return { logLines, duplicateRegistrations };
+    return { logLines, duplicateRegistrations, complete };
 }
 /** Build the `/jira/ping` URL exactly like the MCP `ping` tool / buildGetUrl. */
 export function buildPingUrl(baseUrl, repoName) {
@@ -3642,8 +3747,20 @@ export function generateBootstrapKeySecret(randomBytes) {
  * the identity guard in both shapes, and prepare / repoint / promote / discard all
  * still match on it.
  */
-export function fingerprintBootstrapInvite(token) {
-    return createHash("sha256").update(token, "utf-8").digest("hex");
+export function fingerprintBootstrapInvite(token, baseUrl) {
+    if (baseUrl === undefined)
+        return createHash("sha256").update(token, "utf-8").digest("hex");
+    return fingerprintBootstrapFields("bridge-bootstrap-invite-v1", [baseUrl, token]);
+}
+function fingerprintBootstrapFields(domain, fields) {
+    const hash = createHash("sha256").update(domain + "\0", "utf-8");
+    for (const field of fields) {
+        const bytes = Buffer.from(field, "utf-8");
+        const length = Buffer.alloc(4);
+        length.writeUInt32BE(bytes.length);
+        hash.update(length).update(bytes);
+    }
+    return hash.digest("hex");
 }
 /** The exchange endpoint: `<base>/setup/bootstrap`. No query string — ever. */
 export function buildBootstrapExchangeUrl(baseUrl) {
@@ -3659,15 +3776,15 @@ export function buildBootstrapExchangeUrl(baseUrl) {
  * the legacy three-field one, byte for byte.
  */
 export async function exchangeBootstrapInvite(deps, baseUrl, token, repoName, keySecret, email) {
+    const modern = typeof repoName !== "string";
+    const identity = modern ? { repo_display_name: validateBootstrapDisplayName(repoName.repoDisplayName) } : { repo_name: repoName };
     const url = buildBootstrapExchangeUrl(baseUrl);
     let resp;
     try {
         resp = await deps.fetch(url, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(email
-                ? { token, repo_name: repoName, key_secret: keySecret, email }
-                : { token, repo_name: repoName, key_secret: keySecret }),
+            body: JSON.stringify({ token, ...identity, key_secret: keySecret, ...(email ? { email } : {}) }),
             signal: AbortSignal.timeout(10_000),
         });
     }
@@ -3683,13 +3800,17 @@ export async function exchangeBootstrapInvite(deps, baseUrl, token, repoName, ke
             ok: false,
             kind: "failed",
             message: `Could not reach the Bridge API at ${baseUrl} to redeem the bootstrap invite. Check ` +
-                "BAPI_BASE_URL and your network. The invite has not been used.",
+                "BAPI_BASE_URL and your network. Creation outcome is unknown; preserve proof and rerun the same attempt.",
         };
     }
     if (resp.ok) {
         let repo;
         try {
             const body = (await resp.json());
+            if (modern) {
+                const identity = validateBootstrapServerIdentity(body);
+                return { ok: true, repoName: identity.repo_name, displayName: identity.repo_display_name };
+            }
             repo = body?.repo_name;
         }
         catch {
@@ -3711,7 +3832,7 @@ export async function exchangeBootstrapInvite(deps, baseUrl, token, repoName, ke
         }
         return { ok: true, repoName: validated.value };
     }
-    if (resp.status === 409) {
+    if (resp.status === 409 && !modern) {
         return {
             ok: false,
             kind: "repo-name-taken",
@@ -3744,7 +3865,7 @@ export async function exchangeBootstrapInvite(deps, baseUrl, token, repoName, ke
     return {
         ok: false,
         kind: "failed",
-        message: `The bootstrap exchange failed (HTTP ${resp.status}). Verify BAPI_BASE_URL and try again.`,
+        message: `The bootstrap exchange failed (HTTP ${resp.status}). Preserve proof and rerun the same attempt; verify server compatibility and contact installation support if it persists.`,
     };
 }
 /** The invite-email prompt (BAPI-1263), shown once after an `email_required` refusal. */
@@ -3910,6 +4031,27 @@ export function buildSelfServeMintUrl(baseUrl) {
 export const SIGNUP_VERIFICATION_CODE_LENGTH = 6;
 /** The one prompt label. The E2E harness and the static contract both pin it. */
 export const INSTALL_BRIDGE_CODE_PROMPT = "Email verification code: ";
+/**
+ * The address verification codes are sent from. Mirrors the server's
+ * `DEFAULT_FROM_ADDRESS` in `api/library/email/provider.py`; keep the two in step.
+ */
+export const INSTALL_BRIDGE_VERIFICATION_SENDER = "noreply@bridgegpt-api.com";
+/**
+ * The shared lead-in printed immediately before every self-serve
+ * {@link promptForVerificationCode} call (modern and legacy paths, fresh or resumed):
+ * three unindented lines, then a blank line. It prints neither the prompt nor any
+ * expiry or time-left text.
+ *
+ * BAPI-1449 (verification recovery) builds on this lead-in instead of adding its
+ * own, and may later return the sender from the request endpoint rather than using
+ * {@link INSTALL_BRIDGE_VERIFICATION_SENDER}.
+ */
+export function logVerificationCodeLeadIn(log, email) {
+    log(`We emailed a ${SIGNUP_VERIFICATION_CODE_LENGTH}-digit code to ${maskSignupEmail(email)}.`);
+    log(`It usually arrives within two minutes. It comes from ${INSTALL_BRIDGE_VERIFICATION_SENDER} — check your`);
+    log("spam or junk folder if you don't see it.");
+    log("");
+}
 /** Shown when a stored, unexpired challenge is picked up on a later run. */
 export const INSTALL_BRIDGE_RESUME_VERIFICATION_HEADING = "Resume email verification";
 /**
@@ -4680,8 +4822,8 @@ function buildDeferredLaunchStepPreview() {
 /**
  * The optional agent-notes offer preview line (BAPI-1207). A --dry-run never
  * prompts or writes; when the selection resolves to at least one writable
- * notes target this states plainly that a real interactive run would ask
- * default-No consent before touching it. Empty when the selection resolves to
+ * notes target this states plainly that a real interactive run writes it
+ * without asking. Empty when the selection resolves to
  * no writable target (e.g. Windsurf-only), mirroring how the GitHub offer
  * lines are unconditional but this offer's applicability is not.
  */
@@ -4696,10 +4838,10 @@ function buildAgentNotesPreviewLines(notesTargets, platformLabels) {
         "Step 4c — reached only after the Step 4b VCS connect offer has completed or been",
         "          explicitly deferred (a declined or incomplete connect is announced first,",
         "          with the command to finish it later, and never blocks this step).",
-        `Step 4c — optional: Bridge MCP guidance for ${subject} (SKIPPED in --dry-run): if the`,
-        `          terminal is interactive, offer to write guidance so ${subject} know${plural ? "" : "s"} when to reach`,
-        `          for Bridge's MCP tools, in a Bridge-owned marker region in ${notesTargets.join(" and ")}; defaults`,
-        "          to No, and existing content outside that region is always preserved. No notes files are",
+        `Step 4c — Bridge MCP guidance for ${subject} (SKIPPED in --dry-run): if the`,
+        `          terminal is interactive, a real run writes guidance so ${subject} know${plural ? "" : "s"} when to reach`,
+        `          for Bridge's MCP tools, in a Bridge-owned marker region in ${notesTargets.join(" and ")}, without asking,`,
+        "          then prints how to remove it. Existing content outside that region is preserved. No notes files are",
         "          written in --dry-run.",
     ];
 }
@@ -5315,6 +5457,20 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             // Built from the FINAL merged deps for the same reason (BAPI-775): a test
             // that overrides only `readFile` or only `cwd` must see its override here.
             localProvisioning: buildConductorLocalDeps(deps),
+            // BAPI-1391: the read-only discovery filesystem over THIS working tree, and
+            // the short-lived qualifying executor (the existing executor CLI with a
+            // `runExecutor` override limiting it to `gate_qualification` jobs).
+            gate: deps.conductorGate ?? {
+                discoveryFs: createNodeGateDiscoveryFs(deps.cwd),
+                // BAPI-1405: epic-branch CI inspection over this working tree, with the
+                // owner's own shell-free `gh`.
+                epicBranchCi: buildEpicBranchCiDeps(deps.cwd),
+                runQualificationExecutor: createQualificationExecutorRunner({
+                    runExecutorCli,
+                    runExecutor,
+                    errorLog: deps.errorLog,
+                }),
+            },
         };
         return runInstallBridgeConductorCli(argv.slice(1), conductorDeps);
     }
@@ -5330,6 +5486,29 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         return 1;
     }
     const options = parsed.options;
+    if (options.displayName !== undefined && (options.repo !== undefined || deps.env.BAPI_REPO_NAME?.trim())) {
+        errorLog("Error: --display-name conflicts with --repo or BAPI_REPO_NAME. Use a friendly label for creation or a canonical selector for legacy creation/reconnect.");
+        return 1;
+    }
+    if (options.displayName !== undefined && !options.inviteMode && !options.email && !deps.env.BAPI_INVITE?.trim() && !deps.env.BAPI_SIGNUP_EMAIL?.trim() && (options.apiKey !== undefined || deps.env.BAPI_API_KEY?.trim())) {
+        errorLog("Error: --display-name applies only to new creation. Existing keys use canonical --repo selection or single-project resolution.");
+        return 1;
+    }
+    // ---- BAPI-1398: --remove-bridge-permissions — removal only, nothing else ----
+    // Ahead of the base-URL check, onboarding, every prompt, every credential read,
+    // and every network call: it touches only the two settings files and Bridge's
+    // ownership manifest.
+    if (options.removeBridgePermissions) {
+        return runBridgePermissionsRemoval({
+            cwd: deps.cwd,
+            homeDir: deps.homedir(),
+            readFile: deps.readFile,
+            writeFile: (p, data) => deps.writeFile(p, data, { encoding: "utf-8" }),
+            mkdir: (p, o) => deps.mkdir(p, o),
+            log,
+            errorLog,
+        });
+    }
     // Deliberately still ahead of the onboarding branch, any prompt, any network
     // call, and the --dry-run preview: a scheme-less value (the classic error) used
     // to throw ERR_INVALID_URL deep inside `buildPingUrl` — even in --dry-run — often
@@ -5490,7 +5669,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // The selection is pure and deterministic for every explicit, env-driven, and
     // non-TTY invocation; only a BARE interactive run is asked which branch it wants
     // (BAPI-626 — otherwise a first-time user can never reach self-serve).
-    const branchResult = await resolveInstallBridgeOnboardingBranchForRun(options, deps, argv);
+    const branchResult = await resolveInstallBridgeOnboardingBranchForRun(options, deps, argv, baseUrl);
     if (!branchResult.ok) {
         errorLog(`Error: ${branchResult.error}`);
         return 1;
@@ -5532,7 +5711,12 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // key-authentication ping, so there is no source to attribute.
     let apiKeySource;
     if (selfServeSignupMode) {
-        const emailResult = await resolveSignupEmail(options, deps, baseUrl);
+        const emailResult = await resolveSignupEmail(options, deps, baseUrl, branchResult.onboardingEmail
+            ? {
+                email: branchResult.onboardingEmail,
+                privacyNoticeShown: branchResult.privacyNoticeShown === true,
+            }
+            : undefined);
         if (!emailResult.ok) {
             errorLog(`Error: ${emailResult.error}`);
             return 1;
@@ -5667,6 +5851,56 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     //     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.
+    if (!bootstrapInviteMode && options.displayName !== undefined) {
+        errorLog("Error: --display-name applies only to creation; existing-key registration uses canonical selection.");
+        return 1;
+    }
+    let modernAttempt;
+    if (options.tools?.length === 0 && !options.agentName) {
+        log(buildManualInstallBridgeContinuation("empty-selection", []));
+        return 0;
+    }
+    if (bootstrapInviteMode && resolveConfiguredRepoName(options, deps.env) === undefined) {
+        if (!selfServeSignupMode) {
+            const legacy = await lookupLegacyBootstrapInvite(fingerprintBootstrapInvite(inviteToken), modernWriteDeps(deps));
+            if (!legacy.ok) {
+                errorLog(legacy.error);
+                return 1;
+            }
+            if (legacy.repoName)
+                options.repo = legacy.repoName;
+        }
+        else {
+            // Historical default creation used the folder basename as its canonical name.
+            const oldName = validateRepoName(path.basename(deps.cwd));
+            if (oldName.ok) {
+                const legacy = await deps.lookupSelfServeBootstrapPending({ repoName: oldName.value, now: deps.now() }, modernWriteDeps(deps));
+                if (!legacy.ok) {
+                    errorLog(legacy.error);
+                    return 1;
+                }
+                if (legacy.state === "resumable" || legacy.state === "challenge")
+                    options.repo = oldName.value;
+                if (legacy.state === "challenge-expired") {
+                    errorLog("Saved signup expired. Preserve proof and contact installation support.");
+                    return 1;
+                }
+            }
+        }
+        if (options.repo === undefined) {
+            try {
+                modernAttempt = await redeemModernInstallAttempt(deps, options, baseUrl, inviteToken, signupEmail, selfServeSignupMode);
+                apiKey = modernAttempt.record.keySecret;
+                options.repo = modernAttempt.repoName;
+                bootstrapInviteMode = false;
+                deps.log(`Project '${modernAttempt.displayName}' recovered; completing installation.`);
+            }
+            catch (error) {
+                errorLog(error instanceof ModernInstallRecoveryError ? error.message : "Installation could not complete. Preserve recovery proof and resume from the same folder and invite/signup; contact installation support if needed.");
+                return 1;
+            }
+        }
+    }
     let repoName;
     /** The resolver's OUTCOME (C-4), or undefined when it was never called. */
     let serverRepoResolutionStatus;
@@ -5798,6 +6032,24 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // before any of the credential/repo/host resolution above — so by this point
     // the run is unconditionally the LIVE path. See the early return above for
     // the inert preview.
+    // One advisory per live interactive handoff. Never construct probe dependencies
+    // on dry-run/noninteractive paths, and never change install/consent outcomes.
+    let advisoryShown = false;
+    const showFirstBuildAdvisory = async (agent) => {
+        if (advisoryShown || !deps.isTTY || options.dryRun)
+            return;
+        advisoryShown = true;
+        try {
+            const advisory = await collectFirstBuildAdvisory({
+                decision: agent ? { kind: "spawn", agent } : { kind: "manual", reason: "manual-continuation" },
+                configuredHosts: labelsForPlatforms(selectedPlatforms),
+            }, { ...deps.startTicketsDeps, platform: deps.platform, env: deps.env, cwd: deps.cwd });
+            log(formatFirstBuildAdvisory(advisory));
+        }
+        catch {
+            log(`First-build prerequisites: diagnostic availability unknown. Run ${INSTALL_BRIDGE_DOCTOR_COMMAND} for read-only follow-up.`);
+        }
+    };
     // ---- Resolved-empty selection: a handled no-op (exit 0), never a Claude fallback ----
     // AC-3: with zero configured tools there is nothing to write and no session to open.
     // Return BEFORE any config/credential write, materialization, prewarm, or spawn, so a
@@ -5805,14 +6057,15 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     if (planLaunch.kind === "manual" && planLaunch.reason === "empty-selection") {
         // Explicit empty selection: no labels to name, so the generic fallback is
         // intentional here — pass [] rather than `labelsForPlatforms(selectedPlatforms)`.
+        await showFirstBuildAdvisory(null);
         log(buildManualInstallBridgeContinuation("empty-selection", []));
         return 0;
     }
     // ---- Finalize the launch agent for spawn-capable decisions ----
-    // choose-one: pick exactly one via the numbered chooser (TTY only); a non-TTY run or
-    // a failed/aborted chooser degrades to the manual continuation (finalAgentName stays
-    // null). This runs AFTER the multi-select readline closed and BEFORE the GitHub /
-    // consent flows, so no two stdin readers ever overlap.
+    // choose-one: on a TTY, take the first launchable agent the user selected and say so
+    // (BAPI-1448 retired the launch-agent chooser; `--agent` still wins
+    // upstream in the pure launch decision). A non-TTY run degrades to the manual
+    // continuation (finalAgentName stays null).
     let finalAgentName = null;
     let finalSpawnCommand = null;
     if (planLaunch.kind === "spawn") {
@@ -5820,8 +6073,9 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         finalSpawnCommand = planLaunch.spawnCommand;
     }
     else if (planLaunch.kind === "choose-one") {
-        const chosen = await chooseInstallBridgeLaunchAgent(planLaunch.agents, deps);
+        const chosen = deps.isTTY ? (planLaunch.agents[0] ?? null) : null;
         if (chosen) {
+            log(`Using ${toolLabelForLaunchAgent(chosen)} for the setup session (the first tool you selected). Pass --agent to choose another.`);
             const spec = resolveAgentSpec(chosen);
             if (!spec) {
                 errorLog(`Error: no launch agent is registered for '${chosen}'.`);
@@ -5831,7 +6085,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             const modelAlias = await resolveValidatedPremiumModelAlias(deps, spec);
             finalSpawnCommand = deps.buildShellCommand(spec, INSTALL_BRIDGE_AGENT_PROMPT, deps.cwd, deps.platform, modelAlias);
         }
-        // chosen === null → non-TTY / unavailable / invalid → manual continuation below.
+        // chosen === null → non-TTY → manual continuation below.
     }
     // planLaunch.kind === "manual" (no-launchable) → finalAgentName stays null.
     // ---- Materialize the Step 5 launch command + kick off the pre-warm — ONLY for a
@@ -6020,7 +6274,6 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                     challengeExpiresAt = liveChallenge.expiresAt;
                     challengeEmail = liveChallenge.email;
                     log(`  ${INSTALL_BRIDGE_RESUME_VERIFICATION_HEADING}`);
-                    log(`  We already emailed a code to ${maskSignupEmail(challengeEmail)}.`);
                 }
                 else {
                     const requested = await requestSelfServeChallenge(deps, baseUrl, signupEmail);
@@ -6080,12 +6333,9 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                             "No workspace has been set up — fix the problem and re-run.");
                         return false;
                     }
-                    log(`  We emailed a code to ${maskSignupEmail(challengeEmail)}.`);
                 }
-                log(`  Enter the ${SIGNUP_VERIFICATION_CODE_LENGTH}-digit code to finish setting up your workspace.`);
-                const remaining = formatChallengeRemaining(challengeExpiresAt, deps.now());
-                if (remaining)
-                    log(`  ${remaining}`);
+                // BAPI-1448: the shared lead-in, fresh or resumed, directly before code entry.
+                logVerificationCodeLeadIn(log, challengeEmail);
                 // Phase 2, second half, and phase 3. One resend is offered on the recovery
                 // path only — never proactively — so the budget is spent on the user's
                 // explicit request rather than by the CLI's own retry logic.
@@ -6467,7 +6717,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             log(currentStep);
         }
         // BAPI-668: a bootstrap-minted key is verified WITHOUT source attribution.
-        const ping = await verifyConnectivity(deps, baseUrl, repoName, apiKey, bootstrapInviteMode ? undefined : apiKeySource);
+        const ping = modernAttempt ? { ok: true } : await verifyConnectivity(deps, baseUrl, repoName, apiKey, bootstrapInviteMode ? undefined : apiKeySource);
         if (!ping.ok) {
             // BAPI-667: in either need-key mode the exchange already succeeded and the
             // pending record survives, so this failure IS resumable — but only with the
@@ -6482,14 +6732,22 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         // file. Advisory: it warns on any problem and never fails the install.
         unprovenBridgeConfigPending = false;
         await reconcileBridgeConfigAfterPing(deps, repoName, scaffoldedBridgeConfigText);
+        if (modernAttempt) {
+            const reconciled = parseBridgeConfigToml(await deps.readFile(bridgeConfigPath(deps.cwd)));
+            if (!reconciled.ok || reconciled.manifest.repoName !== repoName)
+                return fatal("Installation incomplete: canonical configuration read-back failed. Preserve proof and resume from this folder.");
+        }
         // ---- BAPI-1221 (S2): persist the captured posture, now that connectivity
         // is validated and `repoName`/`apiKey` are both final. Overwrites any
         // existing value unconditionally — the old value is never read first. A
         // no-answer (or a prompt/stream exception the picker already absorbed)
         // reports the same fail-open remediation without ever attempting a write.
+        let persistedPosture;
         if (optimizationPostureSelection) {
             const postureResult = await persistOptimizationPosture(deps, baseUrl, apiKey, repoName, optimizationPostureSelection);
             reportOptimizationPostureOutcome(log, postureResult, optimizationPostureSelection, selectedPlatforms[0]);
+            if (postureResult.kind === "success")
+                persistedPosture = optimizationPostureSelection;
         }
         else if (optimizationPostureEligible) {
             log(OPTIMIZATION_POSTURE_UNCHANGED_MESSAGE);
@@ -6535,6 +6793,21 @@ 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 });
+        if (modernAttempt) {
+            if (writeResult.skipped.length || writeResult.written.length !== targets.length) {
+                return fatal("Installation incomplete: selected host configuration was declined or failed. Recovery proof is preserved.");
+            }
+            for (const item of writeResult.written) {
+                const config = JSON.parse(await deps.readFile(path.join(deps.cwd, item.relPath)));
+                const target = targets.find(target => target.relPath === item.relPath);
+                const binding = target ? config[target.topLevelKey]?.[item.registrationKey] : undefined;
+                const keyMatches = item.mode === "secret-free"
+                    ? binding?.env && !Object.prototype.hasOwnProperty.call(binding.env, "BAPI_API_KEY")
+                    : binding?.env?.BAPI_API_KEY === apiKey;
+                if (binding?.env?.BAPI_REPO_NAME !== repoName || !keyMatches)
+                    return fatal("Installation incomplete: host binding read-back failed. Recovery proof is preserved.");
+            }
+        }
         // BAPI-807: a both-key project config is a FAIL-LOUD condition, not an
         // ordinary skip. Nothing was written (the pre-write scan returned before the
         // first target), and continuing would report a successful install over a
@@ -6572,6 +6845,8 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         const globalProvisioning = await provisionSelectedGlobalTargets(deps, selectedPlatforms, entry, needKeyManual);
         for (const line of globalProvisioning.logLines)
             log(line);
+        if (modernAttempt && !globalProvisioning.complete)
+            return fatal("Installation incomplete: a selected host requires completion. Recovery proof is preserved.");
         // BAPI-807: a global target that refused because it already carries both
         // registrations is fail-loud, exactly like the project-config case above —
         // never an ordinary vendor fallback the run can shrug off.
@@ -6653,7 +6928,21 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         // in bootstrap mode the exchange loop above is the ONLY way to reach here, so the
         // two are equivalent — but keying promotion to the same state that justifies the
         // catch block's resume guidance makes that invariant explicit and un-driftable.
-        if (bootstrapExchangeSucceeded) {
+        if (modernAttempt) {
+            currentStep = INSTALL_BRIDGE_STEP_LABELS.persistCredential;
+            log(currentStep);
+            let promoted = await promoteModernBootstrapCredential(modernAttempt.scope, modernAttempt.record, credentialWriteDeps, options.force);
+            if (!promoted.ok && promoted.needsConsent && deps.isTTY && deps.promptLine) {
+                const consent = (await deps.promptLine("Replace the existing canonical project credential? [y/N]: ")).trim().toLowerCase();
+                if (consent === "y" || consent === "yes")
+                    promoted = await promoteModernBootstrapCredential(modernAttempt.scope, modernAttempt.record, credentialWriteDeps, true, promoted.observedKey);
+            }
+            if (!promoted.ok)
+                return fatal("Installation incomplete: credential promotion failed. Preserve proof and resume from the same folder.");
+            log(formatProjectCredentialStoreLine(repoName, credentialStorePath));
+            log(`Project '${modernAttempt.displayName}' installed successfully.`);
+        }
+        else if (bootstrapExchangeSucceeded) {
             // FAIL-CLOSED (unlike normal mode below). The pending secret IS the minted admin
             // key — if it never lands under bapi:<repo>, the user has a live key they cannot
             // resolve. Promotion removes the pending record and writes the credential in one
@@ -6742,8 +7031,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         // selected set. `writeAgentNotes` never touches `writeMcpInstallState` or any
         // other persisted install-state contract — consent is re-evaluated every run.
         const notesPlan = resolveAgentNotesTargets(selectedPlatforms);
-        const notesPlatformLabels = labelsForPlatforms(notesPlan.supportedPlatforms);
-        const notesOffer = await offerAgentGuidanceNotes(deps, log, notesPlan.targets, notesPlatformLabels);
+        const notesOffer = offerAgentGuidanceNotes(deps, notesPlan.targets);
         let notesResult;
         let notesWriteFailed = false;
         if (notesOffer.kind === "consented") {
@@ -6759,6 +7047,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 for (const file of notesResult.files) {
                     if (file.status === "failed") {
                         errorLog(`  warning: could not update ${file.target} with agent notes (${file.reason}).`);
+                        errorLog(`  Resolve the reported issue in ${file.target}, then rerun an interactive install to retry guidance.`);
                     }
                 }
             }
@@ -6772,6 +7061,42 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         const notesSummaryLine = buildAgentNotesSummaryLine(notesOffer, notesResult, notesWriteFailed, notesPlan.unsupportedPlatforms);
         if (notesSummaryLine)
             log(notesSummaryLine);
+        // The removal hint only when something was actually written (BAPI-1448).
+        const notesWrittenTargets = (notesResult?.files ?? [])
+            .filter((f) => f.status === "written")
+            .map((f) => f.target);
+        if (notesWrittenTargets.length > 0)
+            log(INSTALL_BRIDGE_AGENT_NOTES_REMOVAL_HINT);
+        const notesUnchangedTargets = (notesResult?.files ?? [])
+            .filter((f) => f.status === "skipped")
+            .map((f) => f.target);
+        // ---- BAPI-1398: Bridge permission rules for /drive-epic-run (Claude Code) ----
+        // After the durable install work and the other offers, before the session
+        // opens. Project rules are written as part of the normal install. The user
+        // settings change is NOT part of install (BAPI-1448): it lives in the
+        // `bridge-permissions` subcommand, offered in-session by /drive-epic-run. Every
+        // failure here is advisory: a malformed settings file is reported and skipped,
+        // and the install still completes.
+        if (selectedPlatforms.includes("claude-code")) {
+            try {
+                await (deps.installBridgePermissions ?? runBridgePermissionsInstallStep)({
+                    cwd: deps.cwd,
+                    homeDir: deps.homedir(),
+                    env: deps.env,
+                    readFile: deps.readFile,
+                    writeFile: (p, data) => deps.writeFile(p, data, { encoding: "utf-8" }),
+                    mkdir: (p, o) => deps.mkdir(p, o),
+                    log,
+                    errorLog,
+                    ensureGitignored: (relPath) => ensureGitignoredShared(deps.cwd, relPath, gitignoreDeps),
+                    // BAPI-1446: pin the SessionStart upgrade-notice hook to the effective Claude Code pin.
+                    sessionStartHook: { pinnedVersion: await discoverClaudeCodeEffectivePin({ cwd: deps.cwd, readFile: deps.readFile, targetVersion: VERSION }) },
+                });
+            }
+            catch {
+                errorLog("  warning: could not write Bridge's permission rules (unexpected error; non-fatal).");
+            }
+        }
         // ---- Step 3b (await) — settle the background pre-warm before the session opens ----
         // The warm was kicked off (only on a spawn-capable path) right after the
         // launch-command guards; await it HERE so the bucket is settled before the spawned
@@ -6794,6 +7119,30 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                     `The first MCP launch may pay a one-time cold install and could be slow. ${MCP_TIMEOUT_GUIDANCE}`);
             }
         }
+        for (const line of buildInstallBridgeMaintenanceHint())
+            log(line);
+        await showFirstBuildAdvisory(finalAgentName);
+        // ---- BAPI-1448: the defaults summary, once, right before the launch consent ----
+        // Every input is already in memory except the optional ticket prefix, which is one
+        // bounded read of the manifest the GitHub offer already uses. Any failure there just
+        // omits the cell: the summary never blocks or changes the install's outcome.
+        let ticketPrefix;
+        try {
+            const details = await fetchGithubConfigurationDetails({ fetch: deps.fetch, baseUrl, apiKey }, repoName);
+            ticketPrefix = details.ticketPrefix;
+        }
+        catch {
+            ticketPrefix = undefined;
+        }
+        log("");
+        log(buildInstallBridgeDefaultsSummary({
+            displayName: modernAttempt?.displayName ?? repoName,
+            ...(ticketPrefix ? { ticketPrefix } : {}),
+            isNewProject: Boolean(modernAttempt) || bootstrapExchangeSucceeded,
+            ...(persistedPosture ? { persistedPosture } : {}),
+            claudeCodeSelected: selectedPlatforms.includes("claude-code"),
+            guidance: { written: notesWrittenTargets, unchanged: notesUnchangedTargets },
+        }));
         // ---- Step 5 — consent-gate, then spawn the selected tool (or print continuation) ----
         // AC-7: for a spawn-capable path, ask Y/N first (`requestInstallBridgeLaunchConsent`
         // resolves to no-spawn without prompting on a non-TTY run). A decline, a no-launchable
@@ -6908,3 +7257,124 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         }
     }
 }
+class ModernInstallRecoveryError extends Error {
+}
+function modernWriteDeps(deps) {
+    return { env: deps.env, homedir: deps.homedir, platform: deps.platform, readFile: deps.readFile,
+        mkdir: deps.mkdir, writeFile: deps.writeFile, rename: deps.rename, chmod: deps.chmod, unlink: deps.unlink, open: deps.open };
+}
+async function redeemModernInstallAttempt(deps, options, baseUrl, token, signupEmail, selfServe) {
+    if (!deps.realpath)
+        throw new ModernInstallRecoveryError("Canonical folder resolution is unavailable. Contact installation support.");
+    const folder = await deps.realpath(deps.cwd);
+    const folderDigest = fingerprintBootstrapFields("bridge-bootstrap-folder-v1", [baseUrl, folder]);
+    const signupLocator = `bootstrap-pending:signup:${folderDigest}`;
+    const makeScope = (locator) => ({ baseUrl, folder, locator, folderReference: `bootstrap-folder:${folderDigest}` });
+    let fingerprint = token ? fingerprintBootstrapInvite(token, baseUrl) : "";
+    let scope = makeScope(selfServe ? signupLocator : `bootstrap-pending:invite:${fingerprint}`);
+    const writeDeps = modernWriteDeps(deps);
+    const loaded = await lookupModernBootstrapRecord(scope, writeDeps);
+    if (!loaded.ok)
+        throw new Error(loaded.error);
+    let record = loaded.record;
+    const resumed = record !== null;
+    let label = record?.label ?? options.displayName;
+    if (label === undefined) {
+        if (!deps.isTTY || !deps.promptLine)
+            throw new ModernInstallRecoveryError("Modern invite creation requires --display-name in a non-interactive terminal.");
+        // BAPI-1448: a valid folder name is the label, with no question. The prompt
+        // survives only for a folder name the validator rejects.
+        let suggestion = "";
+        try {
+            suggestion = validateBootstrapDisplayName(path.basename(folder));
+        }
+        catch { /* explicit label required */ }
+        if (suggestion) {
+            label = suggestion;
+        }
+        else {
+            label = validateBootstrapDisplayName(await deps.promptLine("Project display name: "));
+        }
+    }
+    if (selfServe) {
+        if (!deps.isTTY || !deps.promptLine)
+            throw new ModernInstallRecoveryError("Self-serve email verification requires an interactive terminal.");
+        if (!record) {
+            const intent = await prepareModernBootstrapSignup(scope, label, signupEmail, () => generateBootstrapKeySecret(deps.randomBytes), writeDeps);
+            if (!intent.ok || !intent.record)
+                throw new Error(intent.ok ? "Signup proof missing." : intent.error);
+            record = intent.record;
+            const requested = await requestSelfServeChallenge(deps, baseUrl, signupEmail);
+            if (!requested.ok)
+                throw new ModernInstallRecoveryError("Signup handle could not be established. Preserve recovery proof; contact installation support before restarting signup.");
+            const saved = await mutateModernBootstrapRecord(scope, writeDeps, current => {
+                if (!current)
+                    throw new ModernInstallRecoveryError("Signup proof missing.");
+                return { ...current, challengeHandle: requested.handle, challengeExpiresAt: requested.expiresAt };
+            });
+            if (!saved.ok || !saved.record)
+                throw new Error(saved.ok ? "Signup proof missing." : saved.error);
+            record = saved.record;
+        }
+        if (record.replayToken && record.fingerprint) {
+            token = record.replayToken;
+            fingerprint = record.fingerprint;
+            scope = makeScope(`bootstrap-pending:invite:${fingerprint}`);
+        }
+        else {
+            if (!record.challengeHandle || !record.challengeExpiresAt)
+                throw new ModernInstallRecoveryError("The previous signup response is unresolved. Preserve proof and contact installation support before restarting.");
+            if (Date.parse(record.challengeExpiresAt) <= deps.now())
+                throw new ModernInstallRecoveryError("The saved verification challenge expired. Preserve proof and contact installation support.");
+            logVerificationCodeLeadIn(deps.log, record.signupEmail ?? signupEmail);
+            const code = await promptForVerificationCode(deps, deps.log);
+            if (!code)
+                throw new ModernInstallRecoveryError("Verification incomplete. Resume the same signup from this folder.");
+            const verified = await verifySelfServeChallenge(deps, baseUrl, record.challengeHandle, code);
+            if (!verified.ok)
+                throw new ModernInstallRecoveryError("Verification did not complete. Preserve proof and resume the same signup.");
+            token = verified.token;
+            fingerprint = fingerprintBootstrapInvite(token, baseUrl);
+            const inviteScope = makeScope(`bootstrap-pending:invite:${fingerprint}`);
+            const transitioned = await transitionModernBootstrapSignup(makeScope(signupLocator), inviteScope, fingerprint, token, record.challengeHandle, writeDeps);
+            if (!transitioned.ok || !transitioned.record)
+                throw new Error(transitioned.ok ? "Signup proof missing." : transitioned.error);
+            record = transitioned.record;
+            scope = inviteScope;
+        }
+    }
+    else {
+        const prepared = await prepareModernBootstrapInvite(scope, fingerprint, label, () => generateBootstrapKeySecret(deps.randomBytes), writeDeps);
+        if (!prepared.ok || !prepared.record)
+            throw new Error(prepared.ok ? "Invite proof missing." : prepared.error);
+        record = prepared.record;
+    }
+    if (!record)
+        throw new ModernInstallRecoveryError("Recovery proof missing.");
+    if (resumed)
+        deps.log("Resuming the original installation; changing the entered label does not rename its project.");
+    if (record.canonical && record.serverLabel) {
+        const ping = await verifyConnectivity(deps, baseUrl, record.canonical, record.keySecret);
+        if (!ping.ok)
+            throw new ModernInstallRecoveryError("Canonical connectivity failed. Preserve proof and resume the same attempt.");
+        return { scope, record, repoName: record.canonical, displayName: record.serverLabel };
+    }
+    let exchange = await exchangeBootstrapInvite(deps, baseUrl, token, { repoDisplayName: record.label }, record.keySecret);
+    if (!exchange.ok && exchange.kind === "email-required") {
+        const email = deps.isTTY ? await promptForBoundedEmail(deps, INVITE_EMAIL_PROMPT) : undefined;
+        if (!email)
+            throw new ModernInstallRecoveryError("An email is required; resume the same invite in an interactive terminal.");
+        exchange = await exchangeBootstrapInvite(deps, baseUrl, token, { repoDisplayName: record.label }, record.keySecret, email);
+    }
+    if (!exchange.ok && exchange.message.includes("Creation outcome is unknown"))
+        throw new ModernInstallRecoveryError("Creation outcome is unknown. Preserve recovery proof and rerun the same attempt from the original folder and invite/signup.");
+    if (!exchange.ok || !exchange.displayName)
+        throw new ModernInstallRecoveryError("Creation or replay did not complete. Preserve proof and rerun from this folder with the same invite/signup; verify server compatibility or contact installation support.");
+    const checkpoint = await checkpointModernBootstrapIdentity(scope, record, exchange.repoName, exchange.displayName, writeDeps);
+    if (!checkpoint.ok || !checkpoint.record)
+        throw new Error(checkpoint.ok ? "Checkpoint missing." : checkpoint.error);
+    const ping = await verifyConnectivity(deps, baseUrl, exchange.repoName, record.keySecret);
+    if (!ping.ok)
+        throw new ModernInstallRecoveryError("Canonical connectivity failed. Preserve proof and resume the same attempt.");
+    return { scope, record: checkpoint.record, repoName: exchange.repoName, displayName: exchange.displayName };
+}