@bridge_gpt/mcp-server 0.2.36 → 0.2.37

package/build/doctor.js

@@ -25,11 +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
@@ -62,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",
@@ -209,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}`);
@@ -238,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`
@@ -320,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.`,
             });
         }
     }
@@ -525,6 +523,57 @@ 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") {
@@ -715,6 +764,65 @@ export function formatExecutorServiceDiagnosticsReport(diagnostics) {
     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
@@ -829,6 +937,10 @@ export async function runDoctorCli(argv, overrides = {}) {
     // 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;
@@ -845,6 +957,19 @@ export async function runDoctorCli(argv, overrides = {}) {
             };
             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.
@@ -854,7 +979,41 @@ export async function runDoctorCli(argv, overrides = {}) {
             }));
         }
     }
+    // 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;
 }

package/build/executor/cli.js

@@ -15,6 +15,8 @@ import { resolveBaseUrl, resolveExecutorApiAccess, EXECUTOR_BASE_URL_REQUIRED_ME
 import { createExecutorHttpClient } from "./http-client.js";
 import { runExecutor } from "./runner.js";
 import { runExecutorWatchCli } from "./watch-cli.js";
+import { sweepOrphanedWorkerConfigDirectories } from "./worker-config-isolation.js";
+import { pathApiForProvisioningPlatform } from "../mcp-provisioning.js";
 /** Fixed executor timing/behavior defaults. */
 const DEFAULT_POLL_INTERVAL_MS = 15_000;
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 60_000;
@@ -173,6 +175,25 @@ export function parseExecutorArgs(argv, context) {
     };
     return { kind: "ok", options };
 }
+/**
+ * Build the sweep boundary from executor deps, or `null` when this executor was
+ * constructed without the filesystem operations the sweep needs. `null` simply
+ * skips the sweep — unlike isolation itself, a missing sweep is not a safety
+ * problem, only uncollected residue.
+ */
+function buildWorkerConfigSweepDeps(deps) {
+    const { tmpdir, readdir, lstatPath, rmRecursive } = deps;
+    if (!tmpdir || !readdir || !lstatPath || !rmRecursive)
+        return null;
+    return {
+        tmpdir,
+        readdir,
+        lstatPath,
+        rmRecursive,
+        join: (...segments) => pathApiForProvisioningPlatform(deps.platform).join(...segments),
+        now: deps.now,
+    };
+}
 function hasRepoFlag(argv) {
     return argv.some((a) => a === "--repo" || a === "--repos" || a.startsWith("--repos="));
 }
@@ -228,6 +249,13 @@ export async function runExecutorCli(argv, overrides = {}) {
     // the first repo's key. Uses the (injectable) single-repo resolver per repo.
     const resolveApi = overrides.resolveApiAccess ?? resolveExecutorApiAccess;
     const apiKeyByRepo = {};
+    // BAPI-727: retain the normalized base URL from the SUCCESSFUL access result —
+    // not `options.baseUrl` (the raw, pre-validation CLI string) and not
+    // `deps.env.BAPI_BASE_URL` (which loses to an explicit `--base-url`). Worker MCP
+    // provisioning propagates this exact value, so a worker can never be pointed at a
+    // different endpoint than the executor that dispatched it. Every repo resolves
+    // against the same explicit URL, so the value is identical across the loop.
+    let resolvedBaseUrl;
     for (const repo of options.repos) {
         const access = await resolveApi(repo, deps, baseUrl);
         if (!access.ok) {
@@ -235,6 +263,7 @@ export async function runExecutorCli(argv, overrides = {}) {
             return 1;
         }
         apiKeyByRepo[repo] = access.apiKey;
+        resolvedBaseUrl = access.baseUrl;
     }
     const createHttpClient = overrides.createHttpClient ?? createExecutorHttpClient;
     const httpClient = createHttpClient({
@@ -244,9 +273,30 @@ export async function runExecutorCli(argv, overrides = {}) {
         mcpVersion: VERSION,
         fetch: deps.fetch,
     });
+    // BAPI-731: sweep isolation directories orphaned by an ungraceful earlier exit
+    // (SIGKILL, OOM, host reboot) where per-job disposal never ran. Deliberately a
+    // ONE-SHOT startup step, separate from per-job disposal: normal cleanup stays
+    // immediate, and this only reclaims residue. Never blocks claiming — a sweep
+    // failure is a bounded diagnostic, because refusing to start over leftover
+    // temp directories would be a worse failure than the leftovers.
+    const sweep = overrides.sweepOrphanedWorkerConfigDirectories ?? sweepOrphanedWorkerConfigDirectories;
+    try {
+        const isolationSweepDeps = buildWorkerConfigSweepDeps(deps);
+        if (isolationSweepDeps) {
+            const swept = await sweep(isolationSweepDeps);
+            for (const diagnostic of swept.diagnostics)
+                errorLog(diagnostic);
+        }
+    }
+    catch {
+        errorLog("worker config isolation sweep did not complete; continuing startup");
+    }
     const run = overrides.runExecutor ?? runExecutor;
+    // Hand the loop the VALIDATED runtime configuration: the parsed options plus the
+    // normalized base URL resolution actually settled on.
+    const runtimeOptions = { ...options, resolvedBaseUrl };
     try {
-        return await run(options, deps, httpClient);
+        return await run(runtimeOptions, deps, httpClient);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);

package/build/executor/credentials.js

@@ -7,6 +7,7 @@
  * diagnostics/results.
  */
 import { resolveBapiCredentials } from "../credential-store.js";
+import { normalizeBaseUrlCandidate } from "../base-url.js";
 /**
  * The documented production Bridge API base URL — the value an operator pastes
  * into `BAPI_BASE_URL` or `--base-url` when they *do* mean production.
@@ -25,13 +26,6 @@ export const DEFAULT_BAPI_BASE_URL = "https://bridgegpt-api.com";
  */
 export const EXECUTOR_BASE_URL_REQUIRED_MESSAGE = "no Bridge API base URL configured for the executor: pass --base-url <url> or set BAPI_BASE_URL " +
     `(production is ${DEFAULT_BAPI_BASE_URL}). The executor never defaults to production.`;
-/** Trim, strip every trailing slash, and treat an empty result as absent. */
-function normalizeBaseUrlCandidate(raw) {
-    if (typeof raw !== "string")
-        return null;
-    const normalized = raw.trim().replace(/\/+$/, "");
-    return normalized.length > 0 ? normalized : null;
-}
 /**
  * Resolve the executor's base URL: explicit override (`--base-url`) first, then
  * `BAPI_BASE_URL`, then failure. A blank override is treated as absent so a

package/build/executor/deps.js

@@ -9,7 +9,7 @@
  */
 import { execFile, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-import { readFile, writeFile, appendFile, mkdir, stat, statfs } from "node:fs/promises";
+import { readFile, writeFile, appendFile, mkdir, mkdtemp, chmod, rm, readdir, lstat, stat, statfs, } from "node:fs/promises";
 import os from "node:os";
 import { promisify } from "node:util";
 import { resolveMcpShimInvocationForRuntime } from "../mcp-server-invocation.js";
@@ -85,6 +85,23 @@ export function createDefaultExecutorDeps() {
             const s = await statfs(path);
             return { bavail: Number(s.bavail), bsize: Number(s.bsize) };
         },
+        // --- Worker config isolation filesystem boundaries (BAPI-731) ----------
+        // Bound to real `node:fs/promises` operations here so the isolation module
+        // itself never reaches for a filesystem global and stays fully unit-testable.
+        mkdtemp: (prefix) => mkdtemp(prefix),
+        chmod: (path, mode) => chmod(path, mode),
+        rmRecursive: (path) => rm(path, { recursive: true, force: true }),
+        readdir: (dirPath) => readdir(dirPath),
+        // `lstat`, never `stat`: a symlinked isolation parent or swept entry must be
+        // recognizable AS a symlink rather than reported as its target directory.
+        lstatPath: (path) => lstat(path)
+            .then((s) => ({
+            isDirectory: s.isDirectory(),
+            isSymbolicLink: s.isSymbolicLink(),
+            mtimeMs: s.mtimeMs,
+        }))
+            .catch(() => null),
+        tmpdir: () => os.tmpdir(),
         sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
         now: () => Date.now(),
         setTimer: (cb, ms) => setTimeout(cb, ms),