@bridge_gpt/mcp-server 0.2.67 → 0.2.68

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).
  *
@@ -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";
@@ -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,6 +187,7 @@ 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";
@@ -189,6 +197,7 @@ 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 { 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";
@@ -443,7 +452,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",
@@ -561,6 +573,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 +661,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 +687,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 +841,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 +962,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 +1007,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 +1015,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 +1045,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 +1113,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,
@@ -1120,14 +1175,14 @@ 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
+ * The default-Yes agent-notes consent prompt (BAPI-1435; 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]: `;
+    return `${INSTALL_BRIDGE_AGENT_NOTES_PROMPT_PREFIX}${subject} know${plural ? "" : "s"} how to use the Bridge MCP? Enter adds guidance for ${subject}. [Y/n]: `;
 }
 /**
  * The offer-context lines printed immediately before the agent-notes prompt
@@ -1147,6 +1202,12 @@ export function buildAgentNotesOfferContext(targets, platformLabels) {
         "  created or refreshed — any existing content, inside or outside it, is otherwise preserved.",
     ];
 }
+function agentGuidancePromptConsents(result) {
+    if (result?.kind !== "answer" || typeof result.value !== "string")
+        return false;
+    const value = result.value.trim().toLowerCase();
+    return value === "" || value === "y" || value === "yes";
+}
 /**
  * Offer to create or refresh the cross-platform agent notes, if the selected
  * platforms resolve to at least one writable target (BAPI-1207).
@@ -1162,20 +1223,18 @@ export async function offerAgentGuidanceNotes(deps, log, targets, platformLabels
     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 || !deps.promptGuidanceLine)
         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" };
+        const answer = await deps.promptGuidanceLine(buildAgentNotesPrompt(platformLabels));
+        return agentGuidancePromptConsents(answer) ? { 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" };
+        deps.errorLog("Agent guidance skipped: the prompt could not be read; no guidance files were changed.");
+        return { kind: "prompt-error" };
     }
 }
 /**
@@ -1192,11 +1251,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}.`;
     }
@@ -1235,6 +1296,56 @@ export function promptLineViaReadline(promptText, input = process.stdin, output
         });
     });
 }
+/** Observe CR/LF before readline, counting split CRLF as one submission. */
+export function promptGuidanceLineViaReadline(promptText, input = process.stdin, output = process.stderr) {
+    return new Promise((resolve) => {
+        const readable = input;
+        if (readable.readableEnded || readable.destroyed) {
+            resolve({ kind: "eof" });
+            return;
+        }
+        let terminators = 0;
+        let previousCR = false;
+        let settled = false;
+        let rl;
+        const observe = (chunk) => {
+            for (const char of chunk.toString()) {
+                if (char === "\r")
+                    terminators++;
+                else if (char === "\n" && !previousCR)
+                    terminators++;
+                previousCR = char === "\r";
+            }
+        };
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            input.removeListener("data", observe);
+            input.removeListener("end", eof);
+            input.removeListener("close", eof);
+            input.removeListener("error", eof);
+            rl?.removeListener("close", eof);
+            rl?.close();
+            resolve(result);
+        };
+        const eof = () => finish({ kind: "eof" });
+        input.prependListener("data", observe);
+        input.once("end", eof);
+        input.once("close", eof);
+        input.once("error", eof);
+        rl = readline.createInterface({ input, output });
+        rl.once("close", eof);
+        if (settled || readable.readableEnded || readable.destroyed) {
+            rl.close();
+            eof();
+            return;
+        }
+        rl.question(promptText, (value) => {
+            finish(terminators > 0 ? { kind: "answer", value } : { kind: "eof" });
+        });
+    });
+}
 /**
  * Default pre-warm spawner (BAPI-451 W3). Spawns array-based (`shell: false`) so
  * no argument is ever shell-interpreted, ignores all child stdio (node-gyp /
@@ -1328,6 +1439,7 @@ export function createDefaultInstallBridgeDeps() {
     return {
         env: process.env,
         cwd: process.cwd(),
+        realpath: async (folder) => realpath(folder),
         platform: process.platform,
         homedir: os.homedir,
         isTTY,
@@ -1349,6 +1461,7 @@ export function createDefaultInstallBridgeDeps() {
         randomBytes: (size) => cryptoRandomBytes(size),
         promptSecret: isTTY ? promptSecretViaReadline : undefined,
         promptLine: isTTY ? promptLineViaReadline : undefined,
+        promptGuidanceLine: isTTY ? promptGuidanceLineViaReadline : undefined,
         promptMultiSelect: isTTY ? promptMultiSelectViaReadline : undefined,
         vendor: createDefaultVendorProcessDeps(spawn),
         fetch: productionFetch,
@@ -1643,6 +1756,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,7 +2138,15 @@ 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) {
     // BAPI-757 (R-3 / AC-9): self-serve signup now REQUIRES an interactive terminal,
@@ -2385,9 +2577,14 @@ const OPTIMIZATION_POSTURE_MAX_CORRECTIONS = 20;
  */
 function buildOptimizationPostureMenu(primaryPlatform) {
     return ("How should Bridge optimize its work on this repository?\n" +
-        "  1. Quality\n" +
-        "  2. Speed\n" +
-        `  3. ${buildOptimizationPostureOptionThree(primaryPlatform)}\n` +
+        "  1. Quality — fuller planning and review policy.\n" +
+        "  2. Speed — a combined planning pass and normally one review round.\n" +
+        `  3. ${buildOptimizationPostureOptionThree(primaryPlatform)} — leaner planning/review defaults\n` +
+        "     and lower harness model tiers where supported.\n" +
+        "These are active defaults, subject to explicit policy/model overrides.\n" +
+        `Your ${optimizationPostureSubscriptionNounPhrase(primaryPlatform)} is separate from Bridge credits.\n` +
+        "Enter keeps an existing saved preference; projects without one use Quality.\n" +
+        "You can change this later with /teach-bridge.\n" +
         `${OPTIMIZATION_POSTURE_CORRECTION} `);
 }
 /**
@@ -2496,7 +2693,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;
     }
@@ -3386,6 +3583,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 +3616,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 +3634,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 +3642,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 +3844,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 +3873,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 +3897,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 +3929,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 +3962,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. */
@@ -4699,7 +4917,7 @@ function buildAgentNotesPreviewLines(notesTargets, platformLabels) {
         `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",
+        "          to Yes [Y/n] on submitted Enter; EOF skips. Existing content outside that region is preserved. No notes files are",
         "          written in --dry-run.",
     ];
 }
@@ -5177,6 +5395,10 @@ export function isMinttyNonInteractiveInstall(platform, env, isTTY) {
 }
 export async function runInstallBridgeCli(argv, overrides = {}) {
     const deps = { ...createDefaultInstallBridgeDeps(), ...overrides };
+    if (Object.prototype.hasOwnProperty.call(overrides, "promptLine") &&
+        !Object.prototype.hasOwnProperty.call(overrides, "promptGuidanceLine")) {
+        deps.promptGuidanceLine = undefined;
+    }
     // When the caller overrode only `fetch` (the common test seam), bind the
     // default resolver to the FINAL merged fetch so server resolution still routes
     // through the override. An explicit `resolveRepoViaServer` override is honored.
@@ -5315,6 +5537,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 +5566,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
@@ -5667,6 +5926,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 +6107,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,6 +6132,7 @@ 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;
     }
@@ -6467,7 +6795,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,6 +6810,11 @@ 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
@@ -6535,6 +6868,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 +6920,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 +7003,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
@@ -6759,6 +7123,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 +7137,31 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         const notesSummaryLine = buildAgentNotesSummaryLine(notesOffer, notesResult, notesWriteFailed, notesPlan.unsupportedPlatforms);
         if (notesSummaryLine)
             log(notesSummaryLine);
+        // ---- 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 asks once and is skipped without a yes or a terminal. 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,
+                    promptLine: deps.isTTY ? deps.promptLine : undefined,
+                    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),
+                });
+            }
+            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 +7184,9 @@ 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);
         // ---- 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 +7301,117 @@ 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.");
+        let suggestion = "";
+        try {
+            suggestion = validateBootstrapDisplayName(path.basename(folder));
+        }
+        catch { /* explicit label required */ }
+        const entered = await deps.promptLine(suggestion ? `Project display name [${suggestion}]: ` : "Project display name: ");
+        label = validateBootstrapDisplayName(entered || suggestion);
+    }
+    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.");
+            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 };
+}