failproofai 1.0.0 → 1.0.1-beta.1

package/src/audit/cli-login.ts

@@ -0,0 +1,330 @@
+/**
+ * Email-OTP sign-in, in the terminal.
+ *
+ * The dashboard has had this since the beginning, as two API routes. The CLI
+ * had nothing, which meant the one surface that works on a headless box could
+ * not do the one thing scheduling requires. This is the same flow through the
+ * same functions — `requestLoginCode` / `verifyLoginCode` from
+ * `api-server-client`, `writeAuth` from `auth-store` — writing the same
+ * `~/.failproofai/audit/session.json`.
+ *
+ * Sharing the store is what makes "the CLI and the dashboard are always in
+ * sync" true by construction rather than by discipline: there is one file and
+ * one writer, so signing in here shows up there on the next read, and signing
+ * out there ends the session the scheduled audit was going to report under.
+ */
+import { AuthApiError, requestLoginCode, verifyLoginCode } from "../../lib/auth/api-server-client";
+import {
+  authFromTokenResponse,
+  readAuth,
+  writeAuth,
+  type StoredAuth,
+} from "../../lib/auth/auth-store";
+import {
+  ANSI_RESET,
+  BAR,
+  colorsEnabled,
+  intro,
+  outro,
+  promptText,
+  step,
+  stepOpen,
+} from "../hooks/tui";
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/**
+ * The api-server's own bound on a submitted code (`auth/models.rs`). Matched
+ * here so a paste that is obviously too long is rejected at the prompt, where
+ * it can be retyped, rather than by the server — which answers
+ * `validation_error` rather than `invalid_code`, a distinction the retry loop
+ * below treats as fatal.
+ */
+const CODE_MIN = 4;
+const CODE_MAX = 12;
+
+/**
+ * The spine a prompt hangs off, so the two questions sit inside the same frame
+ * `intro`/`outro` draw. Empty when colour is off or output is piped: the frame
+ * is decoration, and a log file should not collect box-drawing characters.
+ */
+function spine(): string {
+  return colorsEnabled(process.stdout)
+    ? `${ANSI_DIM_BAR}${BAR}${ANSI_RESET}  `
+    : "";
+}
+const ANSI_DIM_BAR = "\x1B[2m";
+
+/**
+ * Codes are numeric (`auth/otp.rs` generates digits only), so anything else in
+ * the field is packaging: "Your failproof code is 123456", a copied "123 456",
+ * a stray trailing space from a double-click selection. Keeping the digits is
+ * the difference between a paste that works and one that costs a fresh email.
+ *
+ * Applied only when the input HAS digits and something else — a field of pure
+ * digits passes through untouched, so a genuinely wrong code is still reported
+ * as wrong rather than silently rewritten into a different one.
+ */
+export function extractCode(raw: string): string {
+  const trimmed = raw.trim();
+  if (/^\d+$/.test(trimmed)) return trimmed;
+  const runs = trimmed.match(/\d+/g) ?? [];
+  if (runs.length === 0) return trimmed;
+  // A run long enough to BE a code wins outright.
+  //
+  // Joining every digit in the line was the whole rule, and the prompt's own
+  // hint ("paste the whole line if you like") walks straight into it: the real
+  // message reads `Your failproof code is 123456 (expires in 10 minutes)`, so
+  // the join produced `12345610` — eight digits, which passes the 4–12
+  // validator, reaches the server, and burns an attempt on a code nobody typed.
+  // Anything the sentence adds after the code is short; the code is not.
+  const whole = runs.find((run) => run.length >= CODE_MIN);
+  if (whole) return whole;
+  // Otherwise the digits really are split — a copied `123 456` — and joining
+  // them is the reconstruction that was always intended.
+  return runs.join("");
+}
+
+export interface SignedIn {
+  id: string;
+  email: string;
+}
+
+/**
+ * Whether a sign-in flow actually ran.
+ *
+ * The caller uses it to decide whether its confirmation continues an open frame
+ * or stands on its own: the `│` spine means "a flow is happening", so printing
+ * one under a command that answered instantly from the session file would be a
+ * frame with no beginning.
+ */
+export interface EnsureSignedIn {
+  user: SignedIn;
+  prompted: boolean;
+}
+
+export class LoginError extends Error {}
+
+/**
+ * Whether this terminal can run an interactive prompt.
+ *
+ * Checked BEFORE anything is written, so a CI runner or a cron line gets one
+ * clear sentence instead of a hang on a `readline` nobody will ever answer.
+ */
+export function canPrompt(): boolean {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+/**
+ * The stored session, unless its refresh token has already expired.
+ *
+ * The check is a comparison against a number that is already in the file, so it
+ * keeps the offline-friendly property the doc below argues for: no request, no
+ * network failure mode, nothing new that a dropped wifi connection can break.
+ * What it removes is the case where every one of those is fine and the session
+ * is simply dead — revoked from another machine, or past its refresh window.
+ *
+ * Without it `--schedule` printed `reports to <email>` and exited 0 on a
+ * session that cannot mint another access token, so the user configured
+ * digests, was shown the destination, and then heard nothing for up to a full
+ * interval (90 days at the maximum) with the only signal a line in the journal.
+ * The dashboard already refuses this exact state in `setAutoAuditAction`, so
+ * the two surfaces disagreed on the one thing this feature claims is in sync.
+ *
+ * Expiry is treated as "sign in again", not as an error: the OTP prompt below
+ * is the remedy, and falling through to it is what makes this recoverable in
+ * one command instead of needing the file removed by hand.
+ */
+function sessionStillValid(auth: StoredAuth | null): StoredAuth | null {
+  if (!auth) return null;
+  // Seconds, per StoredAuth. A file whose value is missing was normalised to
+  // `access_expires_at` by `readAuth`, so this is always a real number.
+  return auth.refresh_expires_at * 1000 > Date.now() ? auth : null;
+}
+
+/**
+ * Return the current session, or run the OTP flow to create one.
+ *
+ * Deliberately NOT `whoAmI()`: that round-trips to `/v0/auth/me` and returns
+ * null on a network blip, which here would mean re-prompting a signed-in user
+ * for a code because their wifi dropped. The local file is the source of truth
+ * for "is somebody signed in on this machine"; whether the token still works is
+ * the reporting path's problem, and it already handles that by pausing digests
+ * rather than failing.
+ */
+export async function ensureSignedIn(preset?: string): Promise<EnsureSignedIn> {
+  const existing = sessionStillValid(readAuth());
+  if (existing) {
+    // A machine already reports as somebody. An `--email` naming a DIFFERENT
+    // address is refused rather than honoured: silently re-pointing where a
+    // machine's digests go is the kind of change nobody notices until they
+    // stop arriving, and the flag reads as "sign me in", not "switch accounts".
+    if (preset && !sameAddress(preset, existing.user.email)) {
+      throw new LoginError(
+        `This machine is already signed in as ${existing.user.email}.\n` +
+          `To report as ${preset.trim().toLowerCase()} instead, sign out first — ` +
+          `from the dashboard, or by removing ~/.failproofai/audit/session.json.`,
+      );
+    }
+    return { user: existing.user, prompted: false };
+  }
+
+  if (!canPrompt()) {
+    throw new LoginError(
+      "Signing in needs an interactive terminal, and this one is not.\n" +
+        "Run `failproofai audit --schedule` from a shell you are sitting at,\n" +
+        "or sign in from the dashboard — both write the same session file.",
+    );
+  }
+
+  return { user: await runLogin(preset), prompted: true };
+}
+
+/** Addresses compare case-insensitively, because a mail server does. */
+function sameAddress(a: string, b: string): boolean {
+  return a.trim().toLowerCase() === b.trim().toLowerCase();
+}
+
+/**
+ * Reject an address the flag supplied before anything is drawn or sent.
+ *
+ * Returned as a message rather than thrown so the caller can fail at the CLI
+ * boundary, next to where the day count is checked — a typo'd flag should look
+ * like a usage error, not like a sign-in that opened a frame and gave up.
+ */
+export function invalidEmail(address: string): string | null {
+  return EMAIL_RE.test(address.trim())
+    ? null
+    : `\`--email\` needs an email address (got: ${address}).`;
+}
+
+/**
+ * The two prompts, inside the frame `failproofai config` uses.
+ *
+ * Same logo, same `│` spine, same `◆ / ◇` step glyphs, same pink `└` close —
+ * because this is the same product asking, and a sign-in that looked like a
+ * different tool would be the one moment the seam showed. It is also the only
+ * moment this command asks for something personal, which is the moment worth
+ * spending the frame on.
+ *
+ * Exported so a test can drive it without the caller.
+ */
+export async function runLogin(preset?: string): Promise<SignedIn> {
+  intro("scheduled audits need somewhere to send the report");
+
+  let address: string;
+  if (preset) {
+    // Supplied on the command line, so the question is already answered — but
+    // it is still SHOWN, as a settled step, because it is the address a code is
+    // about to be sent to and the flag is exactly where a typo hides.
+    address = preset.trim().toLowerCase();
+    step("your email", address);
+  } else {
+    const email = await promptText({
+      prefix: spine(),
+      message: "your email",
+      hint: "you@yourdomain.com",
+      validate: (v) => (EMAIL_RE.test(v.trim()) ? null : "that doesn't look like an email"),
+    });
+    if (email === null) {
+      outro("Cancelled — nothing was changed.", { ok: false });
+      throw new LoginError("Cancelled.");
+    }
+    address = email.trim().toLowerCase();
+  }
+  let expiresInMin = 10;
+  try {
+    const sent = await requestLoginCode(address);
+    expiresInMin = Math.max(1, Math.ceil(sent.expires_in / 60));
+  } catch (err) {
+    outro("Could not send a login code.", { ok: false });
+    throw new LoginError(describeAuthError(err, "Could not send a login code"));
+  }
+
+  // The address is echoed back on the settled step rather than left to memory:
+  // a typo in it is the single most likely reason no code arrives, and this is
+  // the last place it can be noticed before somebody starts waiting.
+  step("code sent", `to ${address} · expires in ${expiresInMin} min`);
+
+  // Three attempts, matching the server's own per-code cap. Looping forever
+  // would keep a person typing at a code the server stopped accepting after
+  // the fifth try, and one attempt would punish a typo with a fresh email.
+  const ATTEMPTS = 3;
+  for (let attempt = 1; attempt <= ATTEMPTS; attempt += 1) {
+    stepOpen(attempt === 1 ? "the code from that email" : "try that code again");
+    const typed = await promptText({
+      prefix: spine(),
+      message: "code",
+      // Unmasked on purpose. A login code is single-use and expires in minutes,
+      // so hiding it protects nothing and costs the one thing that matters at
+      // this prompt: seeing your own typo before pressing enter.
+      hint:
+        attempt === 1
+          ? "123456 · paste the whole line if you like"
+          : `attempt ${attempt} of ${ATTEMPTS}`,
+      validate: (v) => {
+        // No digits at all is not a mistyped code, it is not a code — caught
+        // here rather than spent as one of the server's five attempts.
+        if (!/\d/.test(v)) return "a code is digits — paste the line from the email";
+        const code = extractCode(v);
+        if (code.length < CODE_MIN) return "that looks too short to be the code";
+        if (code.length > CODE_MAX) return "that looks too long — paste just the code";
+        return null;
+      },
+    });
+    if (typed === null) {
+      outro("Cancelled — nothing was changed.", { ok: false });
+      throw new LoginError("Cancelled.");
+    }
+
+    try {
+      const tokens = await verifyLoginCode(address, extractCode(typed));
+      writeAuth(authFromTokenResponse(tokens));
+      step("signed in", tokens.user.email);
+      return { id: tokens.user.id, email: tokens.user.email };
+    } catch (err) {
+      const wrongCode = err instanceof AuthApiError && err.code === "invalid_code";
+      if (wrongCode && attempt < ATTEMPTS) {
+        step(
+          "that code was wrong or expired",
+          `${ATTEMPTS - attempt} more ${ATTEMPTS - attempt === 1 ? "try" : "tries"} before it asks for a new one`,
+        );
+        continue;
+      }
+      outro("Could not verify that code.", { ok: false });
+      throw new LoginError(describeAuthError(err, "Could not verify that code"));
+    }
+  }
+  outro("Too many wrong codes.", { ok: false });
+  throw new LoginError("Too many wrong codes. Run the command again for a fresh one.");
+}
+
+/**
+ * A sentence a person can act on.
+ *
+ * `AuthApiError` carries the server's own code, and two of them have a remedy
+ * worth naming rather than passing through: a rate limit is a wait, and an
+ * unreachable server on a machine pointed at localhost is almost always an
+ * api-server that is not running.
+ */
+function describeAuthError(err: unknown, prefix: string): string {
+  if (err instanceof AuthApiError) {
+    if (err.code === "rate_limited") {
+      const wait = err.retryAfterSecs;
+      return `${prefix}: too many attempts.${wait ? ` Try again in ${wait}s.` : ""}`;
+    }
+    if (err.status === 0 || err.code === "timeout") {
+      return (
+        `${prefix}: the api-server did not respond.\n` +
+        `It is at ${apiBaseForMessage()} — check that it is running,\n` +
+        `or set FAILPROOF_API_URL to point somewhere else.`
+      );
+    }
+    return `${prefix}: ${err.message}`;
+  }
+  return `${prefix}: ${err instanceof Error ? err.message : String(err)}`;
+}
+
+function apiBaseForMessage(): string {
+  return process.env.FAILPROOF_API_URL ?? process.env.FAILPROOFAI_API_URL ?? "https://api.befailproof.ai";
+}

package/src/audit/cli.ts

@@ -2,8 +2,11 @@
  * `failproofai audit` — run a local audit of your agent-CLI history, then open
  * the dashboard to view it.
  *
- *   failproofai audit          Scan, then launch the dashboard at /audit.
- *   failproofai audit --help   Show usage.
+ *   failproofai audit                Scan, then launch the dashboard at /audit.
+ *   failproofai audit --schedule     Put scans on a timer and mail the findings.
+ *   failproofai audit --no-schedule  Stop the timer.
+ *   failproofai audit --status       What this machine is scheduled to do.
+ *   failproofai audit -h, --help     Show usage.
  *
  * `runAudit()` is a pure local function (no network, no account). We run it,
  * render the same four progress stages the dashboard's RunProgress shows,
@@ -11,9 +14,10 @@
  * the bundled dashboard server and open the browser to /audit — which renders
  * instantly from that cache.
  *
- * No arguments yet — a bare `failproofai audit` does a full scan (all CLIs, all
- * history). Flags (--since, --cli, --project, --port, --no-open) are easy
- * follow-ups against `RunAuditOptions`.
+ * A bare `failproofai audit` does a full scan (all CLIs, all history); the
+ * scheduling flags above write config and never scan. Scan-shaping flags
+ * (--since, --cli, --project, --port, --no-open) are easy follow-ups against
+ * `RunAuditOptions`.
  *
  * `--scheduled` is the one exception, and it is not a flag on the interactive
  * command so much as a second entry point sharing its name: it runs the same
@@ -28,6 +32,7 @@ import { trackHookEvent } from "../hooks/hook-telemetry";
 import { getInstanceId } from "../../lib/telemetry-id";
 import { sanitizeErrorMessage } from "../../lib/telemetry-sanitize";
 import { openWhenReady } from "./open-browser";
+import { describeOutcome, reportHarm } from "./report-harm";
 import { brandAnsi, ANSI_RESET, ANSI_BOLD, ANSI_DIM } from "../hooks/tui";
 
 /** Port the bundled dashboard binds to. Matches `scripts/launch.ts`'s default
@@ -57,29 +62,60 @@ export const AUDIT_STAGES: ReadonlyArray<{ label: string; detail: string }> = [
   { label: "aggregating results", detail: "counting hits, ranking by frequency" },
 ];
 
-const HELP = `
-failproofai audit — audit your AI agent's behavior, then open the dashboard
+/** Column the description text starts at. The widest command line is 37 wide. */
+const HELP_DESC_COL = 40;
 
-USAGE
-  failproofai audit          Scan your agent-CLI session history for risky and
-                             wasteful patterns, then open the audit dashboard.
-  failproofai audit --help   Show this help.
-
-  failproofai audit --scheduled
-                             Headless run: scan, refresh the dashboard's cached
-                             result, print one line, exit. No browser, no
-                             server. This is what a scheduled audit runs; exit
-                             75 means another audit already had the lock.
-
-WHAT IT DOES
-  1. Scans past sessions from every installed agent CLI (Claude, Codex, Cursor,
-     Copilot, OpenCode, Pi) — entirely on your machine.
-  2. Starts the local dashboard and opens
-     http://localhost:${DASHBOARD_PORT}/audit with your results.
+/**
+ * `audit --help`.
+ *
+ * A function rather than a module-level string because the command names are
+ * coloured through `c()`, which reads `colorOn()` at CALL time — a const would
+ * bake in whatever the TTY looked like at import, and this module is imported
+ * by the bundled CLI long before anyone asks for help.
+ *
+ * `--scheduled` is deliberately absent: it is not a flag a person types but a
+ * second entry point the daemon spawns (see the module header), and listing a
+ * machine-facing flag one letter away from `--schedule` in the same block is
+ * how somebody ends up running a 100-second scan when they meant to configure
+ * one. It still works, and still refuses every argument it always refused.
+ */
+export function helpText(): string {
+  const row = (command: string, lines: string[]): string => {
+    // Padding is measured on the RAW command — `c()` adds escape bytes that
+    // occupy no columns, so colouring first would misalign every row.
+    const pad = " ".repeat(Math.max(1, HELP_DESC_COL - 2 - command.length));
+    return lines
+      .map((line, i) =>
+        i === 0 ? `  ${c(CYAN, command)}${pad}${line}` : `${" ".repeat(HELP_DESC_COL)}${line}`,
+      )
+      .join("\n");
+  };
 
-  Runs fully offline — no account or network required. Press Ctrl+C to stop the
-  dashboard server when you're done.
-`.trimStart();
+  return [
+    `${c(BOLD, "failproofai audit")} — review your agent CLIs for risky and wasteful patterns.`,
+    c(DIM, "Everything runs on this machine; only a scheduled digest ever leaves it."),
+    "",
+    c(BOLD, "USAGE"),
+    row("failproofai audit", [
+      "Scan your session history, then open",
+      `http://localhost:${DASHBOARD_PORT}/audit`,
+    ]),
+    row("failproofai audit --schedule [days]", [
+      "Scan on a timer and email the findings.",
+      "Default 7 days, range 1-90.",
+      "Signs you in the first time; add",
+      "--email <address> to skip a prompt.",
+    ]),
+    row("failproofai audit --no-schedule", ["Stop the timer. Leaves you signed in."]),
+    row("failproofai audit --status", [
+      "Whether scheduling is on, where reports",
+      "go, the daemon's state, and when the",
+      "next scan is due.",
+    ]),
+    row("failproofai audit -h, --help", ["Show this help."]),
+    "",
+  ].join("\n");
+}
 
 // ── ANSI helpers ────────────────────────────────────────────────────────────
 // Colours come from the shared brand palette in hooks/tui.ts, so `audit` reads
@@ -365,6 +401,29 @@ export async function runScheduledAudit(): Promise<number> {
         `${num(result.transcripts.scanned)} sessions, ${num(result.totals.hits)} hits\n`,
     );
 
+    // Report harmful findings upstream, if the user switched emailed reports on.
+    //
+    // AFTER the dashboard cache is written and AFTER the success line, because
+    // the scan is the product and this is an optional extra on top of it.
+    // `reportHarm` never throws — every failure inside it is an outcome — so a
+    // dead network, an expired session or an api-server having a bad day cannot
+    // turn a successful scan into exit 1. A machine that never opted in prints
+    // nothing at all and does no work here.
+    //
+    // Scheduled runs ONLY. An interactive `failproofai audit` has a person
+    // sitting in front of the result, so mailing it to them is noise, and it
+    // would also make the manual command do a network call that
+    // `audit --help` promises it does not.
+    const outcome = await reportHarm(result);
+    const line = describeOutcome(outcome);
+    if (line) {
+      // Anything other than a successful send goes to stderr: on a scheduled run
+      // the journal is the only reader, and "the email did not go out" is the
+      // half worth finding with a grep.
+      const stream = outcome.kind === "sent" ? process.stdout : process.stderr;
+      stream.write(`${line}\n`);
+    }
+
     return 0;
   } finally {
     attempt.lock.release();
@@ -454,25 +513,99 @@ export async function runPostSetupAudit(): Promise<void> {
 
 export async function runAuditCli(args: string[]): Promise<void> {
   if (args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(HELP);
+    process.stdout.write(helpText());
     process.exit(0);
   }
   // The headless path, spawned rather than typed. Handled ahead of the
   // rejection below so that adding it costs the interactive path nothing: it
   // still refuses every argument it has always refused.
+  //
+  // `--scheduled` (run one now, headlessly) and `--schedule` (put runs on a
+  // timer) differ by one letter and do completely different things, so this
+  // is checked FIRST and exactly: a `--schedule` typo must not silently start
+  // a 100-second scan, and `--scheduled` must never be read as configuration.
   if (args.includes("--scheduled")) {
     const extra = args.find((a) => a !== "--scheduled");
     if (extra) die(`\`audit --scheduled\` takes no other arguments (got: ${extra}).`);
     process.exit(await runScheduledAudit());
   }
 
-  // No arguments supported yet — reject typos rather than silently doing a bare
-  // audit, so a future `failproofai audit --since 7d` doesn't quietly no-op.
+  // The scheduling controls. These write config and exit; none of them scan.
+  if (args.includes("--status")) {
+    const extra = args.find((a) => a !== "--status");
+    if (extra) die(`\`audit --status\` takes no other arguments (got: ${extra}).`);
+    const { runScheduleStatus } = await import("./schedule-cli");
+    runScheduleStatus();
+    process.exit(0);
+  }
+
+  if (args.includes("--no-schedule")) {
+    const extra = args.find((a) => a !== "--no-schedule");
+    if (extra) die(`\`audit --no-schedule\` takes no other arguments (got: ${extra}).`);
+    const { runScheduleOff } = await import("./schedule-cli");
+    runScheduleOff();
+    process.exit(0);
+  }
+
+  const scheduleAt = args.indexOf("--schedule");
+  if (scheduleAt !== -1) {
+    // Parsed POSITIONALLY rather than by matching values against a set: an
+    // address and a day count are both just strings, and "have I already seen
+    // this string" cannot tell the argument of one flag from the argument of
+    // another.
+    let days: string | undefined;
+    let email: string | undefined;
+    for (let i = 0; i < args.length; i += 1) {
+      const a = args[i];
+      if (a === "--schedule") {
+        // The day count is OPTIONAL, so the next token counts only when it is
+        // not itself a flag — `--schedule --email x` must not read "--email"
+        // as a number of days.
+        const next = args[i + 1];
+        if (next !== undefined && !next.startsWith("-")) {
+          days = next;
+          i += 1;
+        }
+        continue;
+      }
+      if (a === "--email" || a.startsWith("--email=")) {
+        // Both forms, because both are what people type.
+        if (a.startsWith("--email=")) {
+          email = a.slice("--email=".length);
+        } else {
+          email = args[i + 1];
+          i += 1;
+        }
+        if (email === undefined || email.length === 0 || email.startsWith("-")) {
+          die("`--email` needs an address, e.g. `--email you@yourdomain.com`.");
+        }
+        continue;
+      }
+      die(`\`audit --schedule\` does not take ${a}.`);
+    }
+
+    const { runScheduleOn, ScheduleCliError } = await import("./schedule-cli");
+    const { LoginError } = await import("./cli-login");
+    try {
+      await runScheduleOn(days, email);
+    } catch (err) {
+      // Both are "the user needs to read one sentence and try again", not a
+      // stack trace: a wrong day count, a cancelled prompt, an api-server that
+      // is not running.
+      if (err instanceof ScheduleCliError || err instanceof LoginError) die(err.message);
+      throw err;
+    }
+    process.exit(0);
+  }
+
+  // Anything else is rejected rather than silently doing a bare audit, so a
+  // typo like `--sched` does not quietly scan and exit 0 looking like it worked.
   const stray = args.find((a) => a !== "--help" && a !== "-h");
   if (stray) {
     die(
-      `\`audit\` takes no arguments yet (got: ${stray}).\n` +
-        `Run \`failproofai audit\` to scan your history and open the dashboard.`,
+      `\`audit\` does not take ${stray}.\n` +
+        `Run \`failproofai audit\` to scan your history and open the dashboard,\n` +
+        `or \`failproofai audit --help\` for the scheduling commands.`,
     );
   }
 

package/src/audit/dashboard-cache.ts

@@ -126,14 +126,38 @@ export function isCacheStale(cachedAt: string, maxAgeMinutes: number = DEFAULT_M
 }
 
 /**
- * Read just the `cachedAt` timestamp from the dashboard cache file,
- * **bypassing** the TTL check. Used by the empty-state path to tell apart
- * "no audit has ever run" from "your last audit aged out". A non-null
- * return whose age exceeds `DASHBOARD_CACHE_TTL_MINUTES` means the cache
- * was rejected by `readDashboardCache()` for being expired (rather than
- * missing or schema-incompatible).
+ * What the last audit on this machine found, **bypassing** the TTL check.
+ *
+ * Used by the empty-state path to tell apart "no audit has ever run" from
+ * "your last audit aged out" — a non-null return whose age exceeds
+ * `DASHBOARD_CACHE_TTL_MINUTES` means `readDashboardCache()` rejected it for
+ * being expired rather than missing or schema-incompatible — and by /settings
+ * to draw its LAST SCAN and FINDINGS stats.
+ *
+ * Those stats deliberately read from HERE and not from `readDashboardCache()`.
+ * That reader drops an entry once it passes the TTL, which is right for a
+ * dashboard rendering results and exactly backwards for a stat whose subject is
+ * how long ago the scan was: a page that answers "when did this last run" must
+ * not lose the answer for the crime of it having been a while. Reading the
+ * timestamp from one function and the counts from the other is the specific bug
+ * this shape prevents — "6 days ago" beside a blank findings cell, because the
+ * two disagreed about whether the same file existed.
+ *
+ * The counts come from the same object the /audit page renders, so they cannot
+ * drift from it: `totals.hits` is the headline finding count and
+ * `transcripts.scanned` the sessions behind it.
  */
-export function readDashboardCacheMeta(): { cachedAt: string } | null {
+export interface DashboardCacheSummary {
+  cachedAt: string;
+  /** `AuditResult.totals.hits` — total policy hits in that scan. */
+  findings: number | null;
+  /** `AuditResult.transcripts.scanned` — session transcripts walked. */
+  sessionsScanned: number | null;
+  /** `AuditResult.eventsScanned` — normalized tool-use events walked. */
+  eventsScanned: number | null;
+}
+
+export function readDashboardCacheMeta(): DashboardCacheSummary | null {
   const cachePath = getCachePath();
   if (!existsSync(cachePath)) return null;
   try {
@@ -150,7 +174,19 @@ export function readDashboardCacheMeta(): { cachedAt: string } | null {
       || typeof entry.cachedAt !== "string"
       || Number.isNaN(new Date(entry.cachedAt).getTime())
     ) return null;
-    return { cachedAt: entry.cachedAt };
+    // The counts are read defensively rather than assumed: `schemaVersion`
+    // guards the ENTRY's shape, and a torn or hand-edited `result` can still
+    // arrive with a missing field. A null count renders as "—" (unknown), which
+    // is a different claim from 0 (scanned, found nothing) — collapsing the two
+    // would report a clean machine on a file we failed to read.
+    const result = entry.result;
+    const count = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) ? v : null);
+    return {
+      cachedAt: entry.cachedAt,
+      findings: count(result?.totals?.hits),
+      sessionsScanned: count(result?.transcripts?.scanned),
+      eventsScanned: count(result?.eventsScanned),
+    };
   } catch {
     return null;
   }