@bridge_gpt/mcp-server 0.2.34 → 0.2.37

package/build/doctor.js

@@ -14,7 +14,7 @@
  * spawning, no MCP server startup. It only ever runs read-only PATH probes
  * (`which`/`where`, `bash --version`, `git rev-parse`) through the injected deps.
  */
-import { readFile, stat } from "fs/promises";
+import { readdir, readFile, stat } from "fs/promises";
 import { spawn } from "child_process";
 import os from "os";
 import path from "path";
@@ -25,9 +25,14 @@ import { parseDefaultOnEnvFlag } from "./env-flags.js";
 import { createBridgeApiUrls } from "./bridge-api-urls.js";
 import { probeToolSurface } from "./tool-surface-gating.js";
 import { resolveBapiCredentials } from "./credential-store.js";
+import { resolveRequiredStartTicketsRepoName } from "./start-tickets-repo.js";
+import { BRIDGE_PACKAGE_NAME, describeLauncherReason, inspectLauncherConfigs, parseLauncherPin as parseSharedLauncherPin, } from "./launcher-config-inspection.js";
 import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
 import { getDoctorPrereqDescriptors, probePrerequisite, } from "./start-tickets-prereqs.js";
 import { resolveProfiles } from "./mcp-profile.js";
+import { executorLaunchdDirForHome, executorSystemdDirForHome, executorIdFromLaunchdFilename, executorIdFromSystemdFilename, inspectExecutorServiceArtifact, EXECUTOR_SERVICE_BASE_URL_ENV, } from "./executor/index.js";
+import { DEFAULT_BAPI_BASE_URL } from "./executor/credentials.js";
+import { evaluateWorkerConfigIsolationCapability, formatWorkerConfigIsolationReason, } from "./executor/worker-config-isolation.js";
 /**
  * The report/usage title (BAPI-669, U9b). `doctor` diagnoses the whole Bridge
  * install — install status, prerequisites, launcher cache, and tool surface — so it
@@ -60,12 +65,25 @@ export function getDoctorUsage() {
         "After that come the start-tickets prerequisite checks (for the current OS):",
         "the start-tickets preflight prerequisites plus",
         "uv, the selected agent's command, Bridge API credential resolution, and",
-        "worktree MCP registration reachability. Credential resolution reports the",
+        "worktree MCP registration reachability, and a read-only check of whether the",
+        "Claude user config (~/.claude.json) registers a 'bridge-api' MCP server that",
+        "could shadow the registration provisioned into a worker worktree. That check",
+        "only reads the file and runs `git worktree list --porcelain`; it never edits,",
+        "migrates, or writes any configuration. Credential resolution reports the",
         "source it would use (env vs. store target bapi:<repo>); it never reads or",
         "prints the key value and never writes the credential store. To persist or",
         "migrate a credential, use /install-bridge or the `credentials` subcommand —",
         "doctor stays strictly read-only.",
         "",
+        "On a host with a configured conductor executor service it also reports",
+        "whether worker config isolation is healthy: whether this platform and",
+        "authentication layout allow a worker to run with an executor-owned",
+        "CLAUDE_CONFIG_DIR, so operator-scoped MCP servers are unreachable from a",
+        "worker. This check is a read-only capability evaluation: it never seeds or",
+        "removes an isolated directory, never reads the credential store, and never",
+        "prints a credential value. It affects the exit code only when an executor",
+        "service is configured; otherwise it is advisory.",
+        "",
         "It also includes an advisory 'MCP tool surface' section (BAPI-641): what",
         "dynamic capability gating would advertise for this repo. It performs at most",
         "one read-only GET to /jira/mcp/tool-surface (none under the kill switch) and",
@@ -74,6 +92,16 @@ export function getDoctorUsage() {
         "ignore notifications/tools/list_changed must reconnect or start a new MCP",
         "session to observe surface changes; no project MCP config change is required.",
         "",
+        "It also includes an advisory 'Executor provisioning' section (BAPI-688): the",
+        "generated executor service units on this host. It enumerates them read-only by",
+        "fixed convention — ~/Library/LaunchAgents/com.bridge-gpt.executor.*.plist on",
+        "macOS, ~/.config/systemd/user/bridge-gpt-executor-*.service on Linux (Windows",
+        "Task Scheduler setup is manual, so it reports SKIP) — and reports each unit's",
+        "embedded BAPI_BASE_URL and repositories plus whether a Bridge API credential",
+        "resolves for each repo (target bapi:<repo>, source only, never the key value).",
+        "It reads no install-state file, writes nothing, runs no launchctl/systemctl, and",
+        "is advisory: missing, malformed, or credential-less units never change the exit code.",
+        "",
         "Conductor ledger / native-module diagnostics (the SQLite ledger's native",
         "binding load status and Node-version skew) live under a separate command:",
         "  conductor doctor",
@@ -197,7 +225,15 @@ export function formatDoctorPrereqSection(platform, collection) {
     }
     for (const result of collection.results) {
         const status = result.found ? "FOUND  " : "MISSING";
-        const detail = result.found && result.detail ? ` (${result.detail})` : "";
+        // Missing-detail stays suppressed for every prerequisite EXCEPT one that has
+        // been explicitly audited (BAPI-727, `renderDetailWhenMissing`). The general
+        // suppression exists because a missing probe's detail can be arbitrary text —
+        // `probePrerequisite` puts a thrown error's message there. The Claude
+        // MCP-shadowing descriptor is the sole opt-in: its detail is assembled only
+        // from the inspector's fixed scope/path/shape/env-key-name metadata, and it is
+        // precisely the information an operator needs in order to act.
+        const showDetail = result.detail && (result.found || result.renderDetailWhenMissing === true);
+        const detail = showDetail ? ` (${result.detail})` : "";
         lines.push(`${status} ${result.label}${detail}`);
         if (!result.found) {
             lines.push(`  To install manually: ${result.installHint}`);
@@ -226,50 +262,18 @@ export function formatDoctorReport(platform, agent, collection) {
         formatDoctorPrereqSection(platform, collection),
     ].join("\n");
 }
-// ---------------------------------------------------------------------------
-// Launcher-cache diagnostics (BAPI-451 W3, E-4/E-9) — strictly read-only.
-//
-// install-bridge writes a launcher pinned to `@${VERSION}` (a specific `_npx`
-// bucket). The FIRST launch of a not-yet-cached pin pays a cold install inline,
-// which can exceed an MCP client's connect deadline. doctor inspects each
-// project-local config's actual `bridge-api` launcher spec and reports:
-//   - `unpinned`     — `@latest` / no version suffix (cache bucket is unstable).
-//   - `stale-pinned` — pinned to a version other than the running `VERSION`.
-//   - `warmed`       — pinned to `VERSION` and the `_npx` bucket is present.
-//   - `indeterminate`— pinned to `VERSION` but the bucket probe was not a clean
-//                      hit (a.k.a. `pinned-but-unwarmed`), or the config/spec was
-//                      ambiguous. Never silently reported as "warm".
-// The bucket probe is `npx --no-install <spec> --version`: `--no-install` means
-// the probe can never mutate (warm) the cache, honoring the read-only contract.
-// ---------------------------------------------------------------------------
-/** The npm package whose pinned launcher spec doctor inspects. */
-const BRIDGE_PACKAGE_NAME = "@bridge_gpt/mcp-server";
-/** Project-local MCP configs doctor inspects (mirrors install-bridge's targets). */
-const LAUNCHER_CONFIG_TARGETS = [
-    { relPath: ".mcp.json", topLevelKey: "mcpServers" },
-    { relPath: ".cursor/mcp.json", topLevelKey: "mcpServers" },
-    { relPath: ".vscode/mcp.json", topLevelKey: "servers" },
-];
 /**
  * Extract the `@bridge_gpt/mcp-server[@version]` launcher spec from an args array.
- * The package name is itself scoped (`@scope/name`), so the version delimiter is
- * the LAST `@`: `@bridge_gpt/mcp-server` is unpinned (no version), while
- * `@bridge_gpt/mcp-server@0.2.11` pins `0.2.11`. Returns null when no spec matches.
+ *
+ * Kept as a doctor-shaped adapter over the shared parser so doctor's existing
+ * `{ spec, version }` contract is unchanged: `version` is the raw specifier text
+ * (`0.2.11`, `latest`, `^0.2.0`) or null for the bare package.
  */
 export function parseLauncherPin(args) {
-    if (!Array.isArray(args))
+    const parsed = parseSharedLauncherPin(args);
+    if (!parsed)
         return null;
-    for (const arg of args) {
-        if (typeof arg !== "string")
-            continue;
-        if (arg === BRIDGE_PACKAGE_NAME)
-            return { spec: arg, version: null };
-        if (arg.startsWith(`${BRIDGE_PACKAGE_NAME}@`)) {
-            const version = arg.slice(BRIDGE_PACKAGE_NAME.length + 1).trim();
-            return { spec: arg, version: version.length > 0 ? version : null };
-        }
-    }
-    return null;
+    return { spec: parsed.spec, version: parsed.specifier };
 }
 /**
  * Default read-only cache probe. Spawns `npx --no-install <spec> --version`
@@ -308,79 +312,85 @@ function probeNpxNoInstallDefault(spec) {
  * when pinned to the running `VERSION`, probed read-only with `--no-install`.
  */
 export async function inspectLauncherCache(deps) {
+    // Shared, read-only facts first. `isCreatable` is deliberately omitted: doctor
+    // never implies a file would be created, so every absent config comes back
+    // `skip-inactive` and is filtered out below (an absent config is not a finding).
+    const shared = await inspectLauncherConfigs({
+        cwd: deps.cwd,
+        targetVersion: VERSION,
+        readFile: deps.readFile,
+    });
     const inspections = [];
-    for (const { relPath, topLevelKey } of LAUNCHER_CONFIG_TARGETS) {
-        const fullPath = path.join(deps.cwd, relPath);
-        let raw;
-        try {
-            raw = await deps.readFile(fullPath);
-        }
-        catch {
-            continue; // config absent — not a finding.
-        }
-        let parsed;
-        try {
-            parsed = JSON.parse(raw);
-        }
-        catch {
+    for (const found of shared) {
+        // An absent config is not a doctor finding.
+        if (!found.filePresent)
+            continue;
+        const { relPath, spec, currentVersion } = found;
+        // Order matters: an unreadable or malformed config reports NO bridge entry,
+        // but it is still a finding — doctor cannot determine its pin, and saying
+        // nothing would read as "this config is fine". Classify it before the
+        // no-entry skip below.
+        if (found.action === "invalid" || found.action === "unsupported") {
             inspections.push({
                 relPath,
-                spec: null,
-                pinnedVersion: null,
+                spec,
+                pinnedVersion: currentVersion,
                 state: "indeterminate",
-                remediation: "config is not valid JSON — cannot determine the launcher pin.",
+                remediation: `${describeLauncherReason(found.reason)} — cannot determine the launcher pin.`,
             });
             continue;
         }
-        const entry = parsed && typeof parsed === "object"
-            ? parsed[topLevelKey]?.["bridge-api"]
-            : undefined;
-        if (!entry)
-            continue; // no bridge-api launcher in this config — not a finding.
-        const pin = parseLauncherPin(entry.args);
-        if (!pin) {
+        // A valid config that simply carries no bridge-api launcher is not a finding
+        // (matching the pre-BAPI-728 behavior exactly).
+        if (!found.bridgeEntryPresent)
+            continue;
+        if (found.action === "skip-worktree-shim") {
+            // A worktree shim runs a sibling checkout's build directly; there is no
+            // published-package bucket to warm and no pin to compare.
             inspections.push({
                 relPath,
-                spec: null,
+                spec,
                 pinnedVersion: null,
                 state: "indeterminate",
-                remediation: `no ${BRIDGE_PACKAGE_NAME} spec found in the launcher args.`,
+                remediation: "worktree mcp-invoke shim — this registration launches a local worktree build, so no published-package pin applies.",
             });
             continue;
         }
-        if (pin.version === null || pin.version === "latest") {
+        if (found.action === "normalize-unpinned") {
             inspections.push({
                 relPath,
-                spec: pin.spec,
-                pinnedVersion: pin.version,
+                spec,
+                pinnedVersion: null,
                 state: "unpinned",
                 remediation: `pin the launcher to ${BRIDGE_PACKAGE_NAME}@${VERSION} (run /install-bridge or the install-bridge subcommand to rewrite this config).`,
             });
             continue;
         }
-        if (pin.version !== VERSION) {
+        // `repin` (behind) and `ahead` are both "pinned to something other than the
+        // running VERSION" — doctor's long-standing stale-pinned finding.
+        if (found.action === "repin" || found.action === "ahead") {
             inspections.push({
                 relPath,
-                spec: pin.spec,
-                pinnedVersion: pin.version,
+                spec,
+                pinnedVersion: currentVersion,
                 state: "stale-pinned",
-                remediation: `config pins ${pin.version} but this package is ${VERSION}; run upgrade-bridge / install-bridge to repin and re-warm.`,
+                remediation: `config pins ${currentVersion} but this package is ${VERSION}; run upgrade-bridge / install-bridge to repin and re-warm.`,
             });
             continue;
         }
-        // Pinned to the running VERSION — probe the bucket read-only.
-        const probe = await deps.probeNpxNoInstall(pin.spec);
+        // Pinned exactly to the running VERSION — probe the bucket read-only.
+        const probe = await deps.probeNpxNoInstall(spec);
         if (probe.warmed) {
-            inspections.push({ relPath, spec: pin.spec, pinnedVersion: pin.version, state: "warmed" });
+            inspections.push({ relPath, spec, pinnedVersion: currentVersion, state: "warmed" });
         }
         else {
             inspections.push({
                 relPath,
-                spec: pin.spec,
-                pinnedVersion: pin.version,
+                spec,
+                pinnedVersion: currentVersion,
                 state: "indeterminate",
                 remediation: "pinned-but-unwarmed: the pinned _npx bucket is not a confirmed cache hit, so the first MCP launch may pay a one-time cold install. " +
-                    `Warm it with: npx ${pin.spec} --version, or raise MCP_TIMEOUT for the first launch.`,
+                    `Warm it with: npx ${spec} --version, or raise MCP_TIMEOUT for the first launch.`,
             });
         }
     }
@@ -513,6 +523,306 @@ export function formatToolSurfaceDiagnosticReport(diag) {
     lines.push("to observe surface changes; no project MCP configuration change is required.");
     return lines.join("\n");
 }
+/**
+ * Adapt the executor's read-only capability evaluator for doctor.
+ *
+ * READ-ONLY BY CONSTRUCTION: it forwards only `platform` and `env`, and
+ * `evaluateWorkerConfigIsolationCapability` accepts no mutating dependency at
+ * all — no directory-creation, permission-setting, file-writing, or removal
+ * operation is reachable from it even in principle. No directory is seeded, no
+ * credential value is read, and nothing is persisted. That is what preserves
+ * doctor's read-only contract while still answering AC-4's health question.
+ *
+ * NOTE: this module is pinned by `tests/pytest/mcp_server/test_doctor_static_contract.py`,
+ * which asserts the literal token `write` + `File` appears nowhere in this file —
+ * so describe write operations in prose here rather than naming that API.
+ */
+export function collectWorkerConfigIsolationDiagnostic(input) {
+    const capability = evaluateWorkerConfigIsolationCapability({
+        platform: input.platform,
+        env: input.env,
+    });
+    if (capability.supported) {
+        return {
+            status: "healthy",
+            platform: capability.platform,
+            strategy: capability.strategy,
+            required: input.executorConfigured,
+        };
+    }
+    return {
+        status: "unhealthy",
+        platform: capability.platform,
+        remediation: formatWorkerConfigIsolationReason(capability.platform, capability.reason),
+        required: input.executorConfigured,
+    };
+}
+/** Render the isolation section: fixed labels plus already-bounded reason text. */
+export function formatWorkerConfigIsolationDiagnosticReport(diagnostic) {
+    const lines = ["", "Worker config isolation (conductor executor)"];
+    if (diagnostic.status === "healthy") {
+        lines.push(`  HEALTHY  ${diagnostic.platform}: isolation can be established (strategy: ${diagnostic.strategy})`);
+        lines.push("           Workers run with an executor-owned CLAUDE_CONFIG_DIR, so operator-scoped");
+        lines.push("           MCP servers are unreachable from a worker.");
+        return lines.join("\n");
+    }
+    // An executor host cannot dispatch workers safely without isolation, so the
+    // label distinguishes a blocking condition from an advisory one.
+    lines.push(`  ${diagnostic.required ? "UNHEALTHY" : "SKIP     "}  ${diagnostic.remediation ?? ""}`);
+    if (!diagnostic.required) {
+        lines.push("           Advisory only: no executor service is configured on this host.");
+    }
+    return lines.join("\n");
+}
+/** Where generated units live, and how their filenames encode the executor id. */
+function resolveExecutorServiceConvention(platform, homeDir) {
+    if (platform === "darwin") {
+        return {
+            dir: executorLaunchdDirForHome(homeDir),
+            kind: "launchd-plist",
+            idFromFilename: executorIdFromLaunchdFilename,
+        };
+    }
+    if (platform === "linux") {
+        return {
+            dir: executorSystemdDirForHome(homeDir),
+            kind: "systemd-service",
+            idFromFilename: executorIdFromSystemdFilename,
+        };
+    }
+    return null;
+}
+/**
+ * Resolve one repository's credential and IMMEDIATELY discard the key, keeping
+ * only a source/status label. The resolved value never enters a diagnostic
+ * object, a warning, or the rendered report.
+ */
+async function probeRepoCredential(repo, deps, credDeps) {
+    const target = `bapi:${repo}`;
+    const resolve = deps.resolveCredentials ?? resolveBapiCredentials;
+    try {
+        const result = await resolve(repo, credDeps);
+        if (result.ok) {
+            return { repo, target, resolved: true, source: String(result.credentials.source) };
+        }
+        return { repo, target, resolved: false, kind: String(result.kind) };
+    }
+    catch {
+        // Sanitized: a resolver throw is reported as a kind, never as exception text.
+        return { repo, target, resolved: false, kind: "unavailable" };
+    }
+}
+/**
+ * Collect read-only diagnostics for every convention-named executor service unit
+ * on this host. Never throws: a vanished directory entry, an unreadable unit, or
+ * a malformed body becomes a sanitized advisory warning and collection continues.
+ */
+export async function collectExecutorServiceDiagnostics(deps) {
+    if (deps.platform === "win32") {
+        return {
+            status: "skipped",
+            reason: "Windows executor services are set up manually through Task Scheduler, so there is no " +
+                "generated unit to enumerate (`executor install-service` prints the command line instead).",
+        };
+    }
+    const convention = resolveExecutorServiceConvention(deps.platform, deps.homedir());
+    if (!convention) {
+        return {
+            status: "skipped",
+            reason: `platform '${deps.platform}' has no generated executor service format.`,
+        };
+    }
+    let entries;
+    try {
+        entries = await deps.readdir(convention.dir);
+    }
+    catch {
+        return {
+            status: "skipped",
+            reason: `no executor service units found (${convention.dir} is absent or unreadable).`,
+        };
+    }
+    // Sort BEFORE inspection so report ordering is deterministic regardless of the
+    // order the filesystem happened to return entries in.
+    const matching = entries
+        .filter((name) => convention.idFromFilename(name) !== null)
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    if (matching.length === 0) {
+        return {
+            status: "skipped",
+            reason: `no executor service units found in ${convention.dir}.`,
+        };
+    }
+    const credDeps = {
+        env: deps.env,
+        homedir: deps.homedir,
+        platform: deps.platform,
+        readFile: deps.readFile,
+        stat: deps.stat,
+        stderr: () => { },
+    };
+    // Only darwin/linux reach here (win32 and unsupported platforms returned
+    // above), so unit paths always use POSIX semantics — matching the generators.
+    const pathApi = path.posix;
+    const units = [];
+    const warnings = [];
+    for (const name of matching) {
+        const unitPath = pathApi.join(convention.dir, name);
+        const executorId = convention.idFromFilename(name) ?? name;
+        try {
+            await deps.stat(unitPath);
+        }
+        catch {
+            // The entry vanished or became unreadable between enumeration and stat.
+            warnings.push(`${unitPath}: disappeared or became unreadable during collection.`);
+            continue;
+        }
+        let content;
+        try {
+            content = await deps.readFile(unitPath);
+        }
+        catch {
+            units.push({
+                path: unitPath,
+                executorId,
+                baseUrl: null,
+                baseUrlClass: "missing",
+                repos: [],
+                credentials: [],
+                warnings: ["unit could not be read; its configuration cannot be verified."],
+            });
+            continue;
+        }
+        const inspection = inspectExecutorServiceArtifact(convention.kind, content);
+        const unitWarnings = [...inspection.problems];
+        let baseUrlClass;
+        if (!inspection.baseUrl) {
+            baseUrlClass = "missing";
+            unitWarnings.push(`no ${EXECUTOR_SERVICE_BASE_URL_ENV} in the unit — the executor requires an explicit base ` +
+                "URL and will fail to start.");
+        }
+        else if (inspection.baseUrl.replace(/\/+$/, "") === DEFAULT_BAPI_BASE_URL) {
+            baseUrlClass = "production-default";
+            unitWarnings.push(`${EXECUTOR_SERVICE_BASE_URL_ENV} points at production (${DEFAULT_BAPI_BASE_URL}) — legal, ` +
+                "but worth confirming this host is meant to serve production jobs.");
+        }
+        else {
+            baseUrlClass = "configured";
+        }
+        // Probe each DISTINCT repository once per unit, even when the unit repeats it.
+        const distinctRepos = Array.from(new Set(inspection.repos));
+        const credentials = [];
+        for (const repo of distinctRepos) {
+            credentials.push(await probeRepoCredential(repo, deps, credDeps));
+        }
+        units.push({
+            path: unitPath,
+            executorId,
+            baseUrl: inspection.baseUrl,
+            baseUrlClass,
+            repos: inspection.repos,
+            credentials,
+            warnings: unitWarnings,
+        });
+    }
+    return { status: "collected", units, warnings };
+}
+/**
+ * Render the advisory "Executor provisioning" section (pure formatting — no I/O).
+ * Every line is found / WARN / SKIP; nothing here changes the exit code.
+ */
+export function formatExecutorServiceDiagnosticsReport(diagnostics) {
+    const lines = ["", "Executor provisioning (generated service units — advisory)", ""];
+    if (diagnostics.status === "skipped") {
+        lines.push(`SKIP  ${diagnostics.reason}`);
+        lines.push("");
+        lines.push("This section is read-only and advisory: it enumerates units by fixed directory and filename");
+        lines.push("prefix, and never changes the doctor exit code.");
+        return lines.join("\n");
+    }
+    for (const warning of diagnostics.warnings) {
+        lines.push(`WARN  ${warning}`);
+    }
+    for (const unit of diagnostics.units) {
+        lines.push(`found ${unit.path}`);
+        lines.push(`      executor id: ${unit.executorId}`);
+        lines.push(`      ${EXECUTOR_SERVICE_BASE_URL_ENV}: ${unit.baseUrl ?? "(absent)"} [${unit.baseUrlClass}]`);
+        lines.push(`      repos: ${unit.repos.length > 0 ? unit.repos.join(", ") : "(none parsed)"}`);
+        for (const cred of unit.credentials) {
+            lines.push(cred.resolved
+                ? `      credential ${cred.target}: resolved (source: ${cred.source})`
+                : `      credential ${cred.target}: NOT resolved (${cred.kind})`);
+        }
+        for (const warning of unit.warnings) {
+            lines.push(`WARN  ${unit.path}: ${warning}`);
+        }
+    }
+    lines.push("");
+    lines.push("Generated units carry only the base URL, the generating shell's PATH, repositories, and", "executor id — credentials resolve at");
+    lines.push("launch time from BAPI_API_KEY or the user-scoped bapi:<repo> store, so no key value is stored on");
+    lines.push("disk or printed here. Starting, stopping, and enabling a unit stay operator-managed. This section");
+    lines.push("is advisory and never changes the doctor exit code.");
+    return lines.join("\n");
+}
+export async function collectPlaneCredentialDiagnostic(deps) {
+    const anthropic = deps.env.ANTHROPIC_API_KEY;
+    const anthropicKeyPresent = typeof anthropic === "string" && anthropic.trim().length > 0;
+    const resolveRepo = deps.resolveRepoName ?? resolveRequiredStartTicketsRepoName;
+    let repo = null;
+    try {
+        const result = await resolveRepo({ env: deps.env, cwd: deps.cwd, readFile: deps.readFile });
+        if (result.ok)
+            repo = result.repoName;
+    }
+    catch {
+        /* sanitized: identity resolution failure is reported as an absent repo */
+    }
+    if (repo === null) {
+        return { anthropicKeyPresent, repo: null, target: null, bridgeCredentialResolved: false };
+    }
+    // Resolve, then keep ONLY a label. The key never reaches the diagnostic.
+    const status = await probeRepoCredential(repo, { platform: deps.platform, env: deps.env, homedir: deps.homedir, readdir: async () => [], readFile: deps.readFile, stat: deps.stat, resolveCredentials: deps.resolveCredentials }, {
+        env: deps.env,
+        homedir: deps.homedir,
+        platform: deps.platform,
+        readFile: deps.readFile,
+        stat: deps.stat,
+        stderr: () => {
+            /* resolver advisories are not part of the doctor report */
+        },
+    });
+    return {
+        anthropicKeyPresent,
+        repo,
+        target: status.target,
+        bridgeCredentialResolved: status.resolved,
+        source: status.source,
+        kind: status.kind,
+    };
+}
+/** Render the plane readiness section. Advisory: never changes the exit code. */
+export function formatPlaneCredentialDiagnosticReport(diagnostic) {
+    const lines = ["", "Conductor plane credentials (`plane up` — advisory)"];
+    lines.push(diagnostic.anthropicKeyPresent
+        ? "  OK       ANTHROPIC_API_KEY is set in this shell."
+        : "  MISSING  ANTHROPIC_API_KEY is not set in this shell. Isolated workers have no OAuth\n" +
+            "           session and refuse to spawn without it, so `plane up` will refuse.");
+    if (diagnostic.repo === null) {
+        lines.push("  MISSING  the Bridge repository identity could not be resolved. Set BAPI_REPO_NAME or\n" +
+            "           add a valid .bridge/config at the repository root.");
+    }
+    else if (diagnostic.bridgeCredentialResolved) {
+        lines.push(`  OK       credential ${diagnostic.target}: resolved (source: ${diagnostic.source}).`);
+    }
+    else {
+        lines.push(`  MISSING  credential ${diagnostic.target}: NOT resolved (${diagnostic.kind}).\n` +
+            "           A spawned shell never sees .mcp.json env — set BAPI_API_KEY here, or store\n" +
+            "           it with `mcp-server credentials`.");
+    }
+    lines.push("           Read-only: this section resolves an identity and probes a credential. It creates");
+    lines.push("           no .bridge/plane/ directory, persists nothing, and starts no plane member.");
+    return lines.join("\n");
+}
 /**
  * CLI entry for the read-only `doctor` subcommand. Returns a process exit code.
  * Help returns 0; parser errors return 1; otherwise it prints the report and
@@ -621,7 +931,89 @@ export async function runDoctorCli(argv, overrides = {}) {
             }));
         }
     }
+    // Advisory executor-provisioning section (BAPI-688). Strictly read-only: it
+    // enumerates convention-named units under a fixed OS directory, parses their
+    // non-secret configuration, and probes credential resolution WITHOUT retaining
+    // any key. It is collected independently of `DoctorCollectionResult` and, like
+    // the sections above, never affects the exit code — missing units, malformed
+    // units, and unresolved credentials are all advisory.
+    // BAPI-731: set only when isolation is unhealthy AND this host runs an
+    // executor, so an executor-only requirement never fails an ordinary MCP user's
+    // doctor run.
+    let isolationFailed = false;
+    if (overrides.executorService !== false) {
+        try {
+            const injectedFs = deps;
+            const executorDeps = {
+                platform: overrides.executorService?.platform ?? deps.platform,
+                env: overrides.executorService?.env ?? deps.env,
+                homedir: overrides.executorService?.homedir ?? injectedFs.homedir ?? os.homedir,
+                readdir: overrides.executorService?.readdir ?? ((p) => readdir(p)),
+                readFile: overrides.executorService?.readFile ??
+                    injectedFs.readFile ??
+                    ((p) => readFile(p, "utf-8")),
+                stat: overrides.executorService?.stat ?? injectedFs.stat ?? ((p) => stat(p)),
+                resolveCredentials: overrides.executorService?.resolveCredentials,
+            };
+            const executorDiagnostics = await collectExecutorServiceDiagnostics(executorDeps);
+            log(formatExecutorServiceDiagnosticsReport(executorDiagnostics));
+            // BAPI-731: worker config isolation health, rendered right after the
+            // executor-service section because it is only REQUIRED when this host
+            // actually runs an executor. Read-only: it evaluates capability and
+            // creates nothing (see the assertion in `collectWorkerConfigIsolationDiagnostic`).
+            const isolationDiagnostic = collectWorkerConfigIsolationDiagnostic({
+                platform: executorDeps.platform,
+                env: executorDeps.env,
+                executorConfigured: executorDiagnostics.status === "collected" && executorDiagnostics.units.length > 0,
+            });
+            log(formatWorkerConfigIsolationDiagnosticReport(isolationDiagnostic));
+            if (isolationDiagnostic.status === "unhealthy" && isolationDiagnostic.required) {
+                isolationFailed = true;
+            }
+        }
+        catch {
+            // Any unexpected failure still renders a sanitized advisory SKIP line.
+            log(formatExecutorServiceDiagnosticsReport({
+                status: "skipped",
+                reason: "executor service units could not be enumerated on this host.",
+            }));
+        }
+    }
+    // Advisory conductor-plane credential section (BAPI-756). Read-only and, like
+    // every section above, never affects the exit code: `plane up` enforces these
+    // same invariants at the point where they actually block, and an ordinary MCP
+    // user who never runs a conductor plane should not see a failing doctor.
+    if (overrides.planeCredentials !== false) {
+        try {
+            const injectedFs = deps;
+            const planeDeps = {
+                env: overrides.planeCredentials?.env ?? deps.env,
+                cwd: overrides.planeCredentials?.cwd ?? deps.cwd,
+                platform: overrides.planeCredentials?.platform ?? deps.platform,
+                homedir: overrides.planeCredentials?.homedir ?? injectedFs.homedir ?? os.homedir,
+                readFile: overrides.planeCredentials?.readFile ??
+                    injectedFs.readFile ??
+                    ((p) => readFile(p, "utf-8")),
+                stat: overrides.planeCredentials?.stat ?? injectedFs.stat ?? ((p) => stat(p)),
+                resolveRepoName: overrides.planeCredentials?.resolveRepoName,
+                resolveCredentials: overrides.planeCredentials?.resolveCredentials,
+            };
+            log(formatPlaneCredentialDiagnosticReport(await collectPlaneCredentialDiagnostic(planeDeps)));
+        }
+        catch {
+            // Any unexpected failure still renders a sanitized advisory line rather
+            // than dropping the section or leaking exception text.
+            log(formatPlaneCredentialDiagnosticReport({
+                anthropicKeyPresent: false,
+                repo: null,
+                target: null,
+                bridgeCredentialResolved: false,
+            }));
+        }
+    }
     if (!collection.ok)
         return 1;
+    if (isolationFailed)
+        return 1;
     return collection.results.some((r) => !r.found) ? 1 : 0;
 }