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

package/src/hooks/daemon-service.ts

@@ -1,8 +1,7 @@
 /**
- * Installs/uninstalls/checks failproofaid as a real OS-level user service
- * (systemd `--user` on Linux, launchd `LaunchAgent` on macOS) so it's
- * "constant" — starts at login, restarts on crash — without ever needing
- * elevation. User-scope only, matching the daemon itself.
+ * Installs, upgrades, checks, and removes failproofaid as a system-managed
+ * service. The definition is root-owned and starts at boot, but the daemon
+ * process itself runs as the user who configured failproofai.
  *
  * No public `failproofai daemon install`-style subcommand exists —
  * `configure-wizard.ts` calls the functions here directly, the same
@@ -18,15 +17,17 @@ import {
   rmSync,
 } from "node:fs";
 import { homedir, tmpdir, userInfo } from "node:os";
-import { resolve, dirname } from "node:path";
+import { resolve } from "node:path";
 import { execFileSync } from "node:child_process";
 import { hookLogWarn } from "./hook-logger";
-import { getConfigPathForScope } from "./hooks-config";
-import { downloadFailproofaidBinary, installedBinaryPath } from "./daemon-download";
+import { downloadFailproofaidBinary, installFromNpmPackage, installedBinaryPath } from "./daemon-download";
+import { logsDir } from "./fp-home";
+import { version } from "../../package.json";
+import { readVersionFile, updateConfig, writeVersionFile } from "./fp-config";
 
 /**
- * Every `systemctl --user` / `launchctl` call is bounded. Both talk to a
- * per-user session bus or to launchd, and a wedged session makes an
+ * Every `systemctl` / `launchctl` call is bounded. A wedged service manager
+ * makes an
  * unbounded `execFileSync` block forever — inside the interactive wizard
  * that reads as a hang with no output at all (`stdio: "ignore"`), right
  * after the user pressed "apply". A timeout throws instead, which the
@@ -36,7 +37,7 @@ const SERVICE_CMD_TIMEOUT_MS = 10_000;
 
 /**
  * How long to wait for the service manager to actually get the daemon into
- * a running state after `enable --now` / `load -w`. Both commands return as
+ * a running state after restart/load. Those commands return as
  * soon as the job is accepted, which is well before the process has proven
  * it can stay up.
  */
@@ -44,7 +45,7 @@ const SERVICE_START_TIMEOUT_MS = 5_000;
 const SERVICE_START_POLL_MS = 100;
 /**
  * How long a unit has to still be running after it first reports running.
- * `systemctl --user is-active` calls a `Type=simple` unit active the moment
+ * `systemctl is-active` calls a `Type=simple` unit active the moment
  * it forks, so a daemon that dies immediately still reports active once —
  * a single check would wave through exactly the crash-at-startup case this
  * is here to catch. Comfortably longer than the unit's `RestartSec=2`
@@ -76,25 +77,56 @@ const SUDO_PROMPT_TIMEOUT_MS = 120_000;
  * Global scope only: whether *this machine* runs a daemon is not a
  * per-project setting.
  */
-export function setDaemonConfigured(value: boolean): void {
-  const path = getConfigPathForScope("user");
-  let config: Record<string, unknown> = {};
+export function setDaemonConfigured(value: boolean, installedVersion?: string): void {
   try {
-    if (existsSync(path)) config = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
-  } catch {
-    return; // a malformed global config is the install path's problem, not ours
-  }
-  if (value) config.daemonConfigured = true;
-  else delete config.daemonConfigured;
-  try {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(config, null, 2) + "\n", "utf8");
+    updateConfig({ daemon: { configured: value } });
+    // The version lives in VERSION, not here. One file is ABOUT versions and
+    // one copy cannot disagree with itself; keeping a second in config.toml
+    // would be a field that drifts out of step with the file beside it —
+    // exactly the class of bug the single path module exists to prevent.
+    // Cleared on uninstall: a recorded binary version for a service that is no
+    // longer configured is a claim about this machine that is no longer true.
+    writeVersionFile({ daemon: value ? installedVersion : undefined, clearDaemon: !value });
   } catch {
     /* best-effort: never fail a completed setup (or uninstall) over this flag */
   }
 }
 
-export type DaemonServiceStatus = "running" | "stopped" | "not-installed" | "unsupported-platform";
+export type DaemonServiceStatus =
+  | "running"
+  | "stopped"
+  /**
+   * Installed, but systemd evaluated its `ConditionPathExists=` and refused to
+   * start it — the daemon binary or the worker script is gone.
+   *
+   * Deliberately its own state rather than folded into "stopped". "Stopped" is
+   * ambiguous on purpose (a restart in flight looks identical), which is why
+   * nothing is allowed to act destructively on it. A failed condition carries
+   * no such ambiguity: systemd has already decided this unit will not run, and
+   * will keep deciding that at every boot until the missing path returns. That
+   * is provable enough to clear `daemonConfigured` on, and leaving it
+   * indistinguishable from a transient stop is what kept a machine denying
+   * every tool call with no explanation.
+   */
+  | "condition-failed"
+  | "not-installed"
+  /**
+   * Installed, and its state could not be READ — distinct from any claim about
+   * whether it is running.
+   *
+   * Only macOS reaches this. A LaunchDaemon lives in launchd's system domain,
+   * so unlike `systemctl is-active` (which any user can run against a system
+   * unit) reading its state needs the same elevation installing it did, and the
+   * CLI will not prompt for a password from under a TUI. An expired sudo cache
+   * — five minutes by default — therefore means "cannot check", and folding
+   * that into "stopped" made a perfectly healthy daemon look dead: the wizard
+   * then demanded sudo and bounced the service, which on a `daemonConfigured`
+   * machine is a real fail-closed window, to fix nothing. Callers that need the
+   * truth should ask the daemon itself (`probeDaemonEndToEnd`), which needs no
+   * privileges at all.
+   */
+  | "unknown"
+  | "unsupported-platform";
 
 /** Linux + macOS only, per the plan's platform scope — full stop. */
 export function isDaemonSupportedPlatform(): boolean {
@@ -145,13 +177,19 @@ export function resolveFailproofaidBinaryPath(): string | null {
 }
 
 /**
- * Resolves the binary, downloading it from this version's release if it is
- * not already on disk.
+ * Resolves the binary, installing one if it is not already on disk.
  *
- * Only the install path calls this. The npm package ships no binary — it is
- * one CLI tarball for every platform — so `failproofai config` choosing the
- * global scope is the moment a machine that opted into a daemon actually
- * acquires one.
+ * Only the install path calls this — `failproofai config` choosing the global
+ * scope is the moment a machine that opted into a daemon actually acquires
+ * one. Two channels, in this order:
+ *
+ *   1. The `@failproofai/failproofaid-<os>-<arch>` platform package, which a
+ *      plain `npm install failproofai` already brought down as an optional
+ *      dependency. No network, so it is also the only channel that works
+ *      air-gapped or behind a proxy that blocks github.com.
+ *   2. The GitHub Release asset for this exact version, checksum-verified.
+ *      Covers installs that skipped optional dependencies, older tarballs, and
+ *      anyone installing the daemon standalone.
  */
 export async function ensureFailproofaidBinary(): Promise<{ path?: string; reason?: string }> {
   const existing = resolveFailproofaidBinaryPath();
@@ -162,9 +200,18 @@ export async function ensureFailproofaidBinary(): Promise<{ path?: string; reaso
     return { reason: `failproofaid has no prebuilt binary for ${process.platform}/${process.arch}` };
   }
 
+  const fromNpm = installFromNpmPackage(key);
+  if (fromNpm.path) return { path: fromNpm.path };
+
   const result = await downloadFailproofaidBinary(key);
   if (result.path) return { path: result.path };
-  return { reason: result.error ?? "failproofaid binary could not be downloaded" };
+  // Both channels are worth reporting: "not installed" alone reads as a broken
+  // package, and the download error alone hides that npm could have supplied it.
+  return {
+    reason: result.error
+      ? `${result.error} (${fromNpm.error})`
+      : "failproofaid binary could not be installed",
+  };
 }
 
 /**
@@ -210,12 +257,116 @@ export function resolveWorkerCommand(): string | null {
   return `${shellQuote(process.execPath)} ${shellQuote(workerScript)}`;
 }
 
+/**
+ * Resolves the command the daemon should use to run a one-shot `failproofai`
+ * CLI task — today the scheduled audit — passed through as
+ * `FAILPROOFAI_CLI_CMD` in the service's own environment.
+ *
+ * Everything `resolveWorkerCommand` says about `process.execPath` and the
+ * shell quoting applies here verbatim, for the same reason: a system-scope
+ * unit gets no login environment, so its PATH is the system default, and the
+ * single most common Node install (nvm) is on no system PATH. The difference
+ * is the consequence of getting it wrong. A worker that cannot start makes the
+ * daemon visibly unhealthy; an audit that cannot start is SILENT — the config
+ * says the scan is on, nothing ever runs, and the only symptom is a dashboard
+ * that quietly stops moving.
+ *
+ * `dist/cli.mjs` (package.json's `bin.failproofai`), not `bin/failproofai.mjs`
+ * — the latter has a `#!/usr/bin/env bun` shebang and uses syntax node cannot
+ * load (a bare `import … from "../package.json"`, extensionless `.ts`
+ * specifiers). Only the bundle is node-runnable, and it sits beside the
+ * `dist/worker.mjs` the worker command already points at.
+ */
+export function resolveCliCommand(): string | null {
+  if (process.env.FAILPROOFAI_CLI_CMD) return process.env.FAILPROOFAI_CLI_CMD;
+
+  const packageRoot = process.env.FAILPROOFAI_PACKAGE_ROOT;
+  if (!packageRoot) return null;
+  const cliScript = resolve(packageRoot, "dist", "cli.mjs");
+  if (!existsSync(cliScript)) return null;
+  return `${shellQuote(process.execPath)} ${shellQuote(cliScript)}`;
+}
+
 /** POSIX single-quoting: everything is literal inside '…', and a literal
  *  quote is closed, escaped and reopened. */
 function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
+/**
+ * The raw, unquoted path to the worker script the service will run — the same
+ * file `resolveWorkerCommand` builds its shell command around.
+ *
+ * It exists separately because the unit needs the path as a PATH (for
+ * `ConditionPathExists=`), not as a shell word, and recovering one from the
+ * other means unparsing POSIX quoting for a value we already had.
+ *
+ * Returns null when `FAILPROOFAI_WORKER_CMD` is set: that value is an arbitrary
+ * shell command — a wrapper script, an interpreter with flags, `exec`ing
+ * something else entirely — and guessing which token in it is "the file that
+ * must exist" would gate the service on a path nobody promised. An absent
+ * condition is the correct answer to a question we cannot answer.
+ */
+export function workerScriptPath(): string | null {
+  if (process.env.FAILPROOFAI_WORKER_CMD) return null;
+  const packageRoot = process.env.FAILPROOFAI_PACKAGE_ROOT;
+  if (!packageRoot) return null;
+  const workerScript = resolve(packageRoot, "dist", "worker.mjs");
+  return existsSync(workerScript) ? workerScript : null;
+}
+
+/**
+ * The environment the service definition carries, built once so the systemd
+ * and launchd renderers cannot drift apart — a variable added to one and not
+ * the other is invisible until somebody runs the other platform.
+ *
+ * Order is fixed rather than incidental: `upgradedServiceDefinition` rebuilds
+ * a definition from these renderers, so a stable order is what makes a
+ * rewritten unit byte-identical to a freshly installed one rather than merely
+ * equivalent — which is the difference between a diff a human can read and one
+ * they stop reading.
+ */
+/**
+ * Characters that cannot appear in a value interpolated into a systemd unit.
+ *
+ * A newline ENDS THE DIRECTIVE, so a path containing one injects arbitrary
+ * settings into a file that is installed root-owned at `/etc/systemd/system`
+ * and loaded at every boot. A double quote closes `Environment="..."` early and
+ * does the same; a backslash is systemd's own escape character inside a quoted
+ * value and makes the result unpredictable rather than merely wrong.
+ *
+ * The mechanism is demonstrated by this repo's own test, which sets
+ * `FAILPROOFAI_CLI_CMD` to `/usr/bin/true"\nUser=failproofai-no-such-user` and
+ * relies on systemd HONOURING the injected `User=` — it passes only because the
+ * injected user does not exist. A valid one (`User=root`, or an added
+ * `ExecStartPre=`) would have succeeded silently, undoing the
+ * "root-installed but never root-run" invariant the whole design rests on.
+ *
+ * These values are resolved paths and commands; none can legitimately contain
+ * any of these characters. So this REJECTS rather than escaping — a unit that
+ * refuses to be written is a clear failure, and inventing an escaping scheme
+ * for systemd's grammar is a larger surface than the problem.
+ */
+const UNIT_UNSAFE_RE = /["\\\r\n]/;
+
+/** Throws when a value cannot be safely interpolated into a unit file. */
+function assertUnitSafe(value: string, field: string): string {
+  if (UNIT_UNSAFE_RE.test(value)) {
+    throw new Error(
+      `refusing to write a service definition: ${field} contains a quote, backslash or newline ` +
+        `(${JSON.stringify(value)}), which would inject directives into a root-owned unit file`,
+    );
+  }
+  return value;
+}
+
+function serviceEnvironment(workerCmd: string | null, cliCmd: string | null): [string, string][] {
+  const entries: [string, string][] = [];
+  if (workerCmd) entries.push(["FAILPROOFAI_WORKER_CMD", workerCmd]);
+  if (cliCmd) entries.push(["FAILPROOFAI_CLI_CMD", cliCmd]);
+  return entries;
+}
+
 /**
  * The account the daemon runs as. The service is root-*installed* but never
  * root-*run*: everything it touches (the socket, the lock, the policy config)
@@ -240,8 +391,25 @@ function systemdUnitName(user: string = serviceUser()): string {
   return `failproofaid@${user}.service`;
 }
 
+/**
+ * The unit directory, redirectable for tests ONLY.
+ *
+ * It was hardcoded, which left a test asserting "a failed install writes
+ * nothing" checking the REAL `/etc/systemd/system` — so it passed in CI, where
+ * nothing is installed, and failed on the machine of anyone who actually uses
+ * failproofai, whose genuine unit file is sitting right there. That is the bug
+ * class `handler.test.ts`'s header already documents: CI is green, so the red is
+ * only ever seen locally, by exactly the people who most need to trust the suite.
+ *
+ * Read through a function rather than captured at module load, because a test
+ * sets it after importing this module.
+ */
+function systemdUnitDir(): string {
+  return process.env.FAILPROOFAI_SYSTEMD_DIR || "/etc/systemd/system";
+}
+
 function systemdUnitPath(user: string = serviceUser()): string {
-  return resolve("/etc/systemd/system", systemdUnitName(user));
+  return resolve(systemdUnitDir(), systemdUnitName(user));
 }
 
 /**
@@ -306,6 +474,22 @@ export function daemonStatusCommand(): string | null {
     : `sudo launchctl print system/${launchdLabel()}`;
 }
 
+/**
+ * The command that restarts the daemon, for the places where a config change
+ * only takes effect on the next start.
+ *
+ * `--disconnect` is the motivating case: the collector manager starts once for
+ * the daemon's lifetime and the uploader caches its bearer key at construction,
+ * so removing the credential file changes nothing about the process already
+ * running.
+ */
+export function daemonRestartCommand(): string | null {
+  if (!isDaemonSupportedPlatform()) return null;
+  return process.platform === "linux"
+    ? `sudo systemctl restart ${systemdUnitName()}`
+    : `sudo launchctl kickstart -k system/${launchdLabel()}`;
+}
+
 /**
  * Acquires sudo credentials up front, prompting in the terminal if needed.
  *
@@ -337,8 +521,16 @@ export function primeElevation(): boolean {
   }
 }
 
-/** True when privileged commands can run without prompting for a password. */
-function canElevate(): boolean {
+/**
+ * True when privileged commands can run without prompting for a password.
+ *
+ * Exported because onboarding re-checks it: `needs_root` is the most common
+ * reason setup aborts, and it is the one most likely to stop being true (the
+ * user gets sudo rights, or primes their timestamp in another terminal). One
+ * `sudo -n true`, no prompt, milliseconds — and never on the hook path, which
+ * does not reach the first-run gate at all.
+ */
+export function canElevate(): boolean {
   if (typeof process.getuid === "function" && process.getuid() === 0) return true;
   try {
     execFileSync("sudo", ["-n", "true"], { stdio: "ignore", timeout: SERVICE_CMD_TIMEOUT_MS });
@@ -442,24 +634,79 @@ function removeLegacyUserService(): void {
   }
 }
 
-export function systemdUnitContents(binaryPath: string, workerCmd: string | null): string {
-  // Quoted because both values contain a space or a path — systemd's
+export function systemdUnitContents(
+  binaryPath: string,
+  workerCmd: string | null,
+  cliCmd: string | null = null,
+): string {
+  // Quoted because every value here contains a space or a path — systemd's
   // Environment= requires quoting whenever the value does.
-  const envLine = workerCmd ? `Environment="FAILPROOFAI_WORKER_CMD=${workerCmd}"\n` : "";
-  const user = serviceUser();
+  const envLines = serviceEnvironment(workerCmd, cliCmd)
+    .map(([key, value]) => `Environment="${key}=${assertUnitSafe(value, key)}"\n`)
+    .join("");
+  const user = assertUnitSafe(serviceUser(), "User");
+  assertUnitSafe(binaryPath, "ExecStart");
+  assertUnitSafe(homedir(), "HOME");
+
+  // Gate the unit on the two files it cannot run without, so that an install
+  // which is no longer there STOPS rather than thrashes.
+  //
+  // `npm rm -g failproofai` is the case this is for, and npm runs no uninstall
+  // script — see the note on `failproofai uninstall`. It deletes the package,
+  // which takes `dist/worker.mjs` with it, while the daemon binary under
+  // ~/.failproofai survives. Without a condition systemd keeps a daemon alive
+  // whose worker cannot spawn; with a deleted BINARY it is worse, because
+  // ExecStart fails 203/EXEC under `Restart=on-failure` and cycles until it
+  // trips the start-limit and latches into "start request repeated too
+  // quickly" — a state that then refuses a legitimate restart later.
+  //
+  // A failed condition is not a failure: systemd SKIPS the job, leaves the unit
+  // inactive, and `systemctl status` names the exact path that was missing.
+  // That turns an unexplained crash-loop into a one-line diagnosis, and
+  // `daemonServiceStatus()` reads it back as `condition-failed` so the next CLI
+  // command can clear `daemonConfigured` instead of leaving the machine denying
+  // every tool call.
+  //
+  // This deliberately does NOT soften the hook path's fail-closed deny. A
+  // machine that was configured to require the daemon still denies while the
+  // daemon is absent — being skipped by systemd is not consent to stop
+  // enforcing. It shortens how long that lasts and explains why.
+  // Only paths that EXIST right now are gated on, and that filter is load-
+  // bearing rather than belt-and-braces.
+  //
+  // `binaryPath` is an ExecStart value, not necessarily a bare path: systemd
+  // accepts arguments there, and `FAILPROOFAI_DAEMON_BINARY` is documented as
+  // "someone named a binary explicitly" — this repo's own systemd tests set it
+  // to `/usr/bin/sleep infinity`. `ConditionPathExists=` takes a PATH, so
+  // gating on that string looks for a file literally named "sleep infinity",
+  // never finds it, and skips a unit that would have run perfectly. Splitting
+  // on whitespace to recover the binary is worse, because a path may legally
+  // contain spaces and there is no way to tell the two apart from here.
+  //
+  // Existence at render time answers it without guessing: a real binary is on
+  // disk when its unit is written (installDaemonService just put it there), and
+  // a command-with-arguments is not. Same rule the worker script already
+  // follows — never gate on a path that is not there, or the freshly installed
+  // unit skips on its very first start.
+  const conditionPaths = [binaryPath, workerScriptPath()].filter(
+    (p): p is string => typeof p === "string" && existsSync(p),
+  );
+  const conditionLines = conditionPaths
+    .map((p) => `ConditionPathExists=${assertUnitSafe(p, "ConditionPathExists")}\n`)
+    .join("");
+
   return `[Unit]
 Description=failproofai background daemon (failproofaid) for ${user}
 After=network.target
-
+${conditionLines}
 [Service]
 Type=simple
 User=${user}
 # Set explicitly rather than relying on systemd deriving it from User=:
-# failproofaid is user-scope by construction and refuses to start without
-# HOME ("HOME is not set; failproofaid is user-scope only"), so the one
-# variable it cannot do without is not left to a version-dependent default.
+# failproofaid stores per-user state and refuses to start without HOME, so this
+# required variable is not left to a version-dependent default.
 Environment="HOME=${homedir()}"
-${envLine}ExecStart=${binaryPath}
+${envLines}ExecStart=${binaryPath}
 Restart=on-failure
 RestartSec=2
 
@@ -475,12 +722,27 @@ function escapeXml(s: string): string {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
-function launchdPlistContents(binaryPath: string, logDir: string, workerCmd: string | null): string {
-  const envBlock = workerCmd
+function unescapeXml(s: string): string {
+  // &amp; last, or an escaped `&amp;lt;` would come back as `<`.
+  return s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+}
+
+/**
+ * Exported for the same reason `systemdUnitContents` is: it is the only way to
+ * assert the plist's shape from a Linux CI runner, and this is the half of the
+ * pair no Linux test run can otherwise reach.
+ */
+export function launchdPlistContents(
+  binaryPath: string,
+  logDir: string,
+  workerCmd: string | null,
+  cliCmd: string | null = null,
+): string {
+  const env = serviceEnvironment(workerCmd, cliCmd);
+  const envBlock = env.length
     ? `    <key>EnvironmentVariables</key>
     <dict>
-        <key>FAILPROOFAI_WORKER_CMD</key>
-        <string>${escapeXml(workerCmd)}</string>
+${env.map(([key, value]) => `        <key>${key}</key>\n        <string>${escapeXml(value)}</string>`).join("\n")}
     </dict>
 `
     : "";
@@ -523,12 +785,21 @@ export interface DaemonInstallResult {
  * machine that cannot elevate can be told exactly what to run rather than
  * just that something failed.
  */
-function daemonInstallCommands(binaryPath: string, workerCmd: string | null): string[] {
+function daemonInstallCommands(
+  binaryPath: string,
+  workerCmd: string | null,
+  cliCmd: string | null,
+): string[] {
   if (process.platform === "linux") {
     return [
-      `sudo tee ${systemdUnitPath()} <<'EOF'\n${systemdUnitContents(binaryPath, workerCmd)}EOF`,
+      `sudo tee ${systemdUnitPath()} <<'EOF'\n${systemdUnitContents(binaryPath, workerCmd, cliCmd)}EOF`,
       "sudo systemctl daemon-reload",
-      `sudo systemctl enable --now ${systemdUnitName()}`,
+      `sudo systemctl enable ${systemdUnitName()}`,
+      // `restart`, not `enable --now`, for the reason the install path gives:
+      // `--now` does nothing to an already-active unit, and these commands are
+      // handed to someone whose daemon may well be running — an upgrade is the
+      // most likely reason they are reading them.
+      `sudo systemctl restart ${systemdUnitName()}`,
     ];
   }
   return [
@@ -538,18 +809,23 @@ function daemonInstallCommands(binaryPath: string, workerCmd: string | null): st
 }
 
 /**
- * Writes and enables the service unit, starting it immediately. Safe to
- * call repeatedly — re-running replaces the unit file (picking up a
- * changed binary path after an upgrade) and re-enables it.
+ * Writes and enables the service unit, and leaves the machine running THAT
+ * unit — not merely a unit.
+ *
+ * Safe to call repeatedly: re-running replaces the unit file (picking up a
+ * changed binary path after an upgrade) and restarts the service so the
+ * running process is the one the file describes. It used to say it did that
+ * and did not: `enable --now` is a no-op against an active unit, so every
+ * reinstall over a live daemon rewrote the file and left the old process in
+ * place. See the `restartSystemdUnit()` call below.
  */
 export async function installDaemonService(): Promise<DaemonInstallResult> {
   if (!isDaemonSupportedPlatform()) {
     return { installed: false, reason: `failproofaid is not supported on ${process.platform} yet` };
   }
 
-  // May reach the network: the npm package carries no binary, so this is
-  // where a machine opting into the daemon fetches the one built for its
-  // platform from this version's release.
+  // May reach the network when the matching optional platform package is not
+  // installed. The GitHub release asset is the verified fallback channel.
   const { path: binaryPath, reason: binaryReason } = await ensureFailproofaidBinary();
   if (!binaryPath) {
     return { installed: false, reason: binaryReason ?? "failproofaid binary not found for this platform" };
@@ -562,6 +838,11 @@ export async function installDaemonService(): Promise<DaemonInstallResult> {
   // environment is what makes a *service-managed* daemon actually find its
   // worker regardless of what cwd the service manager starts it from.
   const workerCmd = resolveWorkerCommand();
+  // Same best-effort footing as the worker command, and null is survivable in
+  // the same way — the daemon just has no way to run an audit. Unlike the
+  // worker, there is no relative-path fallback to degrade to, which is exactly
+  // why it is resolved here where FAILPROOFAI_PACKAGE_ROOT is reliably set.
+  const cliCmd = resolveCliCommand();
 
   // The service is installed system-wide, which needs root. Check before
   // writing anything, so a machine that cannot elevate gets the exact
@@ -573,7 +854,7 @@ export async function installDaemonService(): Promise<DaemonInstallResult> {
         "root privileges are required to install the failproofaid system service, and sudo credentials were not available. " +
         "Re-run `failproofai config` and approve the sudo prompt — do NOT run the CLI itself under sudo, which would " +
         "configure root's account instead of yours. To install by hand: " +
-        daemonInstallCommands(binaryPath, workerCmd).join(" && "),
+        daemonInstallCommands(binaryPath, workerCmd, cliCmd).join(" && "),
     };
   }
 
@@ -585,12 +866,36 @@ export async function installDaemonService(): Promise<DaemonInstallResult> {
 
   try {
     if (process.platform === "linux") {
-      writePrivilegedFile(systemdUnitPath(), systemdUnitContents(binaryPath, workerCmd));
+      writePrivilegedFile(systemdUnitPath(), systemdUnitContents(binaryPath, workerCmd, cliCmd));
       runPrivileged("systemctl", ["daemon-reload"]);
-      runPrivileged("systemctl", ["enable", "--now", systemdUnitName()]);
+      // `enable` for boot persistence, then `restart` — NOT `enable --now`.
+      //
+      // `--now` starts a unit that is stopped and does NOTHING to one that is
+      // already active. So on every install over a live daemon it returned
+      // success having changed nothing, and the machine kept running the OLD
+      // binary from the OLD unit — the same trap `ensureDaemonServiceCurrent`
+      // already documents and avoids, which this path never inherited.
+      //
+      // Version skew is where that mattered. The wizard's `daemonBroken` is
+      // `daemonUpToDate && !daemonAnswers`, and `daemonUpToDate` requires
+      // `daemonSkew === null`, so skew can never set it — the
+      // uninstall-then-reinstall path does not fire and this install runs
+      // straight over the still-live old process. `probeDaemon()` then reads a
+      // protocol-mismatch reply from that survivor as `ok`, deliberately,
+      // because it is "acted on elsewhere" — elsewhere being here. The CLI
+      // recorded `daemonConfigured` at the NEW version, and
+      // `pruneOldDaemonBinaries()` was then free to delete the binary the
+      // running process had been started from. The documented recovery for a
+      // `PROTOCOL_VERSION` bump (`npm update -g failproofai` → `failproofai
+      // config`) therefore left the machine exactly as skewed as it began.
+      //
+      // `restart` also covers the fresh-install case: it starts a unit that is
+      // not running, so this is strictly `--now` plus the case `--now` missed.
+      runPrivileged("systemctl", ["enable", systemdUnitName()]);
+      restartSystemdUnit();
     } else {
       const plistPath = launchdPlistPath();
-      const logDir = resolve(homedir(), ".failproofai", "logs");
+      const logDir = logsDir();
       mkdirSync(logDir, { recursive: true });
       // Unload any previously-loaded copy first — reloading with a changed
       // binary path (e.g. after an upgrade) is a no-op under plain `load`
@@ -600,7 +905,7 @@ export async function installDaemonService(): Promise<DaemonInstallResult> {
       } catch {
         // Wasn't loaded — fine, this is the common case on a fresh install.
       }
-      writePrivilegedFile(plistPath, launchdPlistContents(binaryPath, logDir, workerCmd));
+      writePrivilegedFile(plistPath, launchdPlistContents(binaryPath, logDir, workerCmd, cliCmd));
       runPrivileged("launchctl", ["load", "-w", plistPath]);
     }
   } catch (err) {
@@ -621,23 +926,550 @@ export async function installDaemonService(): Promise<DaemonInstallResult> {
     hookLogWarn(`daemon service install failed: ${reason}`);
     return { installed: false, reason };
   }
+
+  // NOTE: this reports that the SERVICE is installed and running, which is all
+  // it can honestly claim. Whether the daemon can actually evaluate a hook is a
+  // separate question, answered by `probeDaemonEndToEnd()` — and the caller
+  // must ask it before setting `daemonConfigured`, because that flag is what
+  // makes an unanswering daemon deny every tool call. `configure-wizard.ts`
+  // does exactly that. Keeping the two apart matters: "the unit was written and
+  // systemd started it" is testable against a stub binary, and folding the
+  // probe in here would mean this function could never be tested without a real
+  // failproofaid.
   return { installed: true };
 }
 
 /**
- * Waits for the service to report running, then re-checks after a settle
- * window (see `SERVICE_SETTLE_MS`) so a daemon that dies at startup doesn't
- * pass on the strength of one optimistic reading.
+ * How long the health probe waits for the daemon to answer a real hook.
+ *
+ * Far below the hook path's 30s: this runs from an interactive command, and
+ * the cold start it is most likely to be waiting on (`worker.rs` pre-warms the
+ * worker, ~700ms of Node startup) is comfortably inside it. A daemon that
+ * cannot answer a trivial event in this long is not one to hand a machine's
+ * fail-closed enforcement to.
  */
-async function waitForDaemonRunning(): Promise<boolean> {
-  const deadline = Date.now() + SERVICE_START_TIMEOUT_MS;
+const DAEMON_PROBE_TIMEOUT_MS = 5_000;
+
+/**
+ * How long the probe keeps waiting for the socket to come up before calling the
+ * daemon unreachable. Generous on purpose: this runs once, from an interactive
+ * setup command, and the cost of being impatient is aborting setup at a machine
+ * whose daemon is merely still starting.
+ */
+const DAEMON_PROBE_READY_TIMEOUT_MS = 10_000;
+const DAEMON_PROBE_RETRY_MS = 150;
+
+/**
+ * Ask the daemon to evaluate a real hook, end to end.
+ *
+ * The thing this catches that nothing else did: a unit that is *running* while
+ * the worker behind it cannot start. `ExecStart` bakes in `process.execPath`
+ * and an absolute `dist/worker.mjs`, so an `nvm uninstall 20` leaves a service
+ * systemd reports as perfectly active and a worker that dies on every spawn.
+ * Every existing check passes that machine — `waitForDaemonRunning()` asks the
+ * service manager, `Ping` is answered in `server.rs` without ever touching the
+ * worker, a null `resolveWorkerCommand()` is treated as best-effort, and
+ * `Worker::warm()` swallows its own failure. `daemonConfigured` then gets set,
+ * and because that flag makes every hook fail closed, the machine denies every
+ * tool call across all 12 CLIs — including `UserPromptSubmit`, so the user
+ * cannot even talk to their agent to ask why.
+ *
+ * `SessionStart` rather than a tool event: it traverses the identical path
+ * (socket → daemon → worker → `evaluateHookEvent`) but describes nothing a
+ * policy would deny and records no tool decision, so probing cannot itself
+ * change what the machine does.
+ */
+export type DaemonProbe =
+  | { ok: true }
+  | {
+      ok: false;
+      /**
+       * `unreachable` — nothing ever accepted a connection on the socket.
+       * `worker`      — the daemon accepted a connection but could not answer a
+       *                 hook, which is the worker failing to run.
+       *
+       * Kept apart because the remedies are different, and because reporting
+       * "your worker will not start" at someone whose worker is fine sends them
+       * to inspect a healthy process. `DaemonFailure` cannot make this
+       * distinction: it reports `unreachable` for a refused connection AND for
+       * a request that was accepted and never answered.
+       */
+      reason: "unreachable" | "worker";
+    };
+
+/**
+ * Ask the daemon to evaluate a real hook, end to end.
+ *
+ * The thing this catches that nothing else did: a unit that is *running* while
+ * the worker behind it cannot start. `ExecStart` bakes in `process.execPath`
+ * and an absolute `dist/worker.mjs`, so an `nvm uninstall 20` leaves a service
+ * systemd reports as perfectly active and a worker that dies on every spawn.
+ *
+ * **Why this retries.** It is called moments after `systemctl enable --now`, and
+ * a `Type=simple` unit is reported ACTIVE the instant systemd forks it — before
+ * the daemon has bound its socket. A single attempt therefore raced the bind
+ * and, because the hook path's connect budget is deliberately 150ms, lost that
+ * race on any loaded machine. Setup then aborted with "its worker process could
+ * not be run" at a daemon that was seconds away from serving happily — the
+ * worker had already logged that it was listening. Waiting for the socket is
+ * the fix; relaxing the 150ms is NOT, because that budget is what keeps a dead
+ * daemon from adding latency to every tool call on the hook path.
+ */
+export async function probeDaemon(): Promise<DaemonProbe> {
+  try {
+    const { attemptDaemonHook, daemonAcceptsConnections } = await import("./daemon-client");
+    const deadline = Date.now() + DAEMON_PROBE_READY_TIMEOUT_MS;
+    let everConnected = false;
+
+    for (;;) {
+      if (await daemonAcceptsConnections()) {
+        everConnected = true;
+        const attempt = await attemptDaemonHook(
+          {
+            hookEvent: "SessionStart",
+            cli: "claude",
+            stdin: JSON.stringify({
+              hook_event_name: "SessionStart",
+              source: "failproofai-health-probe",
+            }),
+          },
+          { responseTimeoutMs: DAEMON_PROBE_TIMEOUT_MS },
+        );
+        // A protocol mismatch is a REACHABLE daemon of the wrong vintage, which
+        // is a version problem rather than the lockout this probe exists to
+        // find. It is reported, and acted on, elsewhere.
+        if (attempt.ok || attempt.failure === "protocol-mismatch") return { ok: true };
+      }
+      if (Date.now() >= deadline) break;
+      await new Promise((r) => setTimeout(r, DAEMON_PROBE_RETRY_MS));
+    }
+    return { ok: false, reason: everConnected ? "worker" : "unreachable" };
+  } catch {
+    return { ok: false, reason: "unreachable" };
+  }
+}
+
+/**
+ * "Is anything listening on the daemon socket?" — never throws.
+ *
+ * Split out because `waitForDaemonRunning` needs the connect check WITHOUT the
+ * hook evaluation: it runs inside a settle loop, and a failed import or a
+ * transient refusal there must read as "not yet", never as an error.
+ */
+async function daemonAcceptsConnectionsQuietly(): Promise<boolean> {
+  try {
+    const { daemonAcceptsConnections } = await import("./daemon-client");
+    return await daemonAcceptsConnections();
+  } catch {
+    return false;
+  }
+}
+
+/** Boolean form, for callers that only branch on healthy/not. */
+export async function probeDaemonEndToEnd(): Promise<boolean> {
+  return (await probeDaemon()).ok;
+}
+
+/**
+ * Waits for the service to report running and to HOLD it — a `Type=simple` unit
+ * is active the moment it forks, so one optimistic reading passes a daemon that
+ * died at startup.
+ *
+ * WATCHED, not slept through. This used to sleep `SERVICE_SETTLE_MS` blind and
+ * read the status once at the end, which was wrong in both directions on a
+ * healthy machine and a broken one:
+ *
+ *   • Healthy: the socket is up in ~13ms and answers a real hook in ~125ms, and
+ *     setup still sat there for the remaining ~600ms with the answer already in
+ *     hand. Setup runs this twice on the repair path (uninstall, reinstall), so
+ *     it was over a second of dead wait every time.
+ *   • Broken: a daemon that died at 100ms was not noticed until 750ms, because
+ *     nothing looked until the sleep was over.
+ *
+ * Now the window is polled. Leaving `running` at any point fails immediately,
+ * and the wait ends early once the daemon has answered a real hook — a reply is
+ * strictly stronger evidence of "did not die at startup" than "still active
+ * after an arbitrary sleep", which is all the settle ever established.
+ */
+export interface WaitForDaemonDeps {
+  status?: () => DaemonServiceStatus;
+  accepts?: () => Promise<boolean>;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+}
+
+export async function waitForDaemonRunning(deps: WaitForDaemonDeps = {}): Promise<boolean> {
+  const status = deps.status ?? daemonServiceStatus;
+  const accepts = deps.accepts ?? daemonAcceptsConnectionsQuietly;
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const now = deps.now ?? Date.now;
+
+  const deadline = now() + SERVICE_START_TIMEOUT_MS;
   for (;;) {
-    if (daemonServiceStatus() === "running") break;
-    if (Date.now() >= deadline) return false;
-    await new Promise((r) => setTimeout(r, SERVICE_START_POLL_MS));
+    if (status() === "running") break;
+    if (now() >= deadline) return false;
+    await sleep(SERVICE_START_POLL_MS);
+  }
+
+  const settleUntil = now() + SERVICE_SETTLE_MS;
+  for (;;) {
+    // A unit that has left `running` is dead now; there is nothing to wait out.
+    if (status() !== "running") return false;
+    // A daemon that accepted a connection is a daemon that got past startup and
+    // bound its socket. Deliberately the CHEAP check, not a full hook
+    // evaluation: `probeDaemon` runs the end-to-end one moments later, and
+    // paying for it twice is what this rewrite exists to stop.
+    if (await accepts()) return true;
+    if (now() >= settleUntil) return true;
+    await sleep(SERVICE_START_POLL_MS);
+  }
+}
+
+// ── Upgrading a service definition that predates a variable ──────────────────
+//
+// A machine that installed the daemon before `FAILPROOFAI_CLI_CMD` existed
+// keeps its old unit forever: `npm i -g failproofai@latest` replaces the CLI
+// and never touches /etc/systemd/system, and the wizard's own "already
+// installed and running — leaving it alone" branch skips it too. The daemon
+// then has no way to spawn an audit while `config.toml` says the scheduled
+// scan is on, and nothing anywhere reports a fault. This is the single most
+// likely way the whole feature ends up dead on real machines, so it gets an
+// explicit detect-and-rewrite rather than an assumption that reinstalls happen.
+
+/** Reads the installed unit / plist, or null when no service is installed. */
+function readInstalledServiceDefinition(): string | null {
+  if (!isDaemonSupportedPlatform()) return null;
+  const path = daemonServiceFilePath();
+  if (!path || !existsSync(path)) return null;
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    // Unreadable is not "absent": claiming no service is installed would let a
+    // caller reinstall over something it cannot see. Treated as "nothing to
+    // upgrade" by the one caller below, which is the inert direction.
+    return null;
   }
-  await new Promise((r) => setTimeout(r, SERVICE_SETTLE_MS));
-  return daemonServiceStatus() === "running";
+}
+
+/**
+ * Reads one variable back out of an installed service definition.
+ *
+ * Used to carry values FORWARD across a rewrite. A rewrite resolves each
+ * command from this process, and a resolution that comes back null (no
+ * `FAILPROOFAI_PACKAGE_ROOT`, a `dist/` that moved) must never be allowed to
+ * silently DELETE a working line from a working unit — the rewrite exists to
+ * add a variable, not to drop one.
+ */
+function installedEnvValue(definition: string, name: string): string | null {
+  if (process.platform === "linux") {
+    const m = new RegExp(`^Environment="${name}=(.*)"$`, "m").exec(definition);
+    return m ? m[1] : null;
+  }
+  const m = new RegExp(`<key>${name}</key>\\s*<string>([^<]*)</string>`).exec(definition);
+  return m ? unescapeXml(m[1]) : null;
+}
+
+/**
+ * The binary an installed definition currently starts.
+ *
+ * Preserved across a rewrite rather than re-resolved, because the two disagree
+ * in exactly the upgrade case this is for: `installedBinaryPath()` is
+ * version-stamped (`failproofaid-<version>`), so right after a CLI upgrade the
+ * binary for the NEW version is not on disk yet and resolution returns null,
+ * while the unit still points at the older binary that is there and running.
+ * Re-resolving would either refuse to rewrite or repoint a live service at a
+ * file that does not exist.
+ */
+function installedExecStart(definition: string): string | null {
+  if (process.platform === "linux") {
+    const m = /^ExecStart=(.+)$/m.exec(definition);
+    return m ? m[1].trim() : null;
+  }
+  const m = /<key>ProgramArguments<\/key>\s*<array>\s*<string>([^<]*)<\/string>/.exec(definition);
+  return m ? unescapeXml(m[1]) : null;
+}
+
+/**
+ * True when a service IS installed but its definition predates
+ * `FAILPROOFAI_CLI_CMD`.
+ *
+ * Deliberately a content check against the definition on disk, not a version
+ * number mirrored into `config.toml`. The mirror is the tempting shape — it is
+ * how `daemon.installed_version` is modelled — but that field is declared,
+ * read and cleared and has never once been WRITTEN (both `setDaemonConfigured`
+ * call sites pass no version), which is precisely how a mirror fails: it
+ * reports "current" for a unit nobody updated. A false negative here is the
+ * permanently-inert audit lane this function exists to catch, and the unit
+ * itself cannot lie about what it contains.
+ */
+export function daemonServiceNeedsUpgrade(): boolean {
+  const definition = readInstalledServiceDefinition();
+  if (definition === null) return false;
+  return !definition.includes("FAILPROOFAI_CLI_CMD");
+}
+
+/**
+ * The definition an installed one should become: regenerated by the same
+ * renderers a fresh install uses, carrying forward everything this process
+ * cannot re-resolve. `null` when the input has no readable start command,
+ * which means it is not a definition failproofai wrote and must be left alone.
+ *
+ * Split out from `ensureDaemonServiceCurrent` and kept pure — no privilege, no
+ * service manager, no writes — because the rewrite itself can only be
+ * exercised end-to-end on a machine with root AND the matching service
+ * manager. That is nowhere on a Linux CI runner for the launchd half, and
+ * nowhere at all on a developer box without passwordless sudo, so the one
+ * transformation that must not be wrong would otherwise be the one thing no
+ * ordinary test run ever executes.
+ */
+export function upgradedServiceDefinition(
+  definition: string,
+  cliCmd: string,
+  logDir: string,
+): string | null {
+  const binaryPath = installedExecStart(definition);
+  if (!binaryPath) return null;
+  const workerCmd = resolveWorkerCommand() ?? installedEnvValue(definition, "FAILPROOFAI_WORKER_CMD");
+  try {
+    return process.platform === "linux"
+      ? systemdUnitContents(binaryPath, workerCmd, cliCmd)
+      : launchdPlistContents(binaryPath, logDir, workerCmd, cliCmd);
+  } catch (err) {
+    // A value that cannot be safely interpolated is reported as "no usable
+    // definition" rather than thrown: this runs against a HEALTHY, RUNNING
+    // daemon and the caller's contract is an outcome, not an exception. The
+    // refusal happens before anything is written or stopped, so the machine is
+    // left exactly as it was.
+    hookLogWarn(
+      `service definition not rewritten: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return null;
+  }
+}
+
+export type DaemonUpgradeOutcome =
+  /** No service installed, or its definition already carries the variable. */
+  | "current"
+  /** The definition was rewritten and the service came back running. */
+  | "rewritten"
+  /** It needed a rewrite and did not get one. `reason` says why. */
+  | "failed";
+
+export interface DaemonUpgradeResult {
+  outcome: DaemonUpgradeOutcome;
+  reason?: string;
+  /**
+   * Whether failproofaid is running when this returns — probed, never
+   * inferred from what the commands returned.
+   *
+   * Set on every outcome that touched the service, because on a
+   * `daemonConfigured` machine a stopped daemon is not a lost feature: every
+   * hook event fails closed, across all 12 CLIs, until somebody hand-edits
+   * `policies-config.json`. The caller needs to know that specifically, not
+   * just that "the refresh failed".
+   */
+  daemonRunning?: boolean;
+}
+
+/**
+ * Restart the systemd unit, clearing any start-limit latch first.
+ *
+ * The unit ships `Restart=on-failure` with `RestartSec=2`, so a definition
+ * systemd accepts but cannot run (a poisoned `User=`, a missing binary) does
+ * not fail once — it cycles, and within `DefaultStartLimitIntervalSec` (10s) it
+ * trips `DefaultStartLimitBurst` (5) and latches into "start request repeated
+ * too quickly". On systemd 255 — what ubuntu-24.04 and GitHub's runners ship —
+ * that latch is sticky at the unit level: a later `systemctl restart` is refused
+ * even after the definition on disk has been REPLACED with a good one. A
+ * rollback that restores a perfectly runnable unit then still cannot start it,
+ * and the machine stays fail-closed against a daemon that never comes back.
+ * `reset-failed` clears the failure counter so the restart is deterministic; on
+ * a healthy unit it is a no-op. Best-effort — a `reset-failed` that errors (the
+ * unit was never failed) must never abort the restart that is the real step.
+ */
+function restartSystemdUnit(): void {
+  try {
+    runPrivileged("systemctl", ["reset-failed", systemdUnitName()]);
+  } catch {
+    // The restart below is the operative step; do not let a reset-failed
+    // that errored on an already-clean unit swallow it.
+  }
+  runPrivileged("systemctl", ["restart", systemdUnitName()]);
+}
+
+/**
+ * Puts a previous service definition back and starts the service again,
+ * answering whether failproofaid is running once it has.
+ *
+ * `ensureDaemonServiceCurrent` is the only caller, and it runs exclusively
+ * against a machine whose daemon is UP — which is what makes a half-applied
+ * rewrite so much worse than no rewrite. Stopping a healthy daemon and failing
+ * to start it again trades a dead audit lane for a machine that denies every
+ * tool call, so the refresh must be able to undo itself.
+ *
+ * Best-effort and never throws: it only ever runs where something has already
+ * gone wrong. The return value is `waitForDaemonRunning()` rather than "the
+ * commands succeeded" on purpose — the common rollback failure is a lost sudo
+ * credential, which means nothing was written and the daemon was never down.
+ */
+async function restoreServiceDefinition(previous: string): Promise<boolean> {
+  try {
+    if (process.platform === "linux") {
+      writePrivilegedFile(systemdUnitPath(), previous);
+      runPrivileged("systemctl", ["daemon-reload"]);
+      // reset-failed first: the failed rewrite we are undoing has been cycling
+      // under Restart=on-failure and may have tripped systemd's start-limit,
+      // which on systemd 255 refuses to start even this restored, good unit.
+      restartSystemdUnit();
+    } else {
+      const plistPath = launchdPlistPath();
+      try {
+        runPrivileged("launchctl", ["unload", plistPath]);
+      } catch {
+        // Already unloaded — getting the old definition loaded is the point.
+      }
+      writePrivilegedFile(plistPath, previous);
+      runPrivileged("launchctl", ["load", "-w", plistPath]);
+    }
+  } catch (err) {
+    hookLogWarn(
+      `daemon service definition rollback failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    // Not a verdict on the daemon — fall through to the probe below, which is.
+  }
+  return waitForDaemonRunning();
+}
+
+/**
+ * The one exit for every way a refresh can fail after it started touching the
+ * service. Rolls back when there is something to roll back to, then reports
+ * the daemon's actual state.
+ */
+async function refreshFailed(message: string, previous: string | null): Promise<DaemonUpgradeResult> {
+  hookLogWarn(`daemon service unit refresh failed: ${message}`);
+  const running =
+    previous === null ? daemonServiceStatus() === "running" : await restoreServiceDefinition(previous);
+  return {
+    outcome: "failed",
+    daemonRunning: running,
+    reason: running
+      ? message
+      : `${message}. The previous service definition could not be restored either, so failproofaid is NOT running`,
+  };
+}
+
+/**
+ * Brings an already-installed service definition up to date, in place.
+ *
+ * Narrower than `installDaemonService` on purpose, and it is the narrowness
+ * that makes it safe to run against a healthy machine: it never downloads, it
+ * never touches a machine that has no service, and it keeps the ExecStart and
+ * any environment value it cannot re-resolve. Everything past the first
+ * privileged write is undone by `restoreServiceDefinition` if the daemon does
+ * not come back, so the worst outcome really is the machine it started with —
+ * and when even the rollback cannot get the daemon up, that fact rides out on
+ * `daemonRunning` rather than being folded into a generic failure, because the
+ * caller has to stop asserting `daemonConfigured` over a daemon that is gone.
+ *
+ * It DOES restart the service, which `installDaemonService` does not do on
+ * Linux (`enable --now` is a no-op against an already-active unit, so a
+ * rewritten unit's environment reaches the running process only at the next
+ * boot). Without the restart this "fix" would leave the audit lane inert for
+ * however long the machine stays up — which is the bug, not a smaller version
+ * of it. The restart costs a sub-second window in which a hook can find no
+ * daemon and fail closed, so it is confined to the wizard: `failproofai
+ * config` is an explicit, attended reconfiguration, and the same window
+ * already exists on macOS, where install unloads and reloads on every run.
+ */
+export async function ensureDaemonServiceCurrent(): Promise<DaemonUpgradeResult> {
+  const definition = readInstalledServiceDefinition();
+  if (definition === null || definition.includes("FAILPROOFAI_CLI_CMD")) {
+    return { outcome: "current" };
+  }
+
+  const cliCmd = resolveCliCommand();
+  if (!cliCmd) {
+    return {
+      outcome: "failed",
+      reason:
+        "the failproofai CLI entry point (dist/cli.mjs) could not be located, so there is nothing to " +
+        "write into the unit. Re-run `failproofai config` from a complete install.",
+    };
+  }
+
+  const logDir = logsDir();
+  const upgraded = upgradedServiceDefinition(definition, cliCmd, logDir);
+  if (!upgraded) {
+    return {
+      outcome: "failed",
+      reason:
+        `no safe replacement could be composed for the service definition at ${daemonServiceFilePath()} — ` +
+        `either it has no readable start command (it looks hand-edited) or a value that would go into it ` +
+        `contains a quote, backslash or newline. It was left alone.`,
+      // Reported because nothing was touched: the refusal happens before any
+      // write and before any stop, so whatever was running still is. The
+      // wizard branches on this to decide whether to clear `daemonConfigured`,
+      // and omitting it here would have read as "the daemon may be down" on a
+      // machine whose daemon is perfectly healthy — which on a
+      // `daemonConfigured` box is the difference between a lost audit lane and
+      // every tool call denied.
+      daemonRunning: daemonServiceStatus() === "running",
+    };
+  }
+
+  if (!canElevate()) {
+    return {
+      outcome: "failed",
+      reason: `root privileges are required to rewrite ${daemonServiceFilePath()}, and sudo credentials were not available`,
+    };
+  }
+
+  // What to put back if this goes wrong, and from which point. Set BEFORE the
+  // step that can leave the machine changed, not after it succeeds: on Linux
+  // `writePrivilegedFile` is an `install` copy straight onto the unit path, so
+  // a failure part-way through leaves a truncated unit behind, and on macOS
+  // the unload has already stopped the daemon before anything is written.
+  let previous: string | null = null;
+
+  try {
+    if (process.platform === "linux") {
+      previous = definition;
+      writePrivilegedFile(systemdUnitPath(), upgraded);
+      runPrivileged("systemctl", ["daemon-reload"]);
+      // `restart`, not `enable --now`: the unit is already enabled and active,
+      // so `--now` would return success having changed nothing and the daemon
+      // would keep the environment it was started with. reset-failed first so a
+      // machine that arrived here with an already-latched start-limit (a prior
+      // failed refresh) can still be upgraded.
+      restartSystemdUnit();
+    } else {
+      const plistPath = launchdPlistPath();
+      mkdirSync(logDir, { recursive: true });
+      previous = definition;
+      try {
+        runPrivileged("launchctl", ["unload", plistPath]);
+      } catch {
+        // Not loaded — the rewrite is still the point.
+      }
+      writePrivilegedFile(plistPath, upgraded);
+      runPrivileged("launchctl", ["load", "-w", plistPath]);
+    }
+  } catch (err) {
+    return refreshFailed(err instanceof Error ? err.message : String(err), previous);
+  }
+
+  // The service was running when this started, so anything short of running
+  // now is a regression this call caused — and on a daemon-configured machine
+  // that is every tool call failing closed. A unit that parses but will not
+  // start is exactly the case `systemctl restart`'s exit code does not catch,
+  // so this is the check that hands it to the rollback.
+  if (!(await waitForDaemonRunning())) {
+    return refreshFailed(
+      `the service definition was refreshed but failproofaid did not come back within ${SERVICE_START_TIMEOUT_MS}ms (status: ${daemonServiceStatus()})`,
+      previous,
+    );
+  }
+  return { outcome: "rewritten", daemonRunning: true };
 }
 
 /**
@@ -651,6 +1483,129 @@ async function waitForDaemonRunning(): Promise<boolean> {
  * event on the machine with no recovery short of hand-editing
  * `~/.failproofai/policies-config.json`.
  */
+/**
+ * Bring the installed daemon up to this CLI's version — the second half of an
+ * upgrade that npm does not do.
+ *
+ * `npm i -g` replaces the CLI and nothing else. The binary lives at
+ * `~/.failproofai/bin/failproofaid-<version>` precisely so an upgrade cannot swap
+ * it under a running service, which means after an npm upgrade the two halves are
+ * different versions until something like this runs. `daemonVersionSkew()` has
+ * been reporting that state on every command; this is the command that fixes it.
+ *
+ * Composed from the pieces that already exist rather than reimplementing any of
+ * them: `ensureFailproofaidBinary()` puts the right file on disk (npm optional
+ * dependency first, release asset second, SHA-256 verified either way),
+ * `ensureDaemonServiceCurrent()` rewrites the unit if its shape has changed, and
+ * `waitForDaemonRunning()` is what distinguishes "started" from "started and
+ * still up" — a `Type=simple` unit reports active the moment it forks.
+ *
+ * NEVER clears `daemonConfigured`. A refresh that fails leaves a machine
+ * fail-closed against a daemon that may be down, and that is the correct, loud
+ * state: the remedy is `failproofai config`, and silently downgrading the machine
+ * to in-process evaluation would trade a visible failure for an invisible one.
+ * The lines say so.
+ */
+export async function refreshDaemonToCliVersion(
+  /**
+   * Injectable for tests, matching `waitForDaemonRunning`'s shape in this file.
+   * A `vi.spyOn` on the module namespace cannot intercept these — the module
+   * calls its own local bindings — so without a seam a test asserting either
+   * branch passes for the wrong reason: on a machine with no service, "no-op"
+   * and "the spy worked" are indistinguishable.
+   */
+  deps: {
+    status?: () => DaemonServiceStatus;
+    install?: () => Promise<DaemonInstallResult>;
+    prime?: () => boolean;
+    interactive?: () => boolean;
+  } = {},
+): Promise<{ ok: boolean; lines: string[] }> {
+  const status = deps.status ?? daemonServiceStatus;
+  const install = deps.install ?? installDaemonService;
+  const prime = deps.prime ?? primeElevation;
+  const interactive =
+    deps.interactive ?? (() => Boolean(process.stdin.isTTY && process.stdout.isTTY));
+  if (status() === "not-installed") {
+    return { ok: true, lines: ["No failproofaid service on this machine; nothing to update."] };
+  }
+
+  // `installDaemonService()`, not a binary fetch plus a restart.
+  //
+  // The first version of this did the latter, and it did not work: it called
+  // `ensureFailproofaidBinary()` (which correctly lands
+  // `bin/failproofaid-<this version>`) and then `ensureDaemonServiceCurrent()`,
+  // whose rewrite goes through `upgradedServiceDefinition` — and that PRESERVES
+  // the existing `ExecStart` via `installedExecStart(definition)`, by design,
+  // because its job is to upgrade the unit's SHAPE without changing which binary
+  // runs. So on a machine coming from an older release the new binary was
+  // downloaded, the unit was rewritten, the service was restarted, and the OLD
+  // binary came back up — under a message that said the daemon had been
+  // refreshed. Worse than not having the command, because it reports success.
+  //
+  // `installDaemonService()` is the function that already knows how to make the
+  // service run THIS CLI's version: it resolves the binary for this version,
+  // writes the unit around that path, removes any legacy user unit, reloads,
+  // enables, and waits for the service to reach AND HOLD a running state rather
+  // than trusting the moment a `Type=simple` unit reports active. It is
+  // idempotent, which is what makes it safe to call on an already-installed
+  // machine.
+  // ASK FOR THE PASSWORD, when there is somebody to ask.
+  //
+  // Writing the unit needs root, and `runPrivileged` uses `sudo -n` — which never
+  // prompts. That rule exists for the WIZARD, whose reason is stated where it is
+  // enforced: a password prompt fired from underneath a full-screen TUI is
+  // unreadable at best. It does not transfer to this command, which is plain line
+  // output with nothing to corrupt, and the wizard itself calls `primeElevation()`
+  // for exactly this at exactly this point.
+  //
+  // Without it, `failproofai update` on the machine it exists for — one with a
+  // daemon, upgrading — failed with "sudo credentials were not available" and a
+  // thirty-line unit file to paste by hand. The only working alternatives were
+  // `sudo -v` first (undocumented) or `failproofai config`, an interactive wizard.
+  // That is not an upgrade path.
+  //
+  // Gated on a TTY, not attempted blindly: on a CI runner or a fleet box there is
+  // nobody to type a password, and `sudo -v` there would block on a prompt nothing
+  // will answer. Those runs still fall through to `sudo -n`, fail, and get the
+  // exact commands to run — which is the right outcome for an unattended machine.
+  // `primeElevation()` is itself a no-op when already root or NOPASSWD.
+  if (interactive()) prime();
+
+  const result = await install();
+  if (!result.installed) {
+    return {
+      ok: false,
+      lines: [
+        `failproofaid ${version} could not be installed: ${result.reason ?? "unknown reason"}`,
+        `The previous daemon is untouched. On a machine configured to require it,`,
+        `enforcement continues; collection and cloud policy may be stale until this`,
+        `succeeds. \`${daemonStatusCommand() ?? "systemctl status"}\` will say more.`,
+      ],
+    };
+  }
+  // RECORD THE VERSION, or the refresh is invisible to everything that asks.
+  //
+  // `installDaemonService()` deliberately does not write it — only the wizard did
+  // (`setDaemonConfigured(true, cliVersion)`), because that is where "this machine
+  // is now configured, at this version" is decided. So without this line the new
+  // binary runs while `VERSION.daemon` still names the old one, and
+  // `daemonVersionSkew()` reads that file: every later CLI command keeps nudging
+  // about a stale daemon that was just replaced, and the wizard's `daemonMaybeUp`
+  // stays false on the skew it should no longer see — so a later `failproofai
+  // config` would tear down and rebuild a perfectly current service.
+  //
+  // `writeVersionFile` rather than `setDaemonConfigured(true, …)`: that helper also
+  // sets `daemon.configured`, and turning on fail-closed enforcement as a SIDE
+  // EFFECT of an update is not this command's decision to make. An update refreshes
+  // what is installed; it does not change whether the machine requires it.
+  writeVersionFile({ daemon: version });
+  return {
+    ok: true,
+    lines: [`failproofaid ${version} installed, service restarted and holding.`],
+  };
+}
+
 export async function uninstallDaemonService(): Promise<void> {
   setDaemonConfigured(false);
   if (!isDaemonSupportedPlatform()) return;
@@ -700,6 +1655,89 @@ export async function uninstallDaemonService(): Promise<void> {
  * file exists — a unit can be installed but crash-looped into a stopped
  * state.
  */
+/**
+ * Whether the installed daemon is a different version than this CLI expects.
+ *
+ * The expected version is this CLI's OWN — no lookup, no registry call, no
+ * network. `package.json` and `Cargo.toml` are held identical by CI, and every
+ * downstream path (the download URL, the binary filename, the npm pin) is
+ * derived from that one number, so a CLI can never want a daemon version that
+ * was not published alongside it.
+ *
+ * Returns null when the question does not apply, and the exclusions are the
+ * point:
+ *
+ *   • FAILPROOFAI_DAEMON_BINARY — someone named a binary explicitly; its
+ *     version is their business, not ours to second-guess.
+ *   • a locally-built target/{release,debug} binary — the developer's own
+ *     build. Reporting it "stale" on every command would be noise about the
+ *     exact setup this repo tells contributors to use.
+ *
+ * Only the managed `~/.failproofai/bin/failproofaid-<version>` path is
+ * checked, because it is the only one whose version we actually own.
+ */
+export function daemonVersionSkew(): { installed: string; expected: string } | null {
+  if (process.env.FAILPROOFAI_DAEMON_BINARY) return null;
+  const recorded = readVersionFile()?.daemon;
+  if (!recorded) return null;
+  // Managed installs only — see the exclusions above.
+  if (!existsSync(installedBinaryPath(recorded))) return null;
+  return recorded === version ? null : { installed: recorded, expected: version };
+}
+
+/**
+ * Why a Linux unit that exists is not active: skipped on a condition, or
+ * merely stopped.
+ *
+ * Only reached once `is-active` has already said "not active", so it costs a
+ * second `systemctl` call on the unhealthy path and nothing at all on the
+ * healthy one.
+ *
+ * `ConditionResult` is systemd's own record of the last condition evaluation
+ * and is `no` only after it actually ran them and one failed. A unit that has
+ * never been started since boot reports `yes` (the field's default), so this
+ * cannot invent a `condition-failed` for a unit systemd has not judged — it
+ * under-reports rather than over-reports, which is the safe direction for a
+ * signal that clears `daemonConfigured`.
+ */
+function inactiveLinuxStatus(): DaemonServiceStatus {
+  try {
+    return interpretConditionResult(
+      execFileSync(
+        "systemctl",
+        ["show", systemdUnitName(), "--property=ConditionResult", "--value"],
+        { stdio: ["ignore", "pipe", "ignore"], timeout: SERVICE_CMD_TIMEOUT_MS },
+      ).toString(),
+    );
+  } catch {
+    // No systemd, no systemctl, or a version without `--value`. The unit file
+    // exists, so "stopped" remains the honest answer — and it is the
+    // conservative one, because nothing acts destructively on it.
+    return "stopped";
+  }
+}
+
+/**
+ * `systemctl show --property=ConditionResult --value` → a status.
+ *
+ * Split out from the subprocess so the interpretation can be tested without
+ * `/etc/systemd/system`, which this code reads at a fixed path and no test may
+ * write. The live behaviour — that systemd actually skips a unit whose
+ * `ConditionPathExists=` fails, and records `no` when it does — is proven
+ * against a real systemd in the container test rather than asserted here.
+ *
+ * Only a literal `no` means condition-failed. Anything else — `yes`, an empty
+ * string from a unit systemd has not evaluated since boot, an unfamiliar word
+ * from a future version — is "stopped", which is the state nothing acts
+ * destructively on. This under-reports rather than over-reports on purpose: the
+ * cost of a missed `condition-failed` is a flag cleared one command later, and
+ * the cost of a false one is a healthy machine silently dropped to the
+ * in-process path.
+ */
+export function interpretConditionResult(raw: string): DaemonServiceStatus {
+  return raw.trim() === "no" ? "condition-failed" : "stopped";
+}
+
 export function daemonServiceStatus(): DaemonServiceStatus {
   if (!isDaemonSupportedPlatform()) return "unsupported-platform";
 
@@ -714,14 +1752,14 @@ export function daemonServiceStatus(): DaemonServiceStatus {
       })
         .toString()
         .trim();
-      return out === "active" ? "running" : "stopped";
+      return out === "active" ? "running" : inactiveLinuxStatus();
     } catch {
       // `systemctl is-active` exits non-zero (and execFileSync throws) for
       // every non-"active" state — inactive, failed, or the command not
-      // working at all (no systemd user session, systemctl missing). All
-      // of those are indistinguishable from "stopped" from here, and the
-      // unit file existing is what already ruled out "not-installed".
-      return "stopped";
+      // working at all (no systemd user session, systemctl missing). The unit
+      // file existing already ruled out "not-installed", so the only question
+      // left is whether systemd skipped it on a condition.
+      return inactiveLinuxStatus();
     }
   }
 
@@ -732,6 +1770,13 @@ export function daemonServiceStatus(): DaemonServiceStatus {
     // `launchctl list` cannot see — unlike systemd, reading the state needs
     // the same elevation installing it did.
     const root = typeof process.getuid === "function" && process.getuid() === 0;
+    // Whether we can elevate AT ALL is checked first, because it decides what a
+    // failure below means. Without it, `sudo -n` refusing for want of a cached
+    // credential was indistinguishable from launchctl reporting the job absent,
+    // and both became "stopped" — so a five-minute-old sudo timestamp made a
+    // running daemon read as dead, and the wizard then demanded a password to
+    // unload and reload a service that was fine.
+    if (!root && !canElevate()) return "unknown";
     const args = ["print", `system/${launchdLabel()}`];
     const out = root
       ? execFileSync("launchctl", args, {
@@ -746,6 +1791,9 @@ export function daemonServiceStatus(): DaemonServiceStatus {
     // prints `state = not running` and must not read as healthy.
     return /state\s*=\s*running/.test(out) ? "running" : "stopped";
   } catch {
+    // We could elevate a moment ago, so this is launchctl's own answer: the
+    // label is not loaded in the system domain. The plist exists (checked
+    // above), so that is genuinely "installed but not running".
     return "stopped";
   }
 }