@bridge_gpt/mcp-server 0.2.51 → 0.2.53

package/build/conductor/doctor.js

@@ -16,6 +16,55 @@ import { inspectConductorGitHooks } from "./git-hooks.js";
 import { resolveMcpShimInvocationForRuntime, resolvePackageRootFromModuleUrl, } from "../mcp-server-invocation.js";
 import { MCP_PACKAGE_NAME } from "../mcp-identity.js";
 import { resolveProfiles } from "../mcp-profile.js";
+import { createReadinessCheck, createReadinessCheckSafely, } from "../readiness-check.js";
+/**
+ * Remediation for a conductor context whose resolved MCP groups omit `conductor`.
+ *
+ * Fixed prose: it never interpolates the raw `BRIDGE_MCP_PROFILE` value. The
+ * legacy warning does interpolate it (unchanged), but a consolidated report is a
+ * wider surface and an operator-set environment variable is not a value this
+ * gate needs to echo to name the fix. ADD, never replace — replacing the value
+ * would drop the worker's other groups.
+ */
+export const MCP_PROFILE_REMEDIATION = "ADD `conductor` to BRIDGE_MCP_PROFILE (comma-separated) — do NOT replace the existing value, " +
+    "which would drop the worker's other tool groups. Without it the conductor/event/supervisor " +
+    "tools are not registered.";
+/**
+ * Remediation for a host with no `gh` on PATH.
+ *
+ * LOAD-BEARING, not legacy (AC-7). Conductor merges run under the machine's own
+ * `gh` auth because the GitHub App token is `contents: read` and structurally
+ * cannot merge — see `mcp_server/src/executor/merge-job.ts`. Retiring this check
+ * is blocked on epic A2 (App elevation to `contents: write`); until A2 ships,
+ * `gh` is a real prerequisite and this stays a named check.
+ */
+export const GH_CLI_REMEDIATION = "install the GitHub CLI (`gh`) and put it on PATH; conductor-driven merges run under this " +
+    "host's own `gh` auth because the GitHub App token is `contents: read` and cannot merge.";
+/** Remediation for an installed but unauthenticated `gh` (AC-7; see {@link GH_CLI_REMEDIATION}). */
+export const GH_AUTH_REMEDIATION = "run `gh auth login` to grant the conductor merge permission; otherwise local merge emits " +
+    "merge.failed/skip rather than merging.";
+/** Detail used when `gh` authentication was never tested because `gh` is absent. */
+export const GH_AUTH_SKIPPED_DETAIL = "not tested — `gh` is not installed, so `gh auth status` was never run";
+/**
+ * Remediation for a native ledger whose binding does not load.
+ *
+ * DIAGNOSTIC ONLY (BAPI-526): this never installs, rebuilds, or resolves a
+ * package path, and the remediation names the operator action rather than
+ * performing it. Retiring this check is blocked on epic B3 (parallel-ledger
+ * paring), so it stays a named check until B3 ships (AC-7).
+ */
+export const NATIVE_LEDGER_REMEDIATION = "`better-sqlite3` is an optionalDependency npm silently skips on a build failure — reinstall it " +
+    "for this Node runtime to restore local conductor observability. Diagnostic only: nothing is " +
+    "installed or rebuilt for you.";
+/** Remediation for a worker MCP registration that fell back to the npm channel. */
+export const MCP_REGISTRATION_FORM_REMEDIATION = "build this package so an on-disk entry resolves (`npm run build` in mcp_server), or accept that " +
+    "worker MCP registration depends on the published package being reachable.";
+/** Remediation for an unreadable `engines.node`. */
+export const NODE_ENGINE_REMEDIATION = "reinstall the package so its package.json is readable; until then the expected Node version is " +
+    "unknown and a Node/ABI skew cannot be diagnosed.";
+/** Remediation for a deny-enforcement result the readiness gate could not establish. */
+export const DENY_ENFORCEMENT_SKIP_REMEDIATION = "run `conductor doctor` (without --no-deny-probe) to execute the owning deny-enforcement " +
+    "preflight; `conductor readiness` never spawns that probe itself.";
 /** Explicit display value for an unset `BRIDGE_MCP_PROFILE`. */
 export const MCP_PROFILE_UNSET = "(unset)";
 /**
@@ -105,6 +154,58 @@ export async function inspectNativeLedger(nativeLoad, deps = {}) {
         warnings.push("Could not read package.json engines.node; expected Node version is unknown.");
     }
     const degraded = nativeLoad.degraded || invocation.form !== "absolute-build-path" || engines_node === null;
+    // THREE outcomes over the SAME inputs (BAPI-1055), because the aggregate
+    // `degraded` above folds three independent facts together and each has its own
+    // fix. `degraded` itself is unchanged — this adds structure beside it.
+    //
+    // PATH-FREE by construction: no branch interpolates `mcp_shim_node`, a server
+    // entry path, a package root, or a native error message. Only the module name,
+    // the ABI, the sanitized failure kind, and the closed registration form.
+    const outcomes = [
+        binding_loads
+            ? {
+                id: "native-ledger",
+                label: "Native ledger binding",
+                status: "pass",
+                detail: `${nativeLoad.module} loads (NODE_MODULE_VERSION ${nativeLoad.node_modules_abi})`,
+            }
+            : {
+                id: "native-ledger",
+                label: "Native ledger binding",
+                status: "warn",
+                detail: `${nativeLoad.module} did not load ` +
+                    `(NODE_MODULE_VERSION ${nativeLoad.node_modules_abi}, failure: ${failure_kind})`,
+                remediation: NATIVE_LEDGER_REMEDIATION,
+            },
+        invocation.form === "absolute-build-path"
+            ? {
+                id: "mcp-registration-form",
+                label: "Worker MCP registration form",
+                status: "pass",
+                detail: "resolves an on-disk build entry",
+            }
+            : {
+                id: "mcp-registration-form",
+                label: "Worker MCP registration form",
+                status: "warn",
+                detail: `registration form is \`${invocation.form}\` — the npm-channel fallback`,
+                remediation: MCP_REGISTRATION_FORM_REMEDIATION,
+            },
+        engines_node === null
+            ? {
+                id: "node-engine",
+                label: "Expected Node engine",
+                status: "warn",
+                detail: "package.json engines.node could not be read",
+                remediation: NODE_ENGINE_REMEDIATION,
+            }
+            : {
+                id: "node-engine",
+                label: "Expected Node engine",
+                status: "pass",
+                detail: `expected ${engines_node}; running ${process.version}`,
+            },
+    ];
     return {
         cli_node_version: process.version,
         engines_node,
@@ -116,6 +217,7 @@ export async function inspectNativeLedger(nativeLoad, deps = {}) {
         failure_kind,
         degraded,
         warnings,
+        outcomes,
     };
 }
 /**
@@ -175,6 +277,31 @@ export async function collectConductorNativeLedgerSafe(deps = {}) {
             failure_kind: NATIVE_LEDGER_UNCOLLECTED_FAILURE_KIND,
             degraded: true,
             warnings: ["the native ledger inspection could not be collected on this host"],
+            // The collection failure is its own finding, not a load failure: an
+            // operator who cannot collect the inspection needs to retry it, not
+            // reinstall the binding. Reported at the same granularity as the real
+            // inspector so a consolidated report never loses these three checks.
+            outcomes: [
+                {
+                    id: "native-ledger",
+                    label: "Native ledger binding",
+                    status: "warn",
+                    detail: "the native ledger inspection could not be collected on this host",
+                    remediation: NATIVE_LEDGER_REMEDIATION,
+                },
+                {
+                    id: "mcp-registration-form",
+                    label: "Worker MCP registration form",
+                    status: "skip",
+                    detail: "not determined — the native ledger inspection could not be collected",
+                },
+                {
+                    id: "node-engine",
+                    label: "Expected Node engine",
+                    status: "skip",
+                    detail: "not determined — the native ledger inspection could not be collected",
+                },
+            ],
         };
     }
 }
@@ -206,7 +333,28 @@ export function inspectMcpProfile(env) {
             `do NOT replace the value, which would drop the worker's other groups. ` +
             `Without it the conductor/event/supervisor tools are not registered.`);
     }
-    return { raw_profile, active_groups, conductor_context_detected, degraded, warnings };
+    // Fixed state labels and the CLOSED active-group vocabulary only (BAPI-1055):
+    // `resolveProfiles` yields nothing but recognized group names, so this detail
+    // cannot echo an arbitrary operator-set string the way `raw_profile` can.
+    const outcomes = [
+        degraded
+            ? {
+                id: "mcp-profile",
+                label: "MCP conductor profile",
+                status: "warn",
+                detail: `a conductor context is active but the resolved groups omit \`conductor\` (active: ${active_groups.join(", ")})`,
+                remediation: MCP_PROFILE_REMEDIATION,
+            }
+            : {
+                id: "mcp-profile",
+                label: "MCP conductor profile",
+                status: "pass",
+                detail: conductor_context_detected
+                    ? `conductor context active; resolved groups: ${active_groups.join(", ")}`
+                    : `no conductor context detected; resolved groups: ${active_groups.join(", ")}`,
+            },
+    ];
+    return { raw_profile, active_groups, conductor_context_detected, degraded, warnings, outcomes };
 }
 /**
  * Read-only probe of the local-merge (F4) capability. Runs `gh --version` and
@@ -265,7 +413,60 @@ export function inspectLocalMerge(runCommand) {
     // Capability gap only — local merge is opt-in, so an unauthed host is not a hard
     // failure unless the operator enabled it. Reported as degraded for visibility.
     const degraded = !gh_available || !gh_authed;
-    return { gh_available, gh_authed, degraded, warnings };
+    // TWO outcomes, not one (BAPI-1055): installing `gh` and running `gh auth
+    // login` are independently actionable, and `degraded` below is deliberately
+    // left as the SAME `!gh_available || !gh_authed` conjunction it has always
+    // been. When `gh` is absent the auth outcome is `skip`, never `fail` — the
+    // authentication was never tested, and claiming it failed would send the
+    // operator to `gh auth login` on a host with no `gh`.
+    //
+    // AC-7 — these two checks are LOAD-BEARING and must not be retired here.
+    // Conductor merges run under this machine's own `gh` auth because the GitHub
+    // App token is `contents: read` and structurally cannot merge; see
+    // `mcp_server/src/executor/merge-job.ts` and the `contents: read` constraint
+    // documented in `mcp_server/src/merge-pull-request.ts`. Retirement is owned by
+    // epic A2, after the App is elevated to `contents: write`. Nothing in this
+    // change removes, hides, or downgrades either check, and no merge behaviour is
+    // altered by reporting them.
+    const outcomes = [
+        gh_available
+            ? {
+                id: "gh-cli",
+                label: "GitHub CLI availability",
+                status: "pass",
+                detail: "`gh --version` succeeded",
+            }
+            : {
+                id: "gh-cli",
+                label: "GitHub CLI availability",
+                status: "warn",
+                detail: "`gh` is not installed or not on PATH",
+                remediation: GH_CLI_REMEDIATION,
+            },
+        !gh_available
+            ? {
+                id: "gh-auth",
+                label: "GitHub CLI authentication",
+                status: "skip",
+                detail: GH_AUTH_SKIPPED_DETAIL,
+                remediation: GH_CLI_REMEDIATION,
+            }
+            : gh_authed
+                ? {
+                    id: "gh-auth",
+                    label: "GitHub CLI authentication",
+                    status: "pass",
+                    detail: "`gh auth status` reports an authenticated account",
+                }
+                : {
+                    id: "gh-auth",
+                    label: "GitHub CLI authentication",
+                    status: "warn",
+                    detail: "`gh` is installed but `gh auth status` failed",
+                    remediation: GH_AUTH_REMEDIATION,
+                },
+    ];
+    return { gh_available, gh_authed, degraded, warnings, outcomes };
 }
 /**
  * Build the combined read-only doctor report. Composes the existing ledger
@@ -312,14 +513,18 @@ async function inspectDenyEnforcementSafe(inspect) {
         }
         return await run();
     }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+    catch {
+        // BAPI-1055: the thrown message is NOT interpolated. A spawn failure here
+        // routinely carries an absolute executable path or a temp-directory path,
+        // and this warning now flows into the consolidated readiness report as well
+        // as the doctor's own output. The actionable fact — enforcement could not be
+        // established, so claiming must refuse — is fixed prose.
         return {
             enforced: false,
             layer: "none",
             degraded: true,
             warnings: [
-                `Deny-layer enforcement inspection failed: ${msg}`,
+                "Deny-layer enforcement inspection failed: the probe could not be run.",
                 "The executor claim loop MUST refuse to claim jobs until the deny layer is enforced.",
             ],
         };
@@ -456,3 +661,221 @@ export function formatConductorDoctorReport(report) {
     lines.push(formatClaudeLoginAdvisory(claude_login));
     return lines.join("\n");
 }
+// ---------------------------------------------------------------------------
+// Canonical readiness projection (BAPI-1055)
+// ---------------------------------------------------------------------------
+/**
+ * The complete conductor-doctor prerequisite set, in render order.
+ *
+ * Like the install-side descriptor set, this is STABLE rather than derived from
+ * whatever the report happened to contain: a report that failed to build, or an
+ * injected sentinel carrying only the fields a test cares about, must still
+ * yield every prerequisite — as an explicit unknown, never as an absence.
+ */
+export const CONDUCTOR_READINESS_DESCRIPTORS = [
+    { id: "ledger", label: "Conductor event ledger" },
+    { id: "git-hooks", label: "Conductor git hooks" },
+    { id: "mcp-profile", label: "MCP conductor profile" },
+    { id: "gh-cli", label: "GitHub CLI availability" },
+    { id: "gh-auth", label: "GitHub CLI authentication" },
+    { id: "native-ledger", label: "Native ledger binding" },
+    { id: "mcp-registration-form", label: "Worker MCP registration form" },
+    { id: "node-engine", label: "Expected Node engine" },
+    { id: "deny-enforcement", label: "Deny-layer enforcement" },
+    { id: "claude-login", label: "Claude login" },
+];
+/** Remediation for a degraded local event ledger. */
+export const CONDUCTOR_LEDGER_REMEDIATION = "run `conductor doctor` for the ledger detail, then re-create the local ledger directory with " +
+    "owner-only permissions; the ledger is local observability and never blocks a run.";
+/** Remediation for degraded or missing managed git hooks. */
+export const CONDUCTOR_GIT_HOOKS_REMEDIATION = "run `conductor install-git-hooks` to install the managed post-commit and reference-transaction " +
+    "hooks; they are local, opportunistic, and bypassable.";
+/** Remediation for a Claude login this host cannot confirm. */
+export const CONDUCTOR_CLAUDE_LOGIN_REMEDIATION = "run `claude login` on the host that will run conductor workers; Bridge stores no Anthropic " +
+    "credential and can only advise here.";
+/** Fixed detail for a prerequisite whose owning inspection was not collected. */
+const CONDUCTOR_UNCOLLECTED_DETAIL = "not collected — the conductor doctor did not report this inspection";
+/** Fixed remediation for a prerequisite whose owning inspection was not collected. */
+const CONDUCTOR_UNCOLLECTED_REMEDIATION = "run `conductor doctor` directly to collect this inspection; its state is unknown, not healthy.";
+/** Ordered outcomes an inspection contributed, or `[]` when it reported none. */
+function outcomesOf(inspection) {
+    // Read defensively: an injected sentinel (and the installer's degraded-doctor
+    // fallback) may populate only the fields a test cares about, and an adapter
+    // that threw on a partially-built report would lose the whole locus.
+    return Array.isArray(inspection?.outcomes) ? inspection?.outcomes : [];
+}
+/** Derive the ledger outcome from the ledger doctor result's own `degraded` flag. */
+function ledgerOutcome(report) {
+    const ledger = report?.ledger;
+    if (ledger === undefined)
+        return null;
+    // Fixed facts only: `DoctorResult.path` and `directory_path` are absolute and
+    // are deliberately never projected.
+    return ledger.degraded
+        ? {
+            id: "ledger",
+            label: "Conductor event ledger",
+            status: "warn",
+            detail: `local ledger degraded (schema present: ${ledger.schema_present}, permissions ok: ${ledger.directory_permissions_ok && ledger.database_permissions_ok})`,
+            remediation: CONDUCTOR_LEDGER_REMEDIATION,
+        }
+        : {
+            id: "ledger",
+            label: "Conductor event ledger",
+            status: "pass",
+            detail: `local ledger healthy (schema version ${ledger.user_version ?? "unknown"})`,
+        };
+}
+/** Derive the git-hooks outcome from the hook inspection's own `degraded` flag. */
+function gitHooksOutcome(report) {
+    const hooks = report?.git_hooks;
+    if (hooks === undefined)
+        return null;
+    if (!hooks.is_worktree) {
+        return {
+            id: "git-hooks",
+            label: "Conductor git hooks",
+            status: "skip",
+            detail: "not a git worktree, so no managed conductor hooks apply",
+        };
+    }
+    // Hook NAMES and booleans only — `hooks_dir` is absolute and never projected.
+    const rendered = hooks.hooks
+        .map((hook) => `${hook.name}=${hook.exists && hook.managed_block_present}`)
+        .join(", ");
+    return hooks.degraded
+        ? {
+            id: "git-hooks",
+            label: "Conductor git hooks",
+            status: "warn",
+            detail: `managed hooks installed: ${rendered}`,
+            remediation: CONDUCTOR_GIT_HOOKS_REMEDIATION,
+        }
+        : {
+            id: "git-hooks",
+            label: "Conductor git hooks",
+            status: "pass",
+            detail: `managed hooks installed: ${rendered}`,
+        };
+}
+/**
+ * Derive the deny-enforcement outcome.
+ *
+ * `conductor readiness` NEVER runs the owning probe: `runDenyEnforcementPreflight`
+ * spawns real headless agent runs costing minutes, and an advisory report is not
+ * a reason to pay that. When the report carries an explicitly skipped result the
+ * outcome is `skip` with a remediation naming the command that DOES run it —
+ * never `pass`, which would claim enforcement that was never verified.
+ */
+function denyEnforcementOutcome(report) {
+    const deny = report?.deny_enforcement;
+    if (deny === undefined)
+        return null;
+    if (deny.layer === "none" && !deny.enforced && deny.status === "skip") {
+        return {
+            id: "deny-enforcement",
+            label: "Deny-layer enforcement",
+            status: "skip",
+            detail: "not probed — enforcement is UNVERIFIED, which is not the same as unenforced",
+            remediation: DENY_ENFORCEMENT_SKIP_REMEDIATION,
+        };
+    }
+    // Fixed categories only: the underlying `detail`/`warnings` can carry probe
+    // text, so neither is projected here.
+    return deny.enforced && !deny.degraded
+        ? {
+            id: "deny-enforcement",
+            label: "Deny-layer enforcement",
+            status: "pass",
+            detail: `enforced by the ${deny.layer} layer`,
+        }
+        : {
+            id: "deny-enforcement",
+            label: "Deny-layer enforcement",
+            status: "fail",
+            detail: deny.enforced
+                ? `enforced by the ${deny.layer} layer, but degraded`
+                : "the denied call was not rejected by any layer",
+            remediation: "restore the settings-deny layer before running a conductor worker; the executor claim " +
+                "loop refuses to claim jobs while enforcement is missing.",
+        };
+}
+/** Derive the Claude-login outcome from the advisory detection result. */
+function claudeLoginOutcome(report) {
+    const login = report?.claude_login;
+    if (login === undefined)
+        return null;
+    return login.detected
+        ? {
+            id: "claude-login",
+            label: "Claude login",
+            status: "pass",
+            detail: "a local Claude login marker was detected",
+        }
+        : {
+            id: "claude-login",
+            label: "Claude login",
+            status: "warn",
+            detail: "no local Claude login marker was detected",
+            remediation: CONDUCTOR_CLAUDE_LOGIN_REMEDIATION,
+        };
+}
+/**
+ * Project a conductor-doctor report into canonical readiness checks.
+ *
+ * PURE: no probe, no I/O, and no re-derivation of any verdict. Every outcome is
+ * read from the structured fields the owning inspections now populate, never
+ * parsed out of their free-text `warnings` — a warning is prose an author may
+ * reword, and a gate that read it would change meaning on a copy edit.
+ *
+ * A null report yields the full descriptor set as failures rather than nothing:
+ * "the conductor doctor could not be built" must not read as "there is nothing
+ * to report here".
+ */
+export function mapConductorDoctorReportToReadinessChecks(report) {
+    const collected = new Map();
+    const record = (outcome) => {
+        // First writer wins, so an inspection cannot overwrite another's finding.
+        if (outcome && !collected.has(outcome.id))
+            collected.set(outcome.id, outcome);
+    };
+    record(ledgerOutcome(report));
+    record(gitHooksOutcome(report));
+    for (const outcome of outcomesOf(report?.mcp_profile))
+        record(outcome);
+    for (const outcome of outcomesOf(report?.local_merge))
+        record(outcome);
+    for (const outcome of outcomesOf(report?.native_ledger))
+        record(outcome);
+    record(denyEnforcementOutcome(report));
+    record(claudeLoginOutcome(report));
+    return CONDUCTOR_READINESS_DESCRIPTORS.map(({ id, label }) => {
+        const outcome = collected.get(id);
+        if (!outcome) {
+            // Unknown, and unknown is never healthy: a prerequisite whose owning
+            // inspection did not report is a failure with a restoring remediation.
+            return createReadinessCheck({
+                id: `conductor.${id}`,
+                source: "conductor",
+                label,
+                status: "fail",
+                detail: CONDUCTOR_UNCOLLECTED_DETAIL,
+                remediation: CONDUCTOR_UNCOLLECTED_REMEDIATION,
+            });
+        }
+        return createReadinessCheckSafely({
+            id: `conductor.${id}`,
+            source: "conductor",
+            label: outcome.label || label,
+            status: outcome.status,
+            ...(outcome.detail ? { detail: outcome.detail } : {}),
+            // Same fallback as the plane adapter: a real failure must never be
+            // downgraded into a generic "unreadable check" for want of a fix line.
+            ...(outcome.status === "fail"
+                ? { remediation: outcome.remediation ?? CONDUCTOR_UNCOLLECTED_REMEDIATION }
+                : outcome.status !== "pass" && outcome.remediation
+                    ? { remediation: outcome.remediation }
+                    : {}),
+        });
+    });
+}