@bridge_gpt/mcp-server 0.2.62 → 0.2.66

package/build/conductor/guided-repair.js

@@ -0,0 +1,323 @@
+/**
+ * BAPI-1333 — guided operator repairs: the displayed binding and its local
+ * recovery reference.
+ *
+ * ExplainRun renders a guided command with one `--binding v1.<base64url>` token.
+ * The token names the verb, the run, and the bounded subject the command was
+ * rendered against (a run repair revision plus its control, block, or policy
+ * subject; a scope episode; or a ticket version and head). This module:
+ *
+ * - decodes and strictly validates that token (identifiers only, closed keys);
+ * - turns it into the typed `guard` the server enforces in its guarded write;
+ * - persists a small local reference BEFORE the first POST — the request id, the
+ *   binding, and digests of the binding and the payload — so a transport retry
+ *   or a restarted CLI process re-sends the SAME request instead of re-reading
+ *   the run and approving whatever subject exists now.
+ *
+ * The stored reference never holds a payload value: a policy patch or a driver
+ * context is represented only by its SHA-256 digest. Nothing here performs HTTP.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { canonicalSha256, clearRecoveryReferenceFile, readRecoveryReferenceFile, writeRecoveryReferenceFile, } from "./epic-child-continuation.js";
+export const GUIDED_BINDING_TOKEN_PREFIX = "v1.";
+export const GUIDED_REPAIR_REFERENCE_NAMESPACE = "epic-guided-repairs";
+/** The fixed message when the reference cannot be stored; nothing is sent. */
+export const GUIDED_REFERENCE_STORE_FAILED_MESSAGE = "could not store the local recovery reference, so the request was not sent";
+/** A rerun of the same displayed command with a DIFFERENT payload. */
+export const GUIDED_PAYLOAD_CONFLICT_MESSAGE = "a different request was already issued for this displayed command; nothing " +
+    "was sent. Re-read the run explanation before choosing another action";
+export const GUIDED_REPAIR_VERBS = [
+    "resume-run",
+    "patch-policy",
+    "scope-reparse",
+    "scope-catch-up",
+    "dispatch-remediation",
+];
+/** A malformed or mismatched binding. The message never echoes the token. */
+export class GuidedBindingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GuidedBindingError";
+    }
+}
+const TOKEN_RE = /^[a-z][a-z0-9_]{0,63}$/;
+const SHA_RE = /^[0-9a-f]{40}$/;
+const REQUEST_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const FINGERPRINT_RE = /^[0-9a-f]{64}$/;
+/** Keys each verb's token may carry, beyond `v`, `verb`, and `epic_run_id`. */
+const ALLOWED_KEYS = {
+    "resume-run": [
+        "repair_revision",
+        "subject",
+        "control_state",
+        "control_generation",
+        "block_reason",
+    ],
+    "patch-policy": ["repair_revision", "subject"],
+    "scope-reparse": ["scope_id", "lifecycle_state", "required_commit_sha"],
+    "scope-catch-up": ["scope_id", "lifecycle_state", "required_commit_sha"],
+    "dispatch-remediation": ["ticket_key", "expected_row_version", "expected_head_sha"],
+};
+function invalid() {
+    return new GuidedBindingError("--binding is not a valid guided-repair binding; nothing was sent. Copy the " +
+        "command exactly as the run explanation rendered it.");
+}
+function nonNegativeInt(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+        throw invalid();
+    return value;
+}
+function boundedString(value, max) {
+    if (typeof value !== "string" || value.length === 0 || value.length > max)
+        throw invalid();
+    return value;
+}
+function optionalSha(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "string" || !SHA_RE.test(value))
+        throw invalid();
+    return value;
+}
+function decodeBase64Url(text) {
+    if (!/^[A-Za-z0-9_-]+$/.test(text) || text.length > 2048)
+        throw invalid();
+    return Buffer.from(text, "base64url").toString("utf8");
+}
+/** Decode and strictly validate a `--binding` token. Throws {@link GuidedBindingError}. */
+export function decodeGuidedBinding(token) {
+    if (typeof token !== "string" || !token.startsWith(GUIDED_BINDING_TOKEN_PREFIX)) {
+        throw invalid();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(decodeBase64Url(token.slice(GUIDED_BINDING_TOKEN_PREFIX.length)));
+    }
+    catch (err) {
+        if (err instanceof GuidedBindingError)
+            throw err;
+        throw invalid();
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw invalid();
+    const raw = parsed;
+    if (raw.v !== 1)
+        throw invalid();
+    const verb = raw.verb;
+    if (typeof verb !== "string" || !GUIDED_REPAIR_VERBS.includes(verb)) {
+        throw invalid();
+    }
+    const guidedVerb = verb;
+    const allowed = new Set(["v", "verb", "epic_run_id", ...ALLOWED_KEYS[guidedVerb]]);
+    for (const key of Object.keys(raw)) {
+        if (!allowed.has(key))
+            throw invalid();
+    }
+    const binding = {
+        verb: guidedVerb,
+        epicRunId: boundedString(raw.epic_run_id, 200),
+    };
+    if (guidedVerb === "resume-run" || guidedVerb === "patch-policy") {
+        binding.repairRevision = nonNegativeInt(raw.repair_revision);
+        const subject = raw.subject;
+        if (guidedVerb === "patch-policy") {
+            if (subject !== "policy")
+                throw invalid();
+            binding.subject = "policy";
+        }
+        else if (subject === "control") {
+            if (raw.control_state !== "paused" && raw.control_state !== "quarantined")
+                throw invalid();
+            const generation = nonNegativeInt(raw.control_generation);
+            if (generation < 1 || raw.block_reason !== undefined)
+                throw invalid();
+            binding.subject = "control";
+            binding.controlState = raw.control_state;
+            binding.controlGeneration = generation;
+        }
+        else if (subject === "integration_block") {
+            const reason = raw.block_reason;
+            if (typeof reason !== "string" || !TOKEN_RE.test(reason))
+                throw invalid();
+            if (raw.control_state !== undefined || raw.control_generation !== undefined)
+                throw invalid();
+            binding.subject = "integration_block";
+            binding.blockReason = reason;
+        }
+        else {
+            throw invalid();
+        }
+    }
+    else if (guidedVerb === "dispatch-remediation") {
+        binding.ticketKey = boundedString(raw.ticket_key, 64);
+        binding.expectedRowVersion = nonNegativeInt(raw.expected_row_version);
+        binding.expectedHeadSha = optionalSha(raw.expected_head_sha);
+    }
+    else {
+        binding.scopeId = boundedString(raw.scope_id, 200);
+        const lifecycle = raw.lifecycle_state;
+        if (typeof lifecycle !== "string" || !TOKEN_RE.test(lifecycle))
+            throw invalid();
+        binding.lifecycleState = lifecycle;
+        binding.requiredCommitSha = optionalSha(raw.required_commit_sha);
+    }
+    return binding;
+}
+/** The canonical, snake_case identity of a binding (what its digest covers). */
+export function bindingIdentity(binding) {
+    const out = { verb: binding.verb, epic_run_id: binding.epicRunId };
+    const pairs = [
+        ["repair_revision", binding.repairRevision],
+        ["subject", binding.subject],
+        ["control_state", binding.controlState],
+        ["control_generation", binding.controlGeneration],
+        ["block_reason", binding.blockReason],
+        ["scope_id", binding.scopeId],
+        ["lifecycle_state", binding.lifecycleState],
+        ["required_commit_sha", binding.requiredCommitSha],
+        ["ticket_key", binding.ticketKey],
+        ["expected_row_version", binding.expectedRowVersion],
+        ["expected_head_sha", binding.expectedHeadSha],
+    ];
+    for (const [key, value] of pairs) {
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+/** The typed body `guard` for this binding and request id. */
+export function guardForBinding(binding, requestId) {
+    if (binding.verb === "resume-run" || binding.verb === "patch-policy") {
+        const guard = {
+            request_id: requestId,
+            epic_run_id: binding.epicRunId,
+            repair_revision: binding.repairRevision ?? 0,
+            subject: binding.subject ?? "policy",
+        };
+        if (binding.controlState !== undefined)
+            guard.control_state = binding.controlState;
+        if (binding.controlGeneration !== undefined)
+            guard.control_generation = binding.controlGeneration;
+        if (binding.blockReason !== undefined)
+            guard.block_reason = binding.blockReason;
+        return guard;
+    }
+    if (binding.verb === "dispatch-remediation") {
+        return {
+            request_id: requestId,
+            epic_run_id: binding.epicRunId,
+            expected_row_version: binding.expectedRowVersion ?? 0,
+            expected_head_sha: binding.expectedHeadSha ?? null,
+        };
+    }
+    return {
+        request_id: requestId,
+        epic_run_id: binding.epicRunId,
+        lifecycle_state: binding.lifecycleState ?? "",
+        required_commit_sha: binding.requiredCommitSha ?? null,
+    };
+}
+function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+/**
+ * SHA-256 of a request payload in canonical form (sorted keys; any JSON number).
+ * Only this digest is persisted, so a patch or context never reaches the disk.
+ */
+export function guidedPayloadDigest(payload) {
+    return createHash("sha256").update(stableStringify(payload), "utf8").digest("hex");
+}
+function referenceTarget(binding) {
+    return binding.ticketKey ?? binding.scopeId ?? "run";
+}
+function referenceKey(binding) {
+    return { epicRunId: binding.epicRunId, ticketKey: `${binding.verb}:${referenceTarget(binding)}` };
+}
+function referenceFingerprint(ref) {
+    return canonicalSha256({
+        v: 1,
+        verb: ref.verb,
+        epic_run_id: ref.epicRunId,
+        target: ref.target,
+        request_id: ref.requestId,
+        binding_digest: ref.bindingDigest,
+        payload_digest: ref.payloadDigest,
+    });
+}
+function parseReference(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const ref = raw;
+    if (ref.version !== 1)
+        return null;
+    if (typeof ref.verb !== "string" || !GUIDED_REPAIR_VERBS.includes(ref.verb)) {
+        return null;
+    }
+    for (const key of ["epicRunId", "target", "createdAt"]) {
+        if (typeof ref[key] !== "string" || ref[key].length === 0)
+            return null;
+    }
+    if (typeof ref.requestId !== "string" || !REQUEST_ID_RE.test(ref.requestId))
+        return null;
+    for (const key of ["bindingDigest", "payloadDigest", "fingerprint"]) {
+        if (typeof ref[key] !== "string" || !FINGERPRINT_RE.test(ref[key]))
+            return null;
+    }
+    const parsed = raw;
+    // A reference whose fingerprint no longer matches its own identity was
+    // tampered with or truncated; it never authorizes a re-send.
+    return referenceFingerprint(parsed) === parsed.fingerprint ? parsed : null;
+}
+/**
+ * Reuse the persisted request for this exact binding and payload, or mint and
+ * durably persist a new one BEFORE anything is sent.
+ *
+ * - Same binding, same payload → the SAME request id (transport retry, restart).
+ * - Same binding, different payload → refused locally; nothing is sent.
+ * - Different binding (a newer rendered command) → a new request replaces it.
+ */
+export async function prepareGuidedRequest(binding, payloadDigest, deps = {}) {
+    const key = referenceKey(binding);
+    const bindingDigest = canonicalSha256(bindingIdentity(binding));
+    const existing = parseReference(await readRecoveryReferenceFile(GUIDED_REPAIR_REFERENCE_NAMESPACE, key, deps.store));
+    if (existing !== null && existing.bindingDigest === bindingDigest) {
+        if (existing.payloadDigest !== payloadDigest)
+            return { kind: "payload_conflict" };
+        return { kind: "ready", requestId: existing.requestId, referenceReused: true };
+    }
+    const requestId = (deps.newRequestId ?? randomUUID)();
+    const base = {
+        version: 1,
+        verb: binding.verb,
+        epicRunId: binding.epicRunId,
+        target: referenceTarget(binding),
+        requestId,
+        bindingDigest,
+        payloadDigest,
+    };
+    const reference = {
+        ...base,
+        createdAt: (deps.now ?? (() => new Date()))().toISOString(),
+        fingerprint: referenceFingerprint(base),
+    };
+    try {
+        await writeRecoveryReferenceFile(GUIDED_REPAIR_REFERENCE_NAMESPACE, key, reference, deps.store);
+    }
+    catch {
+        return { kind: "store_failed" };
+    }
+    return { kind: "ready", requestId, referenceReused: false };
+}
+/** Remove the reference once the server returned a definitive answer. Never throws. */
+export async function clearGuidedReference(binding, deps = {}) {
+    await clearRecoveryReferenceFile(GUIDED_REPAIR_REFERENCE_NAMESPACE, referenceKey(binding), deps.store);
+}

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,
+        },
+    };
+}