failproofai 1.0.0-beta.2 → 1.0.0-beta.21

package/scripts/validate-mdx.ts

@@ -25,15 +25,22 @@
  * `findPageError`), so this net is a strict superset of `mintlify validate`:
  * it catches both the frontmatter YAML class that fails `mintlify validate`
  * and the body-MDX class that `mintlify validate` lets through to deploy.
+ *
+ * It also covers a third class neither tool sees: image references whose target
+ * does not exist (`findBrokenAssetRefs`). Those are valid MDX and valid YAML —
+ * nothing errors, the reader just gets a broken image — which is how all 14
+ * translated READMEs shipped with every logo and the architecture GIF broken.
+ * See that function for the mechanism.
  */
-import { readdirSync, statSync, readFileSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
+import { readdirSync, statSync, readFileSync, existsSync } from "node:fs";
+import { dirname, join, relative, resolve, posix } from "node:path";
 import { fileURLToPath } from "node:url";
 import { compile } from "@mdx-js/mdx";
 import YAML from "yaml";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const DOCS_DIR = join(__dirname, "..", "docs");
+const ROOT_DIR = join(__dirname, "..");
+const DOCS_DIR = join(ROOT_DIR, "docs");
 
 export interface MdxParseError {
   message: string;
@@ -178,34 +185,167 @@ export function collectMdxFiles(dir: string): string[] {
   return out;
 }
 
+/** File extensions treated as bundled media rather than a link to a page. */
+const ASSET_RE = /\.(?:png|jpe?g|gif|svg|webp|ico|mp4|webm)$/i;
+
+export interface BrokenAssetRef {
+  /** The reference exactly as written in the page. */
+  ref: string;
+  /** Repo-relative path the reference resolves to, which does not exist. */
+  resolved: string;
+  /** 1-based line the reference appears on. */
+  line: number;
+}
+
+/**
+ * Report every local image reference on a page whose target does not exist on
+ * disk.
+ *
+ * Why this is a separate net from the MDX parse above: a broken image path is
+ * perfectly valid MDX and perfectly valid YAML, so `mintlify validate` and
+ * `findPageError` both pass it — it only surfaces as a missing image in a
+ * reader's browser, which nothing in CI was watching. That is exactly how all
+ * 14 translated READMEs shipped with every logo and the architecture GIF
+ * broken: the translator faithfully copies the root README's repo-root-relative
+ * `assets/logos/*.svg` into `docs/i18n/`, two directories deeper, where they
+ * resolve to nothing (GitHub 404, Mintlify S3 403). The auto-translation
+ * workflow regenerates these pages unattended, so only a deterministic check
+ * keeps that class from coming back.
+ *
+ * Resolution follows the two conventions in this repo:
+ *  - A leading `/` is Mintlify site-absolute → resolve against `docs/`
+ *    (`/agenteye/images/x.png` → `docs/agenteye/images/x.png`).
+ *  - Anything else is relative to the page's own directory, the way GitHub and
+ *    Mintlify both resolve it.
+ *
+ * Skipped: absolute URLs and any other scheme (`https:`, `mailto:`, `data:`),
+ * protocol-relative `//`, bare anchors, and non-asset references — a link to a
+ * `.md`/`.mdx` page or a bare doc slug is nav, already covered by
+ * `mintlify validate`, and would false-positive on extensionless Mintlify
+ * routes.
+ */
+export function findBrokenAssetRefs(
+  file: string,
+  source: string,
+): BrokenAssetRef[] {
+  const pageDir = dirname(file);
+  const out: BrokenAssetRef[] = [];
+  const seen = new Set<string>();
+
+  const lines = source.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const refs = [
+      ...lines[i].matchAll(/\]\(([^)\s]+)/g),
+      ...lines[i].matchAll(/(?:src|href)=["']([^"']+)["']/g),
+    ].map((m) => m[1]);
+
+    // `srcset` carries a comma-separated candidate list, each optionally
+    // followed by a density/width descriptor (`logo.svg 2x`). The README's
+    // logo table pairs every <img src> with a dark-mode <source srcset>, so
+    // extracting only `src` would pass a table half-broken — and only for
+    // dark-theme readers, the half least likely to be caught by eye.
+    for (const m of lines[i].matchAll(/srcset=["']([^"']+)["']/g)) {
+      for (const candidate of m[1].split(",")) {
+        const url = candidate.trim().split(/\s+/)[0];
+        if (url) refs.push(url);
+      }
+    }
+
+    for (const ref of refs) {
+      if (/^[a-z][a-z0-9+.-]*:/i.test(ref)) continue; // https:, mailto:, data:
+      if (ref.startsWith("//") || ref.startsWith("#")) continue;
+      // Strip the query/fragment before testing the extension so a versioned
+      // `x.png?v=2` is still recognised as an asset.
+      const path = ref.split(/[?#]/)[0];
+      if (!ASSET_RE.test(path)) continue;
+
+      const target = path.startsWith("/")
+        ? join(DOCS_DIR, path.slice(1))
+        : resolve(pageDir, path);
+      if (existsSync(target)) continue;
+
+      const key = `${i}:${ref}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({
+        ref,
+        resolved: relative(ROOT_DIR, target).split(/[\\/]/).join(posix.sep),
+        line: i + 1,
+      });
+    }
+  }
+  return out;
+}
+
 async function main(): Promise<void> {
   const files = collectMdxFiles(DOCS_DIR).sort();
-  const failures: Array<{ file: string; error: MdxParseError }> = [];
+  const failures: Array<{
+    file: string;
+    error: MdxParseError;
+    kind: "MDX parse error" | "Broken image";
+  }> = [];
+
+  const collectAssetFailures = (file: string, source: string): void => {
+    for (const broken of findBrokenAssetRefs(file, source)) {
+      failures.push({
+        file: relative(process.cwd(), file),
+        kind: "Broken image",
+        error: {
+          message:
+            `Image \`${broken.ref}\` does not exist — it resolves to ` +
+            `\`${broken.resolved}\`. Paths are relative to the page's own ` +
+            "directory (a leading `/` is relative to `docs/`), so a path " +
+            "copied from a file at a different depth has to be re-pointed.",
+          line: broken.line,
+        },
+      });
+    }
+  };
 
   for (const file of files) {
-    const error = await findPageError(readFileSync(file, "utf-8"));
-    if (error) failures.push({ file: relative(process.cwd(), file), error });
+    const source = readFileSync(file, "utf-8");
+    const error = await findPageError(source);
+    if (error)
+      failures.push({
+        file: relative(process.cwd(), file),
+        error,
+        kind: "MDX parse error",
+      });
+
+    // A page can carry a broken image and still parse, so collect these
+    // independently rather than only when the parse succeeded.
+    collectAssetFailures(file, source);
+  }
+
+  // The root README is not a docs page (it is GitHub-only, and its HTML
+  // comments are illegal MDX, so findPageError would reject it) — but it IS
+  // the source every docs/i18n/README.<lang>.md is translated from. A bad
+  // image path here propagates into 14 files as an absolute raw URL, which
+  // findBrokenAssetRefs deliberately does not follow. Check it at the source.
+  const rootReadme = join(ROOT_DIR, "README.md");
+  if (existsSync(rootReadme)) {
+    collectAssetFailures(rootReadme, readFileSync(rootReadme, "utf-8"));
   }
 
   if (failures.length === 0) {
-    console.log(`✓ ${files.length} MDX page(s) parsed cleanly`);
+    console.log(
+      `✓ ${files.length} MDX page(s) parsed cleanly with no broken images`,
+    );
     return;
   }
 
-  console.error(
-    `✗ ${failures.length} of ${files.length} MDX page(s) failed to parse:\n`,
-  );
-  for (const { file, error } of failures) {
+  console.error(`✗ ${failures.length} problem(s) in ${files.length} page(s):\n`);
+  for (const { file, error, kind } of failures) {
     const pos = error.line
       ? `:${error.line}${error.column ? `:${error.column}` : ""}`
       : "";
-    console.error(`  ${file}${pos}\n    ${error.message}\n`);
+    console.error(`  ${file}${pos}\n    ${kind}: ${error.message}\n`);
     // GitHub Actions inline annotation.
     const loc =
       (error.line ? `,line=${error.line}` : "") +
       (error.column ? `,col=${error.column}` : "");
     console.log(
-      `::error file=${encodeAnnotation(file)}${loc}::MDX parse error: ${encodeAnnotation(error.message)}`,
+      `::error file=${encodeAnnotation(file)}${loc}::${kind}: ${encodeAnnotation(error.message)}`,
     );
   }
   process.exitCode = 1;

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

@@ -12,10 +12,10 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
 import { join } from "node:path";
-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 +44,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 +73,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 +136,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";