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

package/src/audit/audit-lock.ts

@@ -0,0 +1,285 @@
+/**
+ * One audit at a time on this machine, across processes.
+ *
+ * Three entry points can start a scan — a scheduled run, an explicit
+ * `failproofai audit`, and the dashboard's `/api/audit/run` — and every one of
+ * them writes the same sha1-keyed per-transcript cache files and the same
+ * single-slot `audit/dashboard.json`. The only lock that existed before this
+ * was `app/api/audit/_state.ts`, a module-level singleton inside the Next.js
+ * server: invisible to the other two, and by its own admission invisible to a
+ * second Next.js worker as well.
+ *
+ * ## Why a lockfile and not a flock
+ *
+ * `flock()` releases itself when the holder dies, which is exactly the property
+ * we would want — but it needs a held file descriptor, and the interactive path
+ * hands off to `launch()` and lives on for as long as the user leaves the
+ * dashboard open. A lockfile whose contents name the holder can be released at
+ * the end of the SCAN, which is the thing being serialised, and it can be
+ * inspected by a human wondering why their audit refused to start. The cost is
+ * that a crash leaves the file behind, which the stale rules below cover.
+ *
+ * ## The two stale rules
+ *
+ * **A dead pid** is the primary one and the one that fires in practice:
+ * Ctrl+C, SIGKILL and a laptop lid are all "the lock is on disk, the process is
+ * not". **Age** is the backstop for the cases a pid check cannot see — a
+ * recycled pid, or a lock written by a machine that shares this home over a
+ * network filesystem.
+ */
+import {
+  closeSync,
+  linkSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+  writeSync,
+} from "node:fs";
+import { auditLockFile, failproofaiHome, runDir } from "../hooks/fp-home";
+
+/**
+ * How old a lock has to be before its holder is presumed gone even though the
+ * pid still resolves.
+ *
+ * A full scan measured ~104 seconds over 3,277 transcripts on a development
+ * machine with a warm cache. The ceiling has to clear the worst plausible
+ * HONEST run by a wide margin, because stealing from a live audit is the one
+ * outcome this module exists to prevent — it puts two writers on the same cache
+ * files. A cold cache, a much longer history, a spinning disk, or the `nice(19)`
+ * scheduled run competing with a busy laptop can each cost an order of
+ * magnitude, so: one hour, roughly 35× the measured run. Nothing is lost by
+ * being generous here, since the dead-pid rule already collects every crash.
+ */
+export const AUDIT_LOCK_MAX_AGE_MS = 60 * 60_000;
+
+/**
+ * Which entry point holds the lock. Recorded so a refusal can say who it lost
+ * to. All four are wired: `cli` and `scheduled` in `src/audit/cli.ts`,
+ * `dashboard` in `app/api/audit/run/route.ts`, and `onboarding` in
+ * `runPostSetupAudit` — every process that writes the shared cache takes this
+ * lock, so no two of them can co-write it.
+ */
+export type AuditLockSource = "cli" | "scheduled" | "dashboard" | "onboarding";
+
+export interface AuditLockInfo {
+  pid: number;
+  /** Wall-clock ms. Monotonic time would reset every process start. */
+  startedAt: number;
+  source: AuditLockSource;
+}
+
+export interface AuditLockHandle {
+  info: AuditLockInfo;
+  /** Idempotent, never throws, and only ever removes a lock this handle owns. */
+  release(): void;
+}
+
+export type AcquireAuditLockResult =
+  | { ok: true; lock: AuditLockHandle }
+  /** `heldBy` is null when the holder's lock could not be read at all. */
+  | { ok: false; heldBy: AuditLockInfo | null };
+
+/**
+ * Take the lock, stealing a provably-abandoned one.
+ *
+ * Never throws: a caller deciding whether to run an audit must not have to
+ * handle an exception from the thing that decides.
+ */
+export function acquireAuditLock(source: AuditLockSource, now: number = Date.now()): AcquireAuditLockResult {
+  const path = auditLockFile();
+  const info: AuditLockInfo = { pid: process.pid, startedAt: now, source };
+
+  try {
+    ensureRunDir();
+  } catch {
+    // We could not even create the directory the lock lives in, so we cannot
+    // prove exclusivity. Report contention rather than running: a refused audit
+    // is a retry, whereas two unserialised ones corrupt a shared cache.
+    return { ok: false, heldBy: null };
+  }
+
+  if (writeLockExclusive(path, info)) return { ok: true, lock: handleFor(path, info) };
+
+  const held = readLock(path);
+  if (!isStale(held, now)) return { ok: false, heldBy: held };
+
+  try {
+    unlinkSync(path);
+  } catch {
+    // Already gone — another process judged it stale at the same moment. The
+    // O_EXCL retry below is what decides between us.
+  }
+  // Exactly one retry, deliberately. Two processes that both called the lock
+  // stale race here and O_EXCL picks one; looping would let the loser keep
+  // going until it stole the WINNER's brand-new lock.
+  if (writeLockExclusive(path, info)) return { ok: true, lock: handleFor(path, info) };
+  return { ok: false, heldBy: readLock(path) };
+}
+
+/** Whoever holds the lock right now, or null if it is free/unreadable. */
+export function readAuditLock(): AuditLockInfo | null {
+  return readLock(auditLockFile());
+}
+
+/**
+ * The holder only when its lock is still ACTIVE — holder alive and not aged
+ * out; null when the lock is free, unreadable, or provably abandoned.
+ *
+ * For status/UI, not for acquiring: a settings page or `/api/audit/status`
+ * asking "is a scan running somewhere on this machine right now?" must answer
+ * off the same staleness rules `acquireAuditLock` uses, or it would report
+ * "running" forever off a crashed run's leftover lockfile — a dead pid or an
+ * hour-old file the next real acquire would rightly steal. Read-only: unlike
+ * `acquireAuditLock` it never unlinks or steals, so it is safe to call from a
+ * request handler that only wants to describe the machine's state.
+ */
+export function readActiveAuditLock(now: number = Date.now()): AuditLockInfo | null {
+  const held = readLock(auditLockFile());
+  return isStale(held, now) ? null : held;
+}
+
+function isStale(held: AuditLockInfo | null, now: number): boolean {
+  // EEXIST with nothing parseable inside it: either a truncated write or a file
+  // from a version that wrote a different shape. Neither names a holder we
+  // could ever wait for.
+  if (!held) return true;
+  if (!isProcessAlive(held.pid)) return true;
+  // A startedAt in the future (clock skew, a shared home across machines) reads
+  // as fresh, not as stale — the subtraction goes negative and the comparison
+  // fails, which is the direction that does not steal from a live run.
+  return now - held.startedAt > AUDIT_LOCK_MAX_AGE_MS;
+}
+
+function isProcessAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM means the process exists and belongs to somebody else — two OS
+    // users on one box, or a shared home. Alive is the safe reading of that.
+    return (err as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function handleFor(path: string, info: AuditLockInfo): AuditLockHandle {
+  let released = false;
+  const release = (): void => {
+    if (released) return;
+    released = true;
+    process.removeListener("exit", release);
+    // Only ever remove OUR lock. After a steal the file on disk can already
+    // belong to a third process, and deleting that one would hand a live audit
+    // the co-writer this whole module exists to prevent.
+    const current = readLock(path);
+    if (current && current.pid !== info.pid) return;
+    try {
+      unlinkSync(path);
+    } catch {
+      /* already gone */
+    }
+  };
+
+  // `process.exit()` does not unwind, so a `finally` cannot be relied on here:
+  // `failproofai audit` exits directly on both its failure and its
+  // empty-history path. An exit hook covers those, a normal return, and an
+  // uncaught throw. It does NOT run when the default SIGINT disposition kills
+  // the process — Ctrl+C during a scan is precisely what the dead-pid rule is
+  // there for.
+  process.once("exit", release);
+  return { info, release };
+}
+
+function readLock(path: string): AuditLockInfo | null {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<AuditLockInfo>;
+    if (typeof parsed?.pid !== "number" || typeof parsed?.startedAt !== "number") return null;
+    return {
+      pid: parsed.pid,
+      startedAt: parsed.startedAt,
+      source: (parsed.source ?? "cli") as AuditLockSource,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * True when this call published the lock; false when somebody else already had
+ * it (or the write failed for any other reason, which is equally "not ours").
+ *
+ * Written to a staging file and `link()`ed into place rather than created with
+ * `O_EXCL` and then written. Both are atomic about who WINS, but only this one
+ * is atomic about what the winner's file CONTAINS: `open(O_EXCL)` publishes the
+ * final name while the file is still empty, and an empty lock is an unreadable
+ * lock, which `isStale` — correctly — calls abandoned. A competitor landing in
+ * that window steals the lock from a holder that is mid-acquire and both
+ * processes then scan at once, which is the two-writers-on-one-cache outcome
+ * this whole module exists to prevent. `link()` makes the name appear only once
+ * the bytes behind it are already there. (It is also the idiom that survives a
+ * home shared over NFS, where `O_EXCL` has historically not been atomic at all
+ * — one of the cases the age rule above is a backstop for.)
+ */
+function writeLockExclusive(path: string, info: AuditLockInfo): boolean {
+  const body = JSON.stringify(info);
+  // Same directory, so `link()` stays within one filesystem; keyed by pid so
+  // two processes staging at once cannot overwrite each other's bytes.
+  const staging = `${path}.${process.pid}.tmp`;
+  try {
+    writeFileSync(staging, body, { mode: 0o600 });
+  } catch {
+    return false;
+  }
+  try {
+    linkSync(staging, path);
+    return true;
+  } catch (err) {
+    // EEXIST is the answer we asked the kernel for: somebody else holds it.
+    // Anything else means link() itself is unavailable — a filesystem with no
+    // hard links — and refusing there would mean the audit can never run on
+    // that machine at all, so fall back to the create-then-write form.
+    if ((err as NodeJS.ErrnoException).code === "EEXIST") return false;
+    return createThenWrite(path, body);
+  } finally {
+    try {
+      unlinkSync(staging);
+    } catch {
+      /* the link (or the failure) is what mattered; a leftover staging file is not */
+    }
+  }
+}
+
+/** The `O_EXCL` form, kept only as the no-hard-links fallback above. */
+function createThenWrite(path: string, body: string): boolean {
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, "wx", 0o600);
+    writeSync(fd, body);
+    return true;
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* nothing useful to do with a failed close on a lockfile */
+      }
+    }
+  }
+}
+
+function ensureRunDir(): void {
+  // The home first and at the default mode: `run/` below is created 0700, and
+  // letting a recursive mkdir apply that to `~/.failproofai` itself would hide
+  // config.toml, which is world-readable by design.
+  mkdirSync(failproofaiHome(), { recursive: true });
+  // 0700 explicitly, because failproofaid REFUSES TO START when run/ exists
+  // with any other mode (`ensure_run_dir` in crates/failproofaid/src/paths.rs).
+  // A lock file that created this directory under the ambient umask would
+  // therefore stop the daemon coming up — and on a daemon-configured machine a
+  // daemon that cannot start denies every tool call across all 12 CLIs.
+  mkdirSync(runDir(), { recursive: true, mode: 0o700 });
+}

package/src/audit/audit-schedule.ts

@@ -0,0 +1,111 @@
+/**
+ * The first (and only) TypeScript reader of `~/.failproofai/state/audit-schedule.json`.
+ *
+ * The **daemon is the sole writer** of that file (`crates/failproofaid/src/
+ * audit_lane.rs`); everything on this side only reads it. This module is that
+ * read side: `getScheduledAuditAction` calls it to answer "when did the last
+ * scheduled scan run, and when is the next one due?" on the /settings page.
+ *
+ * ## Why this tolerates a file it did not write
+ *
+ * The daemon and the CLI ship and upgrade independently — a machine can be
+ * running a newer `failproofaid` than its `failproofai`, so the schedule file
+ * on disk can be a schema *ahead* of this build. A settings page that threw, or
+ * blanked its whole scheduled-audit section, because one derived state file was
+ * a version in front would be strictly worse than showing slightly less. So we
+ * read every field **by name, independent of `schema`**: a future file that
+ * still carries `next_due_at_ms` still renders a next-due time. Absent,
+ * unreadable, malformed, and non-object all resolve to `null` (the caller shows
+ * "no scheduled scan yet"); a recognised-but-unknown-higher schema still yields
+ * whatever numeric fields it shares, plus `schemaAhead` so the UI can say "a
+ * newer daemon wrote this" rather than silently dropping a field.
+ *
+ * ## What happened to `next-audit.json` — the one open sub-decision (resolved)
+ *
+ * `~/.failproofai/next-audit.json` (`lib/auth/auth-store.ts`
+ * `readReminder`/`writeReminder`) predates the scheduler and looks like a second
+ * source of truth for "the next audit". It is **not**, and after this change
+ * there is exactly one answer to "when does the next *scan* run": this file's
+ * `next_due_at_ms`. The two are kept **separate with deliberately distinct
+ * meanings**, because they answer different questions:
+ *
+ *   - `audit-schedule.json` (here) = when the machine will next **run a scan
+ *     itself**, headless, via the daemon. This is the scan schedule. It needs
+ *     no human and no sign-in. `[audit] auto` + `interval_days` in `config.toml`
+ *     drive it; the daemon derives and writes this file.
+ *   - `next-audit.json` = an **email nudge to a signed-in human** ("come back
+ *     and audit again"), set from the /audit "come back better" section,
+ *     delivered by Failproof Cloud over SES via the api-server. It runs nothing
+ *     locally; it is re-engagement, not a schedule.
+ *
+ * Collapsing them would merge "the box scans on a timer" with "email this person
+ * a reminder", which are neither the same trigger, the same actor, nor the same
+ * effect. So the /settings scheduled-audit section reads and writes **only** the
+ * scan schedule (this file + `[audit]`) and never touches `next-audit.json`,
+ * leaving the reminder as the /audit page's own concern. That keeps the scan
+ * schedule single-writer (the daemon) and single-file, which is the property the
+ * two-sources-of-truth worry was really about.
+ */
+import { readFileSync } from "node:fs";
+import { auditScheduleFile } from "../hooks/fp-home";
+
+/**
+ * The schema the daemon currently writes — mirrors `SCHEMA` in
+ * `crates/failproofaid/src/audit_lane.rs`. Only used to *flag* a file that
+ * declares a higher one (`schemaAhead`); reads never gate on it, on purpose.
+ */
+export const AUDIT_SCHEDULE_SCHEMA = 1;
+
+export interface AuditScheduleView {
+  /** The `schema` the file declared, or null if absent/non-numeric. */
+  schema: number | null;
+  /** Absolute wall-clock ms of the next scheduled scan, or null. */
+  nextDueAtMs: number | null;
+  /** When a scan was last STARTED (written before the child spawns), or null. */
+  lastAttemptAtMs: number | null;
+  /** When a scan last finished successfully (never advanced by an exit-75
+   *  "lock held"), or null. */
+  lastRunAtMs: number | null;
+  /** The scheduled child's last exit code, or null. */
+  lastExitCode: number | null;
+  /** The file declares a schema newer than this build knows. Fields are still
+   *  read best-effort; this only tells the UI to caveat what it shows. */
+  schemaAhead: boolean;
+}
+
+/**
+ * Read the scheduled-audit state, or null when there is nothing usable to show.
+ *
+ * Never throws: every failure mode (absent file, EACCES, truncated write,
+ * non-JSON, JSON that is not an object) collapses to null, which the caller
+ * renders as "no scheduled scan has run yet".
+ */
+export function readAuditSchedule(home?: string): AuditScheduleView | null {
+  let raw: string;
+  try {
+    raw = readFileSync(auditScheduleFile(home), "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+
+  const obj = parsed as Record<string, unknown>;
+  const num = (v: unknown): number | null =>
+    typeof v === "number" && Number.isFinite(v) ? v : null;
+
+  const schema = num(obj.schema);
+  return {
+    schema,
+    nextDueAtMs: num(obj.next_due_at_ms),
+    lastAttemptAtMs: num(obj.last_attempt_at_ms),
+    lastRunAtMs: num(obj.last_run_at_ms),
+    lastExitCode: num(obj.last_exit_code),
+    schemaAhead: schema !== null && schema > AUDIT_SCHEDULE_SCHEMA,
+  };
+}

package/src/audit/cache.ts

@@ -16,6 +16,7 @@ import { homedir } from "node:os";
 import { BUILTIN_POLICIES } from "../hooks/builtin-policies";
 import { AUDIT_DETECTORS } from "./detectors";
 import type { TranscriptAuditResult } from "./types";
+import { auditCacheDir } from "../hooks/fp-home";
 
 let cachedEngineVersion: string | null = null;
 let cachedDetectorVersion: string | null = null;
@@ -44,7 +45,7 @@ function getDetectorVersion(): string {
 }
 
 function getCachePathFor(transcriptPath: string): string {
-  const root = join(homedir(), ".failproofai", "cache", "audit");
+  const root = auditCacheDir();
   const key = createHash("sha1").update(transcriptPath).digest("hex");
   return join(root, `${key}.json`);
 }
@@ -73,8 +74,21 @@ export const CACHE_SCHEMA_VERSION = 3;
 /** Hard expiry: a cached transcript result is rejected on read once it's
  *  this old. Keeps the audit pipeline honest about long-lived results that
  *  may no longer reflect current detector intent even if the transcript
- *  bytes and policy hashes haven't changed. */
-export const CACHE_TTL_MS = 7 * 24 * 60 * 60_000;
+ *  bytes and policy hashes haven't changed.
+ *
+ *  30 days, and it MUST stay clear of the scheduled-audit interval
+ *  (`DEFAULT_AUDIT_INTERVAL_DAYS`, 7). It was 7 days — exactly equal — which
+ *  meant a scheduled run at T+7d found every entry cached at T+0 already
+ *  expired and cold-scanned the entire history: ~104 seconds and megabytes of
+ *  rewrites, on every single run, for a lane whose whole point is to be cheap.
+ *  The margin was one scan duration, so any suspend, missed tick, or deferral
+ *  tipped all of it over at once.
+ *
+ *  Correctness does not rest on this number: `engineVersion` (a hash over every
+ *  builtin's source) and `detectorVersion` already invalidate the cache the
+ *  moment detection logic actually changes. The TTL only bounds staleness for
+ *  changes those two cannot see, so it can be generous. */
+export const CACHE_TTL_MS = 30 * 24 * 60 * 60_000;
 
 interface CacheEntry {
   /** Bumped whenever the on-disk shape changes incompatibly. */
@@ -123,7 +137,7 @@ export function writeCachedTranscriptResult(
   if (sizeBytes === 0) return;
   const cachePath = getCachePathFor(transcriptPath);
   try {
-    mkdirSync(join(homedir(), ".failproofai", "cache", "audit"), { recursive: true });
+    mkdirSync(auditCacheDir(), { recursive: true });
     const entry: CacheEntry = {
       schemaVersion: CACHE_SCHEMA_VERSION,
       cachedAt: Date.now(),

package/src/audit/cli-adapters/goose.ts

@@ -7,7 +7,8 @@
  * lib/goose-sessions.ts parses each session's `messages`), producing the same
  * LogEntry[] shape the other adapters do — so `logEntriesToEvents` handles the
  * rest. Like Devin, each Goose session carries a real `working_dir`, so
- * `audit --project <cwd>` filters work (unlike the cwd-less Hermes gateway).
+ * `audit --project <cwd>` filters work. (Hermes does too, for its `source='cli'`
+ * sessions — only its Slack/Telegram gateway runs are genuinely cwd-less.)
  */
 import { getGooseSessions } from "../../../lib/goose-projects";
 import { getGooseSessionLog } from "../../../lib/goose-sessions";

package/src/audit/cli-adapters/hermes.ts

@@ -7,35 +7,53 @@
  * producing the same LogEntry[] shape the other adapters do — so
  * `logEntriesToEvents` handles the rest.
  *
- * Gateway sessions have no `cwd` (Slack/Telegram runs aren't in a repo), so they
- * group by (profile, `source`) instead of working directory — a Hermes profile
- * is a whole separate home dir with its own state.db (lib/hermes-profiles.ts).
+ * Hermes sessions are NOT uniformly cwd-less. This file used to assert they were
+ * and returned nothing at all for `audit --project <cwd>`, so a Hermes session
+ * driven in a repo silently contributed zero findings to that project's audit.
+ * Verified against hermes-agent 0.19.0: `sessions` carries real `cwd`,
+ * `git_branch` and `git_repo_root` columns, and every `source='cli'` session
+ * populated them.
+ *
+ * Both shapes are real, so both are handled:
+ *   • a session WITH a cwd groups by working directory like Claude/Goose/Devin,
+ *     and takes part in cwd-scoped audits;
+ *   • a session WITHOUT one — a Slack/Telegram gateway run, which genuinely
+ *     isn't in a repo — keeps grouping by (profile, `source`), since a Hermes
+ *     profile is a whole separate home dir with its own state.db
+ *     (lib/hermes-profiles.ts), and is correctly excluded from a cwd filter.
  */
 import { getHermesSessions } from "../../../lib/hermes-projects";
 import { hermesProjectPath } from "../../../lib/hermes-profiles";
 import { getHermesSessionLog } from "../../../lib/hermes-sessions";
+import { encodeFolderName } from "../../../lib/paths";
 import type { NormalizedToolEvent, TranscriptMetadata } from "../types";
 import type { ListOpts } from "./claude";
 import { logEntriesToEvents } from "./shared";
 
+/** Grouping label for one session: its working directory when it has one,
+ *  else the (profile, source) bucket gateway sessions have always used. */
+function hermesProjectName(s: { profile: string; source?: string; cwd?: string }): string {
+  if (s.cwd) return encodeFolderName(s.cwd);
+  return s.source ? hermesProjectPath(s.profile, s.source) : `hermes:${s.profile}`;
+}
+
 export async function listHermesTranscriptMetadata(
   opts: ListOpts = {},
 ): Promise<TranscriptMetadata[]> {
-  // `audit --project <cwd>` filters on working directory; gateway sessions have
-  // none, so Hermes contributes nothing to a cwd-scoped audit.
-  if (opts.projects && opts.projects.length > 0) return [];
-
+  const projectFilter = opts.projects ? new Set(opts.projects) : null;
   const sinceMs = opts.sinceMs ?? 0;
   const sessions = await getHermesSessions();
   const out: TranscriptMetadata[] = [];
   for (const s of sessions) {
     if (s.mtimeMs < sinceMs) continue;
     if (s.messageCount <= 0 && !s.hasMessages) continue; // empty → no events (message_count can lag; trust real messages)
+    // `audit --project <cwd>` filters on the session's working directory, the
+    // same comparison Claude and Goose make. A session with no cwd is not in
+    // any project, so it drops out here rather than at the top of the function.
+    if (projectFilter && (!s.cwd || !projectFilter.has(s.cwd))) continue;
     out.push({
       cli: "hermes",
-      // Group by (profile, channel); gateway sessions are cwd-less, and each
-      // profile is a separate Hermes home with its own state.db.
-      projectName: s.source ? hermesProjectPath(s.profile, s.source) : `hermes:${s.profile}`,
+      projectName: hermesProjectName(s),
       sessionId: s.sessionId,
       transcriptPath: `hermes://${s.sessionId}`,
       mtimeMs: s.mtimeMs,