@bridge_gpt/mcp-server 0.2.60 → 0.2.65

package/build/conductor/hook-runtime-qualification.js

@@ -0,0 +1,340 @@
+/**
+ * Read-only qualification of the runtime a managed conductor Git hook launches
+ * (BAPI-1290).
+ *
+ * BAPI-772 made the hook installer refuse a binary that does not EXIST. That is
+ * not enough for a hook's lifetime: a hook embeds one absolute path and runs it on
+ * every commit for as long as the hook file lives. When that path sits inside the
+ * `npx` cache (`~/.npm/_npx/<hash>/…`), ordinary cache cleanup deletes it and every
+ * later commit silently delivers nothing — the hook body is detached, discards its
+ * output, and ends in `|| true` by design.
+ *
+ * This module answers one question for both installation and diagnostics, so the
+ * two can never disagree: "is this entry a stable, package-owned invocation that
+ * the hook's `node` can actually run, including the native ledger binding?" The
+ * answer is evidence-based:
+ *
+ *   1. the canonical entry is a regular `build/epic-implementer-bin.js`;
+ *   2. it is not inside a prunable `_npx` cache directory;
+ *   3. it lives in the supported persistent npm layout
+ *      (`<prefix>/node_modules/@bridge_gpt/mcp-server/build/…`);
+ *   4. the adjacent `package.json` names this package, maps the
+ *      `epic-implementer` bin to that entry, and carries a compatible version;
+ *   5. the platform is a qualified one (macOS or Linux);
+ *   6. a bounded subprocess — `node` from PATH, exactly what the hook runs —
+ *      executes the entry's private runtime probe and reports a qualified Node
+ *      line and a loadable `better-sqlite3`.
+ *
+ * Anything missing, malformed, or inconclusive is UNAVAILABLE, never healthy. The
+ * failure carries only a fixed classification and a fixed action sentence: no
+ * probed path, no subprocess stderr, no caught exception text.
+ *
+ * Deliberately NOT here: running npm, downloading or installing anything, opening
+ * or migrating the ledger, or starting a service. The one subprocess is the
+ * bounded runtime probe, which only imports the native binding.
+ */
+import { spawnSync } from "node:child_process";
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { MCP_PACKAGE_NAME } from "../mcp-identity.js";
+import { isTransientNpxEntryPath } from "../mcp-server-invocation.js";
+/** The bin name the package maps to the hook entry. */
+export const HOOK_RUNTIME_BIN_NAME = "epic-implementer";
+/** The entry file every managed hook invokes. */
+export const HOOK_RUNTIME_ENTRY_FILENAME = "epic-implementer-bin.js";
+/** The private CLI action the bounded runtime probe runs. Never advertised. */
+export const HOOK_RUNTIME_PROBE_ACTION = "__hook-runtime-probe";
+/** Marker the probe prints so a stray line on stdout can never be mistaken for evidence. */
+export const HOOK_RUNTIME_PROBE_MARKER = "bapi-hook-runtime-probe/1";
+/**
+ * Platforms whose hook shell grammar and persistent npm layout are qualified.
+ * Windows Git hooks run under a different shell/runtime and are unqualified.
+ */
+export const HOOK_RUNTIME_QUALIFIED_PLATFORMS = ["darwin", "linux"];
+/**
+ * The lowest Node major line accepted for durable hooks. Only even (LTS) majors
+ * at or above it qualify; odd "current" lines are unqualified because they have a
+ * short support window and a native ABI that changes under the operator.
+ */
+export const HOOK_RUNTIME_MIN_NODE_MAJOR = 20;
+/**
+ * Compatible package versions: the `0.x` line from `0.2.0` onward. Every such
+ * release ships the renamed `epic-implementer-bin.js` entry and the
+ * `git-hook post-commit` / `git-hook reference-transaction` grammar the managed
+ * hook invokes, so an in-place upgrade inside this range keeps the hook valid
+ * without rewriting it. A `1.x` release must be requalified before it is added.
+ */
+export const HOOK_RUNTIME_COMPATIBLE_RANGE = ">=0.2.0 <1.0.0";
+/** Bounded wall-clock for the runtime probe subprocess. */
+export const HOOK_RUNTIME_PROBE_TIMEOUT_MS = 15_000;
+/** Upper bound on probe output read back; anything larger is malformed. */
+const HOOK_RUNTIME_PROBE_MAX_BUFFER = 16 * 1024;
+/** Every classification, for exhaustive rendering and tests. */
+export const HOOK_RUNTIME_CLASSIFICATIONS = [
+    "ephemeral-cache",
+    "missing",
+    "legacy-name",
+    "unqualified-runtime",
+    "node-unavailable",
+    "native-unavailable",
+    "unknown",
+];
+/** Fixed, path-free operator action for each classification. */
+export const HOOK_RUNTIME_ACTIONS = {
+    "ephemeral-cache": "the hook runtime is inside the npx cache, which cleanup can delete. Install the CLI " +
+        `persistently (\`npm i -g ${MCP_PACKAGE_NAME}\`) and re-run \`epic-implementer install-git-hooks\`.`,
+    missing: "the hook runtime entry is not present. Reinstall the CLI persistently " +
+        `(\`npm i -g ${MCP_PACKAGE_NAME}\`) and re-run \`epic-implementer install-git-hooks\`.`,
+    "legacy-name": "the hook invokes the retired conductor-bin.js entry. Re-run `epic-implementer install-git-hooks` " +
+        "from a persistent install.",
+    "unqualified-runtime": "the hook runtime is not a qualified persistent installation (supported: a persistent npm " +
+        `install of ${MCP_PACKAGE_NAME} ${HOOK_RUNTIME_COMPATIBLE_RANGE} on macOS or Linux with an even ` +
+        `Node LTS line >= ${HOOK_RUNTIME_MIN_NODE_MAJOR}). See mcp_server/docs/CONDUCTOR.md.`,
+    "node-unavailable": "`node` could not be launched from PATH, so the hook cannot run. Put a qualified Node on PATH " +
+        "and re-run `epic-implementer doctor`.",
+    "native-unavailable": "better-sqlite3 does not load for the hook's Node, so no event can be recorded. Reinstall the " +
+        `CLI (\`npm i -g ${MCP_PACKAGE_NAME}\`) with the Node on PATH and re-run \`epic-implementer doctor\`.`,
+    unknown: "the hook runtime could not be verified (a persistent install that predates the runtime probe " +
+        `also lands here). Upgrade it with \`npm i -g ${MCP_PACKAGE_NAME}@latest\`, then re-run ` +
+        "`epic-implementer doctor`.",
+};
+/** One sentence naming a classification and its action. Path-free by construction. */
+export function describeHookRuntimeClassification(classification) {
+    return `${classification}: ${HOOK_RUNTIME_ACTIONS[classification]}`;
+}
+function unavailable(classification) {
+    return { usable: false, classification, reason: describeHookRuntimeClassification(classification) };
+}
+function defaultRealpath(filePath) {
+    try {
+        return realpathSync(filePath);
+    }
+    catch {
+        return null;
+    }
+}
+function defaultIsFile(filePath) {
+    try {
+        return statSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function defaultReadText(filePath) {
+    try {
+        return readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run `node <stableEntry> __hook-runtime-probe` with a short timeout and a small
+ * output cap. `node` is resolved from PATH on purpose: that is the exact runtime
+ * the hook body invokes, so the probe measures what a commit will actually run.
+ * stderr is discarded unread.
+ */
+export function runHookRuntimeProbe(stableEntry) {
+    const result = spawnSync("node", [stableEntry, HOOK_RUNTIME_PROBE_ACTION], {
+        encoding: "utf-8",
+        timeout: HOOK_RUNTIME_PROBE_TIMEOUT_MS,
+        maxBuffer: HOOK_RUNTIME_PROBE_MAX_BUFFER,
+        stdio: ["ignore", "pipe", "ignore"],
+        windowsHide: true,
+    });
+    if (result.error) {
+        const code = result.error.code ?? null;
+        if (code === "ETIMEDOUT")
+            return { kind: "timeout" };
+        return { kind: "spawn-failed", code };
+    }
+    if (result.signal !== null)
+        return { kind: "timeout" };
+    if (result.status !== 0)
+        return { kind: "exit-nonzero" };
+    return { kind: "ok", stdout: result.stdout ?? "" };
+}
+/** Parse `major.minor.patch` (pre-release suffix ignored), or `null`. */
+export function parseSemver(version) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version.trim());
+    if (match === null)
+        return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/** True when `version` is inside {@link HOOK_RUNTIME_COMPATIBLE_RANGE}. */
+export function isCompatibleHookPackageVersion(version) {
+    const parsed = parseSemver(version);
+    if (parsed === null)
+        return false;
+    const [major, minor] = parsed;
+    return major === 0 && minor >= 2;
+}
+/** True when `nodeVersion` is an even LTS major at or above the minimum. */
+export function isQualifiedHookNodeVersion(nodeVersion) {
+    const parsed = parseSemver(nodeVersion);
+    if (parsed === null)
+        return false;
+    const [major] = parsed;
+    return major >= HOOK_RUNTIME_MIN_NODE_MAJOR && major % 2 === 0;
+}
+/**
+ * Locate the persistent package root for a canonical entry: the entry must be
+ * `<root>/build/epic-implementer-bin.js` and `<root>` must be
+ * `…/node_modules/@bridge_gpt/mcp-server`. Returns `null` for any other layout.
+ */
+export function persistentPackageRootOf(canonicalEntry) {
+    if (basename(canonicalEntry) !== HOOK_RUNTIME_ENTRY_FILENAME)
+        return null;
+    const buildDir = dirname(canonicalEntry);
+    if (basename(buildDir) !== "build")
+        return null;
+    const packageRoot = dirname(buildDir);
+    const segments = packageRoot.split(/[\\/]/).filter((s) => s.length > 0);
+    const [scope, name] = MCP_PACKAGE_NAME.split("/");
+    const n = segments.length;
+    if (n < 3)
+        return null;
+    if (segments[n - 1] !== name || segments[n - 2] !== scope || segments[n - 3] !== "node_modules") {
+        return null;
+    }
+    // A `.bin` shim is never a package root, and neither is anything nested in one.
+    if (segments.includes(".bin"))
+        return null;
+    return packageRoot;
+}
+/** Parse and validate the probe's single JSON line, or `null` when malformed. */
+export function parseHookRuntimeProbeOutput(stdout) {
+    const lines = stdout.split(/\r?\n/).filter((l) => l.trim().length > 0);
+    if (lines.length !== 1)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(lines[0]);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return null;
+    const p = parsed;
+    if (p.probe !== HOOK_RUNTIME_PROBE_MARKER)
+        return null;
+    const str = (v) => typeof v === "string" && v.length > 0 && v.length <= 64;
+    if (!str(p.node_version) || !str(p.node_modules_abi) || !str(p.native_module) || !str(p.failure_kind)) {
+        return null;
+    }
+    if (typeof p.native_loads !== "boolean")
+        return null;
+    const nativeVersion = p.native_module_version === null || p.native_module_version === undefined
+        ? null
+        : str(p.native_module_version) ? p.native_module_version : null;
+    const packageVersion = str(p.package_version) ? p.package_version : null;
+    return {
+        node_version: p.node_version,
+        node_modules_abi: p.node_modules_abi,
+        native_module: p.native_module,
+        native_module_version: nativeVersion,
+        native_loads: p.native_loads,
+        failure_kind: p.failure_kind,
+        package_version: packageVersion,
+    };
+}
+/**
+ * Qualify a candidate hook entry. Read-only and never throws: every boundary
+ * failure maps to a fixed classification.
+ */
+export function qualifyHookRuntime(candidateEntry, deps = {}) {
+    try {
+        return qualifyHookRuntimeUnsafe(candidateEntry, deps);
+    }
+    catch {
+        return unavailable("unknown");
+    }
+}
+function qualifyHookRuntimeUnsafe(candidateEntry, deps) {
+    const realpath = deps.realpath ?? defaultRealpath;
+    const isFile = deps.isFile ?? defaultIsFile;
+    const readText = deps.readText ?? defaultReadText;
+    const platform = deps.platform ?? process.platform;
+    const runProbe = deps.runProbe ?? runHookRuntimeProbe;
+    if (typeof candidateEntry !== "string" || candidateEntry.length === 0)
+        return unavailable("missing");
+    if (basename(candidateEntry) === "conductor-bin.js")
+        return unavailable("legacy-name");
+    if (isTransientNpxEntryPath(candidateEntry))
+        return unavailable("ephemeral-cache");
+    const canonical = realpath(candidateEntry);
+    if (canonical === null || !isFile(canonical))
+        return unavailable("missing");
+    // A symlink into the cache is still the cache.
+    if (isTransientNpxEntryPath(canonical))
+        return unavailable("ephemeral-cache");
+    if (basename(canonical) !== HOOK_RUNTIME_ENTRY_FILENAME)
+        return unavailable("unqualified-runtime");
+    const packageRoot = persistentPackageRootOf(canonical);
+    if (packageRoot === null)
+        return unavailable("unqualified-runtime");
+    const pkgText = readText(join(packageRoot, "package.json"));
+    if (pkgText === null)
+        return unavailable("missing");
+    let pkg;
+    try {
+        pkg = JSON.parse(pkgText);
+    }
+    catch {
+        return unavailable("unqualified-runtime");
+    }
+    if (pkg.name !== MCP_PACKAGE_NAME)
+        return unavailable("unqualified-runtime");
+    if (typeof pkg.version !== "string" || !isCompatibleHookPackageVersion(pkg.version)) {
+        return unavailable("unqualified-runtime");
+    }
+    const binMap = pkg.bin !== null && typeof pkg.bin === "object" ? pkg.bin : null;
+    const mapped = binMap?.[HOOK_RUNTIME_BIN_NAME];
+    if (typeof mapped !== "string")
+        return unavailable("unqualified-runtime");
+    const normalizedMapped = mapped.replace(/^\.\//, "").replace(/\\/g, "/");
+    if (normalizedMapped !== `build/${HOOK_RUNTIME_ENTRY_FILENAME}`)
+        return unavailable("unqualified-runtime");
+    if (!HOOK_RUNTIME_QUALIFIED_PLATFORMS.includes(platform))
+        return unavailable("unqualified-runtime");
+    // The stable launch path is the package-owned entry under the persistent
+    // prefix. An in-place `npm i -g` upgrade replaces the files beneath it, so a
+    // hook that embeds this path keeps working across supported upgrades.
+    const stableEntry = join(packageRoot, "build", HOOK_RUNTIME_ENTRY_FILENAME);
+    const outcome = runProbe(stableEntry);
+    if (outcome.kind === "spawn-failed") {
+        return unavailable(outcome.code === "ENOENT" ? "node-unavailable" : "unknown");
+    }
+    if (outcome.kind !== "ok")
+        return unavailable("unknown");
+    const evidence = parseHookRuntimeProbeOutput(outcome.stdout);
+    if (evidence === null)
+        return unavailable("unknown");
+    if (!evidence.native_loads)
+        return unavailable("native-unavailable");
+    if (!isQualifiedHookNodeVersion(evidence.node_version))
+        return unavailable("unqualified-runtime");
+    // The probe must be answering for the package we just read, not some other
+    // build the entry happens to import.
+    if (evidence.package_version !== null && evidence.package_version !== pkg.version) {
+        return unavailable("unknown");
+    }
+    return {
+        usable: true,
+        stable_entry: stableEntry,
+        canonical_entry: canonical,
+        package_name: MCP_PACKAGE_NAME,
+        package_version: pkg.version,
+        platform,
+        runtime: {
+            node_version: evidence.node_version,
+            node_modules_abi: evidence.node_modules_abi,
+            native_module: evidence.native_module,
+            native_module_version: evidence.native_module_version,
+            native_loads: evidence.native_loads,
+            failure_kind: evidence.failure_kind,
+        },
+    };
+}

package/build/conductor/merge-execution-contract.js

@@ -47,13 +47,38 @@ export const MERGE_WORKFLOW_IDENTIFIER = "epic-implementer-merge.yml";
 /** The top-level workflow key carrying the machine-readable contract version. */
 export const MERGE_WORKFLOW_VERSION_MARKER_KEY = "x-bridge-merge-contract-version";
 /**
- * The ONLY workflow contract version this CLI understands.
+ * The workflow contract version this CLI RENDERS and installs.
  *
- * Exact equality. A newer version is a workflow this build has never been taught
- * to reason about, so it is NOT eligible — see
- * {@link classifyMergeExecutionEligibility}.
+ * BAPI-1259 moved it from `1` to `2` (the integration-action job and the
+ * `operation` dispatch input). Whether an INSTALLED version is usable is
+ * answered by the two closed sets below — never by "at least". A newer version
+ * is a workflow this build has never been taught to reason about, so it is NOT
+ * eligible — see {@link classifyMergeExecutionEligibility}.
  */
-export const MERGE_WORKFLOW_EXPECTED_VERSION = 1;
+export const MERGE_WORKFLOW_EXPECTED_VERSION = 2;
+/**
+ * Installed contract versions a CHILD merge may be dispatched to. Mirrors
+ * `MERGE_WORKFLOW_CHILD_MERGE_COMPATIBLE_VERSIONS` in the Python contract.
+ * Version 1's child-merge job is the behavior version 2 keeps unchanged.
+ */
+export const MERGE_WORKFLOW_CHILD_MERGE_COMPATIBLE_VERSIONS = [1, 2];
+/**
+ * Installed contract versions an INTEGRATION action may be dispatched to.
+ * Mirrors `INTEGRATION_ACTION_WORKFLOW_VERSIONS` in the Python contract.
+ */
+export const INTEGRATION_ACTION_WORKFLOW_VERSIONS = [2];
+/** True when an installed marker may receive a child-merge dispatch. */
+export function mergeWorkflowVersionSupportsChildMerge(version) {
+    return (typeof version === "number" &&
+        Number.isInteger(version) &&
+        MERGE_WORKFLOW_CHILD_MERGE_COMPATIBLE_VERSIONS.includes(version));
+}
+/** True when an installed marker may receive an integration-action dispatch. */
+export function mergeWorkflowVersionSupportsIntegrationActions(version) {
+    return (typeof version === "number" &&
+        Number.isInteger(version) &&
+        INTEGRATION_ACTION_WORKFLOW_VERSIONS.includes(version));
+}
 /**
  * The single command that generates the merge workflow and opens its pull
  * request. Every refusal, remediation, and readiness line imports this constant.

package/build/conductor/merge-execution-eligibility.js

@@ -23,14 +23,15 @@
  * credentials or connectivity. Collapsing them sends half of all operators to do
  * work that changes nothing. `could_not_verify` is never treated as eligible.
  *
- * ## Exact version, always
+ * ## Known versions only, always
  *
- * Eligibility requires {@link MERGE_WORKFLOW_EXPECTED_VERSION} exactly. A NEWER
- * version is not eligible either: it is a workflow this build has never been
- * taught to reason about, and "newer is probably fine" is a guess about a merge
- * actuator.
+ * Eligibility requires membership in the closed set
+ * {@link MERGE_WORKFLOW_CHILD_MERGE_COMPATIBLE_VERSIONS} (BAPI-1259: version 1
+ * and version 2 both carry the unchanged child-merge job). A NEWER version is
+ * not eligible: it is a workflow this build has never been taught to reason
+ * about, and "newer is probably fine" is a guess about a merge actuator.
  */
-import { MERGE_WORKFLOW_EXPECTED_VERSION, MERGE_WORKFLOW_REMEDY_COMMAND, } from "./merge-execution-contract.js";
+import { MERGE_WORKFLOW_CHILD_MERGE_COMPATIBLE_VERSIONS, MERGE_WORKFLOW_REMEDY_COMMAND, mergeWorkflowVersionSupportsChildMerge, } from "./merge-execution-contract.js";
 /**
  * Remediation for a verdict that could not be established.
  *
@@ -107,10 +108,10 @@ export function classifyMergeExecutionEligibility(readiness) {
     if (!m.merge_workflow_enabled) {
         return ineligible("workflow_disabled", "the merge workflow is present but disabled");
     }
-    if (m.merge_workflow_version !== MERGE_WORKFLOW_EXPECTED_VERSION) {
+    if (!mergeWorkflowVersionSupportsChildMerge(m.merge_workflow_version)) {
         // A newer version lands here too — see the module docstring.
         return ineligible("workflow_version_mismatch", `merge workflow version ${m.merge_workflow_version ?? "unset"} ` +
-            `(expected ${MERGE_WORKFLOW_EXPECTED_VERSION})`);
+            `(expected one of ${MERGE_WORKFLOW_CHILD_MERGE_COMPATIBLE_VERSIONS.join(", ")})`);
     }
     if (!gh.actions_write) {
         return ineligible("app_actions_write_denied", `the GitHub App holds actions: ${gh.actions_permission_level}`);
@@ -123,7 +124,7 @@ export function classifyMergeExecutionEligibility(readiness) {
     }
     return {
         status: "eligible",
-        detail: `merge workflow present, enabled, version ${MERGE_WORKFLOW_EXPECTED_VERSION}; ` +
+        detail: `merge workflow present, enabled, version ${m.merge_workflow_version}; ` +
             "App actions: write, workflow token write authority, workflow actor admitted",
     };
 }

package/build/conductor/readiness-sections.js

@@ -38,7 +38,7 @@ import { MCP_PACKAGE_NAME } from "../mcp-identity.js";
 import { CLAUDE_REVIEW_WORKFLOW_DRIFT_REMEDIATION, summarizeClaudeReviewWorkflowDrift, } from "../claude-review-workflow-drift.js";
 import { describeNativeLedgerAvailability, GH_ACTIONS_MERGE_AUTH_REMEDIATION, GH_ACTIONS_MERGE_SKIPPED_DETAIL, GH_ACTIONS_MERGE_UNOBSERVABLE_REMEDIATION, } from "./doctor.js";
 import { classifyMergeExecutionEligibility, MERGE_EXECUTION_UNVERIFIABLE_REMEDIATION, } from "./merge-execution-eligibility.js";
-import { MERGE_WORKFLOW_EXPECTED_VERSION, MERGE_WORKFLOW_PATH, } from "./merge-execution-contract.js";
+import { MERGE_WORKFLOW_CHILD_MERGE_COMPATIBLE_VERSIONS, MERGE_WORKFLOW_PATH, mergeWorkflowVersionSupportsChildMerge, } from "./merge-execution-contract.js";
 import { classifyDatabaseMigration, classifySingleTransitionAuthority, classifyWorkerPresent, } from "./bring-up-facts.js";
 /** Operator runbook pointer surfaced beside the executor gap. */
 export const CONDUCTOR_OPERATOR_RUNBOOK_POINTER = "docs/claude/epic-implementer-v2-operator-runbook.md";
@@ -80,6 +80,88 @@ export const EXECUTOR_INSTALL_SERVICE_REMEDIATION = "generate a persistent unit
 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}.`;
 // ---------------------------------------------------------------------------
+// BAPI-1254 — the ONE required-check presentation
+// ---------------------------------------------------------------------------
+/**
+ * Operator-hold sentence shared by every non-verified outcome. It states what an
+ * operator must do; it does not claim this report blocks anything — activation
+ * and dispatch enforcement belong to a separate slice.
+ */
+const REQUIRED_CHECKS_OPERATOR_HOLD = "hold new unattended epic work until this is resolved";
+/** Fixed, secret-free copy for each outcome. Names no check, branch, or SHA. */
+export const REQUIRED_CHECKS_PRESENTATION_COPY = {
+    verified: {
+        detail: "Verified — every configured required check is produced by the lane workflows",
+    },
+    unknown_name: {
+        detail: "Configuration mismatch confirmed — a configured required check conflicts with the " +
+            `current lane producer contract; ${REQUIRED_CHECKS_OPERATOR_HOLD}`,
+        remediation: "repair the project-default required-check configuration so it names the check the " +
+            "lane workflow emits (see the operator runbook's patch-policy section for active runs).",
+    },
+    unverifiable: {
+        detail: "Could not verify — the configured required checks could not be matched to an " +
+            `authoritative producer; ${REQUIRED_CHECKS_OPERATOR_HOLD}`,
+        remediation: "restore required-check verification (a readable default branch with static lane " +
+            "workflows and a current Bridge API), or correct the required-check configuration.",
+    },
+    empty: {
+        detail: "Could not verify — the required-check list is EMPTY, which is unsafe: the done gate " +
+            `would pass unconditionally; ${REQUIRED_CHECKS_OPERATOR_HOLD}`,
+        remediation: "configure a non-empty required-check list naming the checks the lane workflows emit.",
+    },
+    olderServer: {
+        detail: "Could not verify — this Bridge API does not report required-check verification; " +
+            REQUIRED_CHECKS_OPERATOR_HOLD,
+        remediation: "upgrade the Bridge API deploy so it verifies required checks, or correct the " +
+            "required-check configuration; its state is unknown here, not healthy.",
+    },
+};
+/**
+ * Map the validated supervisor facts onto one required-check presentation.
+ *
+ * PURE, and the only place either renderer decides this row: the CLI descriptor
+ * and the install-time section both call it, so they cannot drift and neither
+ * performs a second producer verification. Only the server's `verified` verdict
+ * is satisfied. A nonempty count is never proof, an older server's absent group
+ * is `unverifiable`, and an empty list stays unsafe whatever else is reported.
+ * No remediation suggests disabling required checks.
+ */
+export function presentRequiredChecks(supervisor) {
+    const verdict = supervisor.required_checks_verification ?? null;
+    if (supervisor.required_checks_empty) {
+        return { outcome: "unverifiable", satisfied: false, ...REQUIRED_CHECKS_PRESENTATION_COPY.empty };
+    }
+    if (verdict === null) {
+        return {
+            outcome: "unverifiable",
+            satisfied: false,
+            ...REQUIRED_CHECKS_PRESENTATION_COPY.olderServer,
+        };
+    }
+    if (verdict === "verified") {
+        const fresh = supervisor.required_checks_evidence_fresh === true ? ", fresh evidence" : "";
+        return {
+            outcome: "verified",
+            satisfied: true,
+            detail: `${REQUIRED_CHECKS_PRESENTATION_COPY.verified.detail} ` +
+                `(${supervisor.required_checks_count} required check(s) configured${fresh})`,
+        };
+    }
+    if (verdict === "unknown_name") {
+        return {
+            outcome: "unknown_name",
+            satisfied: false,
+            ...REQUIRED_CHECKS_PRESENTATION_COPY.unknown_name,
+        };
+    }
+    return {
+        outcome: "unverifiable",
+        satisfied: false,
+        ...REQUIRED_CHECKS_PRESENTATION_COPY.unverifiable,
+    };
+}
+// ---------------------------------------------------------------------------
 // Section builders
 // ---------------------------------------------------------------------------
 export function supervisorSection(readiness) {
@@ -109,20 +191,20 @@ export function supervisorSection(readiness) {
     // 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-1254: the verdict comes from the shared `presentRequiredChecks`, the
+    // same mapping the CLI descriptor uses. Only `verified` is `ok`; a confirmed
+    // mismatch and could-not-verify are both `degraded`, never `fatal`.
+    const requiredChecks = presentRequiredChecks(s);
+    sections.push({
+        id: "supervisor-required-checks",
+        label: "Supervisor required CI checks",
+        status: requiredChecks.satisfied ? "ok" : "degraded",
+        detail: requiredChecks.detail,
+        ...(requiredChecks.remediation === undefined
+            ? {}
+            : { remediation: requiredChecks.remediation }),
+    });
     // BAPI-694 (R5) — its OWN section, and WARN-ONLY.
     //
     // `degraded`, never `fatal`: a divergence between the code_review gate's
@@ -292,7 +374,8 @@ export function mergeExecutionSections(readiness) {
                 ? `\`${MERGE_WORKFLOW_PATH}\` present`
                 : `not eligible: \`${MERGE_WORKFLOW_PATH}\` is absent`),
         fact("merge-execution-workflow-enabled", "Merge workflow enabled", m.merge_workflow_enabled, m.merge_workflow_enabled ? "enabled" : "not eligible: disabled or unknown"),
-        fact("merge-execution-workflow-version", "Merge workflow version", m.merge_workflow_version === MERGE_WORKFLOW_EXPECTED_VERSION, `\`${m.merge_workflow_version ?? "unset"}\` (expected \`${MERGE_WORKFLOW_EXPECTED_VERSION}\`)`),
+        fact("merge-execution-workflow-version", "Merge workflow version", mergeWorkflowVersionSupportsChildMerge(m.merge_workflow_version), `\`${m.merge_workflow_version ?? "unset"}\` (expected one of ` +
+            `\`${MERGE_WORKFLOW_CHILD_MERGE_COMPATIBLE_VERSIONS.join(", ")}\`)`),
         fact("merge-execution-app-actions-write", "GitHub App `actions: write`", readiness.github.actions_write, readiness.github.actions_probe_succeeded
             ? `actions: \`${readiness.github.actions_permission_level}\``
             : "could not verify: the App permission could not be checked"),
@@ -688,12 +771,13 @@ export function conductorHookTargetsSection(legacyConductor, conductorContext) {
             detail: "advisory — not a git worktree, so no managed conductor hooks apply",
         };
     }
+    // BAPI-1290: the shared per-hook `usable` verdict — a recognized command, an
+    // executable hook, and a qualified persistent runtime whose Node and native
+    // binding load. A file that merely exists is not delivery, and a hook without
+    // that verdict (an older or partial report) is unknown, never usable.
     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);
+        return hook !== undefined && hook.usable === true;
     };
     const rendered = MANAGED_HOOK_NAMES.map((name) => `${name}=${usable(name)}`).join(", ");
     const allUsable = MANAGED_HOOK_NAMES.every((name) => usable(name));