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

package/src/hooks/handler.ts

@@ -43,6 +43,7 @@ import { hookLogInfo, hookLogWarn } from "./hook-logger";
 import { readStdinPayload } from "./read-stdin";
 import { readActiveCloudManagedPolicies, type CloudManagedPolicyArtifact } from "./cloud-managed-policies";
 import { readActivePause, type ActivePause } from "./session-pause";
+import { layoutWarningForHook } from "./fp-reset";
 
 /**
  * Canonicalize an event name to PascalCase. Codex sends snake_case event names
@@ -182,6 +183,13 @@ export async function evaluateHookEvent(
   opts?: EvaluateHookEventOptions,
 ): Promise<HookEventOutcome> {
   const startTime = performance.now();
+  // A home from another layout resolves to no global config, so every builtin
+  // silently stops firing — the machine looks protected and is not. Say so on
+  // every call rather than deleting anything (a hook is unattended) or denying
+  // (a blanket deny takes UserPromptSubmit with it and locks the user out of
+  // their agent entirely — demonstrated on a real machine during this work).
+  const layoutWarning = layoutWarningForHook();
+  if (layoutWarning) hookLogWarn(layoutWarning);
   try {
     let parsed: Record<string, unknown> = {};
     if (stdinPayload) {
@@ -286,7 +294,40 @@ export async function evaluateHookEvent(
       // Cloud-managed policies are daemon-reconciled artifacts, but they use
       // the same public JS policy API as local custom policies. Verify and add
       // only the paths referenced by the atomically active generation.
-      const cloudManagedPolicies = readActiveCloudManagedPolicies();
+      //
+      // Wrapped, like `readConfigAt` and `readActivePause` above it. This call
+      // has fourteen throw sites — a malformed manifest, an unsafe id, an
+      // integrity mismatch, an unknown effect — and it sat bare inside a `try`
+      // whose only handler is a `finally`, so any of them aborted the entire
+      // evaluation. What that cost depended on where the hook ran, and none of
+      // the outcomes were the intended one: on a daemon machine the client
+      // fail-closed denies every tool call, and off the daemon path the throw
+      // reaches `bin/failproofai.mjs`'s outer catch, which exits 2 with nothing
+      // on stdout — a deny on Claude and Factory, but a logged warning followed
+      // by an ALLOW on Copilot, Cursor, Goose, Pi and Hermes, which read a
+      // decision off stdout and ignore the exit code. One corrupt byte was
+      // either a permanent machine-wide lockout or silent non-enforcement,
+      // depending on the CLI.
+      //
+      // Failing open here degrades ONE layer: builtins and local custom
+      // policies were already registered above and keep enforcing. That is the
+      // same trade `2ad735e5` made on the Rust side, and it is strictly better
+      // than the status quo, which already failed open on five of the twelve —
+      // just accidentally, and without saying so.
+      let cloudManagedPolicies: CloudManagedPolicyArtifact[] = [];
+      try {
+        cloudManagedPolicies = readActiveCloudManagedPolicies();
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        hookLogWarn(
+          `[failproofai] cloud-managed policies could NOT be loaded and are not being enforced: ${msg}. ` +
+            `Local policies are unaffected. Run \`failproofai config --status\` to check this machine's enrolment.`,
+        );
+        void trackHookEvent(getInstanceId(), "cloud_managed_load_error", {
+          event_type: eventType,
+          cli,
+        });
+      }
       // Recorded on every row once a machine is managed, whether or not a cloud
       // policy decided this event: "what was deployed here at the time" is a
       // separate question from "what decided", and only the former can tell a

package/src/hooks/hook-activity-store.ts

@@ -1,7 +1,7 @@
 /**
  * Disk persistence for hook activity entries using page-sized JSONL files.
  *
- * Storage location: ~/.failproofai/cache/hook-activity/
+ * Storage location: ~/.failproofai/hook-activity/ (see fp-home.ts)
  *
  * File structure:
  * - current.jsonl — actively written to, 0–PAGE_SIZE entries
@@ -22,19 +22,32 @@ import {
   unlinkSync,
 } from "node:fs";
 import { join } from "node:path";
-import { homedir } from "node:os";
 import type { IntegrationType } from "./types";
+import { hookActivityDir } from "./fp-home";
 
 export const PAGE_SIZE = 25;
 
-const DEFAULT_STORE_DIR = join(homedir(), ".failproofai", "cache", "hook-activity");
+/**
+ * Layout 2 promoted this out of `cache/`. It was never a cache — nothing
+ * regenerates it, and deleting it loses the decision history the dashboard's
+ * activity tab is built on. Resolved lazily (not at module load) so
+ * FAILPROOFAI_HOME is honoured by tests and containers that set it after
+ * import.
+ */
+const defaultStoreDir = () => hookActivityDir();
 const CURRENT_FILE = "current.jsonl";
 const COUNT_FILE = "current.count"; // tracks line count; O(1) read/write vs rereading current.jsonl
 const STATS_FILE = "stats.json";
 const LOCK_FILE = "current.lock";  // advisory lock for concurrent hook processes
 const LOCK_STALE_MS = 2000;        // steal lock if older than 2 s (covers crashed processes)
 
-let storeDir = DEFAULT_STORE_DIR;
+let storeDirOverride: string | null = null;
+/**
+ * A getter, not a module-load constant: `FAILPROOFAI_HOME` is routinely set by
+ * a test or a container AFTER this module is imported, and a value captured at
+ * import time would silently point every write at the real home.
+ */
+const storeDirValue = () => storeDirOverride ?? defaultStoreDir();
 let rotateSeq = 0;
 
 // ── Types ──
@@ -134,8 +147,8 @@ export interface HookActivityStats {
 // ── Directory setup ──
 
 function ensureDir(): void {
-  if (!existsSync(storeDir)) {
-    mkdirSync(storeDir, { recursive: true });
+  if (!existsSync(storeDirValue())) {
+    mkdirSync(storeDirValue(), { recursive: true });
   }
 }
 
@@ -143,7 +156,7 @@ function ensureDir(): void {
 
 function acquireLock(): void {
   ensureDir();
-  const lockPath = join(storeDir, LOCK_FILE);
+  const lockPath = join(storeDirValue(), LOCK_FILE);
   const deadline = Date.now() + LOCK_STALE_MS;
   while (Date.now() < deadline) {
     try {
@@ -166,7 +179,7 @@ function acquireLock(): void {
 }
 
 function releaseLock(): void {
-  try { unlinkSync(join(storeDir, LOCK_FILE)); } catch { /* ignore */ }
+  try { unlinkSync(join(storeDirValue(), LOCK_FILE)); } catch { /* ignore */ }
 }
 
 // ── Writing (synchronous — hook handler is short-lived) ──
@@ -175,8 +188,8 @@ export function persistHookActivity(entry: HookActivityEntry): void {
   ensureDir();
   acquireLock();
   try {
-    const currentPath = join(storeDir, CURRENT_FILE);
-    const countPath = join(storeDir, COUNT_FILE);
+    const currentPath = join(storeDirValue(), CURRENT_FILE);
+    const countPath = join(storeDirValue(), COUNT_FILE);
 
     const lineCount = readCount(countPath);
     if (lineCount >= PAGE_SIZE) {
@@ -198,7 +211,7 @@ export function persistHookActivity(entry: HookActivityEntry): void {
 
 function rotate(currentPath: string, countPath: string): void {
   const archiveName = `page-${Date.now()}-${rotateSeq++}.jsonl`;
-  const archivePath = join(storeDir, archiveName);
+  const archivePath = join(storeDirValue(), archiveName);
   renameSync(currentPath, archivePath);
   // Reset count for the fresh file (write 0 — next append will set it to 1)
   writeCount(countPath, 0);
@@ -240,7 +253,7 @@ interface StoredStats {
 
 function readStoredStats(): StoredStats {
   try {
-    return JSON.parse(readFileSync(join(storeDir, STATS_FILE), "utf-8")) as StoredStats;
+    return JSON.parse(readFileSync(join(storeDirValue(), STATS_FILE), "utf-8")) as StoredStats;
   } catch {
     return { totalEvents: 0, denyCount: 0, policyMap: {} };
   }
@@ -258,10 +271,10 @@ function updateStats(entry: HookActivityEntry): void {
     s.policyMap[entry.policyName] = (s.policyMap[entry.policyName] ?? 0) + 1;
   }
   // Write atomically: write to a PID-unique temp file then rename — prevents partial reads.
-  const tmpPath = join(storeDir, `stats.json.${process.pid}.tmp`);
+  const tmpPath = join(storeDirValue(), `stats.json.${process.pid}.tmp`);
   try {
     writeFileSync(tmpPath, JSON.stringify(s), "utf-8");
-    renameSync(tmpPath, join(storeDir, STATS_FILE));
+    renameSync(tmpPath, join(storeDirValue(), STATS_FILE));
   } catch {
     try { unlinkSync(tmpPath); } catch { /* ignore */ }
     // Non-fatal: stats file write failure doesn't block the hook
@@ -288,7 +301,7 @@ export function getHookActivityPage(page: number): HookActivityEntry[] {
   if (page < 1) return [];
 
   if (page === 1) {
-    const currentPath = join(storeDir, CURRENT_FILE);
+    const currentPath = join(storeDirValue(), CURRENT_FILE);
     return readJsonlFile(currentPath).reverse();
   }
 
@@ -296,7 +309,7 @@ export function getHookActivityPage(page: number): HookActivityEntry[] {
   const archiveIndex = page - 2;
   if (archiveIndex >= archives.length) return [];
 
-  return readJsonlFile(join(storeDir, archives[archiveIndex])).reverse();
+  return readJsonlFile(join(storeDirValue(), archives[archiveIndex])).reverse();
 }
 
 export function getHookActivityPageCount(): number {
@@ -307,13 +320,13 @@ export function getHookActivityPageCount(): number {
 export function getAllHookActivityEntries(): HookActivityEntry[] {
   ensureDir();
 
-  const currentPath = join(storeDir, CURRENT_FILE);
+  const currentPath = join(storeDirValue(), CURRENT_FILE);
   const currentEntries = readJsonlFile(currentPath).reverse();
 
   const archives = getArchiveFiles();
   const archiveEntries: HookActivityEntry[] = [];
   for (const file of archives) {
-    const entries = readJsonlFile(join(storeDir, file));
+    const entries = readJsonlFile(join(storeDirValue(), file));
     archiveEntries.push(...entries.reverse());
   }
 
@@ -392,7 +405,7 @@ function readJsonlFile(filePath: string): HookActivityEntry[] {
 
 function getArchiveFiles(): string[] {
   try {
-    const files = readdirSync(storeDir);
+    const files = readdirSync(storeDirValue());
     return files
       .filter((f) => f.startsWith("page-") && f.endsWith(".jsonl"))
       .sort((a, b) => {
@@ -414,5 +427,7 @@ function getArchiveFiles(): string[] {
 
 export function _resetForTest(testDir?: string): void {
   rotateSeq = 0;
-  storeDir = testDir ?? DEFAULT_STORE_DIR;
+  // null, not the default path: clearing the override lets the getter re-read
+  // FAILPROOFAI_HOME, which a test may have changed since this module loaded.
+  storeDirOverride = testDir ?? null;
 }

package/src/hooks/hook-logger.ts

@@ -22,13 +22,14 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { logsDir } from "./fp-home";
 
 export type LogLevel = "info" | "warn" | "error";
 
 const LEVEL_ORDER: Record<LogLevel, number> = { info: 0, warn: 1, error: 2 };
 const MAX_FILE_SIZE = 512 * 1024; // 500 KB
 const LOG_FILENAME = "hooks.log";
-const DEFAULT_LOG_DIR = join(homedir(), ".failproofai", "logs");
+const DEFAULT_LOG_DIR = logsDir();
 
 // ── State (lazy-initialized) ──
 

package/src/hooks/hook-telemetry.ts

@@ -7,6 +7,7 @@
 
 import { version } from "../../package.json";
 import { POSTHOG_API_KEY, POSTHOG_PRODUCT } from "../posthog-key";
+import { isTelemetryEnabled } from "../../lib/telemetry-enabled";
 
 const API_KEY = POSTHOG_API_KEY;
 const CAPTURE_URL = "https://us.i.posthog.com/capture/";
@@ -57,7 +58,10 @@ export async function trackHookEvent(
   event: string,
   properties?: Record<string, unknown>,
 ): Promise<void> {
-  if (process.env.FAILPROOFAI_TELEMETRY_DISABLED === "1") return;
+  // Honours the config file as well as the env var — the env var alone cannot
+  // reach a system-scope daemon. Memoised, so this stays off the hook path's
+  // latency budget. See lib/telemetry-enabled.ts.
+  if (!isTelemetryEnabled()) return;
 
   const p = sendEvent(distinctId, event, properties);
   pending.add(p);

package/src/hooks/hooks-config.ts

@@ -7,6 +7,7 @@ import { homedir } from "node:os";
 import type { HooksConfig, ConventionPolicyRecord } from "./policy-types";
 import type { HookScope } from "./types";
 import { hookLogInfo, hookLogWarn } from "./hook-logger";
+import { globalPolicyConfigFile } from "./fp-home";
 
 /** Normalize plural and legacy singular explicit policy paths for consumers. */
 export function configuredCustomPolicyPaths(
@@ -69,7 +70,7 @@ export function readMergedHooksConfig(cwd?: string): HooksConfig {
   const base = findProjectConfigDir(cwd ?? process.cwd());
   const projectPath = resolve(base, ".failproofai", "policies-config.json");
   const localPath = resolve(base, ".failproofai", "policies-config.local.json");
-  const globalPath = resolve(homedir(), ".failproofai", "policies-config.json");
+  const globalPath = globalPolicyConfigFile();
 
   const project = readConfigAt(projectPath);
   const local = readConfigAt(localPath);
@@ -128,7 +129,7 @@ export function readMergedHooksConfig(cwd?: string): HooksConfig {
 }
 
 function getConfigPath(): string {
-  return resolve(homedir(), ".failproofai", "policies-config.json");
+  return globalPolicyConfigFile();
 }
 
 export function readHooksConfig(): HooksConfig {
@@ -160,7 +161,7 @@ export function writeHooksConfig(config: HooksConfig): void {
 export function getConfigPathForScope(scope: HookScope, cwd?: string): string {
   switch (scope) {
     case "user":
-      return resolve(homedir(), ".failproofai", "policies-config.json");
+      return globalPolicyConfigFile();
     case "project":
       return resolve(findProjectConfigDir(cwd ?? process.cwd()), ".failproofai", "policies-config.json");
     case "local":

package/src/hooks/loader-utils.ts

@@ -11,12 +11,75 @@
  *
  * The ESM shim includes hooks API exports.
  */
-import { readFile, writeFile, unlink, access } from "fs/promises";
-import { resolve, dirname, relative } from "path";
+import { readFile, writeFile, unlink, access, mkdir, lstat } from "fs/promises";
+import { tmpdir } from "os";
+import { resolve, dirname, relative, join } from "path";
 import { pathToFileURL } from "url";
+import { createHash } from "crypto";
+import { shimsDir } from "./fp-home";
+import { hookLogWarn } from "./hook-logger";
 
 export const TMP_SUFFIX = ".__failproofai_tmp__.mjs";
 
+/**
+ * Anything this loader generated, by name.
+ *
+ * The temporary tree is written BESIDE the user's sources, because that is the
+ * only place a rewritten relative import still resolves. That was harmless
+ * while the name was fixed — an abnormally terminated hook left at most one
+ * stale file per source, overwritten on the next load — but the name now
+ * carries a pid and a sequence number, so every kill (a CLI hook timeout, a
+ * Ctrl-C) leaves a uniquely-named file behind forever.
+ *
+ * Two consequences, and the second is the visible one: the directory fills up,
+ * and `findSkippedPolicyFiles` reports each leftover back to the user as a
+ * policy file that will not load — an accusation about a file failproofai
+ * wrote itself.
+ */
+const TMP_ARTIFACT_RE = /\.__failproofai_tmp__\./;
+
+/** True for a file this loader generated rather than one the user wrote. */
+export function isTmpArtifact(name: string): boolean {
+  return TMP_ARTIFACT_RE.test(name);
+}
+
+/**
+ * How stale a generated file must be before a sweep will remove it.
+ *
+ * Another process may be mid-load right now, and its temporary tree is live
+ * until its `import()` resolves. Well past the 10s a module load is allowed,
+ * so a sweep can never delete a file another loader is still using.
+ */
+const TMP_SWEEP_MIN_AGE_MS = 60_000;
+
+/**
+ * Remove generated files left behind by a load that was killed.
+ *
+ * Best-effort and never throws: this runs on the hook path, and failing to
+ * tidy up is not worth failing an evaluation over.
+ */
+export async function sweepStaleTmpArtifacts(dir: string, now = Date.now()): Promise<number> {
+  let removed = 0;
+  try {
+    const { readdir, stat } = await import("fs/promises");
+    for (const name of await readdir(dir)) {
+      if (!isTmpArtifact(name)) continue;
+      const path = resolve(dir, name);
+      try {
+        const info = await stat(path);
+        if (now - info.mtimeMs < TMP_SWEEP_MIN_AGE_MS) continue;
+        await unlink(path);
+        removed++;
+      } catch {
+        /* raced with another sweep, or not ours to remove */
+      }
+    }
+  } catch {
+    /* unreadable directory — nothing to sweep */
+  }
+  return removed;
+}
+
 /** Regex to find local relative import specifiers (ESM). */
 const LOCAL_IMPORT_RE = /(?:import\s+(?:[\s\S]*?\s+from\s+)?|export\s+(?:[\s\S]*?\s+from\s+))(['"])(\.\.?\/[^'"]+)\1/g;
 
@@ -74,12 +137,57 @@ export async function resolveLocalImport(
  * Exports the full public API of failproofai: customPolicies, allow, deny, instruct,
  * getCustomHooks, clearCustomHooks.
  */
+/**
+ * Create the ESM shim that lets a policy file's `import ... from 'failproofai'`
+ * resolve, and return where it landed.
+ *
+ * NOT beside `dist/index.js`, which is where this used to go. That directory
+ * belongs to whoever installed the package, and on a system-wide install
+ * (`sudo npm i -g`, a container image, a shared build host, a CI runner) it is
+ * root-owned — so every non-root user running a hook failed with EACCES, the
+ * policy never loaded, and the hook exited 0. Builtins kept firing while
+ * cloud-managed and custom policies silently stopped, so the machine looked
+ * protected. That is the worst available failure for a policy engine.
+ *
+ * Two locations, and the ORDER OF OPERATIONS matters more than the choice:
+ *
+ *  1. `<home>/state/shims` — created at 0700 and owned by the user running the
+ *     hook. Unlike a shared `/tmp`, no other local user can pre-plant a file at
+ *     a path we are about to `import`.
+ *  2. `os.tmpdir()` — only when the first is unusable.
+ *
+ * **The write lives inside the same `try` as the mkdir on purpose.** `mkdir`
+ * with `recursive` RESOLVES on a directory that already exists, whatever its
+ * mode — so a `state/shims` left behind unwritable (a container that ran the
+ * CLI as root and then dropped to a non-root user; this very function creates
+ * that chain) would sail past a mkdir-only guard and throw EACCES on the write,
+ * reproducing the exact fail-open this function exists to fix. Any failure of
+ * either step falls through to the fallback, and says so — a silent slide into
+ * the weaker path is the same class of bug again.
+ */
+async function writeShim(
+  dir: string,
+  name: string,
+  code: string,
+  exclusive: boolean,
+): Promise<string> {
+  const shimPath = join(dir, name);
+  // 0600 explicitly: an unset mode is `0666 & ~umask`, and `umask 000` is
+  // routine in containers — which in the fallback means a world-writable file
+  // in shared /tmp that this process then imports.
+  await writeFile(shimPath, code, {
+    encoding: "utf-8",
+    mode: 0o600,
+    ...(exclusive ? { flag: "wx" as const } : {}),
+  });
+  return shimPath;
+}
+
 export async function createEsmShim(
   distIndex: string,
   distUrl: string,
   tmpSuffix = TMP_SUFFIX,
 ): Promise<{ shimPath: string; shimUrl: string }> {
-  const shimPath = `${distIndex}${tmpSuffix}.shim.mjs`;
   const shimCode = [
     `import _cjs from '${distUrl}';`,
     `export const customPolicies = _cjs.customPolicies;`,
@@ -90,7 +198,35 @@ export async function createEsmShim(
     `export const instruct = _cjs.instruct;`,
     `export default _cjs;`,
   ].join("\n");
-  await writeFile(shimPath, shimCode, "utf-8");
+  // The name still carries `tmpSuffix` (pid + load sequence + a random id).
+  // `fingerprintTemporaryTree` normalises exactly that substring away before
+  // hashing, so the policy module cache still hits; a name it could not
+  // normalise would force a cold module load on every single hook call.
+  const name = `failproofai-dist${tmpSuffix}.shim.mjs`;
+
+  try {
+    const dir = shimsDir();
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    // `mkdir` accepts a pre-existing SYMLINK here and a plain write would
+    // follow it out of the home. Confirm we got a real directory we own,
+    // unreadable to anyone else, before writing something we are about to
+    // execute.
+    const st = await lstat(dir);
+    const uid = typeof process.getuid === "function" ? process.getuid() : null;
+    if (!st.isDirectory() || st.isSymbolicLink() || (uid !== null && st.uid !== uid) || st.mode & 0o077) {
+      throw new Error(`${dir} is not a private directory owned by this user`);
+    }
+    const shimPath = await writeShim(dir, name, shimCode, false);
+    return { shimPath, shimUrl: pathToFileURL(shimPath).href };
+  } catch (err) {
+    hookLogWarn(
+      `policy shim directory unusable (${err instanceof Error ? err.message : String(err)}); falling back to ${tmpdir()}`,
+    );
+  }
+
+  // Predictable name in a shared directory, so O_EXCL: refuse rather than write
+  // through something another user planted.
+  const shimPath = await writeShim(tmpdir(), name, shimCode, true);
   return { shimPath, shimUrl: pathToFileURL(shimPath).href };
 }
 
@@ -103,6 +239,16 @@ export async function rewriteFileTree(
   distUrl: string | null,
   distIndex: string | null,
   tmpSuffix = TMP_SUFFIX,
+  /**
+   * SHA-256 the ENTRY file's raw bytes must match, re-checked here at the moment
+   * they are read for rewriting and import. Cloud-managed policies pass their
+   * pinned digest so the bytes that get imported are the same bytes that were
+   * verified — closing a TOCTOU where an earlier caller hashed the file, then
+   * this function independently re-read it (a window in which a same-user
+   * attacker could swap the bytes so a verified file imports unverified code).
+   * Only the entry is content-addressed; transitive local imports are not.
+   */
+  entrySha256?: string | null,
 ): Promise<string[]> {
   const queue: string[] = [entryPath];
   const visited = new Set<string>();
@@ -120,7 +266,22 @@ export async function rewriteFileTree(
     if (visited.has(filePath)) continue;
     visited.add(filePath);
 
-    let code = await readFile(filePath, "utf-8");
+    let code: string;
+    if (entrySha256 && filePath === entryPath) {
+      // Read the raw bytes, verify the pin against THEM, then decode and rewrite
+      // that same in-memory content — filePath is never read again, so the bytes
+      // imported below are exactly the bytes verified here.
+      const buf = await readFile(filePath);
+      const actual = createHash("sha256").update(buf).digest("hex");
+      if (actual !== entrySha256) {
+        throw new Error(
+          `cloud-managed policy failed integrity re-verification at load: expected ${entrySha256}, got ${actual}`,
+        );
+      }
+      code = buf.toString("utf-8");
+    } else {
+      code = await readFile(filePath, "utf-8");
+    }
 
     // Rewrite 'failproofai' or legacy 'claudeye' imports to the ESM shim (or direct CJS for require)
     if (esmShimUrl) {

package/src/hooks/manager.ts

@@ -24,6 +24,7 @@ import { trackHookEvent } from "./hook-telemetry";
 import { getInstanceId, hashToId } from "../../lib/telemetry-id";
 import { CliError } from "../cli-error";
 import { hookLogWarn } from "./hook-logger";
+import { customPoliciesDir, globalPolicyConfigFile } from "./fp-home";
 
 const VALID_POLICY_NAMES = new Set(BUILTIN_POLICIES.map((p) => p.name));
 
@@ -645,7 +646,7 @@ export async function listHooks(cwd?: string): Promise<void> {
     } else {
       console.log("\n  Run `failproofai policies --install` to get started.");
     }
-    console.log("  Config: ~/.failproofai/policies-config.json\n");
+    console.log(`  Config: ${globalPolicyConfigFile()}\n`);
   } else if (installedScopes.length === 1) {
     // State B: Single scope — table with header row
     const scope = installedScopes[0];
@@ -657,7 +658,7 @@ export async function listHooks(cwd?: string): Promise<void> {
     for (const policy of regularPolicies) printSimpleRow(policy);
     printBetaSection(printSimpleRow);
 
-    console.log("\n  Config: ~/.failproofai/policies-config.json\n");
+    console.log(`\n  Config: ${globalPolicyConfigFile()}\n`);
   } else {
     // State C: Multiple scopes — column table
     const COL = 9;
@@ -701,7 +702,7 @@ export async function listHooks(cwd?: string): Promise<void> {
       for (const policy of betaPolicies) printMultiScopeRow(policy);
     }
 
-    console.log("\n  Config: ~/.failproofai/policies-config.json");
+    console.log(`\n  Config: ${globalPolicyConfigFile()}`);
 
     // Multi-scope warning
     const scopeNames = installedScopes.join(", ");
@@ -765,7 +766,7 @@ export async function listHooks(cwd?: string): Promise<void> {
   // hook path was loading them.
   const base = findProjectConfigDir(cwd ?? process.cwd());
   const projectDir = resolve(base, ".failproofai", "policies");
-  const userDir = resolve(homedir(), ".failproofai", "policies");
+  const userDir = customPoliciesDir();
   const sameDir = userDir === projectDir;
   const conventionDirs: { label: string; dir: string }[] = [
     { label: sameDir ? "Project + User" : "Project", dir: projectDir },

package/src/hooks/onboarding-lock.ts

@@ -0,0 +1,119 @@
+/**
+ * A single-holder guard around first-run onboarding.
+ *
+ * Onboarding used to fire only on a bare `failproofai`. It now fires on any
+ * command an unconfigured machine runs, which makes concurrent runs a real
+ * shape rather than a theoretical one: two terminals, `failproofai audit` in
+ * each, and both draw a wizard. They would then race on the same settings
+ * files and, worse, both try to install the system service — two `sudo`
+ * prompts and two `systemctl enable` calls against one unit.
+ *
+ * ## Why liveness, not a timeout
+ *
+ * The obvious lock carries a timestamp and is treated as stale after N
+ * seconds. That cannot work here: the holder is a human answering questions,
+ * so any N short enough to recover promptly from a crash is also short enough
+ * to evict someone who walked away mid-setup. So the lock records a PID and is
+ * considered held only while that process is actually alive — which recovers
+ * instantly from a crash or a Ctrl-C, and never evicts a live wizard no matter
+ * how long it sits.
+ *
+ * ## Failure direction
+ *
+ * Every failure here resolves to "do not onboard". A lock we cannot take is
+ * indistinguishable from one already held, and skipping onboarding costs a
+ * user one printed hint, where wrongly proceeding costs a duplicated install.
+ * The command the user typed always runs either way.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { onboardingLockFile, stateDir } from "./fp-home";
+
+interface LockBody {
+  pid: number;
+  startedAt: number;
+}
+
+export function onboardingLockPath(home: string = homedir()): string {
+  return onboardingLockFile(home);
+}
+
+/**
+ * Whether `pid` is a live process this user can signal.
+ *
+ * `kill(pid, 0)` performs the permission and existence checks without
+ * delivering a signal. `EPERM` means the process exists but belongs to another
+ * user — still alive, so still holding the lock.
+ */
+function processAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException)?.code === "EPERM";
+  }
+}
+
+function readLock(path: string): LockBody | null {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<LockBody>;
+    if (typeof parsed.pid !== "number") return null;
+    return { pid: parsed.pid, startedAt: Number(parsed.startedAt) || 0 };
+  } catch {
+    // Absent, unreadable, or truncated by a crash mid-write. All three mean
+    // "no live holder we can prove", and the liveness check below is what
+    // actually decides.
+    return null;
+  }
+}
+
+export interface OnboardingLock {
+  /** Release the lock. Safe to call more than once. */
+  release(): void;
+}
+
+/**
+ * Take the onboarding lock, or return `null` if another live process holds it.
+ *
+ * There is a small window between the liveness check and the write in which
+ * two processes could both decide the lock is free. That is accepted
+ * deliberately: closing it needs `O_EXCL` plus stale-file recovery, which
+ * reintroduces exactly the timeout problem this design avoids — and the
+ * consequence of losing that race is two wizards, which is the situation
+ * before this existed, not something worse.
+ */
+export function acquireOnboardingLock(home: string = homedir()): OnboardingLock | null {
+  const path = onboardingLockPath(home);
+  try {
+    const held = readLock(path);
+    // Our own PID appearing here means a previous run in this same process
+    // already holds it — re-entering is fine and must not deadlock.
+    if (held && held.pid !== process.pid && processAlive(held.pid)) return null;
+
+    mkdirSync(stateDir(home), { recursive: true });
+    const body: LockBody = { pid: process.pid, startedAt: Date.now() };
+    writeFileSync(path, JSON.stringify(body), "utf8");
+
+    let released = false;
+    return {
+      release() {
+        if (released) return;
+        released = true;
+        try {
+          // Only remove a lock still recorded as ours: if this process was
+          // evicted as dead and another wizard took over, deleting the file
+          // would release someone else's lock.
+          const current = readLock(path);
+          if (!current || current.pid === process.pid) rmSync(path, { force: true });
+        } catch {
+          /* best effort — a stray lock is reclaimed by the liveness check */
+        }
+      },
+    };
+  } catch {
+    // Unwritable home, read-only filesystem, whatever it is: treat as held.
+    return null;
+  }
+}