@bridge_gpt/mcp-server 0.2.54 → 0.2.56

package/build/install-bridge.js

@@ -149,9 +149,13 @@ import { VERSION } from "./version.generated.js";
 import { validateRepoName } from "./bridge-config.js";
 import { MCP_HOST_TARGETS, HOST_PLATFORM_ORDER, allHostTargets, agentForPlatform, isHostPlatformId, detectDefaultPlatforms, hostAdapterForTarget, } from "./mcp-host-targets.js";
 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 { recordInstalledConductorCapability, recordInstalledExecutorServiceUnit, recordInstalledProjectArtifact, writeMcpInstallState, } from "./mcp-install-state.js";
+// BAPI-1207: opt-in cross-platform agent notes (AGENTS.md / CLAUDE.md).
+import { AGENT_GUIDANCE } from "./agent-guidance.generated.js";
+import { resolveAgentNotesTargets, writeAgentNotes, } from "./agent-notes.js";
 // Executor provisioning (BAPI-779). The generator and the lifecycle module are
 // imported DIRECTLY and driven programmatically — never by spawning
 // `executor install-service` as a subprocess, which would lose the typed plan,
@@ -178,8 +182,8 @@ import { 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 { resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
-import { buildGenericAgentShellCommand, getDefaultSpawnTerminalTabForPlatform, detectTerminal, createDefaultStartTicketsDeps, materializeWorkerLaunchCommand, MAX_TERMINAL_COMMAND_BYTES, } from "./start-tickets.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";
 /** Redaction sentinel — the API-key value is NEVER printed; this stands in. */
 export const REDACTED_API_KEY = "<REDACTED>";
 /**
@@ -226,8 +230,16 @@ export function buildPrewarmCommandPreview() {
  * automatic, gated by the existing readiness funnel
  * (`maybe_auto_parse_if_ready`), with no prompt on any path.
  */
-export const INSTALL_BRIDGE_AGENT_PROMPT = "Execute the /install-bridge command in the install-spawn context (tell the command it is running " +
-    "in the install-spawn context so it SKIPS its Stage 8, Stage 9, and Stage 10 offers). " +
+export const INSTALL_BRIDGE_AGENT_PROMPT = "Run /install-bridge now, with no arguments — that is the entire invocation. You are in the " +
+    "install-spawn context: that is a mode this prompt establishes in plain language, not a " +
+    "command-line option, so never convert it into --context install-spawn or any other flag. The " +
+    "Bridge MCP tools named throughout this command are available only inside this currently running " +
+    "agent session — never invoke them through Bash or by constructing a direct HTTP request. " +
+    "/install-bridge owns and automatically executes its own internal stages; do not reproduce, " +
+    "narrate as separate manual steps, or hand-execute those stages yourself. Never place the " +
+    "API-key value in a Bash command, its arguments, printed output, a log line, an error message, " +
+    "or a file you write; verify connectivity with the in-session ping MCP tool only — never through " +
+    "an environment export, echo, or any other shell probe. " +
     "The command owns its own Stage 2 decision and evaluates it in a fixed order from the install " +
     "manifest — do NOT force an outcome. `configured == true` is JOIN MODE; otherwise a manifest whose " +
     "`greenfield_setup_path` field is already set is GREENFIELD REPORT-ONLY; otherwise the command's " +
@@ -255,6 +267,31 @@ export const INSTALL_BRIDGE_AGENT_PROMPT = "Execute the /install-bridge command
     "back to the complete tool_capabilities catalog or the workflows collection. If " +
     "concise_tool_capabilities is missing or malformed, take the command's single fallback line and " +
     "render nothing else in its place. " +
+    "The same manifest response also carries a SEPARATE top-level human_setup field (contract v9) — an " +
+    "ordered list naming each remaining unconfigured integration and what finishing it unlocks, " +
+    "additive over the same checklist integrations already carries. It is never a third section of " +
+    "concise_tool_capabilities; render it as its own separate block, after the two-section report above. " +
+    "Absent (an older compatible manifest), malformed (not a list, or an entry missing display_text), or " +
+    "a valid empty list all render NOTHING for this block — no heading, no fabricated completion line, " +
+    "no invented setup advice; the two-section report above still renders unaffected either way. A " +
+    "valid non-empty list renders under the heading 'What finishing setup unlocks', one compact item per " +
+    "entry in the server's given order, using human_setup[].display_text as that item's entire " +
+    "substantive content, byte-for-byte — never summarized, reworded, sorted, filtered, merged, or " +
+    "recomposed from configure_in, setup_instructions, required_for, integrations, or any tool/workflow " +
+    "catalog. The same server-authority rule the concise capability report already follows extends to " +
+    "this field. " +
+    "Plain-language narration (BAPI-1174): explain each major action you take — reading the manifest, " +
+    "applying configuration, persisting the routing credential, rendering the capability report — in a " +
+    "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 " +
+    "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, " +
+    "start-tickets, and the like) or to any value a stage marks as server-authored and rendered " +
+    "verbatim (the concise capability report, human_setup display text, a next_step.command string) — " +
+    "those are never reworded, curated, or filtered by you either way. " +
     "In the install-spawn context Stage 6 must STILL call persist_routing_credential, but must NOT " +
     "print or summarize its SUCCESSFUL result anywhere — no 'Stored routing credential for …' line, " +
     "and no restatement of that target or path in any later summary or Return section — because the " +
@@ -352,13 +389,13 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         ...INSTALL_BRIDGE_ONBOARDING_CHOICES.map((choice) => `  ${choice}`),
         "There is NO default — pressing Enter selects nothing; you must type 1 or 2 (one",
         "blank or invalid answer re-prompts once, then exits with guidance). Answering 1",
-        "opens a single hidden token prompt: paste whatever you were given and its SHAPE",
-        "picks the route — a bootstrap invite (bapi_inv_…) is redeemed to CREATE a new",
-        "project and mint your first admin key, while a Bridge API key connects to the",
-        "project that already exists. You are never asked which kind of token you hold.",
-        "Answering 2 prompts for an email and creates a brand-new Bridge workspace for",
-        "you (the self-serve flow). That question is asked ONLY for a bare interactive",
-        "run: passing ANY flag, setting BAPI_API_KEY, or running without an interactive",
+        "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",
+        "bare interactive run: passing ANY flag, setting BAPI_API_KEY, or running without an interactive",
         "terminal keeps the existing deterministic behavior and no prompt.",
         "",
         "On that bare run the route is INFERRED, so it is only announced — the detected",
@@ -426,7 +463,7 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "                    the code is entered — no workspace, no project, no API key.",
         "                    Delivery is asynchronous, so the message arrives shortly",
         "                    after you are prompted rather than instantly. The code",
-        "                    expires 60 minutes after it is requested, and you can ask",
+        "                    expires 4 hours after it is requested, and you can ask",
         "                    for a new one if it does not arrive; earlier codes keep",
         "                    working until one is accepted.",
         "",
@@ -493,7 +530,7 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "                                prompting, or spawning anything. With --invite it",
         "                                also never calls the exchange endpoint and never",
         "                                generates or stores a secret.",
-        "  --agent claude|cursor-agent   Explicit launch override for the post-install",
+        "  --agent claude|cursor-agent|codex  Explicit agent choice for post-install",
         "                                session — it always wins, and there is NO Claude",
         "                                default. Without it the launch tool is derived",
         "                                from your selection: Claude Code opens `claude`.",
@@ -502,9 +539,11 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "                                session); selecting Cursor writes .cursor/mcp.json",
         "                                and prints how to finish by running /install-bridge",
         "                                in a new Cursor session. A selection whose tools have",
-        "                                no agentic CLI (e.g. Copilot) likewise opens nothing",
+        "                                no supported auto-launch path (e.g. Copilot) opens nothing",
         "                                and prints how to finish configuring later. Passing",
-        "                                --agent cursor-agent still force-spawns it.",
+        "                                --agent cursor-agent still force-spawns it. Codex",
+        "                                is accepted only for manual continuation: neither",
+        "                                this bootstrap nor start-tickets launches it yet.",
         "  -h, --help                    Show this help.",
         "",
         "Subcommands:",
@@ -827,7 +866,7 @@ export const INSTALL_BRIDGE_GITHUB_CONNECT_PROMPT = "Connect GitHub? [y/N]: ";
  * Reuses the shared connect-github flow rather than duplicating the API, polling,
  * browser, or picker logic — there is exactly one implementation of that handshake.
  */
-export async function offerGithubConnection(repoName, baseUrl, deps, log) {
+export async function offerGithubConnection(repoName, baseUrl, deps, log, session) {
     // No prompt surface → no offer. Never assume consent on a non-interactive run.
     if (!deps.isTTY || !deps.promptLine)
         return;
@@ -875,7 +914,12 @@ export async function offerGithubConnection(repoName, baseUrl, deps, log) {
             return; // declining is a normal outcome
         const connectDeps = createDefaultConnectGithubDeps();
         const code = await runGithubConnectionFlow(connectDeps, api, repoName);
-        if (code !== 0) {
+        if (code === 0) {
+            // BAPI-1171: only a CONFIRMED success suppresses the Bitbucket offer below —
+            // a decline, failure, or thrown error must never look like a connection.
+            session.vcsConnected = true;
+        }
+        else {
             log("  note: GitHub was not connected. Your install is complete — connect GitHub later with " +
                 `'npx -y ${MCP_PACKAGE_NAME}@latest connect-github --repo ${repoName}'.`);
         }
@@ -915,10 +959,15 @@ export const INSTALL_BRIDGE_BITBUCKET_CONNECT_PROMPT = "Connect Bitbucket? [y/N]
  * Reuses the shared connect-bitbucket flow rather than duplicating the API, polling,
  * browser, or picker logic — there is exactly one implementation of that handshake.
  */
-export async function offerBitbucketConnection(repoName, baseUrl, deps, log) {
+export async function offerBitbucketConnection(repoName, baseUrl, deps, log, session) {
     // No prompt surface → no offer. Never assume consent on a non-interactive run.
     if (!deps.isTTY || !deps.promptLine)
         return;
+    // BAPI-1171: a GitHub connection made earlier in THIS run already leaves the
+    // project with a connected VCS provider — skip provider lookup, prompting, the
+    // browser flow, and the connection handshake entirely rather than asking again.
+    if (session.vcsConnected)
+        return;
     try {
         const credDeps = {
             env: deps.env,
@@ -971,6 +1020,88 @@ export async function offerBitbucketConnection(repoName, baseUrl, deps, log) {
             `Bitbucket later with 'npx -y ${MCP_PACKAGE_NAME}@latest connect-bitbucket --repo ${repoName}'.`);
     }
 }
+/** Default-No agent-notes offer prompt. Mirrors {@link INSTALL_BRIDGE_GITHUB_CONNECT_PROMPT}. */
+export const INSTALL_BRIDGE_AGENT_NOTES_PROMPT = "Add cross-platform agent notes? [y/N]: ";
+/**
+ * The offer-context lines printed immediately before the agent-notes prompt
+ * (BAPI-1207). Names the applicable file(s) and states the marker-scoped,
+ * non-destructive contract up front — mirrors the GitHub/Bitbucket offers'
+ * "explain before asking" convention.
+ */
+export function buildAgentNotesOfferContext(targets) {
+    return [
+        "",
+        "Step 4c — optional: cross-platform agent notes.",
+        `  This creates or refreshes a Bridge-owned region in ${targets.join(" and ")} with situation-`,
+        "  to-tool guidance for a few Bridge MCP tools. Only that marked region is created or",
+        "  refreshed — any existing content in the file, 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).
+ *
+ * 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.
+ */
+export async function offerAgentGuidanceNotes(deps, log, 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)
+        return { kind: "headless-skip" };
+    try {
+        for (const line of buildAgentNotesOfferContext(targets))
+            log(line);
+        const answer = (await deps.promptLine(INSTALL_BRIDGE_AGENT_NOTES_PROMPT)).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" };
+    }
+}
+/**
+ * One secret-free summary line for the final install output (BAPI-1207). Never
+ * reveals guidance content, file bytes, or a credential — only which files
+ * were touched, skipped, or failed, and which selected platforms have no
+ * supported notes convention (currently only Windsurf).
+ */
+export function buildAgentNotesSummaryLine(offer, result, writeFailed, unsupportedPlatforms) {
+    const unsupportedNote = unsupportedPlatforms.length > 0
+        ? ` (${unsupportedPlatforms.join(", ")}: no supported agent-notes convention)`
+        : "";
+    if (offer.kind === "not-applicable") {
+        return unsupportedPlatforms.length > 0 ? `Agent notes: not written${unsupportedNote}.` : undefined;
+    }
+    if (offer.kind === "headless-skip") {
+        return `Agent notes: skipped (non-interactive session)${unsupportedNote}.`;
+    }
+    if (offer.kind === "declined") {
+        return `Agent notes: skipped (declined)${unsupportedNote}.`;
+    }
+    if (writeFailed || !result) {
+        return `Agent notes: could not be written (unexpected error)${unsupportedNote}.`;
+    }
+    const written = result.files.filter((f) => f.status === "written").map((f) => f.target);
+    const unchanged = result.files.filter((f) => f.status === "skipped").map((f) => f.target);
+    const failed = result.files.filter((f) => f.status === "failed").map((f) => f.target);
+    const parts = [];
+    if (written.length > 0)
+        parts.push(`written to ${written.join(", ")}`);
+    if (unchanged.length > 0)
+        parts.push(`already up to date in ${unchanged.join(", ")}`);
+    if (failed.length > 0)
+        parts.push(`failed for ${failed.join(", ")}`);
+    return `Agent notes: ${parts.join("; ")}${unsupportedNote}.`;
+}
 /**
  * Echoed single-line prompt on stderr (used for repo confirmation / value).
  * Exported so `index.ts`'s `--init` can share the exact same prompt mechanics
@@ -1484,11 +1615,18 @@ export async function resolveInviteToken(options, deps) {
  * is never written to a log line; it is only ever echoed as the user's own keystrokes
  * and placed in the mint request body.)
  *
- * No email-format validation is performed here — only surrounding whitespace is
- * trimmed, matching the other CLI input seams and the server's deliberately
- * permissive "stored unvalidated" contract (D-2). The entered value is never echoed
+ * Explicit sources (`--email`, `BAPI_SIGNUP_EMAIL`) still take only trimmed
+ * whitespace — matching the other CLI input seams and the server's deliberately
+ * permissive "stored unvalidated" contract (D-2). The interactive prompt, added by
+ * BAPI-1171, is bounded and additionally requires the trimmed value to match a
+ * minimal `local@domain` shape before it is accepted — mirroring the one-hint/
+ * one-re-prompt contract {@link resolveInstallBridgeOnboardingBranchForRun} uses,
+ * so an unanswerable prompt cannot loop forever. The entered value is never echoed
  * back in an error message.
  */
+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 async function resolveSignupEmail(options, deps) {
     // BAPI-757 (R-3 / AC-9): self-serve signup now REQUIRES an interactive terminal,
     // and the check runs FIRST — before `--email` and before `BAPI_SIGNUP_EMAIL` —
@@ -1507,9 +1645,19 @@ export async function resolveSignupEmail(options, deps) {
     if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
         return { ok: true, value: fromEnv.trim() };
     }
-    const entered = (await deps.promptLine("Email for Bridge workspace setup: ")).trim();
-    if (entered.length > 0) {
-        return { ok: true, value: entered };
+    const promptLine = deps.promptLine;
+    // BAPI-1171: bounded to two reads total — the first answer, then ONE re-prompt
+    // after a single hint line. EOF resolves as an empty value (promptLineViaReadline
+    // resolves "" on close), which fails the shape check like any other blank
+    // answer, so it costs one re-prompt and then fails cleanly rather than hanging.
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const raw = await promptLine("Email for Bridge workspace setup (required): ");
+        const entered = String(raw ?? "").trim();
+        if (INSTALL_BRIDGE_SIGNUP_EMAIL_SHAPE.test(entered)) {
+            return { ok: true, value: entered };
+        }
+        if (attempt === 0)
+            deps.log(INSTALL_BRIDGE_SIGNUP_EMAIL_HINT);
     }
     return { ok: false, error: "No email entered." };
 }
@@ -1557,15 +1705,16 @@ export function resolveInstallBridgeOnboardingBranch(options, env) {
 export const INSTALL_BRIDGE_KEY_SELECTOR_PROMPT = "Welcome to Bridge - do you have a token yet?";
 /**
  * The question's numbered options, in render order. Index + 1 is the accepted
- * token, exactly as before — only the option SET narrowed from three to two.
+ * 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 "Yes" leads to ONE
+ * tokens as far as this question is concerned, and answering "2" leads to ONE
  * hidden prompt whose value selects the route by shape.
  */
 export const INSTALL_BRIDGE_ONBOARDING_CHOICES = [
-    "1. Yes, I have received a token",
-    "2. No, I need one",
+    "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: ";
@@ -1579,9 +1728,9 @@ export const INSTALL_BRIDGE_ONBOARDING_CHOICE_HINT = "Enter 1 or 2.";
  * 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 if you already have a token " +
-    "(an invite or an API key — either one is accepted at the hidden prompt) or 2 to sign up " +
-    "with just an email. Non-interactively, pass --api-key <key> (or set BAPI_API_KEY) for an " +
+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). " +
+    "Non-interactively, pass --api-key <key> (or set BAPI_API_KEY) for an " +
     "existing project, --invite if you were sent an invite token, or --email <addr> to sign up.";
 /**
  * Interactive wrapper around {@link resolveInstallBridgeOnboardingBranch}.
@@ -1651,20 +1800,21 @@ export async function resolveInstallBridgeOnboardingBranchForRun(options, deps,
         // it can never hang or silently select a branch.
         for (let attempt = 0; attempt < 2; attempt += 1) {
             const answer = (await promptLine(INSTALL_BRIDGE_ONBOARDING_CHOICE_PROMPT)).trim();
-            // BAPI-708 (A-1): the accepted tokens are now exactly 1/2 (no letters, no
-            // aliases), preserving the one-strict-line contract. "Yes" routes to the
+            // 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")
-                return { ok: true, branch: { kind: "have-key" }, credentialIntent: "inferred" };
-            if (answer === "2") {
+            if (answer === "1") {
                 return {
                     ok: true,
                     branch: { kind: "need-key", method: "self-serve" },
                     credentialIntent: "inferred",
                 };
             }
+            if (answer === "2")
+                return { ok: true, branch: { kind: "have-key" }, credentialIntent: "inferred" };
             if (attempt === 0)
                 deps.log(INSTALL_BRIDGE_ONBOARDING_CHOICE_HINT);
         }
@@ -1854,8 +2004,8 @@ export function promptMultiSelectViaReadline(promptText, options, input = proces
  *   2. interactive multi-select on a TTY (AC-2: no row pre-selected — the picker
  *      starts empty and 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 or
- *      Copilot CLI just because a global directory exists).
+ *      detected Copilot VS Code and Cursor automatic targets (never Codex just
+ *      because a global directory exists).
  */
 export async function resolveSelectedHostPlatforms(deps, options) {
     // 1. Explicit --tools (empty array is an explicit empty selection).
@@ -1909,7 +2059,7 @@ async function resolveDryRunHostPlatforms(deps, options) {
  * Launch agents install-bridge will NEVER auto-spawn from a host SELECTION, even
  * though their CLI exists and the host's MCP config is still written normally.
  *
- * `cursor-agent` is excluded: its FIRST-RUN workspace-trust handshake collapses
+ * `cursor-agent` and `codex` are excluded. Cursor's FIRST-RUN workspace-trust handshake collapses
  * under our osascript-spawned launch — the "Workspace Trust Required" dialog
  * renders, then the process exits before a selection registers, so configuration
  * never runs (reproduced on a pristine, never-trusted workspace; the identical
@@ -1917,16 +2067,20 @@ async function resolveDryRunHostPlatforms(deps, options) {
  * cursor-agent's own behavior on an untrusted workspace and is not something our
  * launch can drive, so we treat Cursor as a no-auto-launch host: selecting it
  * still writes `.cursor/mcp.json`, then prints the manual `/install-bridge`
- * continuation (same path as Copilot/Codex/Windsurf, which have no agentic CLI).
+ * continuation. Codex does have an agentic CLI, but this workflow is a Claude
+ * `/install-bridge` command and its native skill is not available until after
+ * the bootstrap it would be asked to run completes.
  * An explicit `--agent cursor-agent` override still spawns it — a deliberate,
  * documented power-user opt-in that bypasses this selection guard.
  */
-const SELECTION_NON_LAUNCHABLE_AGENTS = new Set(["cursor-agent"]);
+const SELECTION_NON_LAUNCHABLE_AGENTS = new Set(["cursor-agent", "codex"]);
+/** Agents whose interactive command surface cannot run the post-install recipe yet. */
+const INSTALL_BRIDGE_UNSUPPORTED_AGENTS = new Set(["codex"]);
 /**
  * Resolve the post-install launch decision from the selected host platforms and an
  * OPTIONAL explicit `--agent` override (BAPI-657). Pure and total:
  *
- *  - An explicit `--agent` is an ABSOLUTE override (ratified AC-4): a valid explicit
+ *  - An explicit supported `--agent` is an ABSOLUTE override: a valid explicit
  *    agent always returns `spawn(agent)`, regardless of which tools were selected —
  *    the flag is honored even for a host outside the selection, and it bypasses the
  *    {@link SELECTION_NON_LAUNCHABLE_AGENTS} guard below.
@@ -1941,6 +2095,9 @@ const SELECTION_NON_LAUNCHABLE_AGENTS = new Set(["cursor-agent"]);
  */
 export function resolveInstallBridgeLaunchDecision(selectedPlatforms, explicitAgent) {
     if (explicitAgent) {
+        if (INSTALL_BRIDGE_UNSUPPORTED_AGENTS.has(explicitAgent)) {
+            return { kind: "manual", reason: "unsupported-agent-workflow" };
+        }
         return { kind: "spawn", agent: explicitAgent };
     }
     if (selectedPlatforms.length === 0) {
@@ -2137,8 +2294,8 @@ async function buildDetectionContext(deps) {
 /**
  * Resolve which project-local JSON host configs to write for the selected
  * platforms. Only the project-scoped JSON targets (Claude Code, Cursor, Copilot
- * VS Code) are returned here; global targets (Codex, Copilot CLI) and manual
- * targets (Windsurf) are handled by the registry-driven emitter in
+ * VS Code) are returned here; the global target (Codex) and manual targets
+ * (Windsurf) are handled by the registry-driven emitter in
  * `runInstallBridgeCli`. The returned shape is unchanged so the existing
  * read-merge-write path and overwrite-consent detection are preserved.
  */
@@ -2147,7 +2304,7 @@ function hostConfigTargetsForPlatforms(platforms) {
     return HOST_PLATFORM_ORDER.filter((id) => set.has(id))
         .map((id) => MCP_HOST_TARGETS[id])
         .filter((t) => t.scope === "project" && hostAdapterForTarget(t).format === "json")
-        .map((t) => ({ relPath: t.relPath, topLevelKey: hostAdapterForTarget(t).topLevelKey }));
+        .map(toHostConfigTarget);
 }
 /**
  * Derive the human-facing labels for a set of selected platforms, in registry
@@ -2162,7 +2319,7 @@ export function labelsForPlatforms(platforms) {
 }
 /** Project-local host-config metadata sourced from the shared registry/adapter. */
 function toHostConfigTarget(target) {
-    return { relPath: target.relPath, topLevelKey: hostAdapterForTarget(target).topLevelKey };
+    return { target, relPath: target.relPath, topLevelKey: hostAdapterForTarget(target).topLevelKey };
 }
 /** Resolve which project-local host configs to write, mirroring runInit detection. */
 async function resolveHostConfigTargets(deps) {
@@ -2400,9 +2557,10 @@ async function requestTrackedConfigConsent(deps, relPath) {
  * helper governs launcher-token migration only, never credentials.
  */
 export function preserveExistingLauncherArgs(existing, entry) {
+    const existingEntry = asRecord(existing) ?? {};
     const existingArgs = asRecord(existing)?.args;
     const preserved = refreshBridgeApiPackageSpec(existingArgs, currentBridgePackageSpec());
-    return preserved ? { ...entry, args: preserved } : entry;
+    return { ...existingEntry, ...entry, ...(preserved ? { args: preserved } : {}) };
 }
 /**
  * Read-only pre-scan for both-key configs across EVERY project target (BAPI-807).
@@ -2457,7 +2615,8 @@ async function writeHostConfigs(deps, targets, entries, trackedState, ctx) {
         // file that will be skipped never triggers a misleading write-consent prompt.
         if (read.state === "invalid") {
             deps.errorLog(formatInvalidConfigNotice(target.relPath));
-            for (const line of formatSecretFreeManualMerge(target.relPath, target.topLevelKey, entries.secretFree)) {
+            const secretFreeEntry = adaptBridgeEntryForHostTarget(entries.secretFree, target.target);
+            for (const line of formatSecretFreeManualMerge(target.relPath, target.topLevelKey, secretFreeEntry)) {
                 deps.errorLog(line);
             }
             skipped.push({ relPath: target.relPath, reason: "invalid" });
@@ -2511,7 +2670,8 @@ async function writeHostConfigs(deps, targets, entries, trackedState, ctx) {
         // the full template args, `serve` included. The rule is identical for the
         // real-key and secret-free variants: credential safety must not decide whether
         // a launcher is migrated.
-        topLevel[registrationKey] = preserveExistingLauncherArgs(topLevel[registrationKey], entry);
+        const physicalEntry = adaptBridgeEntryForHostTarget(entry, target.target);
+        topLevel[registrationKey] = preserveExistingLauncherArgs(topLevel[registrationKey], physicalEntry);
         config[target.topLevelKey] = topLevel;
         await deps.mkdir(path.dirname(fullPath), { recursive: true });
         await deps.writeFile(fullPath, JSON.stringify(config, null, 2) + "\n", {
@@ -2522,7 +2682,7 @@ async function writeHostConfigs(deps, targets, entries, trackedState, ctx) {
     return { written, skipped, duplicateRegistrations: [] };
 }
 /**
- * Provision the selected GLOBAL (Codex, Copilot CLI) and MANUAL (Windsurf)
+ * Provision the selected GLOBAL (Codex) and MANUAL (Windsurf)
  * targets through the registry-driven emitter (BAPI-635). Project JSON targets
  * are handled by {@link writeHostConfigs}; this covers everything else. Global
  * config paths are never added to the repository .gitignore. Returns secret-free
@@ -3084,6 +3244,15 @@ export const INSTALL_BRIDGE_VERIFY_THROTTLED = "Bridge is at capacity and could
  * hide a real outage behind a version-skew story.
  */
 export const INSTALL_BRIDGE_VERIFY_SERVER_ERROR = "Error: Bridge could not complete verification right now. Nothing was created — wait a few minutes and re-run this command; the code already emailed to you stays valid until it expires.";
+/**
+ * BAPI-1173: printed after a successful verification whose response says, with an
+ * explicit `trial_granted: false`, that this email already used its one free trial.
+ *
+ * Text only — deliberately no URL. The canonical purchase link is authored once,
+ * server-side, and the first metered-work denial already delivers it. Non-metered
+ * work still runs, so this informs rather than blocks.
+ */
+export const INSTALL_BRIDGE_TRIAL_ALREADY_USED = "Your free trial was already used - this project is on the metered plan; add payment to run metered work.";
 /**
  * Local cap on rejected verification attempts before the CLI stops re-prompting.
  *
@@ -3122,6 +3291,25 @@ export const INSTALL_BRIDGE_SIGNUP_UPGRADE_REQUIRED = [
     "",
     `  npx -y ${MCP_PACKAGE_NAME}@latest install --email <addr>`,
 ].join("\n");
+/**
+ * HTTP 403 on the self-serve request or verify call (BAPI-1171).
+ *
+ * Deliberately distinct from {@link INSTALL_BRIDGE_SIGNUP_UPGRADE_REQUIRED}: a 403
+ * means the request was refused before signup logic ran at all — an upgrade would
+ * not change the outcome, so the message names the actual cause instead.
+ */
+export const INSTALL_BRIDGE_SIGNUP_BLOCKED = "Error: Bridge signup is not available from your current network — your network/IP address " +
+    "appears to be blocked. Try again from a different network, or contact Bridge if you believe " +
+    "this is a mistake.";
+/**
+ * A self-serve HTTP status this client has no specific handling for (BAPI-1171).
+ *
+ * Carries only the numeric status — never response text or a body, which could
+ * echo back the email address or another value this client must not print.
+ */
+export function formatSelfServeUnexpectedStatus(status) {
+    return `Error: Bridge signup returned an unexpected response (status ${status}). Try again in a few minutes.`;
+}
 /**
  * Mask an address for display: first character, then the domain.
  *
@@ -3156,7 +3344,12 @@ export function formatChallengeRemaining(expiresAtIso, nowMs) {
         return "This code has expired.";
     if (minutes === 1)
         return "This code is valid for about another minute.";
-    return `This code is valid for about another ${minutes} minutes.`;
+    if (minutes < 60)
+        return `This code is valid for about another ${minutes} minutes.`;
+    if (minutes < 120)
+        return "This code is valid for about another hour.";
+    const hours = Math.floor(minutes / 60);
+    return `This code is valid for about another ${hours} hours.`;
 }
 /**
  * Prompt for the verification code, validating its shape LOCALLY before any
@@ -3246,8 +3439,11 @@ export async function requestSelfServeChallenge(deps, baseUrl, email) {
         });
     }
     catch (err) {
+        // BAPI-1171: the fetch itself failed (DNS, TLS, connection refused, timeout) —
+        // distinct from the server responding with an error status. The caught value
+        // is never inspected; only its category is reported.
         void err;
-        return { ok: false, category: "failed" };
+        return { ok: false, category: "network-error" };
     }
     if (resp.ok) {
         let handle;
@@ -3278,7 +3474,12 @@ export async function requestSelfServeChallenge(deps, baseUrl, email) {
         return { ok: false, category: "unavailable" };
     if (resp.status === 400 || resp.status === 422)
         return { ok: false, category: "invalid" };
-    return { ok: false, category: "failed" };
+    // BAPI-1171: 403 means the caller's network/IP was refused outright — distinct
+    // from every status above, and from a genuinely unhandled status below. Neither
+    // branch reads the response body.
+    if (resp.status === 403)
+        return { ok: false, category: "blocked" };
+    return { ok: false, category: "unexpected", status: resp.status };
 }
 /**
  * POST the VERIFY phase: a handle and a code in, the invite token out.
@@ -3297,14 +3498,18 @@ export async function verifySelfServeChallenge(deps, baseUrl, handle, code) {
         });
     }
     catch (err) {
+        // BAPI-1171: the fetch itself failed — distinct from the server responding
+        // with an error status. The caught value is never inspected.
         void err;
-        return { ok: false, category: "failed" };
+        return { ok: false, category: "network-error" };
     }
     if (resp.ok) {
         let token;
+        let trialGranted;
         try {
             const body = (await resp.json());
             token = body?.token;
+            trialGranted = body?.trial_granted;
         }
         catch {
             return { ok: false, category: "failed" };
@@ -3314,6 +3519,12 @@ export async function verifySelfServeChallenge(deps, baseUrl, handle, code) {
             !token.startsWith(BOOTSTRAP_INVITE_TOKEN_PREFIX)) {
             return { ok: false, category: "failed" };
         }
+        // BAPI-1173: forward-compatible. Only a real boolean is carried; an absent
+        // field (an older server) or a malformed one leaves the result exactly the
+        // legacy `{ ok: true, token }` shape rather than being coerced to false.
+        if (typeof trialGranted === "boolean") {
+            return { ok: true, token, trialGranted };
+        }
         return { ok: true, token };
     }
     // 401 is the server's uniform invalid-challenge outcome. It covers a wrong code,
@@ -3328,7 +3539,12 @@ export async function verifySelfServeChallenge(deps, baseUrl, handle, code) {
     // caller can say "try again" instead of "upgrade the CLI".
     if (resp.status >= 500)
         return { ok: false, category: "server-error" };
-    return { ok: false, category: "failed" };
+    // BAPI-1171: 403 means the caller's network/IP was refused outright — distinct
+    // from every status above, and from a genuinely unhandled status below. Neither
+    // branch reads the response body.
+    if (resp.status === 403)
+        return { ok: false, category: "blocked" };
+    return { ok: false, category: "unexpected", status: resp.status };
 }
 /**
  * POST the RESEND phase: the handle alone, timing metadata out.
@@ -3630,6 +3846,7 @@ export function buildDryRunPreview(ctx) {
         ...credentialStep,
         ...buildCommitAssetsPreviewLines(ctx.commitSafeAssets, ctx.host.kind === "explicit" ? ctx.host.configTargets : []),
         ...(ctx.host.kind === "explicit" ? buildLaunchStepPreview(ctx.host.launch) : buildDeferredLaunchStepPreview()),
+        ...(ctx.host.kind === "explicit" ? buildAgentNotesPreviewLines(ctx.host.notesTargets ?? []) : []),
     ];
 }
 /**
@@ -3663,7 +3880,9 @@ function describePlannedLaunchAgent(launch) {
     }
     return launch.reason === "empty-selection"
         ? "none — no tools selected"
-        : "none — no launchable tool selected; manual continuation is printed";
+        : launch.reason === "unsupported-agent-workflow"
+            ? "none — selected agent cannot run the install-bridge workflow; manual continuation is printed"
+            : "none — no launchable tool selected; manual continuation is printed";
 }
 /**
  * The Step 5 preview lines, shared by both previews so the launch description
@@ -3715,7 +3934,9 @@ function buildLaunchStepPreview(launch) {
         ...githubLines,
         launch.reason === "empty-selection"
             ? "Step 5 — no agent session: no tools were selected, so nothing is configured or opened; re-run and select at least one tool."
-            : "Step 5 — no automatic launch: no selected tool has an agentic CLI. The deterministic setup completes and copy-pasteable /install-bridge continuation is printed (your Bridge MCP tools stay limited until configured).",
+            : launch.reason === "unsupported-agent-workflow"
+                ? "Step 5 — no automatic launch: the selected agent cannot run the install-bridge workflow. The deterministic setup completes and manual continuation is printed."
+                : "Step 5 — no automatic launch: no selected tool can auto-launch this workflow. The deterministic setup completes and copy-pasteable /install-bridge continuation is printed (your Bridge MCP tools stay limited until configured).",
     ];
 }
 /**
@@ -3729,6 +3950,25 @@ function buildDeferredLaunchStepPreview() {
         "         not yet known — a real run resolves it first, then follows from there).",
     ];
 }
+/**
+ * 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
+ * no writable target (e.g. Windsurf-only), mirroring how the GitHub offer
+ * lines are unconditional but this offer's applicability is not.
+ */
+function buildAgentNotesPreviewLines(notesTargets) {
+    if (notesTargets.length === 0)
+        return [];
+    return [
+        "Step 4c — optional: cross-platform agent notes (SKIPPED in --dry-run): if the terminal is",
+        `          interactive, offer to create or refresh a Bridge-owned marker region in ${notesTargets.join(" and ")}`,
+        "          with situation-to-tool guidance for a few Bridge MCP tools; defaults to No, and",
+        "          existing content outside that region is always preserved. No notes files are",
+        "          written in --dry-run.",
+    ];
+}
 /**
  * Bootstrap-invite dry-run preview. A --dry-run must not consume the invite OR
  * LEAVE STATE BEHIND: skipping the HTTP call is not enough — a preview that wrote
@@ -3809,6 +4049,7 @@ function buildBootstrapDryRunPreview(ctx) {
         ...promoteStep,
         ...buildCommitAssetsPreviewLines(ctx.commitSafeAssets, ctx.host.kind === "explicit" ? ctx.host.configTargets : []),
         ...(ctx.host.kind === "explicit" ? buildLaunchStepPreview(ctx.host.launch) : buildDeferredLaunchStepPreview()),
+        ...(ctx.host.kind === "explicit" ? buildAgentNotesPreviewLines(ctx.host.notesTargets ?? []) : []),
     ];
 }
 /**
@@ -4150,6 +4391,30 @@ export const INSTALL_BRIDGE_NO_GIT_NONINTERACTIVE_WARNING = `Warning: ${INSTALL_
 async function hasProjectRootMarker(deps) {
     return sharedHasProjectRootMarker(deps.cwd, deps.stat);
 }
+/**
+ * Resolve, then live-validate, the premium model alias to pin the spawned
+ * install-spawn session to (BAPI-1206). Fail-open at every step: an agent with
+ * no model override support, a validation failure, or an unavailable live
+ * probe all resolve to `null` (omit `--model`, use the agent default) rather
+ * than aborting installation or spawning. For a statically allowlisted agent
+ * (e.g. claude), {@link validateResolvedModelAliasForAgent} returns the
+ * candidate unchanged without probing anything — only an agent like
+ * `cursor-agent`, which has no `staticModelAliasAllowlist`, triggers the live
+ * advertised-model check. A non-null candidate that fails validation logs a
+ * secret-free diagnostic through `deps.debugLog` (silent unless
+ * `BAPI_INSTALL_DEBUG` is set) and is never surfaced as a user-facing warning.
+ */
+export async function resolveValidatedPremiumModelAlias(deps, agent) {
+    const candidate = resolveModelAlias(agent, "premium");
+    if (!candidate)
+        return null;
+    const validation = await validateResolvedModelAliasForAgent(deps.startTicketsDeps, agent, candidate);
+    if (!validation.ok) {
+        deps.debugLog(`install-bridge: ${validation.warning}`);
+        return null;
+    }
+    return validation.alias;
+}
 // ---------------------------------------------------------------------------
 // CLI entry
 // ---------------------------------------------------------------------------
@@ -4203,9 +4468,12 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // be an argument error. Deliberately after the deps merge and the base-URL
     // resolution above, so the nested command inherits the same final merged deps
     // (including a test's `fetch` override) and the same normalized base URL.
-    // Note this is `install-bridge conductor`; the bare top-level `conductor`
-    // subcommand still routes to `runConductorCli` (the local event ledger) and is
-    // untouched.
+    // Note this is `install-bridge conductor`; it is UNRELATED to the top-level
+    // `conductor`/`epic-implementer` CLI split (S4/BAPI-1080) — the bare
+    // top-level `conductor` token is now a fixed migration stub and the real
+    // event-ledger CLI routes through `runEpicImplementerCli` under the
+    // `epic-implementer` name. This nested `install-bridge conductor` surface is
+    // untouched by that rename.
     if (argv[0] === "conductor") {
         if (!baseUrlResult.ok) {
             errorLog(baseUrlResult.error);
@@ -4339,10 +4607,11 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                     errorLog(`Error: no launch agent is registered for '${launchDecision.agent}'.`);
                     return 1;
                 }
+                const modelAlias = await resolveValidatedPremiumModelAlias(deps, spec);
                 launch = {
                     kind: "spawn",
                     agent: launchDecision.agent,
-                    spawnCommand: deps.buildShellCommand(spec, INSTALL_BRIDGE_AGENT_PROMPT, deps.cwd, deps.platform),
+                    spawnCommand: deps.buildShellCommand(spec, INSTALL_BRIDGE_AGENT_PROMPT, deps.cwd, deps.platform, modelAlias),
                 };
             }
             else if (launchDecision.kind === "choose-one") {
@@ -4356,6 +4625,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 configTargets: dryRunTargets.map((t) => t.relPath),
                 manualEditors: manualEditorNames(await detectManualEditors(deps)),
                 launch,
+                notesTargets: resolveAgentNotesTargets(dryRunPlatforms).targets,
             };
         }
         else {
@@ -4658,8 +4928,8 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // BAPI-635: resolve the AI-coding-tool selection FIRST — BAPI-657 makes this
     // selection (not a hidden --agent default) drive which post-install session opens.
     // Explicit --tools, then the TTY multi-select, then the legacy non-TTY automatic
-    // set. The selected project JSON targets drive the read-merge-write path; selected
-    // global (Codex / Copilot CLI) and manual (Windsurf) targets are provisioned by the
+    // set. The selected project JSON targets drive the read-merge-write path; a selected
+    // global (Codex) or manual (Windsurf) target is provisioned by the
     // registry-driven emitter after the connectivity check.
     const selectedPlatforms = await resolveSelectedHostPlatforms(deps, options);
     const targets = hostConfigTargetsForPlatforms(selectedPlatforms);
@@ -4680,10 +4950,11 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             errorLog(`Error: no launch agent is registered for '${launchDecision.agent}'.`);
             return 1;
         }
+        const modelAlias = await resolveValidatedPremiumModelAlias(deps, spec);
         planLaunch = {
             kind: "spawn",
             agent: launchDecision.agent,
-            spawnCommand: deps.buildShellCommand(spec, INSTALL_BRIDGE_AGENT_PROMPT, deps.cwd, deps.platform),
+            spawnCommand: deps.buildShellCommand(spec, INSTALL_BRIDGE_AGENT_PROMPT, deps.cwd, deps.platform, modelAlias),
         };
     }
     else if (launchDecision.kind === "choose-one") {
@@ -4738,7 +5009,8 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 return 1;
             }
             finalAgentName = chosen;
-            finalSpawnCommand = deps.buildShellCommand(spec, INSTALL_BRIDGE_AGENT_PROMPT, deps.cwd, deps.platform);
+            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.
     }
@@ -4936,8 +5208,24 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                         else if (requested.category === "invalid") {
                             reportFatal("Error: Self-serve setup could not be requested. Check the email value and try again.");
                         }
+                        else if (requested.category === "blocked") {
+                            // BAPI-1171: the request was refused before signup logic ran — an
+                            // upgrade would not change the outcome, so this is NOT protocol
+                            // guidance.
+                            reportFatal(INSTALL_BRIDGE_SIGNUP_BLOCKED);
+                        }
+                        else if (requested.category === "unexpected") {
+                            // BAPI-1171: an HTTP status this client has no specific handling
+                            // for. Reports only the numeric status — never response text.
+                            reportFatal(formatSelfServeUnexpectedStatus(requested.status ?? 0));
+                        }
+                        else if (requested.category === "network-error") {
+                            // BAPI-1171: the fetch itself failed — a transport problem, not a
+                            // protocol mismatch, so this is NOT upgrade guidance either.
+                            reportFatal(INSTALL_BRIDGE_SIGNUP_UNAVAILABLE);
+                        }
                         else {
-                            // R-2: a malformed or tokenless-unexpected response is a PROTOCOL
+                            // R-2: a malformed or tokenless success body is a PROTOCOL
                             // mismatch, not a network problem. Saying "check connectivity" here
                             // was the old behavior and is exactly what this ticket replaces.
                             reportFatal(INSTALL_BRIDGE_SIGNUP_UPGRADE_REQUIRED);
@@ -4986,6 +5274,11 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                     const verified = await verifySelfServeChallenge(deps, baseUrl, challengeHandle, code);
                     if (verified.ok) {
                         inviteToken = verified.token;
+                        // BAPI-1173: only an EXPLICIT false prints. `true`, and an absent field
+                        // from an older server, add nothing.
+                        if (verified.trialGranted === false) {
+                            log(`  ${INSTALL_BRIDGE_TRIAL_ALREADY_USED}`);
+                        }
                         break;
                     }
                     if (verified.category === "rate-limited") {
@@ -4999,10 +5292,28 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                         reportFatal(INSTALL_BRIDGE_VERIFY_SERVER_ERROR);
                         return false;
                     }
+                    if (verified.category === "blocked") {
+                        // BAPI-1171: the request was refused before verification logic ran —
+                        // an upgrade would not change the outcome.
+                        reportFatal(INSTALL_BRIDGE_SIGNUP_BLOCKED);
+                        return false;
+                    }
+                    if (verified.category === "unexpected") {
+                        // BAPI-1171: an HTTP status this client has no specific handling for.
+                        // Reports only the numeric status — never response text.
+                        reportFatal(formatSelfServeUnexpectedStatus(verified.status ?? 0));
+                        return false;
+                    }
+                    if (verified.category === "network-error") {
+                        // BAPI-1171: the fetch itself failed — a transport problem, not a
+                        // protocol mismatch.
+                        reportFatal(INSTALL_BRIDGE_VERIFY_SERVER_ERROR);
+                        return false;
+                    }
                     if (verified.category === "failed") {
-                        // Only a genuine protocol mismatch reaches here now: a malformed body,
-                        // a missing token, a network error, or a 4xx this client does not
-                        // expect. R-2's upgrade instruction is the right answer for those.
+                        // Only a genuine protocol mismatch reaches here now: a malformed body
+                        // or a missing token in an otherwise successful response. R-2's
+                        // upgrade instruction is the right answer for that.
                         reportFatal(INSTALL_BRIDGE_SIGNUP_UPGRADE_REQUIRED);
                         return false;
                     }
@@ -5377,7 +5688,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         for (const { relPath } of writeResult.skipped) {
             log(`  skipped ${relPath} — existing config could not be parsed safely; left untouched`);
         }
-        // BAPI-635: provision selected GLOBAL targets (Codex, Copilot CLI) and MANUAL
+        // BAPI-635: provision a selected GLOBAL target (Codex) and MANUAL
         // targets (Windsurf) via the registry-driven emitter. Global paths are never
         // added to the repository .gitignore.
         // BAPI-669 (R8): only a need-key run has a key the user has never seen, so only it
@@ -5413,12 +5724,6 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         const manualInstructions = buildManualHostInstructions(entry, legacyManualEditors, needKeyManual);
         if (manualInstructions)
             log(manualInstructions);
-        // BAPI-635 (Step 7): when both Claude Code and Copilot CLI are selected, warn
-        // that they use different, non-shared config surfaces.
-        if (selectedPlatforms.includes("claude-code") && selectedPlatforms.includes("copilot-cli")) {
-            log("  Note: Claude Code uses the project .mcp.json while GitHub Copilot CLI uses only its " +
-                "global ~/.copilot/mcp-config.json — the two are configured separately.");
-        }
         // BAPI-708 (B-c): the Claude trust reminder that used to print here was
         // RELOCATED, not dropped — the reload requirement is genuinely actionable (the
         // server does not work until the host reloads), but at Step 3 it duplicated the
@@ -5523,15 +5828,56 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         // the agent spawn, for two reasons: the spawned session's capability report should
         // observe GitHub as configured if the user connects it here, and running it after the
         // spawn would put two prompts on the same terminal at once.
-        await offerGithubConnection(repoName, baseUrl, deps, log);
+        //
+        // BAPI-1171: one shared session-state object, constructed fresh for this run, is
+        // passed to both offers so a GitHub connection made here suppresses the Bitbucket
+        // offer that follows — see `InstallBridgeVcsSessionState`.
+        const vcsSessionState = { vcsConnected: false };
+        await offerGithubConnection(repoName, baseUrl, deps, log, vcsSessionState);
         // ---- optional Bitbucket connect offer (BAPI-966) ----
         // Same placement reasoning as the GitHub offer above. Both offers are called
         // unconditionally here — each self-gates on its OWN provider-scoped configuration
         // state (`fetchGithubConfigurationState`/`fetchBitbucketConfigurationState` return
         // "unavailable" when their integration id is absent from the manifest, which is the
         // normal outcome for the non-matching provider), so only the project's actual VCS
-        // provider ever reaches its prompt.
-        await offerBitbucketConnection(repoName, baseUrl, deps, log);
+        // provider ever reaches its prompt — and the GitHub offer's own success, tracked in
+        // `vcsSessionState`, can additionally short-circuit this one before either check runs.
+        await offerBitbucketConnection(repoName, baseUrl, deps, log, vcsSessionState);
+        // ---- optional cross-platform agent notes offer (BAPI-1207) ----
+        // Placed alongside the GitHub/Bitbucket offers, after the durable install work —
+        // never re-detects platforms; the plan is computed from THIS run's already
+        // selected set. `writeAgentNotes` never touches `writeMcpInstallState` or any
+        // other persisted install-state contract — consent is re-evaluated every run.
+        const notesPlan = resolveAgentNotesTargets(selectedPlatforms);
+        const notesOffer = await offerAgentGuidanceNotes(deps, log, notesPlan.targets);
+        let notesResult;
+        let notesWriteFailed = false;
+        if (notesOffer.kind === "consented") {
+            try {
+                notesResult = await writeAgentNotes({
+                    cwd: deps.cwd,
+                    selectedPlatforms,
+                    guidance: AGENT_GUIDANCE,
+                    readFile: deps.readFile,
+                    writeFile: deps.writeFile,
+                    mkdir: deps.mkdir,
+                });
+                for (const file of notesResult.files) {
+                    if (file.status === "failed") {
+                        errorLog(`  warning: could not update ${file.target} with agent notes (${file.reason}).`);
+                    }
+                }
+            }
+            catch {
+                // Fail-open, mirroring the routing-credential persistence above: the
+                // install itself is already complete and durable.
+                notesWriteFailed = true;
+                errorLog("  warning: could not write agent notes (unexpected error).");
+            }
+        }
+        const notesSummaryLine = buildAgentNotesSummaryLine(notesOffer, notesResult, notesWriteFailed, notesPlan.unsupportedPlatforms);
+        if (notesSummaryLine)
+            log(notesSummaryLine);
         // ---- 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