failproofai 0.0.15 → 1.0.0-beta.1

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "failproofai",
-  "version": "0.0.15",
+  "version": "1.0.0-beta.1",
   "description": "The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously — for Claude Code & the Agents SDK",
   "bin": {
-    "failproofai": "./dist/cli.mjs"
+    "failproofai": "./dist/cli.mjs",
+    "failproofaid": "./bin/failproofaid-shim.mjs"
   },
   "files": [
     "bin/",
@@ -24,7 +25,8 @@
     "predev": "bun run build:cli && bun link",
     "dev": "FAILPROOFAI_TELEMETRY_DISABLED=1 bun scripts/dev.ts --port 8020",
     "build:cli": "bun build --target=node --format=esm --outfile=dist/cli.mjs bin/failproofai.mjs --external posthog-node --external sql.js && node -e \"const fs=require('fs');const c=fs.readFileSync('dist/cli.mjs','utf8');fs.writeFileSync('dist/cli.mjs',c.replace('#!/usr/bin/env bun','#!/usr/bin/env node').replace('// @bun\\n',''))\"",
-    "build": "bun build --target=node --format=cjs --outfile=dist/index.js src/index.ts && bun run build:cli && bun --bun next build && node -e \"const {cpSync}=require('fs');cpSync('.next/static','.next/standalone/.next/static',{recursive:true});\" && node scripts/prune-standalone.mjs",
+    "build:worker": "bun build --target=node --format=esm --outfile=dist/worker.mjs bin/failproofai-worker.mjs --external posthog-node --external sql.js",
+    "build": "bun build --target=node --format=cjs --outfile=dist/index.js src/index.ts && bun run build:cli && bun run build:worker && bun --bun next build && node -e \"const {cpSync}=require('fs');cpSync('.next/static','.next/standalone/.next/static',{recursive:true});\" && node scripts/prune-standalone.mjs",
     "prestart": "bun run build:cli && bun link",
     "start": "FAILPROOFAI_TELEMETRY_DISABLED=1 bun scripts/start.ts",
     "test": "vitest",

package/src/hooks/builtin-policies.ts

@@ -2,6 +2,7 @@
  * Built-in security policies for Claude Code hooks.
  */
 import { resolve, join } from "node:path";
+import { statSync } from "node:fs";
 import { readFile, writeFile, stat, open } from "node:fs/promises";
 import { execSync, execFileSync } from "node:child_process";
 import { homedir } from "node:os";
@@ -240,22 +241,45 @@ const HELM_RE = /(?:^|[;\n]|&&|\|\|?|&)\s*helm(?:\s|$)/;
 // failproofai's own workflow policies depend on them.
 const GH_PIPELINE_RE = /(?:^|[;\n]|&&|\|\|?|&)\s*gh\s+(?:workflow\s+(?:run|enable|disable)|run\s+(?:rerun|cancel)|pr\s+merge|release\s+(?:create|delete)|cache\s+delete|secret\s+(?:set|delete))\b/;
 
-// Caches the current branch per cwd to avoid repeated execSync calls.
-// Trade-off: if the user switches branches externally mid-session, the cache serves
-// the stale value until the process restarts. This is acceptable since branch switches
-// during an active Claude session are rare.
-const gitBranchCache = new Map<string, string>();
+// Caches the current branch per cwd to avoid repeated execSync calls, gated
+// on .git/HEAD's mtime rather than reused unconditionally for the life of
+// the process. In the one-shot-process model that unconditional reuse cost
+// nothing (the cache never outlived a single hook call), but the daemon's
+// warm worker keeps this Map alive across many calls and potentially many
+// different projects' cwds — reusing a branch name forever would silently
+// deny/allow a Stop based on a branch the user checked out an hour ago.
+// git updates .git/HEAD's mtime on every checkout/switch, so a cheap local
+// statSync (no subprocess) is a real, precise invalidation signal. Falls
+// back to always re-fetching (no caching) when .git/HEAD can't be stat'd
+// (worktrees/submodules), matching today's behavior for that case. Bounded
+// at 500 entries so a warm worker touching many projects over its lifetime
+// doesn't grow this unboundedly.
+const gitBranchCache = new Map<string, { branch: string; headMtimeMs: number }>();
+const GIT_BRANCH_CACHE_MAX_ENTRIES = 500;
+
+function statGitHeadMtimeMs(cwd: string): number | null {
+  try {
+    return statSync(join(cwd, ".git", "HEAD")).mtimeMs;
+  } catch {
+    return null;
+  }
+}
 
 function getCurrentBranch(cwd: string): string | null {
   try {
-    let branch = gitBranchCache.get(cwd);
-    if (branch === undefined) {
-      branch = execSync("git rev-parse --abbrev-ref HEAD", {
-        cwd,
-        encoding: "utf8", stdio: ["pipe", "pipe", "pipe"],
-        timeout: 3000,
-      }).trim();
-      gitBranchCache.set(cwd, branch);
+    const headMtimeMs = statGitHeadMtimeMs(cwd);
+    const cached = gitBranchCache.get(cwd);
+    if (cached && headMtimeMs !== null && cached.headMtimeMs === headMtimeMs) {
+      return cached.branch || null;
+    }
+    const branch = execSync("git rev-parse --abbrev-ref HEAD", {
+      cwd,
+      encoding: "utf8", stdio: ["pipe", "pipe", "pipe"],
+      timeout: 3000,
+    }).trim();
+    if (headMtimeMs !== null) {
+      if (gitBranchCache.size >= GIT_BRANCH_CACHE_MAX_ENTRIES) gitBranchCache.clear();
+      gitBranchCache.set(cwd, { branch, headMtimeMs });
     }
     return branch || null;
   } catch {

package/src/hooks/configure-wizard.ts

@@ -39,6 +39,13 @@ import { POLICY_PRESETS, resolvePreset, resolveEverything } from "./policy-prese
 import { discoverPolicyFiles, findSkippedPolicyFiles } from "./custom-hooks-loader";
 import { trackHookEvent } from "./hook-telemetry";
 import { getInstanceId } from "../../lib/telemetry-id";
+import {
+  isDaemonSupportedPlatform,
+  installDaemonService,
+  daemonServiceFilePath,
+  setDaemonConfigured,
+} from "./daemon-service";
+import { hookLogWarn } from "./hook-logger";
 
 export interface WizardIO {
   stdin?: TTYIn;
@@ -263,6 +270,36 @@ export function setCustomPoliciesEnabled(
   }
 }
 
+/**
+ * Maps a daemon-install failure to one of a fixed set of codes, safe to
+ * send off the machine.
+ *
+ * `installDaemonService`'s `reason` is a diagnostic for the local log, not a
+ * telemetry field: on most failure paths it is an errno message naming an
+ * absolute path under `homedir()`, which carries the OS username. Only the
+ * classification travels.
+ */
+export function classifyDaemonInstallFailure(reason: string | undefined): string {
+  if (!reason) return "unknown";
+  if (/not supported on/.test(reason)) return "unsupported_platform";
+  if (/no prebuilt binary for/.test(reason)) return "unsupported_platform";
+  if (/binary not found/.test(reason)) return "binary_not_found";
+  // The download path is where a machine acquires the daemon at all, so its
+  // failures need to be distinguishable: a checksum mismatch is a supply-chain
+  // signal, "disabled" is a deliberate air-gapped opt-out, and a plain fetch
+  // failure is usually a proxy or an offline box — three very different
+  // stories that would otherwise all land in `service_manager_error`.
+  // The service is installed system-wide now, so "couldn't become root" is a
+  // first-class outcome with a specific remedy (re-run under sudo) rather
+  // than an opaque service_manager_error.
+  if (/root privileges are required/.test(reason)) return "needs_root";
+  if (/checksum mismatch|has no entry for/.test(reason)) return "checksum_mismatch";
+  if (/downloads are disabled/.test(reason)) return "downloads_disabled";
+  if (/failed to download/.test(reason)) return "download_failed";
+  if (/did not reach a running state/.test(reason)) return "did_not_start";
+  return "service_manager_error";
+}
+
 /**
  * Summarise the custom policy files on disk, for the review screen.
  *
@@ -322,6 +359,11 @@ export function reviewLines(state: {
   lines.push(`  Where      : ${where}`);
   lines.push(`  Assistants : ${assistantNames.length ? summarize(assistantNames, "assistants") : "(none)"}`);
   lines.push(`  Policies   : ${policies.length} enabled`);
+  if (scope === "user" && isDaemonSupportedPlatform()) {
+    lines.push(
+      `  Daemon     : failproofaid will be installed/started as a background service`,
+    );
+  }
 
   // Reflect the Custom decision, not just what is on disk. Reporting
   // "1 file (project) (auto-loaded)" after the user had just unticked the row
@@ -347,6 +389,10 @@ export function reviewLines(state: {
     }
   }
   lines.push(`    ${homeify(getConfigPathForScope(scope, cwd))}   ${policies.length} policies`);
+  if (scope === "user" && isDaemonSupportedPlatform()) {
+    const servicePath = daemonServiceFilePath();
+    if (servicePath) lines.push(`    ${homeify(servicePath)}   failproofaid service`);
+  }
   return lines;
 }
 
@@ -568,6 +614,35 @@ export async function runConfigureWizard(io: WizardIO = {}): Promise<WizardResul
     { replace: true, quiet: true },
   );
   setCustomPoliciesEnabled(scope, cwd, customEnabled);
+
+  // Daemon setup — unconditional on Linux/macOS whenever the global scope
+  // was chosen (a daemon is per-machine, not per-project), no separate
+  // opt-in step or command. A failure here (binary not found, no service
+  // manager, ...) never fails the wizard — the rest of setup already
+  // applied, and this machine simply stays on the in-process path exactly
+  // as before, since `daemonConfigured` is only set on success.
+  let daemonInstalled = false;
+  if (scope === "user" && isDaemonSupportedPlatform()) {
+    const daemonResult = await installDaemonService();
+    if (daemonResult.installed) {
+      setDaemonConfigured(true);
+      daemonInstalled = true;
+    } else {
+      hookLogWarn(`failproofaid was not installed as a service: ${daemonResult.reason}`);
+    }
+    void emit("configure_daemon_install", {
+      installed: daemonResult.installed,
+      // A bounded classification, never the raw reason: on the failure path
+      // that string is an errno message from writeFileSync/execFileSync
+      // against a homedir()-derived path, so it routinely carries the OS
+      // username and the local filesystem layout ("/home/<user>/.config/
+      // systemd/user/failproofaid.service"). The full text stays local via
+      // the hookLogWarn above.
+      reason: daemonResult.installed ? null : classifyDaemonInstallFailure(daemonResult.reason),
+      platform: process.platform,
+    });
+  }
+
   await applied;
   // Only now — a completed apply — is the launcher considered "seen", so the
   // first-run bare invocation stops redirecting here and opens the dashboard.
@@ -584,9 +659,10 @@ export async function runConfigureWizard(io: WizardIO = {}): Promise<WizardResul
       : customEnabled === false
         ? " · custom policies DISABLED"
         : "";
+  const daemonNote = daemonInstalled ? " · background daemon enabled" : "";
   const assistants = `${clis.length} assistant${clis.length === 1 ? "" : "s"}`;
   outro(
-    `Setup complete — ${policies.length} policies${customNote} · ${assistants}`,
+    `Setup complete — ${policies.length} policies${customNote} · ${assistants}${daemonNote}`,
     { ok: true },
     stdout,
   );

package/src/hooks/daemon-client.ts

@@ -0,0 +1,199 @@
+/**
+ * Thin client for talking to the failproofaid Rust daemon over its Unix
+ * socket. Used by `bin/failproofai.mjs`'s `--hook` path.
+ *
+ * Wire format matches `crates/PROTOCOL.md` exactly: one connection per
+ * 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`.
+ */
+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";
+
+const PROTOCOL_VERSION = 1;
+
+/**
+ * Reaching the daemon and getting an answer out of it are two different
+ * questions, and the caller's fail-closed policy makes conflating them
+ * expensive: on a daemon-configured machine a timeout here is a *deny*, not
+ * a fallback.
+ *
+ * `CONNECT` is the "is anything listening?" budget. Generous for a local
+ * Unix socket (sub-millisecond, no network); a daemon that can't answer an
+ * accept inside this is unhealthy, and failing fast is exactly right — this
+ * is the budget that keeps a dead daemon from adding latency to every hook.
+ *
+ * `RESPONSE` starts once the connection is established, and must cover the
+ * whole evaluation the daemon runs on our behalf: `handler.ts` allows each
+ * custom policy up to 10s, `worker-server.ts` serializes requests so one
+ * can queue behind another, and a project with many convention policies
+ * pays real file I/O on its first evaluation. Budgeting those at connect
+ * speed turned a slow-but-correct evaluation into an intermittent denial of
+ * a legitimate tool call. Matched to the daemon's own ceiling for the same
+ * roundtrip (`worker.rs` sets a 30s read timeout on the worker socket), so
+ * this side never gives up on a request the daemon is still honestly
+ * working on.
+ */
+const DAEMON_CONNECT_TIMEOUT_MS = 150;
+const DAEMON_RESPONSE_TIMEOUT_MS = 30_000;
+
+const MAX_FRAME_LEN = 16 * 1024 * 1024;
+
+export interface DaemonHookRequest {
+  hookEvent: string;
+  cli: IntegrationType;
+  stdin: string;
+  /**
+   * Best-effort cwd of the *originating* CLI process (parsed from the
+   * hook's own stdin payload by the caller) — never the daemon's or this
+   * client process's own cwd. See PROTOCOL.md's note on the process.cwd()
+   * hazard.
+   */
+  cwd?: string;
+}
+
+export interface DaemonHookResponse {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+function socketPath(): string {
+  if (process.env.FAILPROOFAI_DAEMON_SOCKET) return process.env.FAILPROOFAI_DAEMON_SOCKET;
+  return resolve(homedir(), ".failproofai", "run", "failproofaid.sock");
+}
+
+/**
+ * `true` once `failproofai config` has installed and started the daemon for
+ * this machine (global scope only — see `HooksConfig.daemonConfigured`).
+ * Deliberately a single cheap global-only file read (`readHooksConfig`),
+ * not the merged project+local+global reader — whether *this machine* has a
+ * daemon is not a per-project setting, and the merge logic doesn't know
+ * about this key at all.
+ */
+export function isDaemonConfigured(): boolean {
+  try {
+    return readHooksConfig().daemonConfigured === true;
+  } catch {
+    return false;
+  }
+}
+
+function encodeFrame(value: unknown): Buffer {
+  const body = Buffer.from(JSON.stringify(value), "utf8");
+  const header = Buffer.alloc(4);
+  header.writeUInt32BE(body.length, 0);
+  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> {
+  // 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;
+
+  return new Promise<DaemonHookResponse | null>((resolvePromise) => {
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout>;
+    const arm = (ms: number) => {
+      clearTimeout(timer);
+      timer = setTimeout(() => finish(null), 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) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.removeAllListeners();
+      socket.destroy();
+      resolvePromise(result);
+    };
+
+    const socket = createConnection({ path: socketPath() });
+    arm(DAEMON_CONNECT_TIMEOUT_MS);
+
+    let recvBuf = Buffer.alloc(0);
+    let declaredLen: number | null = null;
+
+    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);
+      socket.write(
+        encodeFrame({
+          type: "hook",
+          protocolVersion: PROTOCOL_VERSION,
+          hookEvent: req.hookEvent,
+          cli: req.cli,
+          stdin: req.stdin,
+          cwd: req.cwd,
+        }),
+      );
+    });
+
+    socket.on("data", (chunk: Buffer) => {
+      recvBuf = Buffer.concat([recvBuf, chunk]);
+
+      if (declaredLen === null) {
+        if (recvBuf.length < 4) return;
+        declaredLen = recvBuf.readUInt32BE(0);
+        if (declaredLen > MAX_FRAME_LEN) {
+          finish(null);
+          return;
+        }
+        recvBuf = recvBuf.subarray(4);
+      }
+
+      if (recvBuf.length < declaredLen) return;
+
+      const body = recvBuf.subarray(0, declaredLen);
+      let message: Record<string, unknown>;
+      try {
+        message = JSON.parse(body.toString("utf8")) as Record<string, unknown>;
+      } catch {
+        finish(null);
+        return;
+      }
+
+      if (message.protocolVersion !== PROTOCOL_VERSION) {
+        finish(null);
+        return;
+      }
+      if (
+        message.type === "hookResult" &&
+        typeof message.exitCode === "number" &&
+        typeof message.stdout === "string" &&
+        typeof message.stderr === "string"
+      ) {
+        finish({ 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);
+    });
+
+    socket.on("error", () => finish(null));
+    socket.on("close", () => finish(null));
+  });
+}

package/src/hooks/daemon-download.ts

@@ -0,0 +1,152 @@
+/**
+ * Fetches the compiled `failproofaid` binary for this platform from the
+ * GitHub Release that matches this CLI's own version.
+ *
+ * Why a download rather than a dependency: the daemon is a 4-way
+ * cross-compiled Rust binary, and shipping it through npm means four
+ * per-platform packages that every install resolves, an npm org to own the
+ * scope, and a second publish channel that can silently drift from the first
+ * (it already did — the platform packages were declared as
+ * `optionalDependencies` and never published, so every install of them 404'd).
+ * The release assets have to exist for standalone installs regardless, so
+ * pointing the CLI at the same artifacts leaves exactly one channel.
+ *
+ * The URL is *constructed*, never discovered — no API call, no `releases/latest`
+ * redirect, no rate limit, and no chance of fetching a daemon built from
+ * different source than the CLI talking to it: the tag is this package's own
+ * version, so a CLI upgrade downloads its own matching binary.
+ *
+ * Everything here fails closed and never throws. A daemon that cannot be
+ * fetched leaves the machine on the in-process path it was already using;
+ * a daemon fetched over a corrupted connection is refused outright, because
+ * this writes an executable that a service manager will then run at login.
+ */
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { version } from "../../package.json";
+import type { PlatformKey } from "./daemon-service";
+
+/**
+ * Where release assets live. Overridable so an air-gapped or proxied site can
+ * mirror the four binaries internally — and so tests can serve them from a
+ * local HTTP server without touching the network.
+ */
+const DEFAULT_BASE_URL = "https://github.com/FailproofAI/failproofai/releases/download";
+
+/**
+ * One bound for the whole fetch. Long enough for a ~2 MB asset on a slow
+ * connection, short enough that a black-holed proxy doesn't turn the config
+ * wizard into a hang — the failure mode this replaces is a user staring at a
+ * spinner with no output.
+ */
+const DOWNLOAD_TIMEOUT_MS = 60_000;
+
+function baseUrl(): string {
+  return (process.env.FAILPROOFAI_DAEMON_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, "");
+}
+
+/** Where downloaded binaries live. One directory, one file per version. */
+export function daemonBinaryDir(): string {
+  return resolve(homedir(), ".failproofai", "bin");
+}
+
+/**
+ * The path this CLI's own daemon binary occupies.
+ *
+ * Versioned on purpose. An in-place overwrite would hit `ETXTBSY` against the
+ * running daemon on Linux, and would silently repoint a service unit at a
+ * binary built from different source; a per-version filename makes an upgrade
+ * a new file plus a rewritten unit, and leaves the old one recoverable.
+ */
+export function installedBinaryPath(ver: string = version): string {
+  return resolve(daemonBinaryDir(), `failproofaid-${ver}`);
+}
+
+/** The release asset URL for a platform — constructed, never discovered. */
+export function daemonAssetUrl(key: PlatformKey, ver: string = version): string {
+  return `${baseUrl()}/v${ver}/failproofaid-${key}.gz`;
+}
+
+/** The checksum manifest published alongside the four binaries. */
+export function checksumsUrl(ver: string = version): string {
+  return `${baseUrl()}/v${ver}/SHA256SUMS`;
+}
+
+export interface DaemonDownloadResult {
+  /** Absolute path to the installed, executable binary. */
+  path?: string;
+  /** Local diagnostic — never sent off the machine verbatim. */
+  error?: string;
+}
+
+async function fetchBytes(url: string): Promise<Buffer> {
+  const response = await fetch(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+  if (!response.ok) throw new Error(`GET ${url} returned ${response.status}`);
+  return Buffer.from(await response.arrayBuffer());
+}
+
+/**
+ * Parses a `sha256sum`-format manifest and returns the digest for one asset.
+ *
+ * A missing line is an error rather than a skipped check: the manifest is the
+ * only thing standing between a truncated or substituted download and an
+ * executable this process is about to install as a login service.
+ */
+export function digestFor(manifest: string, assetName: string): string | null {
+  for (const line of manifest.split("\n")) {
+    const match = line.trim().match(/^([0-9a-f]{64})\s+\*?(.+)$/i);
+    if (match && match[2].trim() === assetName) return match[1].toLowerCase();
+  }
+  return null;
+}
+
+/**
+ * Downloads, verifies and installs the daemon binary for `key`.
+ *
+ * Idempotent: an already-installed binary for this version is returned as-is,
+ * so re-running the wizard costs nothing.
+ */
+export async function downloadFailproofaidBinary(key: PlatformKey): Promise<DaemonDownloadResult> {
+  const target = installedBinaryPath();
+  if (existsSync(target)) return { path: target };
+
+  if (process.env.FAILPROOFAI_NO_DOWNLOAD) {
+    return { error: "daemon downloads are disabled (FAILPROOFAI_NO_DOWNLOAD)" };
+  }
+
+  const assetName = `failproofaid-${key}.gz`;
+  // Same directory as the target so the install is a rename within one
+  // filesystem — atomic, and never a half-written binary a service manager
+  // could pick up. The pid keeps two concurrent wizards off each other's file.
+  const tempPath = `${target}.${process.pid}.tmp`;
+
+  try {
+    const [asset, manifest] = await Promise.all([
+      fetchBytes(daemonAssetUrl(key)),
+      fetchBytes(checksumsUrl()).then((b) => b.toString("utf8")),
+    ]);
+
+    const expected = digestFor(manifest, assetName);
+    if (!expected) {
+      return { error: `SHA256SUMS for v${version} has no entry for ${assetName}` };
+    }
+    const actual = createHash("sha256").update(asset).digest("hex");
+    if (actual !== expected) {
+      return { error: `checksum mismatch for ${assetName} (expected ${expected}, got ${actual})` };
+    }
+
+    const binary = gunzipSync(asset);
+    mkdirSync(daemonBinaryDir(), { recursive: true });
+    writeFileSync(tempPath, binary);
+    chmodSync(tempPath, 0o755);
+    renameSync(tempPath, target);
+    return { path: target };
+  } catch (err) {
+    rmSync(tempPath, { force: true });
+    const message = err instanceof Error ? err.message : String(err);
+    return { error: `failed to download failproofaid v${version} for ${key}: ${message}` };
+  }
+}