failproofai 1.0.0-beta.0 → 1.0.0-beta.10

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,11 +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 + ".__failproofai_esm_shim__.mjs";
   const shimCode = [
     `import _cjs from '${distUrl}';`,
     `export const customPolicies = _cjs.customPolicies;`,
@@ -89,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 };
 }
 
@@ -101,6 +238,17 @@ export async function rewriteFileTree(
   entryPath: string,
   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>();
@@ -108,7 +256,7 @@ export async function rewriteFileTree(
 
   let esmShimUrl: string | null = null;
   if (distIndex && distUrl) {
-    const shim = await createEsmShim(distIndex, distUrl);
+    const shim = await createEsmShim(distIndex, distUrl, tmpSuffix);
     tmpFiles.push(shim.shimPath);
     esmShimUrl = shim.shimUrl;
   }
@@ -118,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) {
@@ -148,7 +311,7 @@ export async function rewriteFileTree(
         if (!visited.has(resolved) && !queue.includes(resolved)) {
           queue.push(resolved);
         }
-        let relPath = relative(dir, resolved + TMP_SUFFIX).split("\\").join("/");
+        let relPath = relative(dir, resolved + tmpSuffix).split("\\").join("/");
         if (!relPath.startsWith(".")) relPath = "./" + relPath;
         rewrites.set(specifier, relPath);
       }
@@ -163,7 +326,7 @@ export async function rewriteFileTree(
       code = code.replace(new RegExp(`"${escaped}"`, "g"), `"${replacement}"`);
     }
 
-    const tmpPath = filePath + TMP_SUFFIX;
+    const tmpPath = filePath + tmpSuffix;
     await writeFile(tmpPath, code, "utf-8");
     tmpFiles.push(tmpPath);
   }

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-attempt.ts

@@ -0,0 +1,179 @@
+/**
+ * Why the last first-run setup stopped, and whether it is worth offering again.
+ *
+ * # The problem this exists for
+ *
+ * Setup is deliberately all-or-nothing: every abort path writes NOTHING, so a
+ * machine that could not be configured is left exactly as it was found rather
+ * than carrying half a configuration (a `daemonConfigured` flag with no daemon
+ * behind it denies every tool call across all twelve CLIs). That invariant is
+ * right and is not changed here.
+ *
+ * But it left onboarding with no memory. `isConfigured()` reads three signals —
+ * a global policy config, live user-scope hooks, the legacy marker — and an
+ * abort sets none of them, so "never tried" and "tried twenty times and could
+ * not finish" are indistinguishable. On a machine without passwordless sudo,
+ * every single command relaunched the whole wizard, forever.
+ *
+ * # What this is NOT
+ *
+ * Not a fourth "configured" signal. Nothing here may make `isConfigured()` true.
+ * A machine that failed setup is unconfigured and must keep saying so — to the
+ * hook path, to `--status`, and to the wizard when it is asked for by name.
+ * This only changes whether the wizard is *offered unprompted*.
+ *
+ * # Re-offering
+ *
+ * A hint that never becomes an offer again is its own failure: the common case
+ * is someone who hits the sudo prompt, gives up, and comes back later able to
+ * elevate. So each reason carries a cheap local check for whether its blocker
+ * is gone, and the wizard offers itself again the moment one is:
+ *
+ *   needs_root     -> elevation is now possible without a prompt
+ *   daemon_failed  -> the service manager now reports something different
+ *   cancelled      -> the CLI version changed; an upgrade is a fair moment to
+ *                     ask again, and nothing else about a deliberate cancel
+ *                     should re-nag
+ *
+ * Every probe is local and takes milliseconds. None of them runs on the hook
+ * path — `--hook` never reaches the first-run gate at all.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { onboardingAttemptFile } from "./fp-home";
+import type { WizardAbort } from "./configure-wizard";
+
+/** Bumped only for a deliberate shape change; an unreadable record is ignored. */
+const SCHEMA_VERSION = 1;
+
+export interface OnboardingAttempt {
+  schemaVersion: number;
+  /** Why the wizard stopped. */
+  reason: WizardAbort;
+  /** The CLI that made the attempt, so an upgrade can re-offer. */
+  cliVersion: string;
+  /**
+   * What the service manager said at the time. Compared, never trusted — the
+   * point is only whether it has CHANGED since.
+   */
+  daemonStatus: string;
+  /** Epoch ms, for support and for nothing else. */
+  at: number;
+}
+
+export function readOnboardingAttempt(): OnboardingAttempt | null {
+  const path = onboardingAttemptFile();
+  if (!existsSync(path)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8")) as Partial<OnboardingAttempt>;
+    if (raw.schemaVersion !== SCHEMA_VERSION) return null;
+    if (typeof raw.reason !== "string" || typeof raw.cliVersion !== "string") return null;
+    return {
+      schemaVersion: SCHEMA_VERSION,
+      reason: raw.reason as WizardAbort,
+      cliVersion: raw.cliVersion,
+      daemonStatus: typeof raw.daemonStatus === "string" ? raw.daemonStatus : "",
+      at: typeof raw.at === "number" ? raw.at : 0,
+    };
+  } catch {
+    // A corrupt record reads as "no record", which degrades to today's
+    // behaviour — offering the wizard. Never to "configured".
+    return null;
+  }
+}
+
+/** Best-effort: a machine that cannot record this simply keeps being offered. */
+export function recordOnboardingAttempt(
+  reason: WizardAbort,
+  cliVersion: string,
+  daemonStatus: string,
+  now: number = Date.now(),
+): void {
+  try {
+    const path = onboardingAttemptFile();
+    mkdirSync(dirname(path), { recursive: true });
+    const record: OnboardingAttempt = {
+      schemaVersion: SCHEMA_VERSION,
+      reason,
+      cliVersion,
+      daemonStatus,
+      at: now,
+    };
+    writeFileSync(path, JSON.stringify(record, null, 2), "utf8");
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * Called on a completed apply. A stale record would keep suppressing the offer
+ * on a machine that has since been reconfigured by hand and un-configured again.
+ */
+export function clearOnboardingAttempt(): void {
+  try {
+    rmSync(onboardingAttemptFile(), { force: true });
+  } catch {
+    // best-effort
+  }
+}
+
+export interface RetryProbe {
+  /** Elevation is possible without prompting. */
+  canElevate: () => boolean;
+  /** What the service manager says right now. */
+  daemonStatus: () => string;
+  /** This CLI's version. */
+  cliVersion: string;
+}
+
+/**
+ * Whether the thing that stopped setup last time has since changed.
+ *
+ * `true` means offer the wizard again; `false` means a one-line hint. An
+ * unrecognised reason returns `true` — an unknown blocker is one we cannot
+ * prove is still present, and the safe direction is offering setup rather than
+ * silently withholding it.
+ */
+export function blockerCleared(attempt: OnboardingAttempt, probe: RetryProbe): boolean {
+  switch (attempt.reason) {
+    case "needs_root":
+      return probe.canElevate();
+    case "daemon_failed":
+      // Any movement at all: not-installed -> stopped, stopped -> running, or a
+      // platform that has gained a service manager. Comparing rather than
+      // demanding "running" is what lets a partially-repaired machine be
+      // offered setup again instead of waiting for a state it cannot reach on
+      // its own.
+      return probe.daemonStatus() !== attempt.daemonStatus || probe.canElevate();
+    case "cancelled":
+      // A deliberate stop. Re-asking on the next command is exactly the nagging
+      // this module removes — but an upgrade is a new thing to say, so it is
+      // allowed to ask once more.
+      return probe.cliVersion !== attempt.cliVersion;
+    case "not_a_tty":
+    case "running_as_sudo":
+      // Both are properties of the invocation, not of the machine, so the next
+      // one may well be fine.
+      return true;
+    default:
+      return true;
+  }
+}
+
+/** The one line shown instead of relaunching the wizard. */
+export function attemptHintLines(attempt: OnboardingAttempt): string[] {
+  const why: Record<string, string> = {
+    needs_root: "it needs root to install the failproofaid service",
+    daemon_failed: "the failproofaid service could not be started",
+    cancelled: "it was cancelled",
+    not_a_tty: "there was no terminal to ask in",
+    running_as_sudo: "it was run under sudo",
+  };
+  const detail = why[attempt.reason] ?? "it did not finish";
+  return [
+    ``,
+    `[failproofai] Setup is not finished — ${detail}.`,
+    `              Run \`failproofai config\` when you are ready.`,
+    ``,
+  ];
+}

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;
+  }
+}

package/src/hooks/policy-types.ts

@@ -80,8 +80,36 @@ export interface LlmConfig {
   model?: string;
 }
 
+/**
+ * The collector's non-secret settings. The ingest credential deliberately does
+ * NOT live here: this file is written with a bare `writeFileSync`, so it
+ * inherits the umask and lands at 0664 inside a 0775 `~/.failproofai/` — an API
+ * key here would be readable by every local user. It lives in
+ * `~/.failproofai/ingest.json` at 0600 instead.
+ *
+ * Read by the Rust daemon (`crates/fpai-collect/src/config.rs`); the field
+ * names must stay in step with the `Settings` struct there.
+ */
+export interface CollectorConfig {
+  /**
+   * Ship agent session transcripts. Defaults to false and is a SEPARATE opt-in
+   * from configuring a key, because transcripts carry prompts, file contents
+   * and whatever was pasted into a terminal.
+   */
+  sessions?: boolean;
+  /** Ship hook activity. Carries decisions and tool names, never file contents. */
+  hooks?: boolean;
+  /** `decisions` keeps every deny/instruct exact and aggregates the ~99% allows. */
+  hooksVerbosity?: "all" | "decisions" | "off";
+  redact?: "minimal" | "off";
+  /** Label stamped on every event. Must not contain a comma — ingest skips those lines. */
+  environment?: string;
+}
+
 export interface HooksConfig {
   enabledPolicies: string[];
+  /** Collector settings; see {@link CollectorConfig}. Absent means unconfigured. */
+  collector?: CollectorConfig;
   llm?: LlmConfig;
   policyParams?: Record<string, Record<string, unknown>>;
   /** Explicit custom policy files, loaded in array order. */