failproofai 1.0.0-beta.4 → 1.0.0-beta.6

package/src/hooks/fp-home.ts

@@ -0,0 +1,342 @@
+/**
+ * Every path inside `~/.failproofai`, in one place.
+ *
+ * Before this module the layout was ~40 hardcoded `resolve(homedir(),
+ * ".failproofai", …)` calls in TypeScript and ~10 more in Rust, and the two
+ * sides had drifted into three different ideas of where things lived
+ * (`cache/hook-activity` vs `hook-activity`, `spool` at the root vs under
+ * state). Moving anything meant finding every one of them, and missing one
+ * meant the daemon wrote where the dashboard did not read — silently, because
+ * an absent directory is indistinguishable from an idle one.
+ *
+ * So: nothing outside this file may join a path onto the failproofai home.
+ * The Rust side mirrors it in `crates/failproofaid/src/paths.rs`. The test that
+ * asserts the two agree lives THERE, not here —
+ * `paths::tests::every_mirrored_path_agrees_with_fp_home_ts` imports this module
+ * in a child process and compares every mirrored path against its own.
+ *
+ * This line used to cite `__tests__/hooks/fp-home.test.ts`, which contains no
+ * reference to `crates/` and never checked anything cross-language. While both
+ * files claimed the guard existed, three paths were wrong at once: the daemon's
+ * `run/` ignored `FAILPROOFAI_HOME` (so a healthy daemon on a fail-closed
+ * machine denied every tool call), its cloud policy directory still said
+ * `cloud-managed`, and its credential still said `cloud.json`.
+ *
+ * ## Layout 2
+ *
+ * ```
+ * ~/.failproofai/
+ *   VERSION                  layout / cli / daemon versions
+ *   config.toml       0644   non-secret: mode, daemon, collector prefs
+ *   credentials.toml  0600   every token
+ *   bin/                     downloaded daemon binaries, one per version
+ *   policies/
+ *     local-policies/        the builtin enable/disable set
+ *     cloud-policies/        content-addressed artifacts + active generation
+ *     custom-policies/       user convention policies (*.mjs)
+ *   cursors/<source>/        per-source collector watermarks
+ *   audit/                   audit report + per-session cache
+ *   hook-activity/           decision log the dashboard reads
+ *   custom-agents/           SDK spool (events/ + failed/)
+ *   run/                     sockets + flock  — MUST stay shallow, see below
+ *   state/                   daemon scratch: spool, failed, health, pauses, shims
+ * ```
+ *
+ * **`run/` is deliberately NOT under `state/`.** A Unix socket path must fit
+ * in `sockaddr_un.sun_path` (~108 bytes) and we have hit that ceiling twice
+ * already during development. Every directory level spends part of a budget
+ * that a long `$HOME` has already eaten into, so the socket stays as close to
+ * the root as it can.
+ *
+ * ## Project scope is NOT here
+ *
+ * `<project>/.failproofai/` keeps its old shape — `policies-config.json` and
+ * `policies/*.mjs` at the top. Those files are committed to users' git repos,
+ * so reorganising them would rewrite history in every repo that adopted
+ * failproofai. `hooks-config.ts` still owns those paths.
+ */
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+/**
+ * The on-disk layout this build speaks.
+ *
+ * Bumped whenever a path in this file moves. Recorded in `VERSION`, and what
+ * `detectLayout()` compares against — a home written by a different layout is
+ * refused rather than half-read, because reading a moved directory silently
+ * yields "no data" instead of an error.
+ *
+ * 1 — the original flat/`cache`-based layout, through 1.0.0-beta.5.
+ * 2 — this file.
+ */
+export const LAYOUT_VERSION = 2;
+
+/**
+ * `~/.failproofai`, or `FAILPROOFAI_HOME`.
+ *
+ * The override is load-bearing for tests and containers: everything below is
+ * derived from it, so pointing it elsewhere relocates the entire layout
+ * atomically rather than per-path.
+ */
+export function failproofaiHome(home?: string): string {
+  if (home) return resolve(home, ".failproofai");
+  return process.env.FAILPROOFAI_HOME || resolve(homedir(), ".failproofai");
+}
+
+const at = (...parts: string[]): string => resolve(failproofaiHome(), ...parts);
+
+/**
+ * Same, against an explicitly supplied HOME (not the failproofai home).
+ *
+ * `setup-state` and `onboarding-lock` take a `home` parameter purely so their
+ * tests can point at a temp directory, and a helper that silently ignored it
+ * would send those tests at the developer's real home — which is precisely the
+ * bug this overload exists to make impossible.
+ */
+const atHome = (home: string | undefined, ...parts: string[]): string =>
+  home ? resolve(failproofaiHome(home), ...parts) : at(...parts);
+
+// ── Top level ────────────────────────────────────────────────────────────────
+
+/** Layout / CLI / daemon versions. Also the layout marker. */
+export const versionFile = (home?: string) => atHome(home, "VERSION");
+
+/** Non-secret configuration. World-readable by design; never holds a token. */
+export const configFile = (home?: string) => atHome(home, "config.toml");
+
+/**
+ * Every credential, owner-only.
+ *
+ * Split from `config.toml` because that file is written with a bare
+ * `writeFileSync` and inherits the umask (0664 on a normal machine). A token
+ * there would be readable by every local user on the box — which is exactly
+ * why `ingest.json` and `cloud.json` were separate files before this.
+ */
+export const credentialsFile = (home?: string) => atHome(home, "credentials.toml");
+
+// ── Daemon binaries ──────────────────────────────────────────────────────────
+
+export const binDir = (home?: string) => atHome(home, "bin");
+
+/**
+ * One file per version, never overwritten in place: an in-place write hits
+ * `ETXTBSY` against the running daemon on Linux, and would silently repoint a
+ * live service unit at a binary built from different source.
+ */
+export const daemonBinary = (version: string, home?: string) =>
+  resolve(binDir(home), `failproofaid-${version}`);
+
+// ── Policies ─────────────────────────────────────────────────────────────────
+
+export const policiesDir = (home?: string) => atHome(home, "policies");
+
+/** The builtin enable/disable set and per-policy params, GLOBAL scope only. */
+export const localPoliciesDir = (home?: string) => atHome(home, "policies", "local-policies");
+export const globalPolicyConfigFile = (home?: string) =>
+  resolve(localPoliciesDir(home), "policies-config.json");
+
+/** Cloud-managed generations: `active.json` plus content-addressed artifacts. */
+export const cloudPoliciesDir = (home?: string) => resolve(policiesDir(home), "cloud-policies");
+
+/** User convention policies (`*.mjs`) that load without any flag. */
+export const customPoliciesDir = (home?: string) => resolve(policiesDir(home), "custom-policies");
+
+// ── Collector ────────────────────────────────────────────────────────────────
+
+/** Per-source watermarks. One directory per source — never shared: the cursor
+ *  store rewrites its whole map atomically, so two sources sharing a file
+ *  clobber each other and the loser re-reads from zero after every restart. */
+export const cursorsDir = (source?: string, home?: string) =>
+  source ? resolve(atHome(home, "cursors"), source) : atHome(home, "cursors");
+
+/** The SDK spool root. Mirrors `~/.agenteye/`, which stays supported. */
+export const customAgentsDir = (home?: string) => atHome(home, "custom-agents");
+export const customAgentsEventsDir = (home?: string) => resolve(customAgentsDir(home), "events");
+export const customAgentsFailedDir = (home?: string) => resolve(customAgentsDir(home), "failed");
+
+// ── Audit ────────────────────────────────────────────────────────────────────
+
+export const auditDir = (home?: string) => atHome(home, "audit");
+export const auditDashboardFile = (home?: string) => resolve(auditDir(home), "dashboard.json");
+export const auditCacheDir = (home?: string) => resolve(auditDir(home), "cache");
+
+// ── Hook activity ────────────────────────────────────────────────────────────
+
+/** The decision log: page-sized JSONL the dashboard's activity tab reads. */
+export const hookActivityDir = (home?: string) => atHome(home, "hook-activity");
+
+// ── Runtime ──────────────────────────────────────────────────────────────────
+
+/** Sockets and the singleton flock. Shallow on purpose — see the header note. */
+export const runDir = (home?: string) => atHome(home, "run");
+export const daemonSocket = () =>
+  process.env.FAILPROOFAI_DAEMON_SOCKET || resolve(runDir(), "failproofaid.sock");
+export const workerSocket = (home?: string) => resolve(runDir(home), "worker.sock");
+export const daemonLock = (home?: string) => resolve(runDir(home), "failproofaid.lock");
+
+/**
+ * Single-flight lock for the audit.
+ *
+ * Three separate processes can start one — a scheduled run, `failproofai
+ * audit`, and the dashboard's re-run — and all three write the same
+ * sha1-keyed cache files, so the lock has to be visible across processes.
+ * It sits in `run/` with the other runtime files rather than under `audit/`,
+ * which holds results a human might keep and a reset is expected to clear.
+ *
+ * NOT mirrored in `crates/failproofaid/src/paths.rs` yet: nothing in Rust
+ * takes this lock until the daemon grows its audit lane, and a `pub fn` no
+ * caller uses is a dead_code failure under `-D warnings`.
+ */
+export const auditLockFile = (home?: string) => resolve(runDir(home), "audit.lock");
+
+// ── Daemon scratch state ─────────────────────────────────────────────────────
+
+/** Everything the daemon writes that a human would never open by hand. */
+export const stateDir = (home?: string) => atHome(home, "state");
+/**
+ * Where the policy loader writes its ESM shim.
+ *
+ * Under the user's own home rather than beside the installed package: that
+ * directory belongs to whoever installed failproofai, and on a system-wide
+ * install it is root-owned, which made every non-root hook fail to load
+ * cloud-managed and custom policies — silently, and open.
+ */
+export const shimsDir = (home?: string) => resolve(stateDir(home), "shims");
+export const spoolDir = (home?: string) => resolve(stateDir(home), "spool");
+export const failedDir = (home?: string) => resolve(stateDir(home), "failed");
+export const collectorHealthFile = (home?: string) => resolve(stateDir(home), "collector-health.json");
+/** Per-session enforcement pauses, keyed by a hash of the session id. */
+export const sessionPauseDir = () => resolve(stateDir(), "sessions");
+/**
+ * When the scheduled audit last ran, and when the next one is due.
+ *
+ * The DAEMON is the sole writer (`crates/failproofaid/src/audit_lane.rs`, which
+ * mirrors this path in `paths.rs`) — it owns the schedule, and a second writer
+ * racing it could hand a machine two full scans back to back. Everything on this
+ * side reads it: the interval itself lives in `config.toml`'s `[audit]` table,
+ * which a human edits, while this file is derived state a human never opens,
+ * which is why it sits under `state/` rather than beside the audit results.
+ */
+export const auditScheduleFile = (home?: string) => resolve(stateDir(home), "audit-schedule.json");
+/**
+ * The anonymous instance id this machine reports telemetry under.
+ *
+ * The mirror image of `auditScheduleFile()` above: here the CLI is the sole
+ * writer (`getInstanceId()` in `lib/telemetry-id.ts`, which persists whatever it
+ * resolved) and **failproofaid** only reads, through `telemetry_id_path()` in
+ * `crates/failproofaid/src/paths.rs`. The daemon cannot re-derive the value —
+ * `getInstanceId`'s middle tier hashes Node-formatted strings (`os.arch()` is
+ * `x64` where Rust says `x86_64`), and a near-miss there does not fail, it
+ * silently files one machine under two PostHog persons — so this file is how the
+ * two agree. Derived state a human never opens, hence `state/` rather than
+ * beside `config.toml`.
+ */
+export const telemetryIdFile = (home?: string) => resolve(stateDir(home), "telemetry-id");
+export const launcherMarker = (home?: string) => resolve(stateDir(home), "launcher-configured");
+/**
+ * The version that last reported an install, so an upgrade is reported once.
+ *
+ * Under `state/` in layout 2 like every other piece of derived state, and that
+ * placement fixes a real bug rather than being tidiness: at the root it was
+ * `~/.failproofai/last-version`, which `detectLayout()` lists as a LAYOUT-1
+ * MARKER — while the code that writes it still runs under layout 2, and runs
+ * BEFORE the layout check. So on a genuinely fresh machine the CLI created the
+ * file, then immediately read it back as evidence of an old layout, classified
+ * a brand-new home as stale, and opened every new user's first command with
+ * "failproofai reorganised … Removed 1 item(s) from the old layout."
+ */
+export const lastVersionFile = (home?: string) => resolve(stateDir(home), "last-version");
+export const onboardingLockFile = (home?: string) => resolve(stateDir(home), "onboarding.lock");
+export const codexSessionPathsFile = (home?: string) => resolve(stateDir(home), "codex-session-paths.json");
+
+export const logsDir = (home?: string) => atHome(home, "logs");
+
+// ── Layout 1 (legacy) ────────────────────────────────────────────────────────
+
+/**
+ * Where layout 1 kept things.
+ *
+ * Retained ONLY so `detectLayout()` can recognise an old home and so the reset
+ * can delete it. Nothing reads data from these paths: the decision was
+ * wipe-and-re-setup rather than migrate, because a half-migrated home that
+ * silently reads "no data" is worse than one that says so.
+ */
+export const legacy = {
+  policyConfig: () => at("policies-config.json"),
+  policyConfigLocal: () => at("policies-config.local.json"),
+  cloudCredentials: () => at("cloud.json"),
+  ingestCredentials: () => at("ingest.json"),
+  launcherMarker: () => at(".launcher-configured"),
+  lastVersion: () => at("last-version"),
+  auditDashboard: () => at("audit-dashboard.json"),
+  cacheDir: () => at("cache"),
+  hookActivityDir: () => at("cache", "hook-activity"),
+  auditCacheDir: () => at("cache", "audit"),
+  codexSessionPaths: () => at("cache", "codex-session-paths.json"),
+  spoolDir: () => at("spool"),
+  failedDir: () => at("failed"),
+  collectorHealth: () => at("collector-health.json"),
+  sessionPauseDir: () => at("state", "sessions"),
+  cloudManagedPolicies: () => at("policies", "cloud-managed"),
+  onboardingLock: () => at(".onboarding.lock"),
+} as const;
+
+/**
+ * Every path a reset must remove, in the order it should remove them.
+ *
+ * Enumerated rather than "delete the home directory" so a reset never takes
+ * out something a future layout adds and this list has not been taught about
+ * — and so the function is auditable at a glance, which matters for anything
+ * that deletes user data.
+ */
+export function resettablePaths(): string[] {
+  return [
+    // Layout 1
+    legacy.policyConfig(),
+    legacy.policyConfigLocal(),
+    legacy.cloudCredentials(),
+    legacy.ingestCredentials(),
+    legacy.launcherMarker(),
+    legacy.lastVersion(),
+    legacy.auditDashboard(),
+    legacy.cacheDir(),
+    legacy.spoolDir(),
+    legacy.failedDir(),
+    legacy.collectorHealth(),
+    legacy.onboardingLock(),
+    legacy.cloudManagedPolicies(),
+    // The MACHINE-OWNED children of `policies/`, never the parent.
+    //
+    // `at("policies")` stood here, and on layout 1 that directory IS the
+    // documented home for hand-written personal policies — `docs/
+    // configuration.mdx` names `~/.failproofai/policies/` as the user scope,
+    // and `manager.ts` read it. Those are source files a person wrote; nothing
+    // regenerates them, nothing backed them up, and the reset message named
+    // only "policy config, activity history and audit cache". Worse, the
+    // machine then reported itself configured — `isConfigured()` is a union
+    // that still sees the agent CLIs' untouched settings files — so the wizard
+    // was skipped and hooks kept firing against an empty policy set.
+    //
+    // `custom-policies/` is deliberately absent from this list for the same
+    // reason. Both directories below are re-derived: `local-policies/` by
+    // setup, `cloud-policies/` by the next daemon poll.
+    localPoliciesDir(),
+    cloudPoliciesDir(),
+    at("cursors"),
+    at("state"),
+    // Layout 2.
+    // NOT versionFile() — it is the layout marker, not user data, and the
+    // reset rewrites it immediately afterwards. Listing it made a no-op reset
+    // report "removed 1 item" for a file it had just recreated.
+    configFile(),
+    credentialsFile(),
+    auditDir(),
+    hookActivityDir(),
+    customAgentsDir(),
+    logsDir(),
+    // NOT bin/ — a downloaded daemon binary is large, version-pinned and
+    // re-verified on use, so deleting it only forces a needless re-download.
+    // NOT run/ — sockets belong to a running daemon; removing them out from
+    // under it breaks a live process rather than resetting configuration.
+  ];
+}

package/src/hooks/fp-reset.ts

@@ -0,0 +1,332 @@
+/**
+ * What happens when this CLI meets a home directory written by a different
+ * layout.
+ *
+ * The decision was wipe-and-re-setup rather than migrate. A migration has to
+ * be right on every path or it half-moves a home, and a half-moved home fails
+ * in the worst available way: the daemon writes where the dashboard does not
+ * read, and an absent directory is indistinguishable from an idle one. A reset
+ * is one destructive operation that is either done or not done.
+ *
+ * ## Where the deletion happens, and where it deliberately does not
+ *
+ * Only a real CLI command resets. A HOOK never deletes anything, because a
+ * hook runs unattended, once per tool call, with an agent waiting on stdout —
+ * removing a user's audit history and cursors from inside one would be a
+ * destructive act nobody asked for and nobody saw.
+ *
+ * But a hook must not stay silent either. On a stale layout the merged config
+ * resolves to nothing, so every builtin policy quietly stops firing: the
+ * machine looks protected and is not. That is the single worst outcome here,
+ * so the hook path says so on stderr, every time, until setup is re-run.
+ *
+ * ## Why the hook does not simply deny
+ *
+ * Failing closed is this product's instinct, and it is the wrong instinct
+ * here. A stale layout is the result of an upgrade the user did not ask to be
+ * interrupted by, and this branch has already demonstrated — on this very
+ * machine — that a blanket deny takes `UserPromptSubmit` with it and locks the
+ * user out of their agent entirely, with no way back except hand-editing JSON.
+ * A loud warning that survives until setup runs is the proportionate answer.
+ */
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  LAYOUT_VERSION,
+  customPoliciesDir,
+  failproofaiHome,
+  policiesDir,
+  resettablePaths,
+} from "./fp-home";
+import { detectLayout, readConfig, updateConfig, writeVersionFile, type LayoutState } from "./fp-config";
+import {
+  daemonServiceStatus,
+  daemonVersionSkew,
+  isDaemonSupportedPlatform,
+  probeDaemonEndToEnd,
+} from "./daemon-service";
+
+export interface ResetOutcome {
+  /** Paths that existed and were removed. */
+  removed: string[];
+  /** Basenames of user-authored policy files moved into `custom-policies/`. */
+  migrated: string[];
+  /** The layout that was found before the reset. */
+  from: number;
+}
+
+/** Script files a person could have written by hand. `.d.ts` is a type stub. */
+const USER_SOURCE_RE = /\.(js|mjs|ts)$/;
+
+/**
+ * Move hand-written policies from layout 1's `policies/` into layout 2's
+ * `policies/custom-policies/`, where the loader actually reads them.
+ *
+ * Layout 1 documented `~/.failproofai/policies/` as the user scope for personal
+ * convention policies, and layout 2 moved the directory the loader opens down a
+ * level (`customPoliciesDir()`). Left alone, those files survive the reset —
+ * that part is handled by keeping the parent out of `resettablePaths()` — but
+ * nothing would ever load them again, which is the same silent enforcement gap
+ * by a slower route.
+ *
+ * Every loadable extension moves, not just the `*policies.{js,mjs,ts}` names
+ * the convention loads: a file that misses the naming convention is still
+ * source somebody wrote, and `findSkippedPolicyFiles` exists precisely to tell
+ * them so. Leaving it behind to be reported against an empty directory helps
+ * nobody.
+ *
+ * A destination that already exists is never overwritten — the source is left
+ * in place instead. The parent directory is no longer deleted, so "left in
+ * place" means "still there to look at", which is the right outcome for the
+ * only case that reaches it (a half-finished earlier migration).
+ */
+export function migrateConventionPolicies(): string[] {
+  const from = policiesDir();
+  if (!existsSync(from)) return [];
+  const moved: string[] = [];
+  try {
+    const entries = readdirSync(from, { withFileTypes: true }).filter(
+      (e) => e.isFile() && USER_SOURCE_RE.test(e.name) && !e.name.endsWith(".d.ts"),
+    );
+    if (entries.length === 0) return [];
+
+    const to = customPoliciesDir();
+    mkdirSync(to, { recursive: true });
+    for (const entry of entries) {
+      const target = resolve(to, entry.name);
+      if (existsSync(target)) continue;
+      try {
+        renameSync(resolve(from, entry.name), target);
+        moved.push(entry.name);
+      } catch {
+        // One unmovable file must not strand the rest. It stays where it is,
+        // and the reset no longer deletes that directory.
+      }
+    }
+  } catch {
+    // A policies directory we cannot read is not worth aborting a reset over.
+  }
+  return moved.sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Delete every path layout 1 or layout 2 could have written, then stamp
+ * VERSION so the next run reads as current.
+ *
+ * Enumerated rather than "remove the home directory": a reset must never take
+ * out something a future layout adds that this list has not been taught about,
+ * and `bin/` and `run/` are excluded on purpose — a downloaded daemon binary is
+ * large, version-pinned and re-verified on use, and `run/` holds sockets
+ * belonging to a process that may be alive right now.
+ */
+export function resetHome(from: number): ResetOutcome {
+  // BEFORE the deletions, so a file that is mid-move is never one the reset
+  // then walks over.
+  const migrated = migrateConventionPolicies();
+  const removed: string[] = [];
+  for (const path of resettablePaths()) {
+    if (!existsSync(path)) continue;
+    try {
+      rmSync(path, { recursive: true, force: true });
+      removed.push(path);
+    } catch {
+      // A path we cannot remove is not worth aborting the reset over; the
+      // VERSION stamp below is what stops this repeating, and a leftover
+      // directory from an old layout is inert once nothing reads it.
+    }
+  }
+  writeVersionFile();
+  return { removed, migrated, from };
+}
+
+export interface LayoutCheck {
+  state: LayoutState;
+  /** Lines to print. Empty when there is nothing to say. */
+  lines: string[];
+  /** True when the caller should stop rather than continue. */
+  fatal: boolean;
+  /**
+   * True when this call actually reset the home.
+   *
+   * The caller must force setup when it is set. A reset removes the global
+   * policy config, but `isConfigured()` is a union that also counts the agent
+   * CLIs' settings files — which the reset deliberately leaves alone — so the
+   * machine still reads as configured, the wizard is skipped, and
+   * `markLauncherSeen()` back-fills the marker so every later run skips it too.
+   * The user is left with hooks firing on every tool call against no policies
+   * at all, and nothing ever says so again.
+   */
+  didReset: boolean;
+}
+
+/**
+ * The interactive path: reset a stale home, refuse a future one.
+ *
+ * A future layout is refused rather than reset because the two failures are
+ * not the same. An older home can be rebuilt by re-running setup; a home
+ * written by a NEWER CLI holds data this build cannot read but a simple
+ * upgrade could, and deleting it would destroy something recoverable.
+ */
+export async function checkLayoutForCli(): Promise<LayoutCheck> {
+  const state = detectLayout();
+
+  if (state.kind === "future") {
+    return {
+      state,
+      fatal: true,
+      didReset: false,
+      lines: [
+        `This machine's failproofai directory was written by a newer version`,
+        `(layout ${state.found}; this build speaks ${LAYOUT_VERSION}).`,
+        ``,
+        `Upgrade rather than reset — the data is fine, this build just cannot read it:`,
+        `  npm install -g failproofai@latest`,
+      ],
+    };
+  }
+
+  if (state.kind === "stale") {
+    const { removed, migrated } = resetHome(state.found);
+    return {
+      state,
+      fatal: false,
+      didReset: true,
+      lines: [
+        `failproofai reorganised ${failproofaiHome()} in this version.`,
+        `Removed ${removed.length} item(s) from the old layout — policy config, activity`,
+        `history and audit cache. Your downloaded daemon binary was kept.`,
+        // Named individually rather than counted. These are files a person
+        // wrote; "moved 3 items" is not something you can check at a glance,
+        // and the whole point of saying it is that they can.
+        ...(migrated.length > 0
+          ? [
+              ``,
+              `Kept your own policy file(s) and moved them to where this version`,
+              `loads them (${customPoliciesDir()}):`,
+              ...migrated.map((name) => `  ${name}`),
+            ]
+          : []),
+        ``,
+        `Run \`failproofai config\` to set up again.`,
+      ],
+    };
+  }
+
+  if (state.kind === "absent") writeVersionFile();
+  return {
+    state,
+    fatal: false,
+    didReset: false,
+    lines: [...(await healDaemonFlag()), ...staleDaemonHint()],
+  };
+}
+
+/**
+ * Clear `daemonConfigured` when the service it points at is provably gone.
+ *
+ * This exists because the combination it repairs bricked a real machine during
+ * development. `daemonConfigured` makes every hook route through failproofaid
+ * and FAIL CLOSED when it cannot be reached — so removing the service without
+ * first clearing the flag denies every tool call on the box, including
+ * `UserPromptSubmit`, which locks the user out of their agent entirely. There
+ * was no command to undo it: the only recovery was hand-editing JSON.
+ *
+ * Deliberately keyed on "not-installed", never on "stopped". A stopped service
+ * is usually a restart in progress, and clearing the flag there would silently
+ * downgrade a healthy machine to the in-process path — trading a loud, correct
+ * failure for a quiet, wrong one.
+ */
+async function healDaemonFlag(): Promise<string[]> {
+  try {
+    const cfg = readConfig();
+    if (!cfg.daemon.configured) return [];
+    if (!isDaemonSupportedPlatform()) return [];
+
+    const status = daemonServiceStatus();
+    if (status === "not-installed") {
+      updateConfig({ daemon: { configured: false } });
+      return [
+        `failproofaid is no longer installed, but this machine was still configured`,
+        `to require it — which denies every tool call. Cleared that flag; policies`,
+        `now evaluate in-process. Run \`failproofai config\` to reinstall the daemon.`,
+        ``,
+      ];
+    }
+
+    // Installed and RUNNING is not the same as working, and the difference is
+    // a total lockout. `ExecStart` bakes in `process.execPath`, so an
+    // `nvm uninstall 20` months later leaves a unit systemd still calls active
+    // whose worker dies on every spawn. Nothing else catches it: the install
+    // probe cannot run retroactively, and the not-installed branch above never
+    // fires because the unit is very much installed.
+    //
+    // Clearing the flag is the whole repair, and it is deliberately NOT
+    // accompanied by an uninstall: this runs unprompted at the top of whatever
+    // command the user typed, and tearing down a root-owned service from there
+    // is not a decision to make on their behalf. Removing and reinstalling the
+    // unit is the wizard's job, where a person is present — see the
+    // `daemonAlreadyHealthy` probe in `configure-wizard.ts`.
+    if (status === "running" && !(await probeDaemonEndToEnd())) {
+      updateConfig({ daemon: { configured: false } });
+      return [
+        `failproofaid is running but cannot evaluate policies — its worker process`,
+        `will not start (most often because the Node install its service was built`,
+        `against is gone). This machine was configured to require it, which denies`,
+        `every tool call, so that flag is cleared; policies now evaluate in-process.`,
+        `Run \`failproofai config\` to rebuild the service.`,
+        ``,
+      ];
+    }
+    return [];
+  } catch {
+    // Never let a self-heal attempt break the command the user actually typed.
+    return [];
+  }
+}
+
+/**
+ * One line when the daemon is older than the CLI.
+ *
+ * Deliberately NOT on the hook path. A stale daemon still enforces every policy
+ * correctly — it is slower to notice an upgrade, not broken — so a warning once
+ * per tool call would be noise about something that is working. CLI commands
+ * are where a person is present to act on it.
+ */
+function staleDaemonHint(): string[] {
+  try {
+    const skew = daemonVersionSkew();
+    if (!skew) return [];
+    return [
+      `[failproofai] daemon is ${skew.installed}, CLI is ${skew.expected} — ` +
+        `run \`failproofai config\` to update it.`,
+      ``,
+    ];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The hook path: never delete, never deny, but never stay quiet either.
+ *
+ * Returns a single stderr line when the layout is not current. Hooks run once
+ * per tool call, so this repeats — deliberately. A warning that appears once
+ * and then stops is a warning nobody sees, and the state it describes (a
+ * machine whose global policies have silently stopped firing) persists until
+ * somebody acts on it.
+ */
+export function layoutWarningForHook(): string | null {
+  const state = detectLayout();
+  if (state.kind === "current" || state.kind === "absent") return null;
+  if (state.kind === "future") {
+    return (
+      `[failproofai] this directory was written by a newer version ` +
+      `(layout ${state.found} vs ${LAYOUT_VERSION}) — policies are NOT being enforced. ` +
+      `Upgrade failproofai.`
+    );
+  }
+  return (
+    `[failproofai] setup predates this version — global policies are NOT being enforced. ` +
+    `Run \`failproofai config\` to re-create it.`
+  );
+}