failproofai 1.0.0-beta.5 → 1.0.0-beta.7

package/src/hooks/daemon-service.ts

@@ -23,6 +23,9 @@ import { execFileSync } from "node:child_process";
 import { hookLogWarn } from "./hook-logger";
 import { getConfigPathForScope } from "./hooks-config";
 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
@@ -76,19 +79,16 @@ 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 */
   }
@@ -225,12 +225,94 @@ 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 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)
@@ -321,6 +403,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.
  *
@@ -352,8 +450,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 });
@@ -457,11 +563,19 @@ 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");
   return `[Unit]
 Description=failproofai background daemon (failproofaid) for ${user}
 After=network.target
@@ -474,7 +588,7 @@ User=${user}
 # 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.
 Environment="HOME=${homedir()}"
-${envLine}ExecStart=${binaryPath}
+${envLines}ExecStart=${binaryPath}
 Restart=on-failure
 RestartSec=2
 
@@ -490,12 +604,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>
 `
     : "";
@@ -538,10 +667,14 @@ 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()}`,
     ];
@@ -577,6 +710,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
@@ -588,7 +726,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(" && "),
     };
   }
 
@@ -600,12 +738,12 @@ 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()]);
     } 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`
@@ -615,7 +753,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) {
@@ -636,9 +774,70 @@ 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 };
 }
 
+/**
+ * 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.
+ */
+const DAEMON_PROBE_TIMEOUT_MS = 5_000;
+
+/**
+ * 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 async function probeDaemonEndToEnd(): Promise<boolean> {
+  try {
+    const { attemptDaemonHook } = await import("./daemon-client");
+    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. The hook
+    // path already falls back rather than denying for that case, so it is not
+    // the lockout this probe exists to find.
+    return attempt.ok || attempt.failure === "protocol-mismatch";
+  } catch {
+    return false;
+  }
+}
+
 /**
  * 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
@@ -655,6 +854,353 @@ async function waitForDaemonRunning(): Promise<boolean> {
   return daemonServiceStatus() === "running";
 }
 
+// ── 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;
+  }
+}
+
+/**
+ * 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 revision
+ * 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 };
+}
+
 /**
  * Stops and removes the service, and clears the `daemonConfigured` marker
  * so this machine goes back to in-process evaluation. Best-effort: never
@@ -715,6 +1261,36 @@ 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 };
+}
+
 export function daemonServiceStatus(): DaemonServiceStatus {
   if (!isDaemonSupportedPlatform()) return "unsupported-platform";