@bridge_gpt/mcp-server 0.2.51 → 0.2.53

package/build/conductor/readiness.js

@@ -0,0 +1,710 @@
+/**
+ * The consolidated ADVISORY conductor readiness gate (BAPI-1055, AC-6/AC-7).
+ *
+ * One report that answers "is this host and repository ready to conduct an
+ * epic", assembled from the five loci that each answered part of it before:
+ * `bridge doctor`'s install checklist, `conductor doctor`'s local inspections,
+ * `plane` preflight, the server `conductor-readiness` collector, and the
+ * install-time doctor that already composed four of them. Every prerequisite
+ * comes back as a canonical {@link ReadinessCheck}: a stable id, a
+ * pass/warn/fail/skip status, and — on a failure — exactly ONE named
+ * remediation.
+ *
+ * It COMPOSES; it never re-probes. Each collector still owns its own probe, its
+ * own timeout, and its own verdict, and this module reads what they returned.
+ *
+ * ---
+ *
+ * # Risk boundary for the advisory-only decision (BAPI-1055, R-5)
+ *
+ * This gate reports and remediates. It never blocks.
+ *
+ * **Detection.** Every prerequisite that is not `pass` is emitted as a
+ * structured check with a named remediation: `warn` for a degraded but usable
+ * capability, `fail` for an unmet prerequisite OR one whose state could not be
+ * established, `skip` for a genuine dependency or applicability case. Unknown is
+ * never reported as healthy — an unreadable liveness read, a failed permission
+ * probe, `executor.ready === null`, and a field a newer server would have sent
+ * are all failures, not passes.
+ *
+ * **Containment.** The authoritative refusals are unchanged and live elsewhere:
+ * `V2_READINESS_REQUIREMENTS` in `drive-epic.ts` remains the SOLE hard
+ * route-selection predicate, and the server-side admission (A1b.1/A1b.2) remains
+ * the sole hard refusal. `plane up`'s own blocking preflight still refuses a
+ * bring-up on its own terms. This gate contributes to none of those decisions:
+ * it computes no overall verdict, changes no exit code, and is imported by no
+ * route-selection code. What containment does NOT cover is the gap this gate
+ * exists to fill — local and plane configuration problems that the server
+ * predicates cannot see at all, and that previously surfaced only as prose
+ * buried in a warning.
+ *
+ * **Escalation.** Findings go to the invoking operator as structured CLI output,
+ * with one named remediation each. That remediation is a description of an
+ * operator action; nothing here executes one. An ordinary configuration gap
+ * raises no Sentry event and pages nobody — it is a normal, expected report. A
+ * collector that fails PERSISTENTLY (the same source failing across runs) is the
+ * escalation case, and it escalates to whoever owns that host: the operator for
+ * a local collector, and the Bridge API owner for a server-side collector that
+ * keeps timing out or answering unreadably.
+ *
+ * ## Deferred retirement: local `gh` (AC-7)
+ *
+ * **Detection** is `conductor.gh-cli` and `conductor.gh-auth`, carried as two
+ * separate checks because installing `gh` and authenticating it are two
+ * different operator actions. **Containment** is the existing local-merge
+ * execution path, which refuses and emits `merge.failed`/`merge.skipped` rather
+ * than merging without auth — a missing `gh` degrades a run, it does not corrupt
+ * one. **Escalation** targets the invoking operator first; there is no automated
+ * fallback, because the GitHub App token is `contents: read` and structurally
+ * cannot merge (see `mcp_server/src/executor/merge-job.ts`). **Retirement** is
+ * owned by epic A2, after the App is elevated to `contents: write`. Until A2
+ * ships this check is load-bearing and no code here may remove, hide, or
+ * downgrade it.
+ *
+ * ## Deferred retirement: native SQLite ledger (AC-7)
+ *
+ * **Detection** is `conductor.native-ledger` plus the two Node-environment
+ * checks beside it (`conductor.mcp-registration-form`,
+ * `conductor.node-engine`). **Containment** is diagnostic degradation only: a
+ * ledger whose binding does not load costs local observability, and no code path
+ * here installs, rebuilds, or repairs a package (BAPI-526). **Escalation**
+ * targets the invoking operator, who reinstalls the optional dependency for
+ * their Node runtime. **Retirement** is owned by epic B3, after the parallel
+ * ledger is pared away. Until B3 ships this check is load-bearing.
+ *
+ * ---
+ *
+ * ## Schema versioning
+ *
+ * {@link CONDUCTOR_READINESS_GATE_SCHEMA_VERSION} is INDEPENDENT of the install
+ * doctor's section vocabulary, the conductor doctor's report, the plane
+ * diagnostic shape, and the Python wire response. Each of those evolves for its
+ * own reasons; binding this report's version to any of them would make an
+ * unrelated additive change look like a breaking one here, or worse, hide a real
+ * one.
+ */
+import { mapConductorDoctorReportToReadinessChecks, } from "./doctor.js";
+import { mapInstallStatusChecksToReadinessChecks, } from "../install-doctor.js";
+import { mapPlanePreflightToReadinessChecks, } from "../plane/preflight.js";
+import { runConductorInstallDoctor, } from "./install-doctor.js";
+import { createReadinessCheck, createReadinessCheckSafely, summarizeReadinessChecks, validateReadinessChecks, } from "../readiness-check.js";
+/** This report's own schema version. See the module docstring. */
+export const CONDUCTOR_READINESS_GATE_SCHEMA_VERSION = 1;
+/** Fixed statement carried in every report, so no consumer can mistake it for a gate. */
+export const CONDUCTOR_READINESS_ADVISORY_NOTICE = "Advisory only. This report never blocks bring-up, approval, or a run, and never changes an " +
+    "exit code. Remediations are operator actions and are never executed automatically. " +
+    "drive-epic's V2_READINESS_REQUIREMENTS remains the only hard route-selection predicate, and " +
+    "the server-side admission remains the only hard refusal.";
+// ---------------------------------------------------------------------------
+// Server-fact mapper
+// ---------------------------------------------------------------------------
+/** The complete server-side prerequisite set, in render order. */
+export const SERVER_READINESS_DESCRIPTORS = [
+    { id: "supervisor-setup", label: "Supervisor setup" },
+    { id: "supervisor-config", label: "Supervisor configuration" },
+    { id: "supervisor-required-checks", label: "Supervisor required CI checks" },
+    { id: "auto-merge", label: "Auto-merge posture" },
+    { id: "merge-approval", label: "Merge approval configuration" },
+    { id: "review-policy", label: "Review policy" },
+    { id: "github-credentials", label: "GitHub App credentials" },
+    { id: "github-actions-permission", label: "GitHub App actions permission" },
+    { id: "reconciler-liveness", label: "Reconciler tick liveness" },
+    { id: "executor-readiness", label: "Executor server observation" },
+    { id: "review-workflow", label: "Review workflow protocol" },
+    { id: "conductor-ci-workflow", label: "Conductor CI migration guard" },
+];
+/** Fixed, secret-free prose per failure kind. Never a status body or header. */
+const SERVER_FAILURE_COPY = {
+    "identity-unresolved": {
+        detail: "no server facts were read — the repository identity or credential could not be resolved",
+        remediation: "run /install-bridge (or set BAPI_REPO_NAME and BAPI_API_KEY) for this repository, then re-run.",
+    },
+    unauthorized: {
+        detail: "the Bridge API rejected the credential for this repository",
+        remediation: "re-check the API key and repository name, then re-run; the key may have been rotated.",
+    },
+    "invalid-response": {
+        detail: "the readiness response failed shape validation, so no server fact can be trusted",
+        remediation: "re-run; if it persists the Bridge API deploy is inconsistent with this CLI version.",
+    },
+    unreachable: {
+        detail: "the readiness endpoint could not be reached",
+        remediation: "check network reachability to the Bridge API and re-run; the local checks above are unaffected.",
+    },
+};
+/** Remediations for the individual server facts, as fixed prose. */
+const SERVER_REMEDIATIONS = {
+    supervisorSetup: "run `install conductor` (or `setup-epic`) for this repository to write the project-default supervisor posture.",
+    supervisorConfig: "run `install conductor` for this repository to write the project-default supervisor configuration.",
+    requiredChecks: "configure a non-empty required-check list in done_gate_config; an empty list makes the done gate pass unconditionally.",
+    mergeApproval: "set the merge-approval requirement explicitly in the supervisor configuration rather than leaving it unset.",
+    reviewPolicyMissing: "set the repository review-policy default so the merge path and the code_review gate read the same signal.",
+    reviewPolicyDivergent: "align the repository review-policy default with the done gate's review_state condition, or confirm the difference is intended.",
+    githubCredentials: "connect GitHub from the Bridge setup UI (`install-bridge connect-github`) so owner, repository id, and installation id all resolve.",
+    actionsProbeFailed: "re-run once credentials resolve; the permission could not be checked, which is not the same as confirmed-missing.",
+    actionsMissing: "grant the GitHub App `actions: write`; without it the conductor's workflow rerun lane fails open on 403.",
+    reconcilerUnreadable: "retry once the Bridge API is reachable; reconciler liveness is unknown here, not confirmed stale.",
+    reconcilerStale: "start the reconciler for this repository (the `conductor epic-tick` schedule) so ticks resume.",
+    executorUnreadable: "retry once the Bridge API is reachable; no executor readiness claim is ever made from local state.",
+    executorNeverSeen: "provision and start an executor (`install conductor --executor-id <id>` or `executor install-service`); readiness comes only from a live server observation.",
+    executorStale: "restart the executor service; it was observed once and has gone quiet past the server's staleness threshold.",
+    reviewWorkflowUnknown: "re-run; the default branch's review workflow could not be evaluated, which is not the same as it being absent.",
+    reviewWorkflowIncomplete: "install the claude-review workflow template on the default branch so it emits both the run id and the reviewed SHA the verdict protocol reads.",
+    ciWorkflowUnknown: "re-run; the default branch's conductor CI workflow could not be evaluated, which is not the same as the guard being absent.",
+    ciWorkflowMissingGuard: "add the migration-guard job to the conductor CI workflow on the default branch so migrations are checked before a merge.",
+    olderServer: "upgrade the Bridge API deploy so it reports this fact; its state is unknown here, not healthy.",
+};
+/**
+ * Project the validated server readiness response into `server.*` checks.
+ *
+ * PURE. It re-derives nothing: the server's own `stale` and `ready` conclusions
+ * and its own threshold values are reported as given, and
+ * `V2_READINESS_REQUIREMENTS` is neither imported nor duplicated here — two
+ * implementations of one classification drift, and this one is advisory while
+ * that one decides a route.
+ *
+ * Uncertainty is never healthy. `actions_probe_succeeded === false`, an
+ * unreadable liveness read, `executor.ready === null`, and a field an older
+ * server never sent each map to `fail` with a remediation for RESTORING the
+ * probe — kept deliberately distinct from the confirmed-negative remediation,
+ * because "could not be checked" and "checked and absent" need different
+ * actions.
+ *
+ * Passing `null` (with a `failure` kind) yields the full descriptor set as
+ * failures, so an unreachable server loses no prerequisite from the report.
+ */
+export function mapServerReadinessToChecks(readiness, failure = "unreachable") {
+    if (readiness === null) {
+        const copy = SERVER_FAILURE_COPY[failure];
+        return SERVER_READINESS_DESCRIPTORS.map(({ id, label }) => createReadinessCheck({
+            id: `server.${id}`,
+            source: "server",
+            label,
+            status: "fail",
+            detail: copy.detail,
+            remediation: copy.remediation,
+        }));
+    }
+    const s = readiness.supervisor;
+    const g = readiness.github;
+    const r = readiness.reconciler;
+    const e = readiness.executor;
+    const outcomes = [];
+    outcomes.push(s.setup_present
+        ? { id: "supervisor-setup", status: "pass", detail: `stored (source: ${s.setup_source})` }
+        : {
+            id: "supervisor-setup",
+            status: "fail",
+            detail: "no supervisor setup is stored for this repository",
+            remediation: SERVER_REMEDIATIONS.supervisorSetup,
+        });
+    outcomes.push(s.config_present
+        ? { id: "supervisor-config", status: "pass", detail: `stored (source: ${s.config_source})` }
+        : {
+            id: "supervisor-config",
+            status: "fail",
+            detail: "no supervisor configuration is stored for this repository",
+            remediation: SERVER_REMEDIATIONS.supervisorConfig,
+        });
+    // Counts and booleans are safe facts and stay in `detail`; they never become
+    // checks of their own, because there is nothing separate to remediate.
+    outcomes.push(s.required_checks_empty
+        ? {
+            id: "supervisor-required-checks",
+            status: "warn",
+            detail: "the required-check list is EMPTY — the done gate would pass unconditionally",
+            remediation: SERVER_REMEDIATIONS.requiredChecks,
+        }
+        : {
+            id: "supervisor-required-checks",
+            status: "pass",
+            detail: `${s.required_checks_count} required check(s) configured`,
+        });
+    // Auto-merge OFF is a posture, not a gap: an operator may deliberately merge
+    // by hand. Reported, never remediated.
+    outcomes.push({
+        id: "auto-merge",
+        status: "pass",
+        detail: s.auto_merge_enabled ? "auto-merge enabled" : "auto-merge disabled (operator posture)",
+    });
+    outcomes.push(s.merge_approval_required_set
+        ? { id: "merge-approval", status: "pass", detail: "merge-approval requirement is set explicitly" }
+        : {
+            id: "merge-approval",
+            status: "warn",
+            detail: "the merge-approval requirement is unset, so the merge path falls back to its default",
+            remediation: SERVER_REMEDIATIONS.mergeApproval,
+        });
+    outcomes.push(reviewPolicyOutcome(readiness));
+    outcomes.push(g.credentials_complete
+        ? {
+            id: "github-credentials",
+            status: "pass",
+            detail: "owner, repository id, and installation id all resolved",
+        }
+        : {
+            id: "github-credentials",
+            status: "fail",
+            detail: g.credentials_readable
+                ? `incomplete: ${[
+                    !g.owner_resolved ? "owner" : null,
+                    !g.repo_id_resolved ? "repository id" : null,
+                    !g.installation_id_resolved ? "installation id" : null,
+                ]
+                    .filter(Boolean)
+                    .join(", ")} unresolved`
+                : "no GitHub credential row exists for this repository",
+            remediation: SERVER_REMEDIATIONS.githubCredentials,
+        });
+    outcomes.push(githubActionsOutcome(readiness));
+    outcomes.push(reconcilerOutcome(readiness));
+    outcomes.push(executorOutcome(readiness));
+    outcomes.push(reviewWorkflowOutcome(readiness));
+    outcomes.push(ciWorkflowOutcome(readiness));
+    const byId = new Map(outcomes.map((outcome) => [outcome.id, outcome]));
+    return SERVER_READINESS_DESCRIPTORS.map(({ id, label }) => {
+        const outcome = byId.get(id);
+        if (!outcome) {
+            return createReadinessCheck({
+                id: `server.${id}`,
+                source: "server",
+                label,
+                status: "fail",
+                detail: "this server fact was not reported",
+                remediation: SERVER_REMEDIATIONS.olderServer,
+            });
+        }
+        return createReadinessCheckSafely({
+            id: `server.${id}`,
+            source: "server",
+            label,
+            status: outcome.status,
+            detail: outcome.detail,
+            ...(outcome.status === "pass"
+                ? {}
+                : { remediation: outcome.remediation ?? SERVER_REMEDIATIONS.olderServer }),
+        });
+    });
+}
+/** Review-policy presence and alignment, as one check with one fix each. */
+function reviewPolicyOutcome(readiness) {
+    const s = readiness.supervisor;
+    const alignment = s.review_policy_alignment;
+    if (alignment !== null) {
+        if (alignment.status === "divergent" || alignment.status === "invalid") {
+            return {
+                id: "review-policy",
+                status: "warn",
+                // The server authors one operator-facing sentence for this; it is a
+                // constrained, server-owned explanation, not free-form error text.
+                detail: alignment.explanation,
+                remediation: SERVER_REMEDIATIONS.reviewPolicyDivergent,
+            };
+        }
+        return { id: "review-policy", status: "pass", detail: alignment.explanation };
+    }
+    // A pre-alignment server cannot report alignment. Presence is still knowable.
+    return s.review_policy_present
+        ? {
+            id: "review-policy",
+            status: "pass",
+            detail: "a repository review-policy default is stored (alignment not reported by this server)",
+        }
+        : {
+            id: "review-policy",
+            status: "warn",
+            detail: "no repository review-policy default is stored",
+            remediation: SERVER_REMEDIATIONS.reviewPolicyMissing,
+        };
+}
+/**
+ * GitHub Actions permission.
+ *
+ * A FAILED PROBE and a CONFIRMED insufficient permission are two findings with
+ * two fixes — retry the probe, versus grant the permission — and collapsing them
+ * would send an operator to change a permission that may already be correct.
+ */
+function githubActionsOutcome(readiness) {
+    const g = readiness.github;
+    if (g.actions_write) {
+        return { id: "github-actions-permission", status: "pass", detail: "actions: write" };
+    }
+    if (!g.actions_probe_succeeded) {
+        return {
+            id: "github-actions-permission",
+            status: "fail",
+            detail: "the actions permission could not be checked (this is not a confirmed absence)",
+            remediation: SERVER_REMEDIATIONS.actionsProbeFailed,
+        };
+    }
+    return {
+        id: "github-actions-permission",
+        status: "warn",
+        detail: `actions: ${g.actions_permission_level}`,
+        remediation: SERVER_REMEDIATIONS.actionsMissing,
+    };
+}
+/** Reconciler liveness, preserving the server's own `stale` conclusion. */
+function reconcilerOutcome(readiness) {
+    const r = readiness.reconciler;
+    if (!r.liveness_readable) {
+        return {
+            id: "reconciler-liveness",
+            status: "fail",
+            detail: "reconciler liveness could not be read",
+            remediation: SERVER_REMEDIATIONS.reconcilerUnreadable,
+        };
+    }
+    if (!r.stale) {
+        return {
+            id: "reconciler-liveness",
+            status: "pass",
+            detail: `last tick ${r.last_tick_age_seconds}s ago across ${r.active_run_count} active run(s)`,
+        };
+    }
+    return {
+        id: "reconciler-liveness",
+        status: "fail",
+        detail: r.last_tick_at === null
+            ? "no reconciler tick has been recorded for this repository"
+            : `last tick ${r.last_tick_age_seconds}s ago (server threshold ${readiness.thresholds.reconciler_stale_after_seconds}s)`,
+        remediation: SERVER_REMEDIATIONS.reconcilerStale,
+    };
+}
+/**
+ * Executor readiness — the AUTHORITATIVE executor fact.
+ *
+ * The three not-ready shapes stay distinct because they mean different things
+ * and need different actions: `null` is "never observed", `false` is "observed
+ * but stale", and an unreadable payload is "unknown". Collapsing them would let
+ * a stale executor read like a fresh install, or the reverse.
+ */
+function executorOutcome(readiness) {
+    const e = readiness.executor;
+    if (!e.liveness_readable) {
+        return {
+            id: "executor-readiness",
+            status: "fail",
+            detail: "executor liveness could not be read",
+            remediation: SERVER_REMEDIATIONS.executorUnreadable,
+        };
+    }
+    if (e.ready === true) {
+        return {
+            id: "executor-readiness",
+            status: "pass",
+            detail: `executor ready — last seen ${e.last_seen_age_seconds}s ago`,
+        };
+    }
+    if (e.ready === false) {
+        return {
+            id: "executor-readiness",
+            status: "fail",
+            detail: `observed but not ready — last seen ${e.last_seen_age_seconds}s ago (server threshold ${readiness.thresholds.executor_stale_after_seconds}s)`,
+            remediation: SERVER_REMEDIATIONS.executorStale,
+        };
+    }
+    return {
+        id: "executor-readiness",
+        status: "fail",
+        detail: "never observed by the server",
+        remediation: SERVER_REMEDIATIONS.executorNeverSeen,
+    };
+}
+/** Review-workflow protocol facts. `null` means an older server, not health. */
+function reviewWorkflowOutcome(readiness) {
+    const w = readiness.review_workflow;
+    if (w === null) {
+        return {
+            id: "review-workflow",
+            status: "fail",
+            detail: "this Bridge API deploy did not report the review-workflow facts",
+            remediation: SERVER_REMEDIATIONS.olderServer,
+        };
+    }
+    if (!w.probe_succeeded) {
+        return {
+            id: "review-workflow",
+            status: "fail",
+            detail: w.workflow_present
+                ? "the review workflow is present but could not be evaluated"
+                : "the review workflow could not be found or read on the default branch",
+            remediation: SERVER_REMEDIATIONS.reviewWorkflowUnknown,
+        };
+    }
+    if (w.emits_run_id && w.emits_reviewed_sha) {
+        return {
+            id: "review-workflow",
+            status: "pass",
+            detail: "the default branch's review workflow emits both protocol markers",
+        };
+    }
+    return {
+        id: "review-workflow",
+        status: "fail",
+        detail: `missing marker(s): ${[
+            !w.emits_run_id ? "run id" : null,
+            !w.emits_reviewed_sha ? "reviewed SHA" : null,
+        ]
+            .filter(Boolean)
+            .join(", ")}`,
+        remediation: SERVER_REMEDIATIONS.reviewWorkflowIncomplete,
+    };
+}
+/** Conductor-CI migration-guard facts. `null` means an older server. */
+function ciWorkflowOutcome(readiness) {
+    const c = readiness.conductor_ci_workflow;
+    if (c === null) {
+        return {
+            id: "conductor-ci-workflow",
+            status: "fail",
+            detail: "this Bridge API deploy did not report the conductor-CI workflow facts",
+            remediation: SERVER_REMEDIATIONS.olderServer,
+        };
+    }
+    if (!c.probe_succeeded) {
+        return {
+            id: "conductor-ci-workflow",
+            status: "fail",
+            detail: c.workflow_present
+                ? "the conductor CI workflow is present but could not be evaluated"
+                : "the conductor CI workflow could not be found or read on the default branch",
+            remediation: SERVER_REMEDIATIONS.ciWorkflowUnknown,
+        };
+    }
+    return c.migration_guard_present
+        ? {
+            id: "conductor-ci-workflow",
+            status: "pass",
+            detail: "the default branch's conductor CI workflow runs the migration guard",
+        }
+        : {
+            id: "conductor-ci-workflow",
+            status: "warn",
+            detail: "the conductor CI workflow does not run the migration guard",
+            remediation: SERVER_REMEDIATIONS.ciWorkflowMissingGuard,
+        };
+}
+// ---------------------------------------------------------------------------
+// Install-time section adapter
+// ---------------------------------------------------------------------------
+/**
+ * Sections the install-time doctor builds that the OWNING collectors also
+ * report through their own structured outcomes.
+ *
+ * Deduplication prefers the owner: a section is a prose interpretation of a
+ * probe, while the owning collector's outcome is the probe's own structured
+ * result, and reporting both would show one prerequisite twice with two
+ * wordings. The install-side ids that overlap are listed rather than matched by
+ * heuristic, so adding a section can never silently start shadowing an owner.
+ */
+const INSTALL_SECTION_IDS_OWNED_ELSEWHERE = new Set([
+    // Server facts — owned by `mapServerReadinessToChecks`.
+    "supervisor-configuration",
+    "supervisor-required-checks",
+    "supervisor-review-alignment",
+    "github-credentials",
+    "github-actions-permission",
+    "reconciler-liveness",
+    "executor-observation",
+    "server-readiness",
+    "bridge-access",
+    // Local conductor facts — owned by `mapConductorDoctorReportToReadinessChecks`.
+    "conductor-ledger",
+    "conductor-ledger-loadability",
+    // Legacy embedded reports — owned by their own adapters.
+    "install-status",
+]);
+/** Map the install doctor's own status vocabulary onto the canonical one. */
+function sectionStatus(status) {
+    // `fatal` becomes `fail`, and NOTHING else follows from it here: the exit-code
+    // consequence stays with the installer's `conductorInstallDoctorHasFatal`.
+    if (status === "fatal")
+        return "fail";
+    return status === "degraded" ? "warn" : "pass";
+}
+/**
+ * Project the install-time doctor's remaining sections into `conductor.*` checks.
+ *
+ * These are the prerequisites no other collector owns — executor provisioning,
+ * local service state, the host profile token, hook targets, and the workflow
+ * presence section. Ids are prefixed `install-section-` so they cannot collide
+ * with a conductor-doctor outcome that happens to share a name.
+ */
+export function mapInstallSectionsToReadinessChecks(sections) {
+    const checks = [];
+    const seen = new Set();
+    for (const section of sections ?? []) {
+        if (INSTALL_SECTION_IDS_OWNED_ELSEWHERE.has(section.id))
+            continue;
+        if (seen.has(section.id))
+            continue;
+        seen.add(section.id);
+        const status = sectionStatus(section.status);
+        checks.push(createReadinessCheckSafely({
+            id: `conductor.install-section-${section.id}`,
+            source: "conductor",
+            label: section.label,
+            status,
+            detail: section.detail,
+            ...(status === "pass"
+                ? {}
+                : {
+                    remediation: section.remediation ??
+                        "run `install conductor` for this repository to re-provision this capability.",
+                }),
+        }));
+    }
+    return checks;
+}
+/**
+ * Collect the consolidated advisory readiness report.
+ *
+ * NEVER THROWS. A collector that fails does not remove its prerequisites from
+ * the report — they come back as failed checks with restoring remediations, so a
+ * broken source can never make a report look shorter and healthier.
+ *
+ * The two independent collections (install-time doctor, plane preflight) run
+ * concurrently. No retry and no additional timeout is introduced: each collector
+ * keeps its own.
+ */
+export async function collectConductorReadinessGate(deps) {
+    const [installReport, planeResult] = await Promise.all([
+        runInstallDoctorSafely(deps),
+        runPlaneSafely(deps),
+    ]);
+    const unavailableSources = [];
+    // The install-time doctor is the collector for the install, conductor-section,
+    // and server legs; losing it loses all three.
+    if (installReport === null) {
+        unavailableSources.push("install", "conductor", "server");
+    }
+    // A plane preflight was requested and could not be run. Not requesting one is
+    // not an unavailability — its prerequisites are still reported as unknowns.
+    if (deps.runPlanePreflight && planeResult === null)
+        unavailableSources.push("plane");
+    const checks = [
+        ...mapInstallStatusChecksToReadinessChecks((installReport?.legacyInstallChecks ?? null), installReport === null),
+        ...mapConductorDoctorReportToReadinessChecks(installReport?.legacyConductor ?? null),
+        ...mapInstallSectionsToReadinessChecks(installReport?.sections ?? null),
+        ...mapPlanePreflightToReadinessChecks(planeResult),
+        ...mapServerReadinessToChecks(installReport?.readiness ?? null, classifyServerFailure(installReport)),
+    ];
+    // Validate the ASSEMBLED report, not just the pieces: an injected collector or
+    // a future adapter could hand over an entry that violates the contract, and a
+    // malformed entry becomes a fixed source-scoped failure rather than escaping
+    // into output or dropping the locus.
+    const validated = validateReadinessChecks(checks);
+    return {
+        schemaVersion: CONDUCTOR_READINESS_GATE_SCHEMA_VERSION,
+        advisory: CONDUCTOR_READINESS_ADVISORY_NOTICE,
+        repoName: deps.repoName ?? null,
+        unavailableSources,
+        checks: validated,
+        summary: summarizeReadinessChecks(validated),
+    };
+}
+/** Run the install-time doctor, containing any throw. */
+async function runInstallDoctorSafely(deps) {
+    try {
+        if (deps.runInstallDoctor)
+            return await deps.runInstallDoctor();
+        if (!deps.installDoctor)
+            return null;
+        return await runConductorInstallDoctor(deps.conductorDoctorDeps
+            ? { ...deps.installDoctor, conductorDoctorDeps: deps.conductorDoctorDeps }
+            : deps.installDoctor);
+    }
+    catch {
+        // It is documented never to throw; this contains an injected fake so the
+        // whole report is not lost to one collector.
+        return null;
+    }
+}
+/** Run the plane preflight, containing any throw. */
+async function runPlaneSafely(deps) {
+    if (!deps.runPlanePreflight)
+        return null;
+    try {
+        return await deps.runPlanePreflight();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Why the server facts are missing, when they are.
+ *
+ * Read from the install doctor's OWN fatal/degraded section rather than
+ * re-classified here: it already distinguishes an unresolved identity, a
+ * rejected credential, a malformed body, and an unreachable endpoint, and a
+ * second classification would be a second chance to disagree with the first.
+ */
+function classifyServerFailure(report) {
+    if (report === null)
+        return "unreachable";
+    const sections = report.sections ?? [];
+    if (sections.some((section) => section.id === "bridge-access"))
+        return "identity-unresolved";
+    const serverSection = sections.find((section) => section.id === "server-readiness");
+    if (!serverSection)
+        return "unreachable";
+    if (serverSection.detail.includes("rejected the credential"))
+        return "unauthorized";
+    if (serverSection.detail.includes("shape validation"))
+        return "invalid-response";
+    return "unreachable";
+}
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+/** Status tag, matching the visual hierarchy of the other conductor reports. */
+function readinessTag(status) {
+    if (status === "fail")
+        return "✗ FAIL";
+    if (status === "warn")
+        return "! WARN";
+    if (status === "skip")
+        return "- SKIP";
+    return "✓ PASS";
+}
+/**
+ * Render the consolidated report for a terminal.
+ *
+ * Pure formatting. It carries the SAME content the JSON serialization does —
+ * every canonical check, its source, its status, its detail, and its
+ * remediation — so neither rendering can show an operator a finding the other
+ * hides. It computes no overall verdict, because there is none to compute.
+ */
+export function formatConductorReadinessGateReport(report) {
+    const lines = [
+        "Conductor readiness (advisory)",
+        "══════════════════════════════",
+        `schema version: ${report.schemaVersion}`,
+        `repository:     ${report.repoName ?? "unresolved"}`,
+        "",
+    ];
+    for (const source of ["install", "conductor", "plane", "server"]) {
+        const group = report.checks.filter((check) => check.source === source);
+        if (group.length === 0)
+            continue;
+        lines.push(`[${source}]`);
+        for (const check of group) {
+            lines.push(`  ${readinessTag(check.status)}  ${check.label}  (${check.id})`);
+            if (check.detail)
+                lines.push(`          ${check.detail}`);
+            if (check.remediation)
+                lines.push(`          → ${check.remediation}`);
+        }
+        lines.push("");
+    }
+    const { pass, warn, fail, skip } = report.summary;
+    lines.push(`summary: ${pass} pass, ${warn} warn, ${fail} fail, ${skip} skip`);
+    if (report.unavailableSources.length > 0) {
+        lines.push(`sources that could not be collected: ${report.unavailableSources.join(", ")} ` +
+            "(their prerequisites above are reported as failures, not as passes)");
+    }
+    lines.push("");
+    lines.push(report.advisory);
+    return lines.join("\n");
+}