@bridge_gpt/mcp-server 0.2.50 → 0.2.52

package/build/doctor.js

@@ -28,9 +28,11 @@ import { createBridgeApiUrls } from "./bridge-api-urls.js";
 import { probeToolSurface } from "./tool-surface-gating.js";
 import { resolveBapiCredentials } from "./credential-store.js";
 import { resolveConductorBridgeApiAccess } from "./conductor/bridge-api-client.js";
+import { getLiveRepositoryConductors, getParseDispatcherHealth, } from "./conduct-epic/bridge-client.js";
 import { resolveConductEpicStateDirectory } from "./conduct-epic/checkpoint-store.js";
 import { isConductEpicLockOwnerAlive, parseConductEpicLock, } from "./conduct-epic/lock.js";
 import { resolveRequiredStartTicketsRepoName } from "./start-tickets-repo.js";
+import { collectWorkerContainmentDiagnostic, formatWorkerContainmentDiagnosticReport, } from "./worker-containment-diagnostic.js";
 import { BRIDGE_PACKAGE_NAME, describeLauncherReason, DUPLICATE_REGISTRATION_GUIDANCE, inspectLauncherConfigs, parseLauncherPin as parseSharedLauncherPin, } from "./launcher-config-inspection.js";
 import { MCP_SERVER_NAME, MCP_PACKAGE_NAME, } from "./mcp-identity.js";
 import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
@@ -96,7 +98,17 @@ export function getDoctorUsage() {
         // scoping, and BAPI-791 deleted that doctor section together with the whole
         // worker-auth strategy vocabulary. The section it described exists in no
         // doctor output, so the claim is removed rather than reworded.
-        "Worker containment is no longer reported here. A conductor worker is scoped",
+        "It includes an advisory 'Worker containment' section (BAPI-1019) reporting the",
+        "DECLARED posture a conductor worker runs under: that the executor strips this",
+        "checkout's .env* files from a worker's worktree as the last step before spawn",
+        "(refusing to spawn with ContractError.WorkerEnvFilePresent when it cannot",
+        "confirm they are gone), that a worker's database environment names a target",
+        "that does not exist, and the run policy's default permission posture. The",
+        "section issues ZERO probes — no command, no file read, no network call — and",
+        "reports constants rather than measurements, so it never claims a live check",
+        "ran and never changes the exit code.",
+        "",
+        "MCP containment is still not reported here. A conductor worker is scoped",
         "at spawn time with `--strict-mcp-config --mcp-config <file>`, and the",
         "executor asserts that scope per spawn from the worker's own system/init",
         "event — failing the job with ContractError.McpSurfaceMismatch on a confirmed",
@@ -1401,6 +1413,151 @@ export function formatConductEpicDiagnosticReport(diagnostic) {
     lines.push("           lock, rewrites no checkpoint, and never changes the exit code.");
     return lines.join("\n");
 }
+/**
+ * Collect the operational advisories, read-only.
+ *
+ * Local pilot conductors are identified from the SAME checkpoint-directory and
+ * lock inspection `conduct-epic readiness` uses — `parseConductEpicLock` plus the
+ * injected liveness seam — never from the process table. Only a lock proven live
+ * on THIS host counts; malformed, unreadable, dead, and remote-host locks are
+ * excluded from the live set, with the indeterminate ones counted separately.
+ */
+export async function collectOperationalAdvisories(deps) {
+    const isAlive = deps.isProcessAlive ?? isConductEpicLockOwnerAlive;
+    const now = deps.now ?? (() => new Date());
+    const resolveAccess = deps.resolveAccess ?? resolveConductorBridgeApiAccess;
+    let dispatcher = null;
+    let conductorObservation = "unavailable";
+    const conductors = [];
+    let repo = null;
+    let access = null;
+    try {
+        access = await resolveAccess({
+            env: deps.env,
+            cwd: deps.cwd,
+            homedir: deps.homedir,
+            platform: deps.platform,
+            readFile: deps.readFile,
+            stat: deps.stat,
+        });
+    }
+    catch {
+        access = null;
+    }
+    if (access !== null && access.ok) {
+        repo = access.access.repoName;
+        const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+        const health = await getParseDispatcherHealth(access.access, fetchImpl);
+        dispatcher = health.ok
+            ? health.value
+            : { observation: "unavailable", heartbeatState: null, respondingSchedulerRunning: false };
+        const live = await getLiveRepositoryConductors(access.access, now(), fetchImpl);
+        if (live.ok) {
+            conductorObservation = live.value.observation;
+            conductors.push(...live.value.conductors);
+        }
+    }
+    // Local pilot locks. Read through the same path the readiness section uses; a
+    // failure to read the directory is silence, not a claim that none are held.
+    let indeterminateLocks = 0;
+    if (repo !== null) {
+        const stateDirectory = resolveConductEpicStateDirectory(repo, {
+            env: deps.env,
+            homedir: deps.homedir,
+        });
+        let entries = [];
+        try {
+            entries = await deps.readdir(stateDirectory);
+        }
+        catch {
+            entries = [];
+        }
+        for (const entry of entries) {
+            if (!entry.endsWith(".lock"))
+                continue;
+            const epic = entry.slice(0, -".lock".length);
+            let raw;
+            try {
+                raw = await deps.readFile(path.join(stateDirectory, entry));
+            }
+            catch {
+                indeterminateLocks += 1;
+                continue;
+            }
+            const owner = parseConductEpicLock(raw);
+            if (owner === null) {
+                indeterminateLocks += 1;
+                continue;
+            }
+            const local = owner.host === deps.env.HOSTNAME || owner.host === os.hostname();
+            if (!local) {
+                indeterminateLocks += 1;
+                continue;
+            }
+            if (!isAlive(owner.owner_pid))
+                continue;
+            // A pilot lock and a v2 run are two DISTINCT conductor authorities. Even
+            // when both name the same epic they are not deduplicated — that pairing is
+            // precisely the overlap an operator most needs to see.
+            //
+            // The key comes from a FILENAME, so it is bounded against the epic-key shape
+            // before it is rendered; an unrecognized name reports `unknown` rather than
+            // putting arbitrary filesystem text into a diagnostic line.
+            conductors.push({
+                kind: "pilot",
+                epicKey: validateTicketKey(epic, "epic key").ok ? epic : null,
+                state: "lock held",
+                livenessSource: "lock",
+            });
+        }
+        if (conductors.length > 0 && conductorObservation !== "observed") {
+            conductorObservation = "observed";
+        }
+    }
+    return { dispatcher, conductorObservation, conductors, indeterminateLocks };
+}
+/** Render the operational-advisories section. Advisory: never changes the exit code. */
+export function formatOperationalAdvisoryReport(diagnostic) {
+    const lines = ["", "operational advisories (advisory)"];
+    const dispatcher = diagnostic.dispatcher;
+    if (dispatcher === null) {
+        lines.push("  SKIP     Parse dispatcher: not checked (no Bridge credential resolved).");
+    }
+    else if (dispatcher.observation === "observed") {
+        lines.push("  OK       Parse dispatcher: observable — queued repository parses are being swept.");
+    }
+    else if (dispatcher.observation === "absent") {
+        lines.push("  WARN     Parse dispatcher: NOT observed. Queued repository parses wait for the\n" +
+            "           `worker:` dyno's parse-queue sweep; nothing else dispatches them.");
+    }
+    else {
+        lines.push("  SKIP     Parse dispatcher: unavailable — the liveness read produced no verdict.\n" +
+            "           This is not evidence that no dispatcher is running.");
+    }
+    if (diagnostic.conductorObservation === "unavailable") {
+        lines.push("  SKIP     Concurrent conductors: unavailable — the repository-scoped read produced\n" +
+            "           no verdict.");
+    }
+    else if (diagnostic.conductors.length === 0) {
+        lines.push("  OK       Concurrent conductors: none live on this repository.");
+    }
+    else {
+        lines.push(`  WARN     Concurrent conductors: ${diagnostic.conductors.length} live on this repository.`);
+        for (const conductor of diagnostic.conductors) {
+            lines.push(`           ${conductor.kind}  epic=${conductor.epicKey ?? "unknown"}  ` +
+                `state=${conductor.state}  liveness=${conductor.livenessSource}`);
+        }
+        lines.push("           A distinct-epic overlap is informational and may be legitimate: separately\n" +
+            "           scoped epics do not share transition authority.");
+    }
+    if (diagnostic.indeterminateLocks > 0) {
+        lines.push(`           ${diagnostic.indeterminateLocks} local lock(s) could not be judged (remote host,\n` +
+            "           malformed, or unreadable) and are excluded from the live count.");
+    }
+    lines.push("           Read-only: this section issues two Bridge GETs and reads local lock state. It");
+    lines.push("           runs NO command probe, repairs no scheduler, and never changes the exit code.");
+    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
@@ -1550,6 +1707,34 @@ export async function runDoctorCli(argv, overrides = {}) {
             /* local-launcher diagnostics are advisory; never block the doctor report */
         }
     }
+    // Worker containment advisory section (BAPI-1019/A.7). Placed beside the other
+    // advisory sections and, uniquely, issuing NO probe of any kind — no command,
+    // no file read, no network call. That is what keeps doctor's "an unsupported
+    // platform issues zero command probes" guarantee intact: a section that cannot
+    // probe cannot break it on any platform.
+    //
+    // Wrapped in the same swallowing `try` as its neighbours. It reports declared
+    // constants, so it should not be able to throw at all — which is exactly why an
+    // unexpected throw here must not take the whole report (or the exit code) with
+    // it.
+    if (overrides.workerContainment !== false) {
+        try {
+            log(formatWorkerContainmentDiagnosticReport(collectWorkerContainmentDiagnostic()));
+        }
+        catch {
+            // Degrade VISIBLY rather than dropping a section the help text promises:
+            // the formatter's own unusable-input path renders the heading with
+            // "Not confirmed" rows, which is the honest answer and is exactly what a
+            // reader needs to see instead of silence. Passing `undefined` reuses that
+            // one fallback rather than inventing a second wording here.
+            try {
+                log(formatWorkerContainmentDiagnosticReport(undefined));
+            }
+            catch {
+                /* worker-containment posture is advisory; never block the doctor report */
+            }
+        }
+    }
     // Advisory MCP tool-surface capability section (BAPI-641). Strictly read-only:
     // one 500 ms GET (or none, under the kill switch). Any timeout, malformed
     // response, or unexpected throw degrades to a "fail-open to full surface" line
@@ -1701,6 +1886,50 @@ export async function runDoctorCli(argv, overrides = {}) {
             }));
         }
     }
+    // Advisory operational-advisories section (BAPI-963), placed immediately after
+    // `conduct-epic readiness` because both are read by the same operator at the
+    // same moment — "can I conduct?" then "what else is already running?".
+    //
+    // Gated on `collection.ok` for the same reason the section above is: an
+    // unsupported platform reports nothing. That gate is belt-and-braces here,
+    // because this section issues NO command probe on any path — the two facts it
+    // reports come from read-only Bridge GETs and from local lock state. The
+    // "unsupported platform runs zero probes" pin is therefore untouched by it.
+    //
+    // Advisory with respect to the EXIT CODE: an absent dispatcher, a concurrent
+    // conductor, and an unavailable read all leave doctor's pass/fail exactly as
+    // the required prerequisites computed it.
+    if (overrides.operationalAdvisories !== false && collection.ok) {
+        try {
+            const injectedFs = deps;
+            const advisoryDeps = {
+                env: overrides.operationalAdvisories?.env ?? deps.env,
+                cwd: overrides.operationalAdvisories?.cwd ?? deps.cwd,
+                platform: overrides.operationalAdvisories?.platform ?? deps.platform,
+                homedir: overrides.operationalAdvisories?.homedir ?? injectedFs.homedir ?? os.homedir,
+                readFile: overrides.operationalAdvisories?.readFile ??
+                    injectedFs.readFile ??
+                    ((p) => readFile(p, "utf-8")),
+                stat: overrides.operationalAdvisories?.stat ?? injectedFs.stat ?? ((p) => stat(p)),
+                readdir: overrides.operationalAdvisories?.readdir ?? ((p) => readdir(p)),
+                resolveAccess: overrides.operationalAdvisories?.resolveAccess,
+                isProcessAlive: overrides.operationalAdvisories?.isProcessAlive,
+                fetchImpl: overrides.operationalAdvisories?.fetchImpl,
+                now: overrides.operationalAdvisories?.now,
+            };
+            log(formatOperationalAdvisoryReport(await collectOperationalAdvisories(advisoryDeps)));
+        }
+        catch {
+            // Any unexpected failure still renders a sanitized advisory section rather
+            // than dropping it or leaking exception text.
+            log(formatOperationalAdvisoryReport({
+                dispatcher: null,
+                conductorObservation: "unavailable",
+                conductors: [],
+                indeterminateLocks: 0,
+            }));
+        }
+    }
     // Opt-in stale-ticket-branch section (BAPI-948). Gated on argv, not on platform
     // support: it runs ONLY when the operator named at least one `--stale-branch`
     // ticket, so an ordinary `doctor` run issues zero extra command probes and