failproofai 1.0.0-beta.2 → 1.0.0-beta.21

package/src/hooks/custom-hooks-loader.ts

@@ -11,29 +11,57 @@
  * and results in an empty hook list for that file. Builtins continue normally.
  */
 import { resolve, isAbsolute, basename } from "node:path";
+import { randomUUID } from "crypto";
 import { existsSync, readdirSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { pathToFileURL } from "node:url";
-import { homedir } from "node:os";
+import { createHash } from "node:crypto";
 import { hookLogWarn, hookLogError, hookLogInfo } from "./hook-logger";
-import { getCustomHooks, clearCustomHooks } from "./custom-hooks-registry";
-import { findDistIndex, rewriteFileTree, TMP_SUFFIX, cleanupTmpFiles } from "./loader-utils";
+import { customPolicies, getCustomHooks, clearCustomHooks } from "./custom-hooks-registry";
+import {
+  findDistIndex,
+  rewriteFileTree,
+  TMP_SUFFIX,
+  cleanupTmpFiles,
+  isTmpArtifact,
+  sweepStaleTmpArtifacts,
+} from "./loader-utils";
 import { findProjectConfigDir } from "./hooks-config";
 import { trackHookEvent } from "./hook-telemetry";
 import { getInstanceId } from "../../lib/telemetry-id";
 import type { CustomHook } from "./policy-types";
+import type { CloudManagedPolicyArtifact } from "./cloud-managed-policies";
+import { customPoliciesDir, shimsDir } from "./fp-home";
 
 const LOADING_KEY = "__FAILPROOFAI_LOADING_HOOKS__";
 
 /** Regex matching convention policy filenames: *policies.{js,mjs,ts} */
 const CONVENTION_FILE_RE = /policies\.(js|mjs|ts)$/;
 
+/** Monotonic suffix for physically distinct temporary module trees. Bun
+ * ignores URL query strings when caching imports, so a query-only cache
+ * buster silently drops custom policies after the first request in the warm
+ * daemon worker. A unique filename is honored by both Bun and Node. */
+let loadSequence = 0;
+
+interface CachedPolicyModule {
+  fingerprint: string;
+  hooks: CustomHook[];
+}
+
+/** One retained module instance per source entry. Reusing its registered hook
+ * functions prevents an unbounded ESM module-cache leak in the resident worker.
+ * A source-tree change replaces this entry and imports one new module. */
+const policyModuleCache = new Map<string, CachedPolicyModule>();
 /**
- * Monotonic counter used to cache-bust each dynamic import. Loading N files
- * creates N module instances rather than reusing one; every caller here is
- * either a one-shot CLI command or a short-lived hook process, so the
- * lifetime cost is bounded by the process, not by uptime.
+ * Cap, for the reason `gitBranchCache` states and this cache did not carry
+ * over: a warm worker touching many projects over its lifetime must not grow
+ * this unboundedly. Keyed by absolute policy-file path and holding cloned hook
+ * closures, so the entries are not small. Cleared wholesale rather than evicted
+ * one at a time — the next load simply re-imports, which is the same cost the
+ * cache exists to avoid paying twice, not a correctness change.
  */
-let loadSequence = 0;
+const POLICY_MODULE_CACHE_MAX_ENTRIES = 500;
 
 /** Script extensions we could load, used to spot near-miss filenames. */
 const LOADABLE_EXT_RE = /\.(js|mjs|ts)$/;
@@ -76,7 +104,11 @@ export function findSkippedPolicyFiles(dir: string): string[] {
           e.isFile() &&
           LOADABLE_EXT_RE.test(e.name) &&
           !CONVENTION_FILE_RE.test(e.name) &&
-          !e.name.endsWith(".d.ts"),
+          !e.name.endsWith(".d.ts") &&
+          // Never our own generated files. They are `.mjs` and never match the
+          // convention, so each one a killed load left behind was reported to
+          // the user as a policy file that would not load.
+          !isTmpArtifact(e.name),
       )
       .map((e) => e.name)
       .sort((a, b) => a.localeCompare(b));
@@ -85,13 +117,69 @@ export function findSkippedPolicyFiles(dir: string): string[] {
   }
 }
 
+/**
+ * How long a policy module gets to finish evaluating its top level.
+ *
+ * Matches the 10s `handler.ts` gives a policy's `fn` to run, for the same
+ * reason: a policy file is user code, and user code that hangs must cost one
+ * skipped policy rather than the process.
+ *
+ * `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` shortens it for tests — a suite proving
+ * the deadline fires should not have to sit out the real one.
+ */
+function moduleLoadTimeoutMs(): number {
+  const override = Number(process.env.FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS);
+  return Number.isFinite(override) && override > 0 ? override : 10_000;
+}
+
+/**
+ * `import()`, but it cannot hang forever.
+ *
+ * A bare `await import(...)` on a module whose top level contains an `await`
+ * that never resolves never settles — it does not reject, so no `catch` and no
+ * `finally` anywhere above it ever runs. In the one-shot hook path that costs
+ * one hook process, which the agent CLI's own timeout reaps. In the warm daemon
+ * worker it holds `worker-server.ts`'s serialization chain forever, and every
+ * subsequent hook on the machine queues behind it and fail-closed denies.
+ *
+ * Losing the race does NOT cancel the import — nothing can. It stops us
+ * *waiting* on it, which is the part that matters, and the caller's `catch`
+ * below reports the file as failed to load. The abandoned module keeps its
+ * half-initialized entry in the ESM cache, but each load writes a uniquely
+ * named temporary tree, so a retry imports a different specifier and is never
+ * poisoned by it.
+ */
+async function importWithDeadline(fileUrl: string): Promise<void> {
+  const budget = moduleLoadTimeoutMs();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([
+      import(/* webpackIgnore: true */ fileUrl),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`timed out loading module after ${budget}ms`)),
+          budget,
+        );
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
 /**
  * Load a single policy file into the globalThis custom hooks registry.
  * Does NOT clear the registry — caller is responsible for that.
  */
 async function loadSingleFile(
   absPath: string,
-  opts?: { strict?: boolean; conventionScope?: "project" | "user" },
+  opts?: {
+    strict?: boolean;
+    conventionScope?: "project" | "user";
+    /** Cloud-managed policies pass their pinned digest for load-time re-verification. */
+    verifyEntrySha?: string;
+  },
 ): Promise<void> {
   const g = globalThis as Record<string, unknown>;
   g[LOADING_KEY] = true;
@@ -101,30 +189,48 @@ async function loadSingleFile(
     const distIndex = await findDistIndex();
     const distUrl = distIndex ? pathToFileURL(distIndex).href : null;
 
-    tmpFiles = await rewriteFileTree(absPath, distUrl, distIndex);
-
-    const entryTmp = absPath + TMP_SUFFIX;
-    // Cache-bust the specifier. NOTE this works under Node but NOT under Bun,
-    // which caches by resolved path and ignores the query — and the shipped
-    // binary runs under Bun. It is kept because it makes repeat loads behave
-    // the same on both runtimes where it can, but nothing may DEPEND on a
-    // repeat load re-executing; callers dedupe paths instead (see above).
-    // The temp path is deterministic, so a second
-    // load of the same file inside one process hit the ESM module cache, the
-    // module body never re-ran, no `customPolicies.add` fired, and the caller
-    // saw zero hooks — indistinguishable from a broken policy file. That is
-    // exactly what `failproofai policies` rendered as "failed to load" for
-    // every file when it walked a shared project/user directory twice.
-    // A distinct query string makes it a distinct module to the loader.
-    const fileUrl = `${pathToFileURL(entryTmp).href}?v=${++loadSequence}`;
-    await import(/* webpackIgnore: true */ fileUrl);
+    const sequence = ++loadSequence;
+    // pid + sequence is not unique enough on its own: two containers sharing a
+    // mounted HOME, or two pid namespaces, can collide — and on the shim's
+    // fallback path a collision means EEXIST, which fails the load OPEN. A
+    // random id removes the class. It costs nothing: `fingerprintTemporaryTree`
+    // normalises the whole suffix away, so the module cache still hits.
+    const tmpSuffix = `${TMP_SUFFIX}.${process.pid}.${sequence}.${randomUUID()}.mjs`;
+    tmpFiles = await rewriteFileTree(
+      absPath,
+      distUrl,
+      distIndex,
+      tmpSuffix,
+      opts?.verifyEntrySha,
+    );
+
+    const fingerprint = await fingerprintTemporaryTree(tmpFiles, tmpSuffix);
+    const cached = policyModuleCache.get(absPath);
+    if (cached?.fingerprint === fingerprint) {
+      for (const hook of cached.hooks) customPolicies.add({ ...hook });
+      return;
+    }
+
+    const entryTmp = absPath + tmpSuffix;
+    const fileUrl = pathToFileURL(entryTmp).href;
+    const hooksBefore = getCustomHooks().length;
+    await importWithDeadline(fileUrl);
+    if (policyModuleCache.size >= POLICY_MODULE_CACHE_MAX_ENTRIES) policyModuleCache.clear();
+    policyModuleCache.set(absPath, {
+      fingerprint,
+      hooks: getCustomHooks()
+        .slice(hooksBefore)
+        .map((hook) => ({ ...hook })),
+    });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     const errorType = /Cannot find module|MODULE_NOT_FOUND|ENOENT/i.test(msg)
       ? "module_not_found"
       : /SyntaxError|Unexpected token/i.test(msg)
         ? "syntax_error"
-        : "runtime_error";
+        : /timed out loading module/i.test(msg)
+          ? "load_timeout"
+          : "runtime_error";
     void trackHookEvent(getInstanceId(), "custom_hooks_load_error", {
       error_type: errorType,
       is_convention: !!opts?.conventionScope,
@@ -139,6 +245,18 @@ async function loadSingleFile(
   }
 }
 
+async function fingerprintTemporaryTree(tmpFiles: string[], tmpSuffix: string): Promise<string> {
+  const hash = createHash("sha256");
+  for (const tmpFile of [...tmpFiles].sort()) {
+    // The generated filenames change per load. Normalize both the logical path
+    // and rewritten import specifiers so identical source graphs hash equally.
+    hash.update(tmpFile.replaceAll(tmpSuffix, TMP_SUFFIX));
+    const contents = await readFile(tmpFile, "utf8");
+    hash.update(contents.replaceAll(tmpSuffix, TMP_SUFFIX));
+  }
+  return hash.digest("hex");
+}
+
 /**
  * Load a single explicit custom hooks file (legacy API).
  * Clears the registry, loads the file, returns registered hooks.
@@ -214,7 +332,11 @@ function warnSkippedPolicyFiles(dir: string, scope: "project" | "user"): void {
 
 export async function loadAllCustomHooks(
   customPoliciesPaths: string | string[] | undefined,
-  opts?: { sessionCwd?: string; customPoliciesEnabled?: boolean },
+  opts?: {
+    sessionCwd?: string;
+    customPoliciesEnabled?: boolean;
+    cloudManagedPolicies?: CloudManagedPolicyArtifact[];
+  },
 ): Promise<LoadAllResult> {
   clearCustomHooks();
 
@@ -236,6 +358,43 @@ export async function loadAllCustomHooks(
   // convention passes.
   const loadedPaths = new Set<string>();
 
+  // Cloud policies keyed by the artifact they resolve to — and artifacts are
+  // CONTENT-ADDRESSED, so two policies whose source is byte-identical share one
+  // path. Building this map with a plain `new Map(entries)` let the last one win
+  // silently, and since `loadedPaths` then loads that file exactly once, the
+  // other policy vanished: its id never appeared in `failproofai policies` or in
+  // the decision log, and — the part that matters — ITS EFFECT DECIDED NOTHING.
+  // An `enforce` policy sharing bytes with an `observe` one was downgraded to
+  // observation, which is a silent enforcement gap, and the reverse turned a
+  // measurement-only rollout into live denials.
+  //
+  // It could not happen before the flattening: `deployments/<n>/<id>.mjs` gave
+  // every policy its own path even when the bytes matched.
+  //
+  // One module instance is right — `customPolicies.add` is an unconditional
+  // push, so importing the file twice would register every hook twice and run
+  // the policy twice per event. So the collision is resolved rather than
+  // avoided, and it resolves toward ENFORCEMENT: over-enforcing is visible to
+  // whoever hits it, while under-enforcing is exactly the silent failure this
+  // codebase exists to remove. It is also announced, so an operator can give the
+  // two policies distinguishable source instead of living with the merge.
+  const cloudManagedByPath = new Map<string, CloudManagedPolicyArtifact>();
+  for (const policy of opts?.cloudManagedPolicies ?? []) {
+    const key = resolve(policy.path);
+    const existing = cloudManagedByPath.get(key);
+    if (!existing) {
+      cloudManagedByPath.set(key, policy);
+      continue;
+    }
+    hookLogWarn(
+      `cloud-managed policies ${existing.id} and ${policy.id} have identical source, so they share ` +
+        `one artifact and load as one policy; enforcing it if either asks to enforce`,
+    );
+    if (existing.effect !== "enforce" && policy.effect === "enforce") {
+      cloudManagedByPath.set(key, policy);
+    }
+  }
+
   // 1. Explicit custom policy paths. Accept a string for callers/configs using
   // the legacy singular form.
   for (const customPoliciesPath of typeof customPoliciesPaths === "string"
@@ -248,9 +407,23 @@ export async function loadAllCustomHooks(
       if (!loadedPaths.has(absPath)) {
         loadedPaths.add(absPath);
         const hooksBefore = getCustomHooks().length;
-        await loadSingleFile(absPath);
+        // A cloud-managed policy re-verifies its pinned digest at load, binding
+        // the imported bytes to what desired-state promised.
+        await loadSingleFile(absPath, {
+          verifyEntrySha: cloudManagedByPath.get(absPath)?.sha256,
+        });
         for (const hook of getCustomHooks().slice(hooksBefore)) {
-          (hook as CustomHook & { __policyId?: string }).__policyId = customPolicyId(absPath, hook.name);
+          const cloudManaged = cloudManagedByPath.get(absPath);
+          const tagged = hook as CustomHook & {
+            __policyId?: string;
+            __cloudManaged?: CloudManagedPolicyArtifact;
+          };
+          if (cloudManaged) {
+            tagged.__cloudManaged = cloudManaged;
+            tagged.__policyId = `cloud:${cloudManaged.id}@${cloudManaged.version}:${hook.name}`;
+          } else {
+            tagged.__policyId = customPolicyId(absPath, hook.name);
+          }
         }
       }
     } else {
@@ -268,21 +441,51 @@ export async function loadAllCustomHooks(
   // exactly that — and it is discovered here as well. Skip what step 1 loaded,
   // or the file is imported twice and every hook in it fires twice per event.
   const projectDir = resolve(projectRoot, ".failproofai", "policies");
-  if (conventionEnabled) warnSkippedPolicyFiles(projectDir, "project");
+  // Clear out generated files a killed load left behind, before anything scans
+  // this directory. The temporary tree has to be written beside the sources for
+  // a rewritten relative import to resolve, and its name now carries a pid and
+  // sequence number — so unlike the old fixed name, each abnormal termination
+  // leaks one file permanently rather than leaving one that the next load
+  // overwrites. Best-effort and age-gated, so it can never remove a tree
+  // another process is still importing.
+  // WHICH SCOPE this directory is depends on whether it IS the user directory.
+  // Run an agent CLI with the cwd set to $HOME and `<cwd>/.failproofai/policies`
+  // resolves to `~/.failproofai/policies` — the user scope itself. Layout 3 made
+  // that reachable by collapsing `customPoliciesDir()` onto `policiesDir()`;
+  // layout 2 nested the user directory one level deeper, so the two could never
+  // be the same path.
+  //
+  // Tagging it `project` there would make a policy's id depend on where the
+  // agent happened to be launched from — `convention:project:x-policies.mjs:foo`
+  // from $HOME and `convention:user:x-policies.mjs:foo` from anywhere else — and
+  // a disable is RECORDED AGAINST THAT ID. So a user who switched a policy off
+  // would find it firing again whenever they worked out of their home
+  // directory, with nothing to explain it. The files are the user's global
+  // policies; that the cwd also points at them is incidental.
+  const projectScope: "project" | "user" = projectDir === customPoliciesDir() ? "user" : "project";
+  if (conventionEnabled) {
+    void sweepStaleTmpArtifacts(projectDir);
+    warnSkippedPolicyFiles(projectDir, projectScope);
+  }
+  // The shim directory leaks the same way and is swept on the same terms. It is
+  // ours alone and outside the policy tree, so nothing else would ever reap it;
+  // the age gate is what keeps this from removing a shim another process is
+  // still importing.
+  void sweepStaleTmpArtifacts(shimsDir());
   const projectFiles = conventionEnabled
     ? discoverPolicyFiles(projectDir).filter((f) => !loadedPaths.has(f))
     : [];
   for (const file of projectFiles) {
     loadedPaths.add(file);
     const hooksBefore = getCustomHooks().length;
-    await loadSingleFile(file, { conventionScope: "project" });
+    await loadSingleFile(file, { conventionScope: projectScope });
     const newHooks = getCustomHooks().slice(hooksBefore);
     for (const hook of newHooks) {
-      (hook as CustomHook & { __policyId?: string }).__policyId = conventionPolicyId("project", basename(file), hook.name);
+      (hook as CustomHook & { __policyId?: string }).__policyId = conventionPolicyId(projectScope, basename(file), hook.name);
     }
     if (newHooks.length > 0) {
       conventionSources.push({
-        scope: "project",
+        scope: projectScope,
         file: basename(file),
         hookNames: newHooks.map((h) => h.name),
       });
@@ -303,8 +506,11 @@ export async function loadAllCustomHooks(
   // so the second import is a no-op — but Node honours the query and would
   // double-register. The binary runs under Bun and the tests under Node, so the
   // bug is invisible from both sides. Do not rely on that; dedupe the paths.
-  const userDir = resolve(homedir(), ".failproofai", "policies");
-  if (conventionEnabled && userDir !== projectDir) warnSkippedPolicyFiles(userDir, "user");
+  const userDir = customPoliciesDir();
+  if (conventionEnabled && userDir !== projectDir) {
+    void sweepStaleTmpArtifacts(userDir);
+    warnSkippedPolicyFiles(userDir, "user");
+  }
   const userFiles =
     conventionEnabled && userDir !== projectDir
       ? discoverPolicyFiles(userDir).filter((f) => !loadedPaths.has(f))

package/src/hooks/daemon-client.ts

@@ -6,17 +6,15 @@
  * request, a 4-byte big-endian u32 length prefix followed by that many
  * bytes of UTF-8 JSON, camelCase fields, `"type"` as the tag.
  *
- * This module makes NO decision about what to do when the daemon can't be
- * reached — `tryDaemonHook` just returns `null` on any failure. The caller
- * (`bin/failproofai.mjs`) decides: fall back to full in-process evaluation
- * on a machine that was never daemon-configured, or fail closed on one that
- * was. See `isDaemonConfigured`.
+ * This module reports whether a daemon request succeeded, was unreachable, or
+ * used an incompatible protocol. The caller (`bin/failproofai.mjs`) owns the
+ * fail-closed response for daemon-configured machines.
  */
 import { createConnection } from "node:net";
-import { resolve } from "node:path";
-import { homedir } from "node:os";
 import type { IntegrationType } from "./types";
-import { readHooksConfig } from "./hooks-config";
+import { existsSync } from "node:fs";
+import { daemonSocket as daemonSocketPath } from "./fp-home";
+import { readConfig } from "./fp-config";
 
 const PROTOCOL_VERSION = 1;
 
@@ -66,9 +64,90 @@ export interface DaemonHookResponse {
   stderr: string;
 }
 
+/**
+ * Why an attempt failed. BOTH cases deny; they differ only in what the user is
+ * told to do about it.
+ *
+ * `protocol-mismatch` means a daemon answered, so it is alive — we simply
+ * cannot speak its wire format. The cause is known and benign: the CLI upgraded
+ * via npm and the daemon has not been reinstalled yet, so the remedy is
+ * `failproofai config`, and naming it is the difference between a one-command
+ * fix and a support ticket.
+ *
+ * `unreachable` means nothing answered. A stopped service, a deleted socket and
+ * deliberate tampering are indistinguishable from here.
+ *
+ * This comment used to say a mismatch should FALL BACK to in-process
+ * evaluation, "because denying every tool call over it would take a working
+ * machine offline to protect nothing". `2926252` deliberately reversed that,
+ * and `bin/failproofai.mjs` now routes both failures to the same forced deny:
+ * on a daemon-configured machine the daemon is the ONLY evaluator, and a second
+ * policy engine reachable by breaking the first is not a guarantee. The
+ * distinction survives in the MESSAGE and nowhere else. Do not restore the
+ * fallback without revisiting that decision — the comment outliving the code is
+ * exactly how it would come back by accident.
+ */
+export type DaemonFailure = "unreachable" | "protocol-mismatch";
+
+export type DaemonAttempt =
+  | { ok: true; response: DaemonHookResponse }
+  | { ok: false; failure: DaemonFailure };
+
+/**
+ * Whether a daemon is listening, regardless of how it was started.
+ *
+ * Distinct from `daemonServiceStatus()`, which asks the service manager. A
+ * daemon run by hand — during development, or from a container — is invisible
+ * to that check but is very much running and pulling policy, so reporting "not
+ * installed, so nothing will be pulled" at someone whose machine is actively
+ * enforcing is simply false.
+ */
+export function daemonSocketPresent(): boolean {
+  try {
+    return existsSync(socketPath());
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether the daemon socket accepts a connection *right now*.
+ *
+ * Narrower than `daemonSocketPresent()` (a stale socket file outlives the
+ * process that made it) and narrower than `attemptDaemonHook`, which reports
+ * `"unreachable"` for BOTH a refused connection and a request that was accepted
+ * and then never answered. Those two have different causes and different
+ * remedies — a socket that is not up yet versus a worker that cannot run — and
+ * telling them apart is the whole point of this function.
+ *
+ * Connect budget only; nothing is sent. Used by the health probe, never on the
+ * hook path.
+ */
+export async function daemonAcceptsConnections(
+  timeoutMs = DAEMON_CONNECT_TIMEOUT_MS,
+): Promise<boolean> {
+  if (process.platform === "win32") return false;
+  return new Promise<boolean>((resolve) => {
+    let settled = false;
+    const done = (v: boolean) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(v);
+    };
+    const socket = createConnection({ path: socketPath() });
+    const timer = setTimeout(() => done(false), timeoutMs);
+    timer.unref?.();
+    socket.on("connect", () => done(true));
+    socket.on("error", () => done(false));
+  });
+}
+
 function socketPath(): string {
   if (process.env.FAILPROOFAI_DAEMON_SOCKET) return process.env.FAILPROOFAI_DAEMON_SOCKET;
-  return resolve(homedir(), ".failproofai", "run", "failproofaid.sock");
+  return daemonSocketPath();
 }
 
 /**
@@ -81,8 +160,11 @@ function socketPath(): string {
  */
 export function isDaemonConfigured(): boolean {
   try {
-    return readHooksConfig().daemonConfigured === true;
+    return readConfig().daemon.configured === true;
   } catch {
+    // Unreadable config reads as NOT daemon-configured. The failure direction
+    // is deliberate: the alternative is a machine that fails closed on every
+    // tool call because a config file got truncated.
     return false;
   }
 }
@@ -94,32 +176,41 @@ function encodeFrame(value: unknown): Buffer {
   return Buffer.concat([header, body]);
 }
 
-/**
- * Attempts one hook evaluation via the daemon. Returns `null` on **any**
- * failure — no socket, connection refused, timeout, malformed response,
- * protocol-version mismatch, or an explicit `error` message from the
- * daemon. The caller never needs to distinguish failure modes; it just
- * falls through to whatever its own fallback policy is.
- */
-export async function tryDaemonHook(req: DaemonHookRequest): Promise<DaemonHookResponse | null> {
+/** Attempts a daemon evaluation while preserving the failure category. */
+export async function attemptDaemonHook(
+  req: DaemonHookRequest,
+  opts?: {
+    /**
+     * Override the RESPONSE budget only — the connect budget is never
+     * relaxed. Used by the health probe (`probeDaemonEndToEnd`), which runs
+     * from an interactive command rather than a hook and must not make a
+     * person wait out the full 30s hook budget to be told their daemon is
+     * broken. Never set this on the hook path: 30s is matched to the
+     * daemon's own read timeout so this side never gives up on a request the
+     * daemon is still honestly working on.
+     */
+    responseTimeoutMs?: number;
+  },
+): Promise<DaemonAttempt> {
   // Windows never has a daemon in this phase (see the plan's platform
   // scope) — skip the attempt outright rather than depending on however
   // Node happens to behave when handed a POSIX socket path on Windows.
-  if (process.platform === "win32") return null;
+  if (process.platform === "win32") return { ok: false, failure: "unreachable" };
+  const responseBudget = opts?.responseTimeoutMs ?? DAEMON_RESPONSE_TIMEOUT_MS;
 
-  return new Promise<DaemonHookResponse | null>((resolvePromise) => {
+  return new Promise<DaemonAttempt>((resolvePromise) => {
     let settled = false;
     let timer: ReturnType<typeof setTimeout>;
     const arm = (ms: number) => {
       clearTimeout(timer);
-      timer = setTimeout(() => finish(null), ms);
+      timer = setTimeout(() => fail("unreachable"), ms);
       // Don't let this timer alone keep the process alive if everything else
       // has already finished — it's always cleared on the success/failure
       // paths below, this just avoids it being the sole reason a --hook
       // process lingers if something upstream forgets to await us.
       timer.unref?.();
     };
-    const finish = (result: DaemonHookResponse | null) => {
+    const finish = (result: DaemonAttempt) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
@@ -127,6 +218,7 @@ export async function tryDaemonHook(req: DaemonHookRequest): Promise<DaemonHookR
       socket.destroy();
       resolvePromise(result);
     };
+    const fail = (failure: DaemonFailure) => finish({ ok: false, failure });
 
     const socket = createConnection({ path: socketPath() });
     arm(DAEMON_CONNECT_TIMEOUT_MS);
@@ -137,7 +229,7 @@ export async function tryDaemonHook(req: DaemonHookRequest): Promise<DaemonHookR
     socket.on("connect", () => {
       // Connected: the daemon is demonstrably reachable, so the question is
       // no longer "is it there" but "how long does this evaluation take".
-      arm(DAEMON_RESPONSE_TIMEOUT_MS);
+      arm(responseBudget);
       socket.write(
         encodeFrame({
           type: "hook",
@@ -157,7 +249,7 @@ export async function tryDaemonHook(req: DaemonHookRequest): Promise<DaemonHookR
         if (recvBuf.length < 4) return;
         declaredLen = recvBuf.readUInt32BE(0);
         if (declaredLen > MAX_FRAME_LEN) {
-          finish(null);
+          fail("unreachable");
           return;
         }
         recvBuf = recvBuf.subarray(4);
@@ -170,12 +262,16 @@ export async function tryDaemonHook(req: DaemonHookRequest): Promise<DaemonHookR
       try {
         message = JSON.parse(body.toString("utf8")) as Record<string, unknown>;
       } catch {
-        finish(null);
+        fail("unreachable");
         return;
       }
 
       if (message.protocolVersion !== PROTOCOL_VERSION) {
-        finish(null);
+        // Catches BOTH directions. A newer CLI sends v2 and the daemon replies
+        // with an error stamped v1; an older CLI sends v1 and a newer daemon
+        // replies stamped v2. Either way the versions disagree here, and either
+        // way a daemon answered — so this is skew, not absence.
+        fail("protocol-mismatch");
         return;
       }
       if (
@@ -184,16 +280,23 @@ export async function tryDaemonHook(req: DaemonHookRequest): Promise<DaemonHookR
         typeof message.stdout === "string" &&
         typeof message.stderr === "string"
       ) {
-        finish({ exitCode: message.exitCode, stdout: message.stdout, stderr: message.stderr });
+        finish({
+          ok: true,
+          response: {
+            exitCode: message.exitCode,
+            stdout: message.stdout,
+            stderr: message.stderr,
+          },
+        });
         return;
       }
-      // Anything else — an explicit `error` message, a `pong` (protocol
-      // confusion), or a well-formed-but-wrong-shape body — is treated
-      // identically to a connection failure: no partial trust.
-      finish(null);
+      // Anything else — an explicit `error` message at a MATCHING protocol
+      // version, a `pong` (protocol confusion), or a well-formed-but-wrong-shape
+      // body — is treated identically to a connection failure: no partial trust.
+      fail("unreachable");
     });
 
-    socket.on("error", () => finish(null));
-    socket.on("close", () => finish(null));
+    socket.on("error", () => fail("unreachable"));
+    socket.on("close", () => fail("unreachable"));
   });
 }