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

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,

package/src/audit/cli.ts

@@ -14,8 +14,14 @@
  * 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`.
+ *
+ * `--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
+ * scan with no TTY, no browser and no server, and reports its outcome through
+ * an exit code. See `runScheduledAudit`.
  */
 import { runAudit } from "./index";
+import { acquireAuditLock, type AuditLockInfo } from "./audit-lock";
 import { writeDashboardCache } from "./dashboard-cache";
 import type { AuditResult, RunAuditOptions } from "./types";
 import { trackHookEvent } from "../hooks/hook-telemetry";
@@ -28,6 +34,16 @@ import { brandAnsi, ANSI_RESET, ANSI_BOLD, ANSI_DIM } from "../hooks/tui";
  *  for `start` mode, which `failproofai` (bare) already uses. */
 const DASHBOARD_PORT = 8020;
 
+/**
+ * `EX_TEMPFAIL` from sysexits.h — "another audit already holds the lock".
+ *
+ * A distinct code rather than 1, because the scheduler that spawns the headless
+ * run has to tell the two apart: a failure deserves a report, while losing the
+ * lock means only "come back in fifteen minutes". Collapsing them would make a
+ * healthy machine that simply ran two audits close together look broken.
+ */
+export const EXIT_AUDIT_ALREADY_RUNNING = 75;
+
 /**
  * Mirror of `app/audit/_components/run-progress.tsx`'s `STAGES`. Kept identical
  * so the CLI and the dashboard's in-progress view tell the same story — the
@@ -49,6 +65,12 @@ USAGE
                              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.
@@ -247,10 +269,13 @@ function printSummary(result: AuditResult): void {
 
 /**
  * Which entry point ran the audit. `onboarding` is the automatic post-setup run;
- * `cli` is an explicit `failproofai audit`. Carried on every cli_audit_* event so
- * the first audit a user ever runs is distinguishable from later deliberate ones.
+ * `cli` is an explicit `failproofai audit`; `scheduled` is the headless run the
+ * daemon spawns. Carried on every cli_audit_* event so the first audit a user
+ * ever runs, a deliberate one, and one nobody was present for stay distinct —
+ * without which an opt-in scheduled scan would silently inflate the counts that
+ * describe what people actually do by hand.
  */
-type AuditSource = "cli" | "onboarding";
+type AuditSource = "cli" | "onboarding" | "scheduled";
 
 /** Shared so both entry points report cli_audit_completed identically. */
 function auditCompletedProps(source: AuditSource, result: AuditResult) {
@@ -263,6 +288,89 @@ function auditCompletedProps(source: AuditSource, result: AuditResult) {
   };
 }
 
+/** One line naming whoever holds the lock, for a refusal message. */
+function heldByLine(held: AuditLockInfo | null): string {
+  if (!held) return "another audit is already running";
+  const ageS = Math.max(0, Math.round((Date.now() - held.startedAt) / 1000));
+  return `another audit is already running (pid ${held.pid}, started by ${held.source} ${ageS}s ago)`;
+}
+
+// ── Headless (scheduled) audit ───────────────────────────────────────────────
+
+/**
+ * Run the audit with nobody watching: no TTY animation, no browser, no prompts,
+ * no dashboard server left behind.
+ *
+ * This is the entry point the scheduler spawns, and it must be a SEPARATE
+ * short-lived process. `src/hooks/worker-server.ts` serialises every request
+ * through one promise chain that `crates/failproofaid/src/worker.rs` caps at
+ * 30s, and `daemon-client.ts` turns that timeout into a DENY — so a ~104-second
+ * audit on the warm worker would be a machine-wide fail-closed denial across
+ * all 12 CLIs for as long as it ran.
+ *
+ * Returns the exit code instead of exiting, so the caller owns the exit and
+ * this stays callable from a test:
+ *   0  the scan completed (whether or not it found anything)
+ *   1  the scan failed, or its result could not be persisted
+ *  75  another audit holds the lock — not an error, come back later
+ */
+export async function runScheduledAudit(): Promise<number> {
+  const attempt = acquireAuditLock("scheduled");
+  if (!attempt.ok) {
+    // Deliberately ahead of cli_audit_started: a run that never started must
+    // not be counted as one that did.
+    process.stderr.write(`failproofai: ${heldByLine(attempt.heldBy)}; skipping this scheduled run\n`);
+    return EXIT_AUDIT_ALREADY_RUNNING;
+  }
+
+  const instanceId = getInstanceId();
+  try {
+    // Every event here is awaited, unlike runAuditCli's fire-and-forget
+    // `started`. Nothing keeps this process alive once the audit settles — no
+    // dashboard server, no user — and there is nobody waiting on latency
+    // either, so the bounded (5s, never-throws) send costs nothing that matters.
+    await trackHookEvent(instanceId, "cli_audit_started", { source: "scheduled" });
+
+    let result: AuditResult;
+    try {
+      result = await runAudit({});
+    } catch (err) {
+      await trackHookEvent(instanceId, "cli_audit_failed", {
+        source: "scheduled",
+        error_type: err instanceof Error ? err.name : "unknown",
+        error_message: sanitizeErrorMessage(err),
+      });
+      process.stderr.write(
+        `failproofai: scheduled audit failed: ${err instanceof Error ? err.message : String(err)}\n`,
+      );
+      return 1;
+    }
+
+    await trackHookEvent(instanceId, "cli_audit_completed", auditCompletedProps("scheduled", result));
+
+    // No cache write for an empty scan, matching both interactive paths — and it
+    // matters more here. This run is unattended, so overwriting a real earlier
+    // audit's cached result with an empty one (after a history rotation, or on a
+    // service unit whose HOME resolves somewhere else) would blank the dashboard
+    // with nobody present to notice why.
+    if (result.eventsScanned > 0 && !writeDashboardCache({}, result)) {
+      // The cache is the only channel by which this run's result reaches
+      // anyone, so failing to write it is a failed run, not a footnote.
+      process.stderr.write("failproofai: scheduled audit ran but its result could not be saved\n");
+      return 1;
+    }
+
+    process.stdout.write(
+      `failproofai: audit complete — ${num(result.eventsScanned)} tool calls across ` +
+        `${num(result.transcripts.scanned)} sessions, ${num(result.totals.hits)} hits\n`,
+    );
+
+    return 0;
+  } finally {
+    attempt.lock.release();
+  }
+}
+
 // ── Post-setup background audit ────────────────────────────────────────────────
 
 /**
@@ -279,47 +387,67 @@ function auditCompletedProps(source: AuditSource, result: AuditResult) {
 export async function runPostSetupAudit(): Promise<void> {
   if (process.env.FAILPROOFAI_NO_AUTO_AUDIT === "1") return;
 
-  const instanceId = getInstanceId();
-  // Fire-and-forget, as in runAuditCli: the multi-second scan below keeps the
-  // process alive long enough for this to land, and the completed/failed event
-  // that follows is awaited.
-  void trackHookEvent(instanceId, "cli_audit_started", { source: "onboarding" });
-
-  process.stdout.write(
-    `\n  ${c(PINK, "✦")} ${c(BOLD, "failproofai audit now running")}  ${c(DIM, "· ctrl+c to stop")}\n\n`,
-  );
-
-  let result: AuditResult;
-  try {
-    result = await runWithProgress({});
-  } catch (err) {
-    // Awaited: this function returns straight into the dashboard boot, and a
-    // fire-and-forget fetch would race it.
-    await trackHookEvent(instanceId, "cli_audit_failed", {
-      source: "onboarding",
-      error_type: err instanceof Error ? err.name : "unknown",
-      error_message: sanitizeErrorMessage(err),
-    });
+  // Take the same cross-process cache lock the scheduled run, `failproofai
+  // audit` and the dashboard re-run take. This onboarding scan writes the very
+  // same sha1-keyed per-transcript cache and single-slot dashboard cache, so it
+  // is the fourth writer and must serialise with the other three — a scheduled
+  // daemon child can already be mid-scan when setup finishes. Held ⇒ skip, best
+  // effort: the dashboard boots on whatever the holder's run leaves behind, and
+  // this is pre-warming, not a result anyone is waiting on. `onboarding` matches
+  // the telemetry source below and the lock source declared in audit-lock.ts.
+  const attempt = acquireAuditLock("onboarding");
+  if (!attempt.ok) {
     process.stdout.write(
-      `  ${c(PINK, "!")} ${c(DIM, "audit couldn't finish — run")} ${c(CYAN, "failproofai audit")} ${c(DIM, "later.")}\n\n`,
+      `\n  ${c(DIM, "an audit is already running — the dashboard will show its result.")}\n\n`,
     );
     return;
   }
 
-  // Reported before the empty-history return below, so an onboarding audit that
-  // finds nothing is still counted — matching runAuditCli, which reports
-  // completed regardless of what the scan turned up.
-  await trackHookEvent(instanceId, "cli_audit_completed", auditCompletedProps("onboarding", result));
+  try {
+    const instanceId = getInstanceId();
+    // Fire-and-forget, as in runAuditCli: the multi-second scan below keeps the
+    // process alive long enough for this to land, and the completed/failed event
+    // that follows is awaited.
+    void trackHookEvent(instanceId, "cli_audit_started", { source: "onboarding" });
 
-  if (result.eventsScanned === 0) {
     process.stdout.write(
-      `\n  ${c(DIM, "no agent sessions to audit yet — come back after using your agent.")}\n\n`,
+      `\n  ${c(PINK, "✦")} ${c(BOLD, "failproofai audit now running")}  ${c(DIM, "· ctrl+c to stop")}\n\n`,
     );
-    return;
+
+    let result: AuditResult;
+    try {
+      result = await runWithProgress({});
+    } catch (err) {
+      // Awaited: this function returns straight into the dashboard boot, and a
+      // fire-and-forget fetch would race it.
+      await trackHookEvent(instanceId, "cli_audit_failed", {
+        source: "onboarding",
+        error_type: err instanceof Error ? err.name : "unknown",
+        error_message: sanitizeErrorMessage(err),
+      });
+      process.stdout.write(
+        `  ${c(PINK, "!")} ${c(DIM, "audit couldn't finish — run")} ${c(CYAN, "failproofai audit")} ${c(DIM, "later.")}\n\n`,
+      );
+      return;
+    }
+
+    // Reported before the empty-history return below, so an onboarding audit that
+    // finds nothing is still counted — matching runAuditCli, which reports
+    // completed regardless of what the scan turned up.
+    await trackHookEvent(instanceId, "cli_audit_completed", auditCompletedProps("onboarding", result));
+
+    if (result.eventsScanned === 0) {
+      process.stdout.write(
+        `\n  ${c(DIM, "no agent sessions to audit yet — come back after using your agent.")}\n\n`,
+      );
+      return;
+    }
+    writeDashboardCache({}, result);
+    printSummary(result);
+    process.stdout.write("\n");
+  } finally {
+    attempt.lock.release();
   }
-  writeDashboardCache({}, result);
-  printSummary(result);
-  process.stdout.write("\n");
 }
 
 // ── Entry point ──────────────────────────────────────────────────────────────
@@ -329,6 +457,15 @@ export async function runAuditCli(args: string[]): Promise<void> {
     process.stdout.write(HELP);
     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.
+  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.
   const stray = args.find((a) => a !== "--help" && a !== "-h");
@@ -339,6 +476,18 @@ export async function runAuditCli(args: string[]): Promise<void> {
     );
   }
 
+  // Taken before any telemetry so a refused run is not counted as a started
+  // one, and released the moment the SCAN is done — see below, well before
+  // launch() parks this process on the dashboard.
+  const attempt = acquireAuditLock("cli");
+  if (!attempt.ok) {
+    process.stderr.write(
+      `Error: ${heldByLine(attempt.heldBy)}.\n` +
+        `Two audits write the same cache files, so this one won't start. Try again shortly.\n`,
+    );
+    process.exit(EXIT_AUDIT_ALREADY_RUNNING);
+  }
+
   const instanceId = getInstanceId();
   // Fire-and-forget is safe for `started`: the multi-second audit below (and the
   // awaited cli_audit_completed / cli_audit_failed) keep the process alive long
@@ -393,6 +542,13 @@ export async function runAuditCli(args: string[]): Promise<void> {
     );
   }
 
+  // Released here, not in a `finally`: the lock covers the SCAN, and launch()
+  // below keeps this process alive for as long as the user leaves the dashboard
+  // open. Holding it that long would block every scheduled run until the
+  // one-hour stale ceiling expired. The exit paths above (die(), the
+  // empty-history exit) are covered by the handle's own process-exit hook.
+  attempt.lock.release();
+
   const url = `http://localhost:${DASHBOARD_PORT}/audit`;
   process.stdout.write(
     `\n  ${c(DIM, "starting the dashboard…")}\n` +

package/src/audit/dashboard-cache.ts

@@ -11,10 +11,9 @@
  * makes navigating back to /audit instant without re-running.
  */
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
 import { writeJsonAtomically } from "../../lib/atomic-write";
 import type { AuditResult, RunAuditOptions } from "./types";
+import { auditDashboardFile } from "../hooks/fp-home";
 
 const DEFAULT_MAX_AGE_MINUTES = 30;
 
@@ -50,7 +49,7 @@ export interface DashboardCacheEntry {
 }
 
 function getCachePath(): string {
-  return join(homedir(), ".failproofai", "audit-dashboard.json");
+  return auditDashboardFile();
 }
 
 /** Read the cache file. Returns null on missing/corrupt/unreadable file —

package/src/audit/report.ts

@@ -31,7 +31,6 @@ function noColorEnabled(): boolean {
 }
 
 function stripAnsi(s: string): string {
-  // eslint-disable-next-line no-control-regex
   return s.replace(/\x1B\[[0-9;]*m/g, "");
 }
 

package/src/hooks/backfill-cli.ts

@@ -0,0 +1,247 @@
+/**
+ * `failproofai backfill` — re-ship history the collector has already read past.
+ *
+ * The collector never re-reads a file it has a cursor for, which is right for
+ * steady state and wrong exactly twice:
+ *
+ *   • the dashboard's data was cleared, or a machine was re-enrolled into a
+ *     different org, and the history on disk is now the only copy;
+ *   • cursors advanced before there was anywhere to send to, so everything
+ *     before the connection was never shipped at all.
+ *
+ * Both leave a machine whose transcripts exist locally and nowhere else, with no
+ * way to ask for them again short of deleting files by hand and hoping.
+ *
+ * SAFE BY CONSTRUCTION, not by luck. Re-reading is already the documented
+ * recovery path for a damaged cursor store — "starting over re-ships records the
+ * server already dedups" — and redaction is deterministic, so a re-shipped event
+ * hashes identically to its first send and collapses into the row that is
+ * already there rather than duplicating it.
+ *
+ * HANDS OFF rather than doing the work. The cursors it needs to rewind are held
+ * in memory by the RUNNING collector, which would write them straight back over;
+ * only the daemon can stop the collector first. So this writes a request the
+ * daemon drains on its next tick.
+ *
+ * What it does NOT hand off is the checking. Every precondition a person can get
+ * wrong — no daemon, no credential, collection switched off — is verified here,
+ * synchronously, before returning. The alternative is what already happened once
+ * on a real machine: the CLI reported success, and the actual failure sat in the
+ * journal for twenty minutes while batches parked.
+ */
+import { existsSync, mkdirSync, writeFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { failproofaiHome } from "./fp-home";
+import { readConfig } from "./fp-config";
+import { readIngestCredential } from "./collector-config";
+import { daemonServiceStatus, isDaemonSupportedPlatform } from "./daemon-service";
+
+/** Default window. `--since` widens it. */
+export const DEFAULT_BACKFILL_DAYS = 30;
+
+export interface BackfillOptions {
+  /** Epoch ms. Everything modified at or after this is re-read. */
+  sinceMs?: number;
+  /** Report what would be re-read and write nothing. */
+  dryRun?: boolean;
+  /** Injected for tests. */
+  now?: number;
+}
+
+export interface BackfillResult {
+  exitCode: number;
+  lines: string[];
+}
+
+/**
+ * `~/.failproofai/state/backfill-request.json` — mirrored from the daemon's
+ * `paths::backfill_request_path()`. Two processes, one path; the comment there
+ * says why that is written down twice rather than derived.
+ */
+export function backfillRequestPath(home?: string): string {
+  return join(failproofaiHome(home), "state", "backfill-request.json");
+}
+
+/**
+ * Where each agent CLI keeps its transcripts, so the command can say what it is
+ * about to re-read rather than asking for trust.
+ *
+ * Deliberately a SURVEY, not the source of truth. The daemon decides what is
+ * actually collected from its own config; this list only produces the sentence
+ * a person reads before agreeing. A directory missing here means a quieter
+ * message, never a missed backfill.
+ */
+const SESSION_DIRS: Array<{ cli: string; dir: string }> = [
+  { cli: "Claude Code", dir: ".claude/projects" },
+  { cli: "OpenAI Codex", dir: ".codex/sessions" },
+  { cli: "Cursor", dir: ".cursor/chats" },
+  { cli: "GitHub Copilot", dir: ".copilot/history-session-state" },
+  { cli: "OpenCode", dir: ".local/share/opencode/storage" },
+  { cli: "Factory Droid", dir: ".factory/sessions" },
+  { cli: "Antigravity", dir: ".gemini/antigravity-cli/brain" },
+];
+
+interface Survey {
+  cli: string;
+  files: number;
+  newest: number;
+}
+
+/** What is on disk and inside the window, per CLI. */
+function surveySessions(sinceMs: number, homeDir: string): Survey[] {
+  const out: Survey[] = [];
+  for (const { cli, dir } of SESSION_DIRS) {
+    const root = join(homeDir, dir);
+    if (!existsSync(root)) continue;
+    let files = 0;
+    let newest = 0;
+    const walk = (d: string, depth: number) => {
+      // Bounded: these trees are date-nested a few levels deep, and an
+      // unbounded walk on a symlinked home is a way to hang a CLI command.
+      if (depth > 6) return;
+      let entries;
+      try {
+        entries = readdirSync(d, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const e of entries) {
+        const p = join(d, e.name);
+        if (e.isDirectory()) {
+          walk(p, depth + 1);
+          continue;
+        }
+        try {
+          const st = statSync(p);
+          if (st.mtimeMs >= sinceMs) {
+            files += 1;
+            newest = Math.max(newest, st.mtimeMs);
+          }
+        } catch {
+          /* raced away mid-walk */
+        }
+      }
+    };
+    walk(root, 0);
+    if (files > 0) out.push({ cli, files, newest });
+  }
+  return out;
+}
+
+export function runBackfillCommand(opts: BackfillOptions = {}): BackfillResult {
+  const now = opts.now ?? Date.now();
+  const sinceMs = opts.sinceMs ?? now - DEFAULT_BACKFILL_DAYS * 24 * 60 * 60 * 1000;
+  const home = failproofaiHome();
+
+  if (!existsSync(home)) {
+    return {
+      exitCode: 1,
+      lines: [`No failproofai home at ${home}. Run \`failproofai config\` first.`],
+    };
+  }
+
+  // Checked HERE, not left to the daemon. Handing off an impossible request and
+  // reporting success is the failure this command is partly a response to.
+  const ingest = readIngestCredential();
+  if (!ingest) {
+    return {
+      exitCode: 1,
+      lines: [
+        "This machine is not connected, so there is nowhere to send history.",
+        "Connect first: `failproofai config --connect <url> --token <key>`.",
+      ],
+    };
+  }
+
+  let sessions = false;
+  let hooks = false;
+  try {
+    const cfg = readConfig();
+    sessions = cfg.collector?.sessions ?? false;
+    hooks = cfg.collector?.hooks ?? false;
+  } catch {
+    /* an unreadable config is reported as "nothing enabled" below */
+  }
+  if (!sessions && !hooks) {
+    return {
+      exitCode: 1,
+      lines: [
+        "Collection is switched off, so a backfill would re-read history and send",
+        'none of it. Enable it in ~/.failproofai/config.json under "collector".',
+      ],
+    };
+  }
+
+  const found = surveySessions(sinceMs, dirname(home));
+  const totalFiles = found.reduce((n, f) => n + f.files, 0);
+  const sinceLabel = new Date(sinceMs).toISOString().slice(0, 10);
+
+  const lines: string[] = [
+    `Re-reading everything modified since ${sinceLabel}, and sending it again.`,
+    "",
+  ];
+  // Named honestly: only what the config actually enables, because that is all
+  // the daemon will ship. Promising transcripts on a machine with
+  // `sessions = false` would be a lie the user could only catch by waiting.
+  lines.push(
+    `  streams: ${[sessions && "session transcripts", hooks && "hook decisions"]
+      .filter(Boolean)
+      .join(" + ")}`,
+  );
+  if (sessions) {
+    if (found.length === 0) {
+      lines.push("  sessions: none found on disk in this window");
+    } else {
+      for (const f of found) {
+        lines.push(`  ${f.cli}: ${f.files} file${f.files === 1 ? "" : "s"}`);
+      }
+    }
+  }
+
+  if (opts.dryRun) {
+    lines.push("", "--dry-run: nothing was requested.");
+    return { exitCode: 0, lines };
+  }
+
+  try {
+    const path = backfillRequestPath();
+    mkdirSync(dirname(path), { recursive: true });
+    // Whole-file write of a small JSON object: the daemon deletes it before
+    // acting, so a partially-written file can only ever be read once, and an
+    // unparseable one is discarded rather than retried.
+    writeFileSync(path, `${JSON.stringify({ sinceMs, requestedAtMs: now }, null, 2)}\n`, {
+      mode: 0o600,
+    });
+  } catch (err) {
+    return {
+      exitCode: 2,
+      lines: [
+        ...lines,
+        "",
+        `Could not write the request: ${err instanceof Error ? err.message : String(err)}`,
+      ],
+    };
+  }
+
+  lines.push("", "Requested. The daemon picks this up within a few seconds.");
+
+  // A daemon that is not running will act on the request whenever it next
+  // starts — the request is a file, deliberately, so it survives that. Saying so
+  // is the difference between "nothing happened" and "nothing happened yet".
+  if (isDaemonSupportedPlatform()) {
+    const status = daemonServiceStatus();
+    if (status !== "running") {
+      lines.push(
+        `failproofaid is ${status}, so nothing moves until it starts. The request is`,
+        "on disk and will be honoured then.",
+      );
+    }
+  }
+  lines.push(
+    "",
+    `Watch it land:  ${totalFiles > 0 ? `~${totalFiles} files queued · ` : ""}` +
+      "`failproofai config --status`",
+  );
+  return { exitCode: 0, lines };
+}