@bridge_gpt/mcp-server 0.2.62 → 0.2.65

package/build/conductor/git-hooks.js

@@ -8,11 +8,25 @@
  * surrounding user hook content is preserved, and anything that looks binary or
  * unsafe to merge is left untouched with a warning. Missing hooks are a degraded
  * OPTIONAL capability — never a fatal error.
+ *
+ * BAPI-1290 adds LIFETIME to BAPI-772's existence check. A hook embeds one
+ * absolute entry path and runs it for as long as the hook file lives, so the
+ * installer now embeds only a QUALIFIED persistent package-owned entry (see
+ * `hook-runtime-qualification.ts`) and refuses a prunable `npx` cache path before
+ * touching anything. Both hook files are planned before either is published, each
+ * is published through a same-directory temporary file and an atomic rename, and a
+ * two-file update that stops half-way is reported as partial rather than complete.
  */
-import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync, } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeSync, } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { MCP_PACKAGE_NAME } from "../mcp-identity.js";
+import { isTransientNpxEntryPath } from "../mcp-server-invocation.js";
+import { posixShellQuote } from "../platform-escaping.js";
 import { runGitCommand } from "./git-inspection.js";
+import { describeHookRuntimeClassification, qualifyHookRuntime, } from "./hook-runtime-qualification.js";
 /** Markers delimiting the conductor-managed block inside a hook file. */
 export const BRIDGE_CONDUCTOR_HOOK_START = "# >>> BRIDGE_CONDUCTOR_HOOK_START >>>";
 export const BRIDGE_CONDUCTOR_HOOK_END = "# <<< BRIDGE_CONDUCTOR_HOOK_END <<<";
@@ -52,27 +66,55 @@ export const CONDUCTOR_HOOK_BIN_UNRESOLVED_REASON = `no usable ${CONDUCTOR_BIN_F
     "(searched: the sibling bundle layout, the parent TypeScript-emit layout, and " +
     `the invocation target when it is named ${CONDUCTOR_BIN_FILENAME}). ` +
     "Reinstall or rebuild the package so a conductor binary ships beside the executing module.";
+/** Bounded wall-clock for the installation-time `npm root -g` lookup. */
+export const NPM_GLOBAL_ROOT_TIMEOUT_MS = 10_000;
+/**
+ * Default `npm root -g`: bounded, offline, output capped, stderr discarded.
+ * Returns `null` on any failure, timeout, or output that is not one absolute path.
+ */
+export function defaultNpmGlobalRoot() {
+    if (process.platform === "win32")
+        return null;
+    try {
+        const result = spawnSync("npm", ["root", "-g"], {
+            encoding: "utf-8",
+            timeout: NPM_GLOBAL_ROOT_TIMEOUT_MS,
+            maxBuffer: 8 * 1024,
+            stdio: ["ignore", "pipe", "ignore"],
+            env: { ...process.env, npm_config_offline: "true", npm_config_update_notifier: "false" },
+        });
+        if (result.error || result.status !== 0)
+            return null;
+        const lines = (result.stdout ?? "").split(/\r?\n/).filter((l) => l.trim().length > 0);
+        if (lines.length !== 1)
+            return null;
+        const root = lines[0].trim();
+        return isAbsolute(root) ? root : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
- * Absolute, canonical path of the `epic-implementer-bin.js` belonging to the
- * artifact that is currently executing (BAPI-772, the BAPI-768 pattern applied
- * to hooks; renamed from `conductor-bin.js` by S4/BAPI-1080).
+ * Resolve the QUALIFIED persistent hook entry for the artifact that is
+ * executing (BAPI-772 probing, BAPI-1290 lifetime qualification).
  *
  * ## Why this cannot be path arithmetic
  *
- * The old implementation hard-coded ONE layout — `dirname(import.meta.url)/../
- * conductor-bin.js`, the tsc emit — and returned it unverified. In the shipped
- * esbuild bundle this module IS `build/epic-implementer-bin.js`, so the directory hop
- * landed on `<pkg>/epic-implementer-bin.js`, a path that has never existed. Every hook
- * installed from the published package embedded that dead path, and because hook
- * bodies discard output and end in `|| true`, each commit ENOENTed in silence
- * while `epic-implementer doctor` still called the hooks healthy.
+ * The old implementation hard-coded ONE layout and returned it unverified; every
+ * hook installed from the published package embedded a path that never existed.
+ * So candidates are drawn only from the executing module's own URL and Node's
+ * actual invocation target — never `process.cwd()` or an assumed package root —
+ * and each is canonicalized and must stat as a regular file.
+ *
+ * ## Why existence is not enough
  *
- * So this resolver PROBES. Candidates are drawn only from the executing module's
- * own URL and Node's actual invocation target — never `process.cwd()` or an
- * assumed package root, which could point a hook at a *different build* than the
- * one the operator installed from. Every candidate is canonicalized through
- * `realpath` (which also collapses `..` segments and rejects a dangling symlink)
- * and must stat as a regular file before it can be returned.
+ * An `npx` invocation executes from `~/.npm/_npx/<hash>/…`, which ordinary cache
+ * cleanup deletes. A hook that embeds that path dies with the cache, silently.
+ * So the found candidate is QUALIFIED: it must be a persistent package-owned
+ * entry whose `node` and native binding actually work. An `_npx` caller may
+ * instead select an already-installed persistent global package (located with a
+ * bounded offline `npm root -g`); otherwise it is refused before any mutation.
  */
 export function resolveConductorHookBin(overrides = {}) {
     const deps = {
@@ -80,7 +122,44 @@ export function resolveConductorHookBin(overrides = {}) {
         argv1: overrides.argv1 ?? process.argv[1],
         realpath: overrides.realpath ?? defaultRealpath,
         isFile: overrides.isFile ?? defaultIsFile,
+        qualify: overrides.qualify ?? ((entry) => qualifyHookRuntime(entry)),
+        npmGlobalRoot: overrides.npmGlobalRoot ?? defaultNpmGlobalRoot,
     };
+    const found = findExecutingHookBinCandidate(deps);
+    if (found === null) {
+        return { ok: false, reason: CONDUCTOR_HOOK_BIN_UNRESOLVED_REASON, classification: "missing" };
+    }
+    if (isTransientNpxEntryPath(found)) {
+        // The executing artifact is in the prunable npx cache. It may hand the hook
+        // to an ALREADY-installed persistent package, never to itself.
+        let root;
+        try {
+            root = deps.npmGlobalRoot();
+        }
+        catch {
+            root = null;
+        }
+        if (root === null)
+            return refusal("ephemeral-cache");
+        const persistent = join(root, ...MCP_PACKAGE_NAME.split("/"), "build", CONDUCTOR_BIN_FILENAME);
+        const qualification = safeQualify(deps.qualify, persistent);
+        if (!qualification.usable) {
+            // A missing or cache-backed global install means "install persistently",
+            // which is what the ephemeral-cache action says. Any other failure names
+            // what is wrong with the global install that WAS found.
+            return refusal(qualification.classification === "missing" || qualification.classification === "ephemeral-cache"
+                ? "ephemeral-cache"
+                : qualification.classification);
+        }
+        return qualifiedResolution(qualification);
+    }
+    const qualification = safeQualify(deps.qualify, found);
+    if (!qualification.usable)
+        return refusal(qualification.classification);
+    return qualifiedResolution(qualification);
+}
+/** First canonical regular-file candidate for the executing artifact, or `null`. */
+function findExecutingHookBinCandidate(deps) {
     const moduleFile = moduleFilePath(deps.moduleUrl);
     const candidates = [];
     if (moduleFile !== null) {
@@ -94,7 +173,8 @@ export function resolveConductorHookBin(overrides = {}) {
     // Last resort, and only ever a validated one: a packaged install launches
     // through a `node_modules/.bin` symlink. Accepted only when the invocation
     // target is exactly the epic-implementer bin — `index.js` or
-    // `epic-implementer-bin.js.bak` must never become a hook target.
+    // `epic-implementer-bin.js.bak` must never become a hook target. The symlink
+    // is canonicalized below, so a `.bin` shim is never itself embedded.
     if (typeof deps.argv1 === "string" && deps.argv1.length > 0) {
         if (basename(deps.argv1) === CONDUCTOR_BIN_FILENAME)
             candidates.push(deps.argv1);
@@ -102,14 +182,8 @@ export function resolveConductorHookBin(overrides = {}) {
     const seen = new Set();
     for (const candidate of candidates) {
         // Canonicalize BEFORE probing so duplicates that differ only by symlink or
-        // `..` segment collapse, and a written hook can only ever embed a canonical
-        // path to an existing file.
-        //
-        // The whole loop is exception-contained: this resolver's contract is that it
-        // returns a discriminated result and NEVER throws, and that has to hold for
-        // an injected boundary too — otherwise a filesystem error (whose message can
-        // carry a home-dir path or credential) escapes as a raw exception and defeats
-        // the sanitized `reason` this function exists to produce.
+        // `..` segment collapse. Exception-contained: an injected boundary that
+        // throws must not escape as a raw (possibly path-bearing) exception.
         let canonical;
         try {
             canonical = deps.realpath(candidate);
@@ -124,13 +198,32 @@ export function resolveConductorHookBin(overrides = {}) {
         seen.add(canonical);
         try {
             if (deps.isFile(canonical))
-                return { ok: true, path: canonical };
+                return canonical;
         }
         catch {
             continue;
         }
     }
-    return { ok: false, reason: CONDUCTOR_HOOK_BIN_UNRESOLVED_REASON };
+    return null;
+}
+function safeQualify(qualify, entry) {
+    try {
+        return qualify(entry);
+    }
+    catch {
+        return { usable: false, classification: "unknown", reason: describeHookRuntimeClassification("unknown") };
+    }
+}
+function refusal(classification) {
+    return { ok: false, classification, reason: describeHookRuntimeClassification(classification) };
+}
+function qualifiedResolution(qualification) {
+    return {
+        ok: true,
+        path: qualification.stable_entry,
+        canonical_path: qualification.canonical_entry,
+        qualification,
+    };
 }
 /** `file://` URL → filesystem path, or `null` when the URL is unusable. */
 function moduleFilePath(moduleUrl) {
@@ -160,31 +253,43 @@ function defaultIsFile(filePath) {
 function wrapManagedBlock(body) {
     return [BRIDGE_CONDUCTOR_HOOK_START, body, BRIDGE_CONDUCTOR_HOOK_END].join("\n");
 }
+/** Comment line every generated managed block carries. */
+const MANAGED_HOOK_COMMENT = "# Managed by Bridge conductor (BAPI-395). Local, unversioned, opportunistic, bypassable.";
 /**
  * Build the managed `post-commit` snippet: launches
- * `node <conductor-bin> git-hook post-commit` fully detached in the background,
+ * `node '<entry>' git-hook post-commit` fully detached in the background,
  * redirecting all output away from the user's git workflow. Failures are tolerated
- * (`|| true`) so the hook never returns non-zero.
+ * (`|| true`) so the hook never returns non-zero. The entry is a single literal
+ * POSIX-quoted argument (BAPI-1290), so spaces and shell metacharacters in the
+ * install prefix are never interpreted.
  */
 export function buildPostCommitHookSnippet(conductorBin) {
     const body = [
-        "# Managed by Bridge conductor (BAPI-395). Local, unversioned, opportunistic, bypassable.",
-        `( node ${JSON.stringify(conductorBin)} git-hook post-commit >/dev/null 2>&1 & ) || true`,
+        MANAGED_HOOK_COMMENT,
+        `( node ${posixShellQuote(conductorBin)} git-hook post-commit >/dev/null 2>&1 & ) || true`,
     ].join("\n");
     return wrapManagedBlock(body);
 }
 /**
  * Build the managed `reference-transaction` snippet: captures stdin to a temp
  * file (the ref updates), then launches
- * `node <conductor-bin> git-hook reference-transaction --phase "$1" --stdin-file <tmp>`
- * detached in the background, redirecting output away from the user's workflow.
+ * `node '<entry>' git-hook reference-transaction --phase "$1" --stdin-file <tmp>`
+ * detached in the background. The temp file is removed INSIDE the detached
+ * subshell after Node exits (BAPI-1290), so it is cleaned up even when `node`, the
+ * entry, or the native binding is unavailable — the producer's own cleanup only
+ * runs when it starts.
+ *
+ * The output redirect sits on the WHOLE backgrounded subshell, not just `node`.
+ * Git runs hooks with stdout sent to its stderr; a background subshell that kept
+ * those descriptors open would make any caller reading git's stderr to EOF
+ * (captured `git` subprocesses, IDEs, agent shells) wait for the producer.
  */
 export function buildReferenceTransactionHookSnippet(conductorBin) {
     const body = [
-        "# Managed by Bridge conductor (BAPI-395). Local, unversioned, opportunistic, bypassable.",
+        MANAGED_HOOK_COMMENT,
         '__bridge_tmp="$(mktemp 2>/dev/null || echo "/tmp/bridge-conductor-refs.$$")"',
         'cat > "$__bridge_tmp"',
-        `( node ${JSON.stringify(conductorBin)} git-hook reference-transaction --phase "$1" --stdin-file "$__bridge_tmp" >/dev/null 2>&1 & ) || true`,
+        `( ( node ${posixShellQuote(conductorBin)} git-hook reference-transaction --phase "$1" --stdin-file "$__bridge_tmp"; rm -f "$__bridge_tmp" ) >/dev/null 2>&1 & ) || true`,
     ].join("\n");
     return wrapManagedBlock(body);
 }
@@ -225,45 +330,118 @@ export function mergeManagedHookSnippet(existing, managedBlock) {
 }
 /** Stable discriminator for an install that never touched the filesystem. */
 export const CONDUCTOR_BIN_UNRESOLVED_ERROR = "CONDUCTOR_BIN_UNRESOLVED";
+/**
+ * Stable discriminator for an install refused while PLANNING the two edits: one
+ * hook is unreadable, symlinked, not a regular file, or unsafe to merge. Nothing
+ * was created, written, or chmodded for either hook.
+ */
+export const GIT_HOOKS_PLAN_REFUSED_ERROR = "GIT_HOOKS_PLAN_REFUSED";
 function snippetForHook(name, conductorBin) {
     return name === "post-commit"
         ? buildPostCommitHookSnippet(conductorBin)
         : buildReferenceTransactionHookSnippet(conductorBin);
 }
 /**
- * Re-validate a resolution before it can reach a hook body. A success produced
- * by an injected {@link GitHooksDeps.resolveBin} seam goes through the same
- * realpath + regular-file rules the production resolver applies, so the seam can
- * substitute a fixture binary but can never bypass validation.
+ * Re-qualify a candidate before it can reach a hook body. A success produced by
+ * an injected {@link GitHooksDeps.resolveBin} seam goes through the same runtime
+ * qualification the production resolver applies, so the seam can substitute a
+ * fixture candidate but can never authorize a merely-existing file, an ephemeral
+ * cache path, or an unverifiable runtime.
  */
-function validateResolvedBin(resolution) {
-    if (!resolution.ok)
-        return resolution;
-    const canonical = defaultRealpath(resolution.path);
-    if (canonical === null || !defaultIsFile(canonical)) {
-        return { ok: false, reason: CONDUCTOR_HOOK_BIN_UNRESOLVED_REASON };
-    }
-    return { ok: true, path: canonical };
+export function validateResolvedBin(candidate, qualify = (entry) => qualifyHookRuntime(entry)) {
+    if (!candidate.ok) {
+        const classification = candidate.classification ?? "missing";
+        return { ok: false, reason: candidate.reason, classification };
+    }
+    const qualification = safeQualify(qualify, candidate.path);
+    if (!qualification.usable)
+        return refusal(qualification.classification);
+    return qualifiedResolution(qualification);
+}
+const DEFAULT_PUBLICATION_FS = {
+    writeExclusive: (filePath, content, mode) => {
+        const fd = openSync(filePath, "wx", mode);
+        try {
+            writeSync(fd, content, null, "utf-8");
+        }
+        finally {
+            closeSync(fd);
+        }
+    },
+    chmod: (filePath, mode) => chmodSync(filePath, mode),
+    rename: (from, to) => renameSync(from, to),
+    unlink: (filePath) => unlinkSync(filePath),
+    mkdir: (dirPath) => {
+        mkdirSync(dirPath, { recursive: true });
+    },
+    lstat: (filePath) => {
+        try {
+            const st = lstatSync(filePath);
+            return { isFile: st.isFile(), isSymlink: st.isSymbolicLink(), mode: st.mode & 0o7777 };
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+    },
+    readFile: (filePath) => readFileSync(filePath, "utf-8"),
+};
+/**
+ * The mode a published hook gets: the ORIGINAL mode with only the missing
+ * execute bits added (execute wherever read is granted, and always for the
+ * owner). A new hook gets 0755.
+ */
+export function publishedHookMode(originalMode) {
+    if (originalMode === null)
+        return 0o755;
+    const base = originalMode & 0o7777;
+    return base | ((base & 0o444) >> 2) | 0o100;
 }
 /**
  * Install or update the managed `post-commit` and `reference-transaction` hooks.
- * Creates the hooks directory when needed and marks hook files executable on
- * POSIX. A non-worktree directory is reported as a degraded optional capability
- * (warning), never a fatal error.
  *
- * BAPI-772: the conductor binary is resolved and validated BEFORE any filesystem
- * mutation. When it cannot be resolved this returns the failure variant and
- * touches nothing — a dead hook is now structurally unwritable rather than
- * silently installed. The generated runtime bodies are unchanged (detached,
- * output discarded, `|| true`): only installation-time resolution is fail-loud.
+ * Order of operations (BAPI-1290):
+ *   1. Resolve and QUALIFY the hook runtime. A refusal touches nothing.
+ *   2. Resolve the shared hooks directory (linked worktrees share one).
+ *   3. PLAN both edits: snapshot each target's bytes and mode, refuse a
+ *      symlinked, non-regular, unreadable, or unsafe hook. A refusal here also
+ *      touches nothing — for either hook.
+ *   4. PUBLISH each hook: write an exclusive same-directory temp file, give it the
+ *      original mode plus only the missing execute bits, re-check that the target
+ *      still matches its snapshot, then rename atomically over it. A target that
+ *      changed meanwhile is left untouched; only owned temp files are removed.
+ *
+ * Two renames are not a transaction. When one hook publishes and the other does
+ * not, the result is `partial` with per-hook outcomes, and no automatic rollback
+ * overwrites the published hook. Re-running the installer re-reads the CURRENT
+ * content and converges to exactly one managed block per hook.
  */
 export function installConductorGitHooks(deps = {}) {
     const platform = deps.platform ?? process.platform;
-    const resolution = validateResolvedBin(deps.resolveBin ? deps.resolveBin() : resolveConductorHookBin());
+    const qualify = deps.qualifyRuntime ?? ((entry) => qualifyHookRuntime(entry));
+    const resolution = deps.resolveBin
+        ? validateResolvedBin(safeCandidate(deps.resolveBin), qualify)
+        : resolveConductorHookBin({ qualify });
     if (!resolution.ok) {
-        return { ok: false, error: CONDUCTOR_BIN_UNRESOLVED_ERROR, reason: resolution.reason };
+        return {
+            ok: false,
+            error: CONDUCTOR_BIN_UNRESOLVED_ERROR,
+            reason: resolution.reason,
+            classification: resolution.classification,
+        };
     }
     const conductorBin = resolution.path;
+    const q = resolution.qualification;
+    const runtime = {
+        package_name: q.package_name,
+        package_version: q.package_version,
+        platform: q.platform,
+        node_version: q.runtime.node_version,
+        node_modules_abi: q.runtime.node_modules_abi,
+        native_module: q.runtime.native_module,
+        native_module_version: q.runtime.native_module_version,
+    };
     const { is_worktree, hooks_dir } = resolveGitHooksDirectory(deps);
     if (!is_worktree || hooks_dir === null) {
         return {
@@ -273,56 +451,250 @@ export function installConductorGitHooks(deps = {}) {
             installed: [],
             warnings: ["not a git worktree; git hooks were not installed (degraded optional capability)"],
             conductor_bin: conductorBin,
+            canonical_bin: resolution.canonical_path,
+            runtime,
+            complete: false,
+            partial: false,
         };
     }
-    const warnings = [];
-    if (!existsSync(hooks_dir)) {
-        mkdirSync(hooks_dir, { recursive: true });
-    }
-    const installed = [];
+    const fs = { ...DEFAULT_PUBLICATION_FS, ...(deps.fs ?? {}) };
+    // ---- Plan both edits before publishing either. ---------------------------
+    const plans = [];
+    const refused = [];
     for (const name of MANAGED_HOOK_NAMES) {
         const hookPath = resolve(hooks_dir, name);
-        let existing = null;
-        if (existsSync(hookPath)) {
+        let stat;
+        try {
+            stat = fs.lstat(hookPath);
+        }
+        catch {
+            refused.push({ name, path: hookPath, warning: "could not inspect existing hook; left untouched" });
+            continue;
+        }
+        let snapshot = null;
+        if (stat !== null) {
+            if (stat.isSymlink) {
+                refused.push({ name, path: hookPath, warning: "existing hook is a symlink; left untouched" });
+                continue;
+            }
+            if (!stat.isFile) {
+                refused.push({ name, path: hookPath, warning: "existing hook is not a regular file; left untouched" });
+                continue;
+            }
+            let content;
             try {
-                existing = readFileSync(hookPath, "utf-8");
+                content = fs.readFile(hookPath);
             }
             catch {
-                installed.push({ name, path: hookPath, action: "skipped", warning: "could not read existing hook" });
-                warnings.push(`could not read existing ${name} hook; left untouched`);
+                refused.push({ name, path: hookPath, warning: "could not read existing hook; left untouched" });
                 continue;
             }
+            snapshot = { content, mode: stat.mode };
         }
-        const merge = mergeManagedHookSnippet(existing, snippetForHook(name, conductorBin));
+        const merge = mergeManagedHookSnippet(snapshot?.content ?? null, snippetForHook(name, conductorBin));
         if (!merge.ok) {
-            installed.push({ name, path: hookPath, action: "skipped", warning: merge.warning });
-            if (merge.warning)
-                warnings.push(`${name}: ${merge.warning}`);
+            refused.push({ name, path: hookPath, warning: merge.warning ?? "existing hook is unsafe to merge; left untouched" });
             continue;
         }
-        writeFileSync(hookPath, merge.content, "utf-8");
-        if (platform !== "win32") {
-            try {
-                chmodSync(hookPath, 0o755);
-            }
-            catch {
-                warnings.push(`could not mark ${name} executable`);
-            }
+        plans.push({ name, path: hookPath, action: merge.action, content: merge.content, snapshot });
+    }
+    if (refused.length > 0) {
+        return {
+            ok: false,
+            error: GIT_HOOKS_PLAN_REFUSED_ERROR,
+            reason: "managed git hooks were NOT installed: " +
+                refused.map((r) => `${r.name}: ${r.warning}`).join("; ") +
+                ". Neither hook was changed.",
+            refused,
+        };
+    }
+    // ---- Publish. -------------------------------------------------------------
+    const warnings = [];
+    try {
+        if (!existsSync(hooks_dir))
+            fs.mkdir(hooks_dir);
+    }
+    catch {
+        const installed = plans.map((plan) => failedStatus(plan, "publish-failed", "hooks directory could not be created"));
+        return {
+            ok: true,
+            is_worktree: true,
+            hooks_dir,
+            installed,
+            warnings: ["the hooks directory could not be created; no hook was changed"],
+            conductor_bin: conductorBin,
+            canonical_bin: resolution.canonical_path,
+            runtime,
+            complete: false,
+            partial: false,
+        };
+    }
+    const installed = [];
+    for (const plan of plans) {
+        const status = publishPlannedHook(plan, hooks_dir, fs, platform);
+        if (status.warning !== undefined)
+            warnings.push(`${status.name}: ${status.warning}`);
+        installed.push(status);
+    }
+    const publishedCount = installed.filter((h) => h.published).length;
+    const complete = MANAGED_HOOK_NAMES.every((name) => installed.some((h) => h.name === name && h.usable));
+    const partial = !complete && publishedCount > 0;
+    if (partial) {
+        warnings.push("only some managed hooks were published; the update is PARTIAL. Re-run " +
+            "`epic-implementer install-git-hooks` to converge (published hooks are not rolled back).");
+    }
+    return {
+        ok: true,
+        is_worktree: true,
+        hooks_dir,
+        installed,
+        warnings,
+        conductor_bin: conductorBin,
+        canonical_bin: resolution.canonical_path,
+        runtime,
+        complete,
+        partial,
+    };
+}
+function safeCandidate(resolveBin) {
+    try {
+        return resolveBin();
+    }
+    catch {
+        return { ok: false, reason: CONDUCTOR_HOOK_BIN_UNRESOLVED_REASON, classification: "unknown" };
+    }
+}
+function failedStatus(plan, outcome, warning) {
+    return {
+        name: plan.name,
+        path: plan.path,
+        action: plan.action,
+        outcome,
+        published: false,
+        mode_ready: false,
+        usable: false,
+        warning,
+    };
+}
+/** True when the target still matches the planned snapshot. */
+function targetMatchesSnapshot(plan, fs) {
+    const current = fs.lstat(plan.path);
+    if (plan.snapshot === null)
+        return current === null;
+    if (current === null || current.isSymlink || !current.isFile)
+        return false;
+    if (current.mode !== plan.snapshot.mode)
+        return false;
+    return fs.readFile(plan.path) === plan.snapshot.content;
+}
+function publishPlannedHook(plan, hooksDir, fs, platform) {
+    const tmpPath = join(hooksDir, `.${plan.name}.bridge-${process.pid}-${randomBytes(6).toString("hex")}.tmp`);
+    let tmpOwned = false;
+    const removeTmp = () => {
+        if (!tmpOwned)
+            return;
+        try {
+            fs.unlink(tmpPath);
         }
-        installed.push({ name, path: hookPath, action: merge.action });
+        catch {
+            /* best-effort: only our own unpublished temp file */
+        }
+    };
+    const mode = publishedHookMode(plan.snapshot?.mode ?? null);
+    try {
+        fs.writeExclusive(tmpPath, plan.content, 0o600);
+        tmpOwned = true;
+        if (platform !== "win32")
+            fs.chmod(tmpPath, mode);
+    }
+    catch {
+        removeTmp();
+        return failedStatus(plan, "publish-failed", "the hook could not be staged; left untouched");
+    }
+    let unchanged;
+    try {
+        unchanged = targetMatchesSnapshot(plan, fs);
+    }
+    catch {
+        unchanged = false;
+    }
+    if (!unchanged) {
+        removeTmp();
+        return failedStatus(plan, "intervening-edit", "the hook changed after it was planned; left untouched (re-run install-git-hooks)");
+    }
+    try {
+        fs.rename(tmpPath, plan.path);
+        tmpOwned = false;
+    }
+    catch {
+        removeTmp();
+        return failedStatus(plan, "publish-failed", "the hook could not be replaced; left untouched");
+    }
+    let modeReady = true;
+    if (platform !== "win32") {
+        try {
+            const after = fs.lstat(plan.path);
+            modeReady = after !== null && (after.mode & 0o100) !== 0;
+        }
+        catch {
+            modeReady = false;
+        }
+    }
+    return {
+        name: plan.name,
+        path: plan.path,
+        action: plan.action,
+        outcome: "published",
+        published: true,
+        mode_ready: modeReady,
+        usable: modeReady,
+        ...(modeReady ? {} : { warning: "the published hook is not executable" }),
+    };
+}
+/** Recognized generated command lines, captured quoted-entry token first. */
+const LEGACY_JSON_TOKEN = '"(?:[^"\\\\]|\\\\.)*"';
+const POSIX_TOKEN = "'[^']*(?:'\\\\''[^']*)*'";
+const POST_COMMIT_TAIL = " git-hook post-commit >/dev/null 2>&1 & \\) \\|\\| true";
+const LEGACY_REF_TAIL = ' git-hook reference-transaction --phase "\\$1" --stdin-file "\\$__bridge_tmp" >/dev/null 2>&1 & \\) \\|\\| true';
+const POSIX_REF_TAIL = ' git-hook reference-transaction --phase "\\$1" --stdin-file "\\$__bridge_tmp"; rm -f "\\$__bridge_tmp" \\) >/dev/null 2>&1 & \\) \\|\\| true';
+const MANAGED_COMMAND_GRAMMARS = [
+    { re: new RegExp(`^\\( node (${LEGACY_JSON_TOKEN})${POST_COMMIT_TAIL}$`), decode: decodeJsonToken },
+    { re: new RegExp(`^\\( node (${LEGACY_JSON_TOKEN})${LEGACY_REF_TAIL}$`), decode: decodeJsonToken },
+    { re: new RegExp(`^\\( node (${POSIX_TOKEN})${POST_COMMIT_TAIL}$`), decode: decodePosixToken },
+    { re: new RegExp(`^\\( \\( node (${POSIX_TOKEN})${POSIX_REF_TAIL}$`), decode: decodePosixToken },
+];
+function decodeJsonToken(token) {
+    try {
+        const parsed = JSON.parse(token);
+        return typeof parsed === "string" && parsed.length > 0 ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function decodePosixToken(token) {
+    const value = token.slice(1, -1).replace(/'\\''/g, "'");
+    if (value.length === 0)
+        return null;
+    // Round-trip check: only exactly what posixShellQuote would emit is accepted.
+    try {
+        return posixShellQuote(value) === token ? value : null;
+    }
+    catch {
+        return null;
     }
-    return { ok: true, is_worktree: true, hooks_dir, installed, warnings, conductor_bin: conductorBin };
 }
 /**
- * Extract the JSON-quoted binary argument from the managed block's generated
- * `node "<path>" git-hook ...` command (BAPI-772).
+ * Extract the entry argument from the managed block's generated
+ * `node <entry> git-hook ...` command (BAPI-772, BAPI-1290).
  *
  * Parsing is deliberately narrow rather than a general shell tokenization: only
- * the exact command shape this module writes is recognized, and the quoted
- * argument is read back with `JSON.parse` — the same encoding
- * {@link buildPostCommitHookSnippet} used to write it, so a path containing
- * spaces or quotes round-trips exactly. A hook that was hand-edited into an
- * unrecognized shape yields `null` rather than a throw or a guess.
+ * the exact command lines this module writes are recognized — the legacy
+ * JSON-quoted form and the current POSIX single-quoted form, for each hook — and
+ * the quoted argument is decoded with the same encoding that wrote it, so a path
+ * containing spaces, quotes, or shell metacharacters round-trips exactly. A hook
+ * that was hand-edited into any other shape (command substitution, extra tokens,
+ * malformed quoting) yields `null` rather than a throw or a guess.
  */
 export function extractManagedHookBinPath(content) {
     const startIdx = content.indexOf(BRIDGE_CONDUCTOR_HOOK_START);
@@ -330,25 +702,52 @@ export function extractManagedHookBinPath(content) {
     if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx)
         return null;
     const block = content.slice(startIdx, endIdx);
-    const match = /\bnode\s+("(?:[^"\\]|\\.)*")\s+git-hook\b/.exec(block);
-    if (match === null)
-        return null;
-    try {
-        const parsed = JSON.parse(match[1]);
-        return typeof parsed === "string" && parsed.length > 0 ? parsed : null;
+    for (const rawLine of block.split("\n")) {
+        const line = rawLine.replace(/\r$/, "");
+        for (const grammar of MANAGED_COMMAND_GRAMMARS) {
+            const match = grammar.re.exec(line);
+            if (match === null)
+                continue;
+            const decoded = grammar.decode(match[1]);
+            if (decoded !== null)
+                return decoded;
+        }
     }
-    catch {
-        return null;
+    return null;
+}
+/** Fixed, path-free warning for a degraded hook state. */
+function hookStateWarning(name, state) {
+    switch (state) {
+        case "usable":
+            return null;
+        case "not-installed":
+            return `${name} hook not installed (degraded optional capability)`;
+        case "no-managed-block":
+            return `${name} hook has no managed conductor block; run \`epic-implementer install-git-hooks\``;
+        case "not-executable":
+            return `${name} hook is not executable, so it never runs; re-run \`epic-implementer install-git-hooks\``;
+        case "unrecognized":
+            return (`${name} hook has a managed block with no recognizable conductor command; ` +
+                "reinstall with `epic-implementer install-git-hooks`");
+        default:
+            return `${name} hook runtime unavailable — ${describeHookRuntimeClassification(state)}`;
     }
 }
 /**
  * Inspect the managed git hooks WITHOUT modifying anything. Reports worktree
- * status, the resolved hooks directory, and per-hook existence, executability, and
- * managed-block presence. Missing hooks and non-worktree directories are reported
- * as degraded optional capability, never fatal.
+ * status, the resolved hooks directory, and per-hook existence, executability,
+ * managed-block presence, and — BAPI-1290 — whether the embedded runtime is a
+ * QUALIFIED persistent install whose Node and native binding actually load.
+ * Missing hooks, unknown evidence, and non-worktree directories are reported as
+ * degraded optional capability, never fatal and never healthy.
+ *
+ * Read-only by contract: no npm discovery, no download, no hook rewrite, no
+ * service start, no ledger open. The only subprocess is the bounded runtime
+ * probe, run at most once per distinct embedded entry.
  */
 export function inspectConductorGitHooks(deps = {}) {
     const platform = deps.platform ?? process.platform;
+    const qualify = deps.qualifyRuntime ?? ((entry) => qualifyHookRuntime(entry));
     const { is_worktree, hooks_dir } = resolveGitHooksDirectory(deps);
     if (!is_worktree || hooks_dir === null) {
         return {
@@ -359,6 +758,15 @@ export function inspectConductorGitHooks(deps = {}) {
             degraded: true,
         };
     }
+    const qualifications = new Map();
+    const qualifyOnce = (entry) => {
+        const cached = qualifications.get(entry);
+        if (cached !== undefined)
+            return cached;
+        const result = safeQualify(qualify, entry);
+        qualifications.set(entry, result);
+        return result;
+    };
     const warnings = [];
     const hooks = [];
     for (const name of MANAGED_HOOK_NAMES) {
@@ -368,6 +776,7 @@ export function inspectConductorGitHooks(deps = {}) {
         let managedPresent = false;
         let embeddedBinPath = null;
         let embeddedBinIsFile = false;
+        let state = "not-installed";
         if (exists) {
             try {
                 const mode = statSync(hookPath).mode;
@@ -376,41 +785,40 @@ export function inspectConductorGitHooks(deps = {}) {
             catch {
                 /* unreadable stat — leave executable false */
             }
+            state = "no-managed-block";
             try {
                 const content = readFileSync(hookPath, "utf-8");
                 managedPresent = content.includes(BRIDGE_CONDUCTOR_HOOK_START);
                 if (managedPresent) {
                     // BAPI-772: a managed block is not enough — the block written by an
-                    // older build can point at a binary that never existed. Stat the
-                    // embedded target READ-ONLY so a dead hook is visible instead of
-                    // reported healthy. Nothing here rewrites or canonicalizes the hook.
+                    // older build can point at a binary that never existed. BAPI-1290: a
+                    // binary that exists is not enough either — it can be a prunable
+                    // cache entry or a runtime whose native binding does not load.
                     embeddedBinPath = extractManagedHookBinPath(content);
-                    // S4 (BAPI-1080): a hook installed before the rename still embeds
-                    // the old `conductor-bin.js` path, which still exists post-upgrade
-                    // as the migration stub — stat-true but dead. Require the embedded
-                    // path's basename to be the current real bin so a stale hook is
-                    // correctly flagged degraded instead of reported healthy.
+                    // S4 (BAPI-1080): the retained `conductor-bin.js` stub still exists
+                    // post-upgrade but is dead, so the basename must be the current bin.
                     embeddedBinIsFile =
                         embeddedBinPath !== null &&
                             basename(embeddedBinPath) === CONDUCTOR_BIN_FILENAME &&
                             defaultIsFile(embeddedBinPath);
                     if (embeddedBinPath === null) {
-                        warnings.push(`${name} hook has a managed block with no recognizable conductor command; ` +
-                            "reinstall with `epic-implementer install-git-hooks`");
+                        state = "unrecognized";
                     }
-                    else if (!embeddedBinIsFile) {
-                        warnings.push(`${name} hook points at a missing or invalid conductor binary (${embeddedBinPath}); ` +
-                            "the hook is dead — reinstall with `epic-implementer install-git-hooks`");
+                    else {
+                        const qualification = qualifyOnce(embeddedBinPath);
+                        state = qualification.usable ? "usable" : qualification.classification;
                     }
                 }
             }
             catch {
-                /* unreadable — leave managedPresent false */
+                state = "unknown";
             }
+            if (state === "usable" && !executable)
+                state = "not-executable";
         }
-        else {
-            warnings.push(`${name} hook not installed (degraded optional capability)`);
-        }
+        const warning = hookStateWarning(name, state);
+        if (warning !== null)
+            warnings.push(warning);
         hooks.push({
             name,
             path: hookPath,
@@ -419,8 +827,11 @@ export function inspectConductorGitHooks(deps = {}) {
             managed_block_present: managedPresent,
             embedded_bin_path: embeddedBinPath,
             embedded_bin_is_file: embeddedBinIsFile,
+            recognized_command: embeddedBinPath !== null,
+            state,
+            usable: state === "usable",
         });
     }
-    const degraded = hooks.some((h) => !h.exists || !h.managed_block_present || !h.embedded_bin_is_file);
+    const degraded = hooks.some((h) => !h.usable);
     return { is_worktree: true, hooks_dir, hooks, warnings, degraded };
 }