@bridge_gpt/mcp-server 0.2.38 → 0.2.39

package/build/install-bridge.js

@@ -144,11 +144,19 @@ import os from "os";
 import path from "path";
 import readline from "readline";
 import { runInit, buildBridgeApiEntry, resolveInitScaffoldAssets, refreshBridgeApiPackageSpec, currentBridgePackageSpec, } from "./init.js";
+import { hasProjectRootMarker as sharedHasProjectRootMarker } from "./project-root.js";
 import { VERSION } from "./version.generated.js";
 import { validateRepoName } from "./bridge-config.js";
 import { MCP_HOST_TARGETS, HOST_PLATFORM_ORDER, allHostTargets, agentForPlatform, isHostPlatformId, detectDefaultPlatforms, } from "./mcp-host-targets.js";
 import { provisionHostTarget, createDefaultVendorProcessDeps, } from "./mcp-host-config.js";
-import { recordInstalledProjectArtifact, writeMcpInstallState } from "./mcp-install-state.js";
+import { recordInstalledExecutorServiceUnit, recordInstalledProjectArtifact, writeMcpInstallState, } from "./mcp-install-state.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,
+// the write outcome, and the unit path this flow has to record.
+import { collectExecutorInstallPreflight, } from "./executor/install-preflight.js";
+import { inspectExecutorServiceState, startExecutorService, } from "./executor/service-lifecycle.js";
+import { executorLaunchdLabelForId, executorSystemdUnitNameForId, executorLaunchdPlistPathForId, executorSystemdUnitPathForId, resolvePackagedExecutorInvocation, writeExecutorServicePlan, } from "./executor/service-unit.js";
 import { runInstallBridgeConductorCli, } from "./install-bridge-conductor.js";
 import { runConductorInstallDoctor, } from "./conductor/install-doctor.js";
 import { resolveConductorBridgeApiAccess, } from "./conductor/bridge-api-client.js";
@@ -846,8 +854,12 @@ export async function offerGithubConnection(repoName, baseUrl, deps, log) {
             `GitHub later with 'npx -y @bridge_gpt/mcp-server@latest connect-github --repo ${repoName}'.`);
     }
 }
-/** Echoed single-line prompt on stderr (used for repo confirmation / value). */
-function promptLineViaReadline(promptText) {
+/**
+ * Echoed single-line prompt on stderr (used for repo confirmation / value).
+ * Exported so `index.ts`'s `--init` can share the exact same prompt mechanics
+ * as `install`'s missing-project-root confirmation (BAPI-818, R1).
+ */
+export function promptLineViaReadline(promptText) {
     return new Promise((resolve) => {
         const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
         // See promptSecretViaReadline: EOF must resolve rather than deadlock the
@@ -983,6 +995,9 @@ export function createDefaultInstallBridgeDeps() {
             fetch: params.fetch,
             reviewPolicySource: params.reviewPolicySource,
             readWorkflowFile: () => params.readFile(claudeReviewWorkflowPath(params.cwd)),
+            // Read-only service-state probe (BAPI-779). Typed to return a state,
+            // never a runner, so the doctor cannot start/enable/reload anything.
+            inspectExecutorServiceState: params.inspectExecutorServiceState,
             installDoctorDeps: {
                 env: params.env,
                 cwd: params.cwd,
@@ -1025,6 +1040,133 @@ export function createDefaultInstallBridgeDeps() {
         conductorRunSetupEpicDryRun: async (argv) => ({
             exitCode: await runSetupEpicCli(argv),
         }),
+        // ---- Executor provisioning seams (BAPI-779) ----
+        lookupExecutable: (name) => defaultExecutablePresenceProbe(name),
+        runLifecycleCommand: (executable, args) => defaultShellFreeRunner(executable, args),
+        // `process.getuid` is absent on win32; a null uid makes the launchd start
+        // plan refuse to build rather than interpolating `undefined` into a domain
+        // target.
+        getuid: () => (typeof process.getuid === "function" ? process.getuid() : null),
+        // MONOTONIC, not wall clock: a budget measured with `Date.now()` would be
+        // shortened or extended by an NTP step mid-observation.
+        monotonicNow: () => Number(process.hrtime.bigint() / 1000000n),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    };
+}
+/**
+ * Shell-free command runner used for every service-manager invocation.
+ *
+ * `shell: false` and an argument ARRAY are the whole point: a unit path or unit
+ * name containing shell metacharacters is data here, never syntax. Output is
+ * captured for internal classification and is deliberately NOT surfaced —
+ * `service-lifecycle.ts` reports a stage and an exit code instead.
+ */
+function defaultShellFreeRunner(executable, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(executable, args, { shell: false, stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString("utf-8");
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf-8");
+        });
+        // A spawn error (ENOENT on `systemctl`, a sandbox denial) rejects, which the
+        // lifecycle module treats as ONE attempted failure — never a retry.
+        child.on("error", reject);
+        child.on("close", (code) => resolve({ exitCode: code ?? 1, stdout, stderr }));
+    });
+}
+/** Presence probe: `<tool> --version` exiting 0 means the tool resolves on PATH. */
+async function defaultExecutablePresenceProbe(name) {
+    try {
+        const result = await defaultShellFreeRunner(name, ["--version"]);
+        return result.exitCode === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Compose the executor-provisioning bundle the nested conductor phase runs on
+ * (BAPI-779), from the FINAL merged deps.
+ *
+ * Every effect is a thin adapter over an existing seam — nothing here decides
+ * anything. The orchestration (consent, ordering, degradation, observation)
+ * stays in `install-bridge-conductor.ts`; moving it into this dispatch layer
+ * would put policy in the place least able to test it.
+ */
+function buildConductorExecutorDeps(deps, baseUrl) {
+    const homeDir = deps.homedir();
+    const lookupExecutable = deps.lookupExecutable ?? defaultExecutablePresenceProbe;
+    const runLifecycleCommand = deps.runLifecycleCommand ?? defaultShellFreeRunner;
+    return {
+        platform: deps.platform,
+        homeDir,
+        uid: deps.getuid ? deps.getuid() : null,
+        // Captured ONCE here, never re-read inside a renderer (BAPI-327): the unit
+        // bakes the generating shell's PATH so a service-launched executor can
+        // resolve the bare `claude` worker command.
+        envPath: deps.env.PATH ?? deps.env.Path ?? "",
+        resolveInvocation: () => resolvePackagedExecutorInvocation(),
+        runPreflight: (input) => collectExecutorInstallPreflight(input, {
+            lookupExecutable: (name) => lookupExecutable(name),
+            homedir: deps.homedir,
+            readFile: deps.readFile,
+        }),
+        // The programmatic generator, NOT a spawned `executor install-service`: the
+        // typed plan, the write outcome, and the unit path all have to come back.
+        writeUnit: (plan) => writeExecutorServicePlan(plan, {
+            stat: (filePath) => deps.stat(filePath),
+            mkdir: (dirPath, options) => deps.mkdir(dirPath, options),
+            writeFile: (filePath, content) => deps.writeFile(filePath, content),
+            // Supplying `readFile` is what enables the `unchanged` outcome, so a
+            // re-run against an identical unit reports the truth instead of an
+            // unnecessary rewrite.
+            readFile: deps.readFile,
+        }),
+        recordUnit: async (unitPath) => {
+            const result = await recordInstalledExecutorServiceUnit(deps.cwd, unitPath, homeDir, {
+                readFile: deps.readFile,
+                writeFile: (p, data) => deps.writeFile(p, data),
+                rename: deps.rename,
+                mkdir: (p, o) => deps.mkdir(p, o),
+                unlink: deps.unlink,
+            });
+            return result.ok ? { ok: true } : { ok: false, error: result.error };
+        },
+        startService: (plan) => startExecutorService(plan, runLifecycleCommand),
+        now: deps.monotonicNow ?? (() => Number(process.hrtime.bigint() / 1000000n)),
+        sleep: deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+    };
+}
+/**
+ * Read-only local service-state inspector for the unified doctor (BAPI-779).
+ *
+ * Resolves the unit's service-manager handle from the executor id through the
+ * generator's own naming helpers, so the doctor addresses exactly the unit the
+ * generator would have written. Returns `unknown` on an unsupported platform
+ * rather than probing anything.
+ */
+function buildDoctorServiceStateInspector(deps) {
+    const runLifecycleCommand = deps.runLifecycleCommand ?? defaultShellFreeRunner;
+    const homeDir = deps.homedir();
+    const uid = deps.getuid ? deps.getuid() : null;
+    return async ({ executorId }) => {
+        if (deps.platform !== "darwin" && deps.platform !== "linux")
+            return "unknown";
+        const inspection = await inspectExecutorServiceState({
+            platform: deps.platform,
+            unitPath: deps.platform === "darwin"
+                ? executorLaunchdPlistPathForId(executorId, homeDir)
+                : executorSystemdUnitPathForId(executorId, homeDir),
+            serviceIdentifier: deps.platform === "darwin"
+                ? executorLaunchdLabelForId(executorId)
+                : executorSystemdUnitNameForId(executorId),
+            uid,
+        }, runLifecycleCommand);
+        return inspection.state;
     };
 }
 /**
@@ -1502,8 +1644,6 @@ export async function resolveSelectedHostPlatforms(deps, options) {
     if (options.tools !== undefined) {
         return options.tools;
     }
-    const ctx = await buildDetectionContext(deps);
-    const detected = new Set(detectDefaultPlatforms(ctx));
     // 2. Interactive single-shot numbered picker on a TTY. No row is pre-selected
     // — the picker has no default state and requires an explicit selection.
     if (deps.isTTY && deps.promptMultiSelect) {
@@ -1512,6 +1652,19 @@ export async function resolveSelectedHostPlatforms(deps, options) {
         return HOST_PLATFORM_ORDER.filter((id) => chosen.includes(id));
     }
     // 3. Legacy non-TTY automatic set: Claude + detected Cursor / Copilot VS Code.
+    return resolveLegacyAutoDetectedHostPlatforms(deps);
+}
+/**
+ * The legacy non-TTY automatic host set (Claude + detected Cursor / Copilot
+ * VS Code) — branch 3 of {@link resolveSelectedHostPlatforms}, extracted so a
+ * `--dry-run` preview (BAPI-818) can compute the SAME deterministic answer
+ * without touching the TTY branch above it (which would prompt). Pure/local:
+ * only reads the injected `stat` boundary, never prompts, never touches the
+ * network.
+ */
+async function resolveLegacyAutoDetectedHostPlatforms(deps) {
+    const ctx = await buildDetectionContext(deps);
+    const detected = new Set(detectDefaultPlatforms(ctx));
     const legacy = ["claude-code"];
     if (detected.has("cursor"))
         legacy.push("cursor");
@@ -1519,6 +1672,21 @@ export async function resolveSelectedHostPlatforms(deps, options) {
         legacy.push("copilot-vscode");
     return HOST_PLATFORM_ORDER.filter((id) => legacy.includes(id));
 }
+/**
+ * Host-platform selection as known LOCALLY at dry-run time (BAPI-818, R2):
+ * an explicit `--tools`, or — when the run would otherwise fall back to the
+ * legacy non-TTY automatic set (no TTY, or no `promptMultiSelect` seam) — that
+ * SAME deterministic local detection. Returns `undefined` ONLY when a real run
+ * would need the interactive multi-select prompt, which a dry run may never
+ * invoke.
+ */
+async function resolveDryRunHostPlatforms(deps, options) {
+    if (options.tools !== undefined)
+        return options.tools;
+    if (deps.isTTY && deps.promptMultiSelect)
+        return undefined;
+    return resolveLegacyAutoDetectedHostPlatforms(deps);
+}
 /**
  * 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.
@@ -3118,45 +3286,72 @@ export function buildCommitGeneratedAssetsNotice(safePaths, gitignoredPaths) {
         return "";
     return [INSTALL_BRIDGE_COMMIT_ASSETS_HEADING, ...lines].join("\n");
 }
+/** The repo-name preview line, honest about whether the value is known yet. */
+function describeDryRunRepoLine(repo, deferredHint) {
+    if (repo.kind === "deferred")
+        return `Repo name:        (not yet known — ${deferredHint})`;
+    const source = repo.kind === "explicit" ? "from --repo" : "from BAPI_REPO_NAME";
+    return `Repo name:        ${repo.value} (${source})`;
+}
+/** A human-readable stand-in for an unresolved repo name inside a sentence. */
+function repoNamePlaceholder(repo) {
+    return repo.kind === "deferred" ? "<repo name — not yet known>" : repo.value;
+}
+/** The project-root preview line. Reports the LOCAL read-only result only — never prompts. */
+function describeDryRunRootLine(projectRootPresent) {
+    return projectRootPresent
+        ? "Project root:     .git found"
+        : "Project root:     no .git found here — a real run would ask to continue (default No)";
+}
 /**
- * Render the --dry-run preview lines. Every secret is ALWAYS redacted — the
- * spawnCommand, config preview, and (in bootstrap-invite mode) the exchange body
- * never embed the API key, the invite token, or the generated `key_secret`.
- *
- * The plan itself holds no secret and no invite fingerprint, so this function
- * CANNOT leak one: in bootstrap-invite mode it is called before any secret exists.
+ * Render the --dry-run preview lines. Every value is either a pure LOCAL
+ * computation or an explicit CLI/env input — nothing here required a prompt, a
+ * credential read/resolution, or a network call to produce (BAPI-818, R2).
+ * Genuinely unresolved information (the repo name absent both `--repo` and
+ * `BAPI_REPO_NAME`; the tool selection absent `--tools`) is reported as
+ * deferred rather than guessed, inferred, or silently omitted.
  */
-export function buildDryRunPreview(plan) {
-    if (plan.bootstrapInvite)
-        return buildBootstrapDryRunPreview(plan);
+export function buildDryRunPreview(ctx) {
+    if (ctx.bootstrapInvite || ctx.selfServeSignup)
+        return buildBootstrapDryRunPreview(ctx);
+    const pingStep = ctx.repo.kind === "deferred"
+        ? ["Step 2 — connectivity ping: deferred (the repo name is not yet known)."]
+        : [
+            `Step 2 — connectivity ping (before any durable key write): GET ${buildPingUrl(ctx.baseUrl, ctx.repo.value)} (X-API-Key: ${REDACTED_API_KEY})`,
+        ];
+    const hostConfigStep = ctx.host.kind === "deferred"
+        ? [
+            "Step 3 — write per-host MCP config: deferred (tool selection is not yet known —",
+            "         a real run asks interactively on a TTY, or auto-detects non-interactively).",
+        ]
+        : [
+            "Step 3 — write per-host MCP config (read-merge-write, launcher version-pinned;",
+            "         a git-tracked config needs default-No consent for the real key, else a",
+            "         secret-free entry; an unparseable config is skipped and left untouched):",
+            ...ctx.host.configTargets.map((t) => `  ${t}: BAPI_REPO_NAME=${repoNamePlaceholder(ctx.repo)}, BAPI_API_KEY=${REDACTED_API_KEY}, BAPI_BASE_URL=${ctx.baseUrl}, BAPI_DOCS_DIR=${ctx.docsDir}`),
+            ...(ctx.host.manualEditors.length > 0
+                ? [`  ${ctx.host.manualEditors.join(" + ")}: detected (global config) — manual setup instructions would be printed.`]
+                : []),
+        ];
+    const credentialStep = ctx.repo.kind === "deferred"
+        ? [`Step 4 — persist routing credential: deferred (the repo name is not yet known) at ${ctx.credentialStorePath}`]
+        : [`Step 4 — persist routing credential: target bapi:${ctx.repo.value} at ${ctx.credentialStorePath}`];
     return [
-        // Any defined status means the read-only GET really happened, so the header is
-        // truthful for every outcome — but ONLY `resolved` may claim the name came back
-        // from the server (BAPI-687, C-4).
-        plan.serverRepoResolutionStatus !== undefined
-            ? "install --dry-run (one read-only repository-resolution GET may already have occurred; no writes, no state-changing requests, no spawns)"
-            : "install --dry-run (no writes, no network, no spawns)",
-        `Repo name:        ${plan.repoName}${plan.serverRepoResolutionStatus === "resolved"
-            ? " (resolved server-side from your API key)"
-            : ""}`,
-        `Base URL (ping):  ${plan.baseUrl}`,
-        `Docs dir:         ${plan.docsDir}`,
-        `Agent:            ${describePlannedLaunchAgent(plan.launch)}`,
+        "install --dry-run (no writes, no network, no spawns, no credential resolved or prompted for)",
+        describeDryRunRepoLine(ctx.repo, "a real run would resolve it from your API key, or prompt if it cannot be"),
+        `Base URL:         ${ctx.baseUrl}`,
+        `Docs dir:         ${ctx.docsDir}`,
+        describeDryRunRootLine(ctx.projectRootPresent),
+        `Agent:            ${ctx.host.kind === "explicit" ? describePlannedLaunchAgent(ctx.host.launch) : "(deferred — tool selection is not yet known)"}`,
         "",
         "Step 1 — scaffold (runInit): commands, agents, pipelines, .bridge/config, secret-free MCP placeholders.",
-        `Step 2 — connectivity ping (before any durable key write): GET ${plan.pingUrl} (X-API-Key: ${REDACTED_API_KEY})`,
-        "Step 3 — write per-host MCP config (read-merge-write, launcher version-pinned;",
-        "         a git-tracked config needs default-No consent for the real key, else a",
-        "         secret-free entry; an unparseable config is skipped and left untouched):",
-        ...plan.configTargets.map((t) => `  ${t}: BAPI_REPO_NAME=${plan.repoName}, BAPI_API_KEY=${REDACTED_API_KEY}, BAPI_BASE_URL=${plan.baseUrl}, BAPI_DOCS_DIR=${plan.docsDir}`),
-        ...(plan.manualEditors.length > 0
-            ? [`  ${plan.manualEditors.join(" + ")}: detected (global config) — manual setup instructions would be printed.`]
-            : []),
-        `Step 3b — pre-warm the version-pinned launcher bucket (fail-open, env sanitized — BAPI_API_KEY removed): ${plan.prewarmCommand}`,
+        ...pingStep,
+        ...hostConfigStep,
+        `Step 3b — pre-warm the version-pinned launcher bucket (fail-open, env sanitized — BAPI_API_KEY removed): ${ctx.prewarmCommand}`,
         MCP_TIMEOUT_GUIDANCE,
-        `Step 4 — persist routing credential: target ${plan.credentialTarget} at ${plan.credentialStorePath}`,
-        ...buildCommitAssetsPreviewLines(plan),
-        ...buildLaunchStepPreview(plan),
+        ...credentialStep,
+        ...buildCommitAssetsPreviewLines(ctx.commitSafeAssets, ctx.host.kind === "explicit" ? ctx.host.configTargets : []),
+        ...(ctx.host.kind === "explicit" ? buildLaunchStepPreview(ctx.host.launch) : buildDeferredLaunchStepPreview()),
     ];
 }
 /**
@@ -3164,12 +3359,12 @@ export function buildDryRunPreview(plan) {
  * returns before the live emission point, and this module's convention is that a
  * preview never advertises different behavior — so the same notice, built from the
  * same resolved manifest, appears here too. The gitignored exclusion set is the
- * plan's own `configTargets` plus the install-state file, exactly as the live path
- * computes it.
+ * caller's own config targets plus the install-state file, exactly as the live
+ * path computes it.
  */
-function buildCommitAssetsPreviewLines(plan) {
-    const notice = buildCommitGeneratedAssetsNotice(plan.commitSafeAssets ?? [], [
-        ...plan.configTargets,
+function buildCommitAssetsPreviewLines(commitSafeAssets, configTargets) {
+    const notice = buildCommitGeneratedAssetsNotice(commitSafeAssets ?? [], [
+        ...configTargets,
         INSTALL_BRIDGE_INSTALL_STATE_PATH,
     ]);
     return notice.length > 0 ? ["", notice] : [];
@@ -3202,7 +3397,7 @@ function describePlannedLaunchAgent(launch) {
  * A --dry-run never writes the launch script, prompts for consent, or spawns, so
  * these lines describe the outcome rather than performing it.
  */
-function buildLaunchStepPreview(plan) {
+function buildLaunchStepPreview(launch) {
     const githubLines = [
         // BAPI-631: described, never performed in --dry-run — a preview must not open a
         // browser or reach the network. It is also strictly optional, so it carries no step
@@ -3220,18 +3415,18 @@ function buildLaunchStepPreview(plan) {
         "          It opens github.com in your browser, and shares no GitHub credential with Bridge; it",
         `          defaults to No and can be run later instead: ${INSTALL_BRIDGE_CONNECT_GITHUB_COMMAND}`,
     ];
-    if (plan.launch.kind === "spawn") {
+    if (launch.kind === "spawn") {
         return [
             ...githubLines,
-            `Step 5 — agent session (${toolLabelForLaunchAgent(plan.launch.agent)}): on a TTY the wizard first asks`,
+            `Step 5 — agent session (${toolLabelForLaunchAgent(launch.agent)}): on a TTY the wizard first asks`,
             "          'Open a … session to do that now? (Y/n)'; only on consent is the full command below",
             "          stored in a restricted launch script (mode 0600, under the system temp dir) and a short",
             "          sourced runner spawned (the script itself is NOT written in --dry-run):",
-            `          ${plan.launch.spawnCommand}`,
+            `          ${launch.spawnCommand}`,
         ];
     }
-    if (plan.launch.kind === "choose-one") {
-        const labels = plan.launch.agents.map((a) => toolLabelForLaunchAgent(a)).join(", ");
+    if (launch.kind === "choose-one") {
+        const labels = launch.agents.map((a) => toolLabelForLaunchAgent(a)).join(", ");
         return [
             ...githubLines,
             `Step 5 — agent session: more than one selected tool can host it (${labels}); on a TTY the wizard`,
@@ -3240,33 +3435,47 @@ function buildLaunchStepPreview(plan) {
     }
     return [
         ...githubLines,
-        plan.launch.reason === "empty-selection"
+        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).",
     ];
 }
+/**
+ * The deferred form of {@link buildLaunchStepPreview}, used when the tool
+ * selection itself was not resolved (no `--tools`) — the launch outcome cannot
+ * be computed without it, so this states that plainly instead of guessing.
+ */
+function buildDeferredLaunchStepPreview() {
+    return [
+        "Step 4b — GitHub connect offer and agent session: deferred (tool selection is",
+        "         not yet known — a real run resolves it first, then follows from there).",
+    ];
+}
 /**
  * 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
  * a pending `key_secret` would have left credential material on disk for a
- * redemption that never happened. So the caller returns here BEFORE the CSPRNG
- * runs and before anything is written.
+ * redemption that never happened. So this is reached BEFORE the CSPRNG runs and
+ * before anything is written — indeed before the invite/email is even resolved,
+ * since the early dry-run short-circuit in `runInstallBridgeCli` returns before
+ * `resolveInviteToken`/`resolveSignupEmail` run at all.
  */
-function buildBootstrapDryRunPreview(plan) {
-    const pendingTarget = `bootstrap-pending:${plan.repoName}`;
+function buildBootstrapDryRunPreview(ctx) {
+    const pendingTarget = `bootstrap-pending:${repoNamePlaceholder(ctx.repo)}`;
     // Self-serve signup (BAPI-618): the ONLY structural difference from a pre-issued
     // invite is a mint-from-email step (Step 2·pre) that turns an email into the
     // invite token before the unchanged redemption below. The preview states plainly
     // that in --dry-run that signup/mint is previewed-and-skipped: no account is
     // created, no mint request is sent, no email leaves the machine. The email and
     // any synthetic token are deliberately absent from this output.
-    const header = plan.selfServeSignup
+    const header = ctx.selfServeSignup
         ? "install --email --dry-run (no writes, no network, no spawns, no account created, no secret generated)"
         : "install --invite --dry-run (no writes, no network, no spawns, no secret generated)";
-    const repoLine = plan.selfServeSignup
-        ? `Repo name:        ${plan.repoName} (created by the self-serve exchange; globally unique)`
-        : `Repo name:        ${plan.repoName} (created by the exchange; globally unique)`;
-    const selfServeStep = plan.selfServeSignup
+    const createdBy = ctx.selfServeSignup ? "the self-serve exchange" : "the exchange";
+    const repoLine = ctx.repo.kind === "deferred"
+        ? `Repo name:        (not yet known — a real run would prompt for a new, globally-unique project name)`
+        : `Repo name:        ${ctx.repo.value} (would be created by ${createdBy}; globally unique)`;
+    const selfServeStep = ctx.selfServeSignup
         ? [
             "Step 2·pre — self-serve signup (PREVIEWED, SKIPPED in --dry-run): no Bridge workspace",
             "          signup is requested, no mint call is made, no email is sent or transmitted, and",
@@ -3277,33 +3486,51 @@ function buildBootstrapDryRunPreview(plan) {
             "          redemption protocol below.",
         ]
         : [];
+    const exchangeUrl = buildBootstrapExchangeUrl(ctx.baseUrl);
+    const pingStep = ctx.repo.kind === "deferred"
+        ? ["Step 2c — connectivity ping with the newly-minted key: deferred (the repo name is not yet known)."]
+        : [
+            `Step 2c — connectivity ping with the newly-minted key (before any durable key write): GET ${buildPingUrl(ctx.baseUrl, ctx.repo.value)} (X-API-Key: ${REDACTED_API_KEY})`,
+        ];
+    const hostConfigStep = ctx.host.kind === "deferred"
+        ? [
+            "Step 3 — write per-host MCP config: deferred (tool selection is not yet known —",
+            "         a real run asks interactively on a TTY, or auto-detects non-interactively).",
+        ]
+        : [
+            "Step 3 — write per-host MCP config (read-merge-write, launcher version-pinned;",
+            "         a git-tracked config needs default-No consent for the real key, else a",
+            "         secret-free entry; an unparseable config is skipped and left untouched):",
+            ...ctx.host.configTargets.map((t) => `  ${t}: BAPI_REPO_NAME=${repoNamePlaceholder(ctx.repo)}, BAPI_API_KEY=${REDACTED_API_KEY}, BAPI_BASE_URL=${ctx.baseUrl}, BAPI_DOCS_DIR=${ctx.docsDir}`),
+            ...(ctx.host.manualEditors.length > 0
+                ? [`  ${ctx.host.manualEditors.join(" + ")}: detected (global config) — manual setup instructions would be printed.`]
+                : []),
+        ];
+    const promoteStep = ctx.repo.kind === "deferred"
+        ? [`Step 4 — promote ${pendingTarget} to its final credential (only after the exchange succeeds) at ${ctx.credentialStorePath}`]
+        : [`Step 4 — promote ${pendingTarget} → bapi:${ctx.repo.value} at ${ctx.credentialStorePath} (only after the exchange succeeds)`];
     return [
         header,
         repoLine,
-        `Base URL:         ${plan.baseUrl}`,
-        `Docs dir:         ${plan.docsDir}`,
-        `Agent:            ${describePlannedLaunchAgent(plan.launch)}`,
+        `Base URL:         ${ctx.baseUrl}`,
+        `Docs dir:         ${ctx.docsDir}`,
+        describeDryRunRootLine(ctx.projectRootPresent),
+        `Agent:            ${ctx.host.kind === "explicit" ? describePlannedLaunchAgent(ctx.host.launch) : "(deferred — tool selection is not yet known)"}`,
         "",
         "Step 1 — scaffold (runInit): commands, agents, pipelines, .bridge/config, secret-free MCP placeholders.",
         ...selfServeStep,
-        `Step 2a — generate key_secret (32 CSPRNG bytes) and fsync it to ${pendingTarget} at ${plan.credentialStorePath}`,
+        `Step 2a — generate key_secret (32 CSPRNG bytes) and fsync it to ${pendingTarget} at ${ctx.credentialStorePath}`,
         "          BEFORE the exchange. If that write fails the run ABORTS and no invite is spent.",
         `Step 2b — redeem the bootstrap invite (replaces the pre-flight ping — there is no key yet):`,
-        `          POST ${plan.exchangeUrl}`,
-        `          body: {"token": "${REDACTED_API_KEY}", "repo_name": "${plan.repoName}", "key_secret": "${REDACTED_API_KEY}"}`,
-        `Step 2c — connectivity ping with the newly-minted key (before any durable key write): GET ${plan.pingUrl} (X-API-Key: ${REDACTED_API_KEY})`,
-        "Step 3 — write per-host MCP config (read-merge-write, launcher version-pinned;",
-        "         a git-tracked config needs default-No consent for the real key, else a",
-        "         secret-free entry; an unparseable config is skipped and left untouched):",
-        ...plan.configTargets.map((t) => `  ${t}: BAPI_REPO_NAME=${plan.repoName}, BAPI_API_KEY=${REDACTED_API_KEY}, BAPI_BASE_URL=${plan.baseUrl}, BAPI_DOCS_DIR=${plan.docsDir}`),
-        ...(plan.manualEditors.length > 0
-            ? [`  ${plan.manualEditors.join(" + ")}: detected (global config) — manual setup instructions would be printed.`]
-            : []),
-        `Step 3b — pre-warm the version-pinned launcher bucket (fail-open, env sanitized — BAPI_API_KEY / BAPI_INVITE removed): ${plan.prewarmCommand}`,
+        `          POST ${exchangeUrl}`,
+        `          body: {"token": "${REDACTED_API_KEY}", "repo_name": "${repoNamePlaceholder(ctx.repo)}", "key_secret": "${REDACTED_API_KEY}"}`,
+        ...pingStep,
+        ...hostConfigStep,
+        `Step 3b — pre-warm the version-pinned launcher bucket (fail-open, env sanitized — BAPI_API_KEY / BAPI_INVITE removed): ${ctx.prewarmCommand}`,
         MCP_TIMEOUT_GUIDANCE,
-        `Step 4 — promote ${pendingTarget} → ${plan.credentialTarget} at ${plan.credentialStorePath} (only after the exchange succeeds)`,
-        ...buildCommitAssetsPreviewLines(plan),
-        ...buildLaunchStepPreview(plan),
+        ...promoteStep,
+        ...buildCommitAssetsPreviewLines(ctx.commitSafeAssets, ctx.host.kind === "explicit" ? ctx.host.configTargets : []),
+        ...(ctx.host.kind === "explicit" ? buildLaunchStepPreview(ctx.host.launch) : buildDeferredLaunchStepPreview()),
     ];
 }
 /**
@@ -3635,20 +3862,15 @@ export const INSTALL_BRIDGE_NO_GIT_ABORT = "Aborted — run install from your pr
 /** The non-TTY form: same finding, stated as a warning, then the run continues. */
 export const INSTALL_BRIDGE_NO_GIT_NONINTERACTIVE_WARNING = `Warning: ${INSTALL_BRIDGE_NO_GIT_WARNING} — continuing (non-interactive).`;
 /**
- * Existence probe for `<cwd>/.git`, through the injected `stat` boundary. A git
+ * Existence probe for `<cwd>/.git`, delegated to the shared project-root probe
+ * (BAPI-818) so `--init` and `install` use exactly one marker definition. A git
  * worktree's `.git` is a FILE rather than a directory, so only existence is
  * checked — never the entry type. Any probe failure is treated as "absent"; this
  * is a hint for a warning, never an authorization decision. Repository-name
  * inference is untouched by it.
  */
 async function hasProjectRootMarker(deps) {
-    try {
-        await deps.stat(path.join(deps.cwd, ".git"));
-        return true;
-    }
-    catch {
-        return false;
-    }
+    return sharedHasProjectRootMarker(deps.cwd, deps.stat);
 }
 // ---------------------------------------------------------------------------
 // CLI entry
@@ -3744,6 +3966,9 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 cwd: deps.cwd,
                 env: deps.env,
                 readFile: deps.readFile,
+                // Read-only service-state probe (BAPI-779), built from the FINAL
+                // merged deps so a test's platform/runner overrides reach the doctor.
+                inspectExecutorServiceState: buildDoctorServiceStateInspector(deps),
             }),
             writeWorkflow: (cwd, content, options) => (deps.conductorWriteWorkflow ??
                 (async () => ({ ok: false, error: "workflow seam unavailable" })))(cwd, content, options, deps),
@@ -3751,6 +3976,10 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 (async () => ({ ok: false, error: "install-state seam unavailable" })))(cwd, relPath, deps),
             runSetupEpicDryRun: (setupArgv) => (deps.conductorRunSetupEpicDryRun ??
                 (async () => ({ exitCode: 1 })))(setupArgv),
+            // Built from the FINAL merged deps (BAPI-779), for the same reason the
+            // seams above are: a test that overrides only `fetch` or only `homedir`
+            // must see its override here, not a stale default captured earlier.
+            executorProvisioning: buildConductorExecutorDeps(deps, conductorBaseUrl),
         };
         return runInstallBridgeConductorCli(argv.slice(1), conductorDeps);
     }
@@ -3782,6 +4011,101 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // every downstream `deps.env` consumer observes it. The caller-owned object (and
     // `process.env`) is never mutated.
     deps.env = { ...deps.env, BAPI_BASE_URL: baseUrl };
+    // ---- BAPI-818 (R2): --dry-run short-circuits HERE — genuinely inert ----
+    // Fires immediately after argument parsing and the pure base-URL validation
+    // above, and strictly BEFORE the project-root confirmation prompt, onboarding
+    // branch selection, credential resolution, the server-side repo-resolution
+    // round-trip, the host multi-select, and every bootstrap/invite, write,
+    // prewarm, or spawn action below. That ordering IS the fix: a dry run used to
+    // reach every one of those first (README:258/119's "no writes, no contacting
+    // Bridge, no opening anything" was false). Everything the preview below reports
+    // is either an explicit CLI/env input or a pure local computation — never a
+    // credential read, an invite exchange, or a network call. The bootstrap-invite
+    // property this ordering must preserve (a preview must neither consume the
+    // invite NOR leave a pending secret on disk) holds trivially here: this branch
+    // returns before `resolveInviteToken`/`resolveSignupEmail` even run.
+    if (options.dryRun) {
+        log(`${INSTALL_BRIDGE_CWD_BANNER_PREFIX}${deps.cwd}`);
+        const repo = typeof options.repo === "string" && options.repo.trim().length > 0
+            ? { kind: "explicit", value: options.repo.trim() }
+            : typeof deps.env.BAPI_REPO_NAME === "string" && deps.env.BAPI_REPO_NAME.trim().length > 0
+                ? { kind: "configured", value: deps.env.BAPI_REPO_NAME.trim() }
+                : { kind: "deferred" };
+        // Read-only local .git probe — the SAME check the live path uses, but
+        // reported here rather than turned into a confirmation prompt.
+        const projectRootPresent = await hasProjectRootMarker(deps);
+        // Pure, deterministic, no I/O (see its own doc comment) — safe to call here
+        // even though the interactive wrapper `resolveInstallBridgeOnboardingBranchForRun`
+        // (which CAN prompt on a bare TTY run) is not.
+        const onboardingBranch = resolveInstallBridgeOnboardingBranch(options, deps.env);
+        const bootstrapInvite = onboardingBranch.kind === "need-key";
+        const selfServeSignup = onboardingBranch.kind === "need-key" && onboardingBranch.method === "self-serve";
+        // Host/tool selection: known locally whenever it would be deterministic in a
+        // real run too — an explicit `--tools`, or the legacy non-TTY auto-detected
+        // set (`resolveDryRunHostPlatforms` mirrors `resolveSelectedHostPlatforms`
+        // exactly, minus the branch that prompts). Only genuinely deferred when a
+        // real run would need the interactive multi-select, which a dry run may not
+        // invoke.
+        const dryRunPlatforms = await resolveDryRunHostPlatforms(deps, options);
+        let host;
+        if (dryRunPlatforms !== undefined) {
+            const dryRunTargets = hostConfigTargetsForPlatforms(dryRunPlatforms);
+            const launchDecision = resolveInstallBridgeLaunchDecision(dryRunPlatforms, options.agentName);
+            let launch;
+            if (launchDecision.kind === "spawn") {
+                const spec = resolveAgentSpec(launchDecision.agent);
+                if (!spec) {
+                    errorLog(`Error: no launch agent is registered for '${launchDecision.agent}'.`);
+                    return 1;
+                }
+                launch = {
+                    kind: "spawn",
+                    agent: launchDecision.agent,
+                    spawnCommand: deps.buildShellCommand(spec, INSTALL_BRIDGE_AGENT_PROMPT, deps.cwd, deps.platform),
+                };
+            }
+            else if (launchDecision.kind === "choose-one") {
+                launch = { kind: "choose-one", agents: launchDecision.agents };
+            }
+            else {
+                launch = { kind: "manual", reason: launchDecision.reason };
+            }
+            host = {
+                kind: "explicit",
+                configTargets: dryRunTargets.map((t) => t.relPath),
+                manualEditors: manualEditorNames(await detectManualEditors(deps)),
+                launch,
+            };
+        }
+        else {
+            host = { kind: "deferred" };
+        }
+        // Local, read-only filesystem probes — never a credential, never the network.
+        const dryRunScaffoldAssets = await resolveInitScaffoldAssets({
+            cwd: deps.cwd,
+            env: deps.env,
+            stat: deps.stat,
+        });
+        const dryRunCredentialStorePath = getPrimaryCredentialStorePath({
+            env: deps.env,
+            homedir: deps.homedir,
+        });
+        for (const line of buildDryRunPreview({
+            baseUrl,
+            docsDir: deps.env.BAPI_DOCS_DIR ?? DEFAULT_BAPI_DOCS_DIR,
+            credentialStorePath: dryRunCredentialStorePath,
+            prewarmCommand: buildPrewarmCommandPreview(),
+            commitSafeAssets: dryRunScaffoldAssets.commitSafePaths,
+            projectRootPresent,
+            repo,
+            host,
+            bootstrapInvite,
+            selfServeSignup,
+        })) {
+            log(line);
+        }
+        return 0;
+    }
     // ---- BAPI-669 (U2): working-directory banner + project-root gate ----
     // See the section comment on `hasProjectRootMarker`: read-only, and positioned
     // ahead of ALL credential and configuration work so a decline costs nothing.
@@ -4098,35 +4422,11 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         env: deps.env,
         stat: deps.stat,
     });
-    const plan = {
-        repoName,
-        baseUrl,
-        docsDir,
-        launch: planLaunch,
-        configTargets: targets.map((t) => t.relPath),
-        commitSafeAssets: scaffoldAssets.commitSafePaths,
-        manualEditors: manualEditorNames(manualEditors),
-        credentialTarget: `bapi:${repoName}`,
-        credentialStorePath,
-        pingUrl: buildPingUrl(baseUrl, repoName),
-        prewarmCommand: buildPrewarmCommandPreview(),
-        ...(bootstrapInviteMode
-            ? { bootstrapInvite: true, exchangeUrl: buildBootstrapExchangeUrl(baseUrl) }
-            : {}),
-        ...(selfServeSignupMode ? { selfServeSignup: true } : {}),
-        ...(serverRepoResolutionStatus !== undefined
-            ? { serverRepoResolutionStatus }
-            : {}),
-    };
-    // ---- --dry-run: preview every step, strictly no side effects ----
-    // Positioned BEFORE the CSPRNG, the pending write, the exchange, the scaffold,
-    // the config writes, the pre-warm, and the spawn: in bootstrap-invite mode a
-    // preview must neither consume the invite NOR leave a pending secret on disk.
-    if (options.dryRun) {
-        for (const line of buildDryRunPreview(plan))
-            log(line);
-        return 0;
-    }
+    // NOTE (BAPI-818, R2): `--dry-run` no longer branches here. It short-circuits
+    // far earlier — immediately after argument parsing and base-URL validation,
+    // 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.
     // ---- 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