@bridge_gpt/mcp-server 0.2.52 → 0.2.53

package/build/conductor/readiness-sections.js

@@ -0,0 +1,666 @@
+/**
+ * The shared conductor readiness SECTION layer (BAPI-1055).
+ *
+ * Extracted verbatim from `conductor/install-doctor.ts`, where these builders
+ * had already composed four of the five prerequisite loci. Nothing about a
+ * section changed in the move: same ids, same labels, same statuses, same
+ * detail text, same installer remediations. What changed is who may consume
+ * them — the install-time doctor and the advisory `conductor readiness` gate now
+ * read ONE adapter set instead of interpreting the same probes twice.
+ *
+ * ## Why extraction rather than a second aggregator
+ *
+ * The obvious alternative was to build the consolidated gate beside the install
+ * doctor. That would have left two independent gates over the same probes, which
+ * is precisely the duplication AC-6 exists to remove — and they would drift, as
+ * two implementations of one classification always do. Evolving the install
+ * doctor in place was the other alternative, and it would have mixed advisory
+ * reporting into an install-time, fatal-capable contract.
+ *
+ * ## The fatal boundary stays with the installer
+ *
+ * `ConductorInstallSectionStatus` keeps its `fatal` state, because the installer
+ * genuinely refuses to write on one (`conductorInstallDoctorHasFatal` gates the
+ * pre-write abort in `install-bridge-conductor.ts`). That refusal is unchanged.
+ * The advisory gate maps `fatal` onto the canonical `fail` status and never
+ * inherits the exit-code consequence: an advisory command that could exit
+ * non-zero would not be advisory.
+ *
+ * ## Purity
+ *
+ * Every builder here is PURE — it reads an already-collected report and returns
+ * sections. No probe, no network call, no filesystem write, no process spawn.
+ * The one exception is {@link inspectWorkflowPresence}, which awaits the
+ * READ-ONLY reader seams its caller injects and never opens a path of its own.
+ */
+import { MANAGED_HOOK_NAMES } from "./git-hooks.js";
+import { MCP_PACKAGE_NAME } from "../mcp-identity.js";
+import { CLAUDE_REVIEW_WORKFLOW_DRIFT_REMEDIATION, summarizeClaudeReviewWorkflowDrift, } from "../claude-review-workflow-drift.js";
+import { describeNativeLedgerAvailability } from "./doctor.js";
+/** Operator runbook pointer surfaced beside the executor gap. */
+export const CONDUCTOR_OPERATOR_RUNBOOK_POINTER = "docs/claude/epic-conductor-v2-operator-runbook.md";
+/**
+ * Capability-matrix guidance for the executor leg.
+ *
+ * Amended by BAPI-779 (R-1): `install conductor` can now write the unit AND
+ * start it, each behind its own consent. What did NOT change is the readiness
+ * rule — `executor_ready` still comes only from a live server observation, so
+ * neither a written unit nor a successful local start may produce that claim.
+ */
+export const EXECUTOR_PROVISIONING_GUIDANCE = "`install conductor` writes the unit and starts it, each behind its own consent; " +
+    "readiness still comes only from a live server observation";
+/**
+ * The `BRIDGE_MCP_PROFILE` token that makes the 8 conductor MCP tools visible.
+ *
+ * The tools are profile-gated, never core, and this is the only token that
+ * un-gates them — so the doctor names it explicitly rather than describing the
+ * gap abstractly (BAPI-775).
+ */
+export const CONDUCTOR_PROFILE_TOKEN = "conductor";
+/** Remediation for a host MCP config that carries no Bridge entry at all. */
+export const CONDUCTOR_PROFILE_TOKEN_NO_ENTRY_REMEDIATION = "no supported host MCP config carries a Bridge entry — run " +
+    `\`npx ${MCP_PACKAGE_NAME} install\` to register one, then re-run \`install conductor\`.`;
+/** Remediation for an entry that exists but lacks the conductor token. */
+export const CONDUCTOR_PROFILE_TOKEN_REMEDIATION = "re-run `install conductor` and accept the tool-visibility consent; the conductor " +
+    "tools become visible after the MCP client is restarted.";
+/** Remediation surfaced whenever the managed conductor hooks are not usable. */
+export const CONDUCTOR_HOOK_TARGET_REMEDIATION = "re-run `install conductor` and accept the local-observability consent, or run " +
+    "`conductor install-git-hooks` directly.";
+/** Remediation surfaced when the ledger's native binding does not load. */
+export const CONDUCTOR_LEDGER_LOADABILITY_REMEDIATION = "`better-sqlite3` is an optionalDependency npm silently skips on a build failure — " +
+    "reinstall it for this Node runtime to restore local conductor observability.";
+/** Remediation surfaced whenever no healthy generated service unit is detected. */
+export const EXECUTOR_INSTALL_SERVICE_REMEDIATION = "generate a persistent unit with `install conductor --executor-id <id>` or " +
+    "`executor install-service` (or run the executor by hand) — " +
+    `see ${CONDUCTOR_OPERATOR_RUNBOOK_POINTER}.`;
+/** Remediation for a unit that exists but whose service is not running. */
+export const EXECUTOR_SERVICE_START_REMEDIATION = "start the service (re-run `install conductor` and accept the start consent, or run the " +
+    `printed launchctl/systemctl command by hand) — see ${CONDUCTOR_OPERATOR_RUNBOOK_POINTER}.`;
+// ---------------------------------------------------------------------------
+// Section builders
+// ---------------------------------------------------------------------------
+export function supervisorSection(readiness) {
+    const s = readiness.supervisor;
+    const sections = [];
+    if (!s.setup_present || !s.config_present) {
+        const missing = [
+            !s.setup_present ? "setup" : null,
+            !s.config_present ? "config" : null,
+        ].filter(Boolean).join(" and ");
+        sections.push({
+            id: "supervisor-configuration",
+            label: "Supervisor configuration",
+            status: "degraded",
+            detail: `project-default supervisor ${missing} absent`,
+            remediation: "bootstrap writes the safe project-default posture.",
+        });
+    }
+    else {
+        sections.push({
+            id: "supervisor-configuration",
+            label: "Supervisor configuration",
+            status: "ok",
+            detail: `setup=${s.setup_source}, config=${s.config_source}`,
+        });
+    }
+    // Deliberately its OWN section, not folded into the one above: "configured but
+    // unsafe" and "not configured" drive different operator actions, and an empty
+    // required-check list makes the CI gate pass unconditionally rather than fail.
+    sections.push(s.required_checks_empty
+        ? {
+            id: "supervisor-required-checks",
+            label: "Supervisor required CI checks",
+            status: "degraded",
+            detail: "required-check list is EMPTY — the done gate would pass unconditionally",
+            remediation: "bootstrap writes a non-empty required-check list into done_gate_config.",
+        }
+        : {
+            id: "supervisor-required-checks",
+            label: "Supervisor required CI checks",
+            status: "ok",
+            detail: `${s.required_checks_count} required check(s) configured`,
+        });
+    // BAPI-694 (R5) — its OWN section, and WARN-ONLY.
+    //
+    // `degraded`, never `fatal`: a divergence between the code_review gate's
+    // signal and the merge path's may be exactly what the operator intended, and
+    // blocking an install over a legitimate posture would be worse than the
+    // silence this replaces. It also changes no gate: both settings are reported,
+    // neither is coerced into the other's vocabulary.
+    //
+    // Absent (`null`) means the server predates BAPI-694 and cannot report
+    // alignment, so no section is emitted at all — an advisory addition must not
+    // manufacture a finding out of a server that never answered.
+    const alignment = s.review_policy_alignment;
+    if (alignment !== null) {
+        if (alignment.status === "divergent" || alignment.status === "invalid") {
+            sections.push({
+                id: "supervisor-review-alignment",
+                label: "Supervisor review-policy alignment",
+                status: "degraded",
+                detail: alignment.explanation,
+                remediation: alignment.status === "invalid"
+                    ? "fix the done gate's review_state condition — review configuration " +
+                        "exists but cannot be read, so the merge path refuses rather than merges."
+                    : "set the repository review-policy default and the done gate's " +
+                        "review_state condition to the same signal, or confirm the difference " +
+                        `is intended — see ${CONDUCTOR_OPERATOR_RUNBOOK_POINTER}.`,
+            });
+        }
+        else {
+            // `aligned` and `not_configured` are both non-warning states, and are
+            // reported separately: "they agree" and "neither is set" are different
+            // facts, and collapsing them would imply a stored default that is absent.
+            sections.push({
+                id: "supervisor-review-alignment",
+                label: "Supervisor review-policy alignment",
+                status: "ok",
+                detail: alignment.explanation,
+            });
+        }
+    }
+    return sections;
+}
+export function githubCredentialsSection(readiness) {
+    const g = readiness.github;
+    if (g.credentials_complete) {
+        return {
+            id: "github-credentials",
+            label: "GitHub App credentials",
+            status: "ok",
+            detail: "owner, repository id, and installation id all resolved",
+        };
+    }
+    const missing = [
+        !g.owner_resolved ? "owner" : null,
+        !g.repo_id_resolved ? "repository id" : null,
+        !g.installation_id_resolved ? "installation id" : null,
+    ].filter(Boolean).join(", ");
+    return {
+        id: "github-credentials",
+        label: "GitHub App credentials",
+        status: "degraded",
+        detail: g.credentials_readable
+            ? `incomplete: ${missing} unresolved`
+            : "no GitHub credential row for this repository",
+        remediation: "connect GitHub from the Bridge setup UI (`install-bridge connect-github`).",
+    };
+}
+export function githubActionsSection(readiness) {
+    const g = readiness.github;
+    if (g.actions_write) {
+        return {
+            id: "github-actions-permission",
+            label: "GitHub App actions permission",
+            status: "ok",
+            detail: "actions: write",
+        };
+    }
+    if (!g.actions_probe_succeeded) {
+        // "Could not be checked" is NOT the same finding as "confirmedly missing" —
+        // the first needs a retry, the second needs a permission grant.
+        return {
+            id: "github-actions-permission",
+            label: "GitHub App actions permission",
+            status: "degraded",
+            detail: "permission could not be checked",
+            remediation: "re-run once credentials resolve; the workflow rerun lane fails open on 403 until this reads `write`.",
+        };
+    }
+    return {
+        id: "github-actions-permission",
+        label: "GitHub App actions permission",
+        status: "degraded",
+        detail: `actions: ${g.actions_permission_level}`,
+        remediation: "grant the GitHub App `actions: write`; the conductor's workflow rerun lane fails open on 403 without it.",
+    };
+}
+export function reconcilerSection(readiness) {
+    const r = readiness.reconciler;
+    if (!r.liveness_readable) {
+        // BAPI-1055: unreadable is NOT the same finding as stale, and it had no
+        // remediation at all — so a report could name a gap with no next step.
+        return {
+            id: "reconciler-liveness",
+            label: "Reconciler tick liveness",
+            status: "degraded",
+            detail: "liveness could not be read",
+            remediation: "retry once the Bridge API is reachable; reconciler liveness is unknown here, " +
+                "which is not the same as confirmed-stale.",
+        };
+    }
+    if (!r.stale) {
+        return {
+            id: "reconciler-liveness",
+            label: "Reconciler tick liveness",
+            status: "ok",
+            detail: `last tick ${r.last_tick_age_seconds}s ago across ${r.active_run_count} active run(s)`,
+        };
+    }
+    return {
+        id: "reconciler-liveness",
+        label: "Reconciler tick liveness",
+        status: "degraded",
+        detail: r.last_tick_at === null
+            ? "no reconciler tick recorded for this repository"
+            : `last tick ${r.last_tick_age_seconds}s ago (threshold ${readiness.thresholds.reconciler_stale_after_seconds}s)`,
+        remediation: "start the reconciler (`conductor epic-tick` schedule) for this repository.",
+    };
+}
+export function workflowSection(presence, reviewPolicySource, driftDetail) {
+    if (presence === "present") {
+        return {
+            id: "claude-review-workflow",
+            label: "claude-review workflow",
+            status: "ok",
+            // BAPI-941: when the lineage comparison ran but could not be completed,
+            // that uncertainty rides on the SAME informational detail line rather than
+            // becoming a status of its own. The section stays `ok`: the workflow is
+            // installed and readable, which is all this section has ever asserted.
+            detail: driftDetail
+                ? `.github/workflows/claude-review.yml present — ${driftDetail}`
+                : ".github/workflows/claude-review.yml present",
+        };
+    }
+    // BAPI-941: present but stale. Reported through the SAME section, status
+    // vocabulary, and detail/remediation shape as every other degraded state — no
+    // new health component, no bespoke styling, and no color dependence: the
+    // detail's own wording carries the warning. The file IS installed, so this is
+    // never `absent`, and the policy-applicability branch below does not apply
+    // (a stale workflow only matters to a policy that consumes its verdict, and
+    // the caller only classifies drift when it does).
+    if (presence === "drifted") {
+        return {
+            id: "claude-review-workflow",
+            label: "claude-review workflow",
+            status: "degraded",
+            detail: driftDetail ??
+                ".github/workflows/claude-review.yml differs from the repository default branch",
+            remediation: CLAUDE_REVIEW_WORKFLOW_DRIFT_REMEDIATION,
+        };
+    }
+    // Applicability is policy-dependent: a run whose review signal is GitHub's own
+    // review decision does not need the Claude workflow at all, so its absence is
+    // not a gap. Reporting it as degraded there would train operators to ignore
+    // this section.
+    if (reviewPolicySource === "native_review_decision" || reviewPolicySource === "none") {
+        return {
+            id: "claude-review-workflow",
+            label: "claude-review workflow",
+            status: "ok",
+            detail: `not applicable for review policy '${reviewPolicySource}'`,
+        };
+    }
+    return {
+        id: "claude-review-workflow",
+        label: "claude-review workflow",
+        status: "degraded",
+        detail: presence === "unreadable"
+            ? ".github/workflows/claude-review.yml could not be read"
+            : ".github/workflows/claude-review.yml absent",
+        remediation: "the selected review policy consumes the sticky verdict this workflow emits; install the template.",
+    };
+}
+/**
+ * Real detection of BAPI-688 generated service units, composed from
+ * `collectExecutorServiceDiagnostics`. Never `fatal` (a missing unit is a
+ * repairable gap, and blocking every install on it would be wrong) and never
+ * omitted (the flow must not read as fully provisioned by silence).
+ *
+ * This section reports UNIT PRESENCE and nothing else (BAPI-779). Whether the
+ * service manager is actually running the unit is
+ * {@link executorServiceStateSection}, and whether the SERVER has observed an
+ * executor is {@link executorObservationSection}. Three separate facts, three
+ * separate sections — a healthy unit here proves only that a file exists.
+ */
+export function executorProvisioningSection(diagnostics) {
+    const base = { id: "executor-provisioning", label: "Executor provisioning" };
+    if (diagnostics === null) {
+        return {
+            ...base,
+            status: "degraded",
+            detail: "executor service-unit diagnostics could not be collected",
+            remediation: EXECUTOR_INSTALL_SERVICE_REMEDIATION,
+        };
+    }
+    if (diagnostics.status === "skipped") {
+        // The collector's `reason` is already sanitized and secret-free (fixed
+        // convention paths only): "no units found", unsupported platform, or the
+        // Windows manual-Task-Scheduler case.
+        return {
+            ...base,
+            status: "degraded",
+            detail: diagnostics.reason,
+            remediation: EXECUTOR_INSTALL_SERVICE_REMEDIATION,
+        };
+    }
+    const unhealthy = diagnostics.units.filter((unit) => unit.warnings.length > 0 || unit.credentials.some((cred) => !cred.resolved));
+    const ids = diagnostics.units.map((unit) => unit.executorId).join(", ");
+    if (unhealthy.length === 0 && diagnostics.warnings.length === 0) {
+        return {
+            ...base,
+            status: "ok",
+            detail: `${diagnostics.units.length} generated service unit(s) found (${ids}); ` +
+                "unit presence only — see the service-state and observation sections",
+        };
+    }
+    return {
+        ...base,
+        status: "degraded",
+        detail: `${diagnostics.units.length} generated service unit(s) found (${ids}), but ` +
+            `${unhealthy.length} unit(s) carry warnings or unresolved credentials — see the ` +
+            "embedded executor-provisioning report",
+        remediation: EXECUTOR_INSTALL_SERVICE_REMEDIATION,
+    };
+}
+/**
+ * Local service-manager state for the units that were discovered (BAPI-779).
+ *
+ * Never `fatal`: this is a diagnostic, and an unreadable service manager is a
+ * gap in the *report*, not a broken install. `unknown` is deliberately not
+ * collapsed into `not-found` — "the probe could not answer" and "the service
+ * manager has no such unit" lead to different operator actions.
+ */
+export function executorServiceStateSection(observations, unitsDiscovered, inspectorAvailable) {
+    const base = { id: "executor-service-state", label: "Executor service state" };
+    if (!unitsDiscovered) {
+        return {
+            ...base,
+            status: "degraded",
+            detail: "no generated unit to inspect, so no service state was collected",
+            remediation: EXECUTOR_INSTALL_SERVICE_REMEDIATION,
+        };
+    }
+    if (!inspectorAvailable || observations.length === 0) {
+        return {
+            ...base,
+            status: "degraded",
+            detail: "local service state could not be collected on this host",
+            remediation: EXECUTOR_SERVICE_START_REMEDIATION,
+        };
+    }
+    // Deterministic ordering by executor id so two runs of the same host render
+    // identically regardless of enumeration order.
+    const rendered = [...observations]
+        .sort((a, b) => (a.executorId < b.executorId ? -1 : a.executorId > b.executorId ? 1 : 0))
+        .map((o) => `${o.executorId}=${o.state}`)
+        .join(", ");
+    const allActive = observations.every((o) => o.state === "active");
+    return allActive
+        ? { ...base, status: "ok", detail: `service state: ${rendered}` }
+        : {
+            ...base,
+            status: "degraded",
+            detail: `service state: ${rendered}`,
+            remediation: EXECUTOR_SERVICE_START_REMEDIATION,
+        };
+}
+/**
+ * The AUTHORITATIVE executor fact: what the server has observed (BAPI-779).
+ *
+ * This is the only section permitted to say `executor_ready`, and only for
+ * `readiness.executor.ready === true`. The three not-ready shapes are kept
+ * distinct because they mean different things: `null` is "never observed" (the
+ * executor has not claimed yet), `false` is "observed but stale" (it claimed
+ * once and went quiet), and an unreadable readiness payload is "unknown" (the
+ * doctor cannot say). Collapsing them would let a stale executor read like a
+ * fresh install, or vice versa.
+ */
+export function executorObservationSection(readiness) {
+    const base = { id: "executor-observation", label: "Executor server observation" };
+    if (readiness === null || !readiness.executor.liveness_readable) {
+        return {
+            ...base,
+            status: "degraded",
+            detail: "server executor observation is unknown (readiness could not be read)",
+            remediation: "retry once the Bridge API is reachable; no readiness claim is made from local state.",
+        };
+    }
+    const e = readiness.executor;
+    const seen = e.last_seen_at === null
+        ? "never seen"
+        : `last seen ${e.last_seen_at} (${e.last_seen_age_seconds}s ago)`;
+    if (e.ready === true) {
+        return { ...base, status: "ok", detail: `executor_ready — ${seen}` };
+    }
+    if (e.ready === false) {
+        return {
+            ...base,
+            status: "degraded",
+            detail: `observed but stale/not ready — ${seen}`,
+            remediation: EXECUTOR_SERVICE_START_REMEDIATION,
+        };
+    }
+    return {
+        ...base,
+        status: "degraded",
+        detail: `never observed by the server — ${seen}`,
+        remediation: EXECUTOR_SERVICE_START_REMEDIATION,
+    };
+}
+// ---------------------------------------------------------------------------
+// Local conductor capability sections (BAPI-775)
+//
+// Three INDEPENDENT read-only checks — host profile token, managed hook targets,
+// native ledger loadability. All three are non-fatal by construction: a missing
+// local conductor capability is a repairable gap, and letting one flip
+// `conductorInstallDoctorExitCode` to 1 would make every ordinary install fail
+// on a capability it never asked for.
+// ---------------------------------------------------------------------------
+/**
+ * Whether this host looks like a conductor context.
+ *
+ * Composed from the two facts already collected: the resolved MCP-profile
+ * inspection (`BAPI_CONDUCTOR_ENABLED` or a registered epic-tick schedule) and
+ * the read-only host token inspection. Outside such a context a missing local
+ * capability is ADVISORY — reporting it as a gap would train operators of
+ * ordinary repositories to ignore this whole part of the report.
+ */
+export function detectConductorContext(legacyConductor, profile) {
+    // Read defensively: an INJECTED report sentinel (and the installer's own
+    // degraded-doctor fallback) may populate only the fields a test cares about,
+    // and a doctor that throws on a partially-built report would abort the run it
+    // exists to diagnose. Same posture as the defensive legacy formatters below.
+    return (legacyConductor?.mcp_profile?.conductor_context_detected === true ||
+        profile?.tokenPresent === true);
+}
+/**
+ * Host MCP profile-token presence.
+ *
+ * Reports CONFIG IDENTIFIERS AND BOOLEANS ONLY — never an entry, an `env`
+ * object, a command line, an API key, or an unrelated profile token — and names
+ * only the three configs the merge path can write, so nothing here can imply
+ * that Codex or Copilot configuration was inspected or changed.
+ */
+export function conductorProfileTokenSection(profile, conductorContext) {
+    const base = { id: "conductor-profile-token", label: "MCP conductor profile token" };
+    if (profile === null) {
+        return {
+            ...base,
+            status: "degraded",
+            detail: "the host MCP profile token could not be inspected",
+            remediation: CONDUCTOR_PROFILE_TOKEN_REMEDIATION,
+        };
+    }
+    const carrying = profile.configs
+        .filter((c) => c.state === "token-present")
+        .map((c) => c.path);
+    const scope = "inspected .mcp.json, .vscode/mcp.json, .cursor/mcp.json only " +
+        "(Codex and Copilot host configuration is not inspected)";
+    if (carrying.length > 0) {
+        return {
+            ...base,
+            status: "ok",
+            detail: `\`${profile.token}\` present in ${carrying.join(", ")}; ${scope}`,
+        };
+    }
+    // "No entry anywhere" and "an entry without the token" are different findings
+    // with different next steps, so they never collapse into one remediation.
+    const detail = profile.bridgeEntryPresent
+        ? `no supported host config carries the \`${profile.token}\` token; ${scope}`
+        : `no supported host config carries a Bridge entry; ${scope}`;
+    const remediation = profile.bridgeEntryPresent
+        ? CONDUCTOR_PROFILE_TOKEN_REMEDIATION
+        : CONDUCTOR_PROFILE_TOKEN_NO_ENTRY_REMEDIATION;
+    return conductorContext
+        ? { ...base, status: "degraded", detail, remediation }
+        : { ...base, status: "ok", detail: `advisory — ${detail}`, remediation };
+}
+/**
+ * Managed conductor hook targets, DERIVED from `legacyConductor.git_hooks`.
+ *
+ * Derived, never re-probed: a second parse of the same hook files is a second
+ * chance to disagree with the report embedded right below this section. Healthy
+ * requires each managed hook to exist, carry the managed block, and point at an
+ * embedded binary that stats as a regular file — a hook whose target vanished is
+ * a dead hook, and reporting it as installed is the exact failure BAPI-772 made
+ * structurally impossible at INSTALL time but which can still arise later.
+ *
+ * Renders hook NAME and boolean state only. The embedded absolute binary path is
+ * read for the file check and never copied into this section.
+ */
+export function conductorHookTargetsSection(legacyConductor, conductorContext) {
+    const base = { id: "conductor-hook-targets", label: "Conductor hook targets" };
+    // Nullish, not `=== null`: an injected builder may resolve `undefined`, and a
+    // doctor that throws on it would abort the run it exists to diagnose.
+    if (legacyConductor === null || legacyConductor === undefined) {
+        return {
+            ...base,
+            status: "degraded",
+            detail: "hook targets could not be derived (the conductor doctor was not collected)",
+            remediation: CONDUCTOR_HOOK_TARGET_REMEDIATION,
+        };
+    }
+    // Defensive for the same reason as {@link detectConductorContext}: an injected
+    // sentinel need not carry every legacy field.
+    const hooks = legacyConductor.git_hooks;
+    if (hooks === undefined) {
+        return {
+            ...base,
+            status: "degraded",
+            detail: "hook targets could not be derived (the conductor doctor reported no hook state)",
+            remediation: CONDUCTOR_HOOK_TARGET_REMEDIATION,
+        };
+    }
+    if (!hooks.is_worktree) {
+        return {
+            ...base,
+            status: "ok",
+            detail: "advisory — not a git worktree, so no managed conductor hooks apply",
+        };
+    }
+    const usable = (name) => {
+        const hook = (hooks.hooks ?? []).find((h) => h.name === name);
+        return (hook !== undefined &&
+            hook.exists &&
+            hook.managed_block_present &&
+            hook.embedded_bin_is_file);
+    };
+    const rendered = MANAGED_HOOK_NAMES.map((name) => `${name}=${usable(name)}`).join(", ");
+    const allUsable = MANAGED_HOOK_NAMES.every((name) => usable(name));
+    if (allUsable) {
+        return { ...base, status: "ok", detail: `managed hooks usable: ${rendered}` };
+    }
+    const detail = `managed hooks usable: ${rendered}`;
+    return conductorContext
+        ? { ...base, status: "degraded", detail, remediation: CONDUCTOR_HOOK_TARGET_REMEDIATION }
+        : {
+            ...base,
+            status: "ok",
+            detail: `advisory — ${detail}`,
+            remediation: CONDUCTOR_HOOK_TARGET_REMEDIATION,
+        };
+}
+/**
+ * Native ledger loadability, DERIVED from `legacyConductor.native_ledger`.
+ *
+ * No parallel `better-sqlite3` check: the mapping from an inspection to
+ * available/degraded lives in one place ({@link describeNativeLedgerAvailability}),
+ * so this section and the conductor doctor can never disagree about whether the
+ * binding loads. A degraded result carries the module name, the ABI, and the
+ * sanitized failure kind, because the common cause is npm silently skipping an
+ * optionalDependency build and that is undiagnosable without the ABI.
+ */
+export function conductorLedgerLoadabilitySection(legacyConductor) {
+    const base = {
+        id: "conductor-ledger-loadability",
+        label: "Conductor ledger loadability",
+    };
+    if (legacyConductor === null || legacyConductor === undefined) {
+        return {
+            ...base,
+            status: "degraded",
+            detail: "ledger loadability could not be derived (the conductor doctor was not collected)",
+            remediation: CONDUCTOR_LEDGER_LOADABILITY_REMEDIATION,
+        };
+    }
+    const inspection = legacyConductor.native_ledger;
+    if (inspection === undefined) {
+        return {
+            ...base,
+            status: "degraded",
+            detail: "ledger loadability could not be derived (the conductor doctor reported no native-ledger state)",
+            remediation: CONDUCTOR_LEDGER_LOADABILITY_REMEDIATION,
+        };
+    }
+    const availability = describeNativeLedgerAvailability(inspection);
+    if (availability.status === "available") {
+        return { ...base, status: "ok", detail: "ledger available — the native binding loads" };
+    }
+    return {
+        ...base,
+        status: "degraded",
+        detail: `ledger degraded — ${availability.module} did not load ` +
+            `(NODE_MODULE_VERSION ${availability.nodeModulesAbi}, failure: ${availability.failureKind})`,
+        remediation: CONDUCTOR_LEDGER_LOADABILITY_REMEDIATION,
+    };
+}
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+/**
+ * BAPI-941: the workflow's local state AND, when the seam is supplied and the
+ * file is genuinely present, its lineage relative to the default branch. The
+ * drift detail is bounded text from the shared classifier — never git stderr and
+ * never file content.
+ */
+export async function inspectWorkflowPresence(readWorkflowFile, classifyWorkflowDrift) {
+    const local = await inspectWorkflowLocalPresence(readWorkflowFile);
+    if (local !== "present" || !classifyWorkflowDrift)
+        return { presence: local };
+    try {
+        const classification = await classifyWorkflowDrift();
+        if (classification.state === "drifted") {
+            return {
+                presence: "drifted",
+                driftDetail: summarizeClaudeReviewWorkflowDrift(classification),
+            };
+        }
+        if (classification.state === "unverified") {
+            // Inconclusive, so the presence state stays `present` and non-failing. The
+            // uncertainty is still reported, through the existing detail line rather
+            // than by inventing a failure the probe did not establish.
+            return {
+                presence: "present",
+                driftDetail: summarizeClaudeReviewWorkflowDrift(classification),
+            };
+        }
+        return { presence: "present" };
+    }
+    catch {
+        // A thrown probe is an unavailable comparison, not a fault in the workflow.
+        return { presence: "present" };
+    }
+}
+export async function inspectWorkflowLocalPresence(readWorkflowFile) {
+    try {
+        await readWorkflowFile();
+        return "present";
+    }
+    catch (err) {
+        // ENOENT is the ordinary "absent" case; anything else is "unreadable". The
+        // error's message is never surfaced — it can echo an absolute path.
+        const code = err?.code;
+        return code === "ENOENT" ? "absent" : "unreadable";
+    }
+}