failproofai 1.0.0 → 1.0.1-beta.0

package/src/audit/schedule-cli.ts

@@ -0,0 +1,352 @@
+/**
+ * `failproofai audit --schedule [days]` / `--no-schedule` / `--status`.
+ *
+ * ## Why this exists
+ *
+ * Until now the only way to turn scheduled audits on was the dashboard's
+ * settings page — a browser. `failproofaid` is a SYSTEM service:
+ * `WantedBy=multi-user.target`, starts at boot, needs no login, survives
+ * logout. That design exists for headless boxes, detached tmux, cron and CI
+ * runners, and not one of those can open a settings page. The feature was
+ * built for machines that had no way to switch it on.
+ *
+ * ## Parity is structural, not a promise
+ *
+ * Every write here goes through the same `updateConfig` the dashboard's server
+ * actions call, and the session goes through the same `auth-store`. There is
+ * one `config.json`, one `audit/session.json`, and one writer function for
+ * each — so "the CLI and the dashboard are always in sync" is a consequence of
+ * the shape rather than something to keep true by hand. Two files, or two
+ * writers, is where that promise starts needing tests to defend it.
+ *
+ * Two doc comments in `app/actions/` used to claim `failproofai config` already
+ * wrote these keys. It never did — the wizard calls `updateConfig` zero times.
+ * Those comments are corrected in this change rather than left describing a
+ * command that did not exist.
+ */
+import { readConfig, updateConfig } from "../hooks/fp-config";
+import { daemonServiceStatus, isDaemonSupportedPlatform } from "../hooks/daemon-service";
+import { readAuth } from "../../lib/auth/auth-store";
+import { readAuditSchedule } from "./audit-schedule";
+import { readDashboardCacheMeta } from "./dashboard-cache";
+import { readMachineIdentity } from "./machine-store";
+import { ensureSignedIn, invalidEmail, LoginError } from "./cli-login";
+import {
+  ANSI_BOLD,
+  ANSI_DIM,
+  ANSI_RESET,
+  brandAnsi,
+  colorsEnabled,
+  outro,
+  step,
+} from "../hooks/tui";
+
+/** Mirrors `fp-config`'s own bounds so the error can name them before writing. */
+const MIN_DAYS = 1;
+const MAX_DAYS = 90;
+
+export class ScheduleCliError extends Error {}
+
+/**
+ * Colour and the spine answer to ONE gate, checked at call time.
+ *
+ * They used to disagree: these helpers emitted ANSI unconditionally while the
+ * frame asked `colorsEnabled`, so a piped `--status` came out as escape codes
+ * with no structure — the worst of both. `colorsEnabled` is false off a TTY and
+ * under `NO_COLOR`, which is exactly when a readout should be plain text.
+ */
+const styled = () => colorsEnabled(process.stdout);
+const wrap = (open: string, s: string) => (styled() ? `${open}${s}${ANSI_RESET}` : s);
+const pink = (s: string) => wrap(brandAnsi("pink"), s);
+const green = (s: string) => wrap(brandAnsi("guide"), s);
+const dim = (s: string) => wrap(ANSI_DIM, s);
+const bold = (s: string) => wrap(ANSI_BOLD, s);
+
+/**
+ * The readout's left margin.
+ *
+ * Deliberately NOT the `│` spine the sign-in uses. A spine means "a flow is
+ * happening, with a beginning and an end"; `--status` is a snapshot of a
+ * machine, and hanging one off a frame that never opened reads as an unfinished
+ * wizard. Alignment does the work here instead.
+ */
+const rail = () => " ";
+
+/**
+ * One labelled row of the `--status` readout.
+ *
+ * A fixed label column so the values line up into a second column that can be
+ * read straight down — the whole point of this command is answering "what is
+ * this machine doing" at a glance, and a ragged left edge makes four facts read
+ * as four sentences.
+ */
+const LABEL_WIDTH = 15;
+function row(label: string, value: string, note?: string): string {
+  const gap = " ".repeat(Math.max(1, LABEL_WIDTH - label.length));
+  return `${rail()}  ${dim(label)}${gap}${value}${note ? `  ${dim(note)}` : ""}`;
+}
+
+/**
+ * Turn scheduled audits on, signing in first if needed.
+ *
+ * Scheduling and mailing are ONE decision — the reason to put a scan on a timer
+ * is to be told what it found — so this requires a session, exactly as the
+ * dashboard's `setAutoAuditAction` does. A timer set with nobody to tell is a
+ * switch that reads as on and produces nothing, discoverable only by noticing
+ * that no digest ever arrives.
+ *
+ * The interval is written and then RE-READ, so what is printed is what the
+ * config actually kept — `readIntervalDays` owns the 1..90 clamp and a second
+ * copy of those bounds here would be one more thing to drift.
+ */
+export async function runScheduleOn(
+  daysArg: string | undefined,
+  emailArg?: string,
+): Promise<void> {
+  let days: number | undefined;
+  if (daysArg !== undefined) {
+    const parsed = Number(daysArg);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
+      throw new ScheduleCliError(
+        `\`--schedule\` takes a whole number of days (got: ${daysArg}).`,
+      );
+    }
+    if (parsed < MIN_DAYS || parsed > MAX_DAYS) {
+      throw new ScheduleCliError(
+        `\`--schedule\` must be between ${MIN_DAYS} and ${MAX_DAYS} days (got: ${parsed}).`,
+      );
+    }
+    days = parsed;
+  }
+
+  // Checked here, beside the day count and before anything is drawn or sent: a
+  // typo'd flag should read as a usage error, not as a sign-in that opened a
+  // frame and then gave up.
+  if (emailArg !== undefined) {
+    const bad = invalidEmail(emailArg);
+    if (bad) throw new ScheduleCliError(bad);
+  }
+
+  const { user, prompted } = await ensureSignedIn(emailArg);
+
+  const next = updateConfig({
+    // Stamped in the SAME call that sets `auto`, never separately: this records
+    // that a person completed a sign-in and read the disclosure printed below,
+    // and it is what `reportHarm` gates sending on. A machine that inherited
+    // `auto` from a release where it meant "scan locally" has no stamp and
+    // sends nothing until it comes through here.
+    audit: {
+      auto: true,
+      reportsConsentedAt: Date.now(),
+      ...(days !== undefined ? { intervalDays: days } : {}),
+    },
+  });
+  const interval = next.audit.intervalDays;
+
+  // Two rows rather than one long one: at 80 columns the combined sentence
+  // wrapped, and a wrapped summary loses the spine on its second row.
+  // The third row enumerates what leaves the machine, and it is not optional.
+  // This is the ONLY opt-in path on the headless boxes the whole feature was
+  // built for — the settings panel says "sends: counts, redacted examples, and
+  // this machine's name" and argues in its own comment that a checkable list
+  // beats a stronger claim, and that reasoning applies here at least as much.
+  // The list is the real payload from `report-harm.ts`: machine id, hostname,
+  // platform, the window bounds and the redacted examples.
+  const summary = [
+    `every ${interval} day${interval === 1 ? "" : "s"} · reports to ${user.email}`,
+    "you only hear from it when a scan finds something harmful",
+    "each report sends: finding counts, redacted example commands, this machine's name",
+  ];
+
+  if (prompted) {
+    // A sign-in just drew the frame, so the result continues it and the `└`
+    // closes both at once — rather than the frame ending and a loose line
+    // appearing underneath.
+    step("scheduled audits are on", summary);
+  } else {
+    // Nothing was asked, so nothing was a flow: a spine here would open a frame
+    // that has no beginning.
+    process.stdout.write(
+      `\n${green("✓")}  ${bold("scheduled audits are on")}\n` +
+        summary.map((r) => `   ${dim(r)}\n`).join(""),
+    );
+  }
+
+  // The switch is config; whether anything RUNS is the daemon. Saying "on"
+  // without checking would be the same "on but silent" state the settings panel
+  // exists to make visible.
+  warnIfDaemonWontRun();
+
+  if (prompted) {
+    outro("failproofai audit --status  ·  when the next scan is due");
+  } else {
+    process.stdout.write(dim(`\n   failproofai audit --status   when the next scan is due\n\n`));
+  }
+}
+
+export function runScheduleOff(): void {
+  const before = readConfig().audit.auto;
+  const next = updateConfig({ audit: { auto: false } });
+  if (next.audit.auto) {
+    process.stdout.write("Could not turn scheduled audits off.\n");
+    return;
+  }
+  if (!before) {
+    process.stdout.write(dim("\nScheduled audits were already off.\n\n"));
+    return;
+  }
+  process.stdout.write(
+    `\n${green("✓")}  ${bold("scheduled audits are off")}\n` +
+      `   ${dim("nothing runs on a timer and nothing is sent")}\n` +
+      `   ${dim("your session is untouched — sign out from the dashboard for that")}\n\n`,
+  );
+}
+
+/**
+ * What this machine is actually doing.
+ *
+ * The one command with no equivalent anywhere else: on a headless box there was
+ * previously no way to ask whether scheduling was on, when the last scan ran, or
+ * whether the daemon was even up. Every value is read from the same places the
+ * dashboard reads them.
+ */
+export function runScheduleStatus(): void {
+  const config = readConfig();
+  const auth = readAuth();
+  const sched = readAuditSchedule();
+  const meta = readDashboardCacheMeta();
+  const machine = readMachineIdentity();
+  const daemon = daemonServiceStatus();
+
+  const on = config.audit.auto;
+  const out: string[] = [""];
+
+  // The state first and alone, in the accent that matches it — everything below
+  // is detail about a machine that is either doing this or not, and reading the
+  // detail first is reading the answer to a question nobody asked yet.
+  out.push(
+    `${rail()}  ${bold("scheduled audit")}   ${on ? green("on") : dim("off")}` +
+      (on ? dim(`  every ${config.audit.intervalDays} days`) : ""),
+  );
+  out.push(rail());
+
+  // A session whose refresh window has closed cannot mint another access token,
+  // so it is a destination in name only. Showing the address for one would tell
+  // somebody their digests are going somewhere they are not.
+  const live = auth && auth.refresh_expires_at * 1000 > Date.now() ? auth : null;
+  out.push(row("reports to", live ? live.user.email : dim("— signed out")));
+  if (on && !live) {
+    // The state the reporter surfaces as "signed-out". Named here for the same
+    // reason the settings panel names it: the scans keep running, so silence
+    // about the digests would look like the feature failing.
+    out.push(row("", pink("scans continue; digests are paused until you sign in")));
+  } else if (on && config.audit.reportsConsentedAt === undefined) {
+    // Signed in, scheduled, and still not sending: this machine set `audit.auto`
+    // when it only meant "scan locally", so nothing has consented to the digest
+    // leaving the box. Without this row the status screen would show a healthy
+    // schedule and a live address and still mail nothing, with no explanation
+    // anywhere the user can see.
+    out.push(
+      row("", pink("scans continue; digests need a fresh opt-in — run `--schedule` to turn them on")),
+    );
+  }
+
+  out.push(row("daemon", describeDaemon(daemon)));
+
+  if (sched?.nextDueAtMs != null && on) {
+    out.push(row("next scan", untilPhrase(sched.nextDueAtMs)));
+  }
+  if (sched?.lastRunAtMs != null) {
+    const exit = sched.lastExitCode;
+    out.push(
+      row(
+        "last scheduled",
+        agoPhrase(sched.lastRunAtMs),
+        exit != null && exit !== 0 && exit !== 75 ? pink(`exit ${exit}`) : undefined,
+      ),
+    );
+  }
+  out.push(
+    row("last result", meta?.cachedAt ? agoPhrase(Date.parse(meta.cachedAt)) : dim("none yet")),
+  );
+  if (machine?.last_reported_at) {
+    out.push(row("last reported", agoPhrase(Date.parse(machine.last_reported_at))));
+  }
+  out.push("");
+
+  process.stdout.write(out.join("\n"));
+}
+
+function describeDaemon(status: ReturnType<typeof daemonServiceStatus>): string {
+  switch (status) {
+    case "running":
+      return green("running");
+    case "stopped":
+      return pink("stopped — run `failproofai config` to repair it");
+    case "not-installed":
+      return pink("not installed — run `failproofai config`");
+    case "condition-failed":
+      return pink("installed but its binary is missing — run `failproofai config`");
+    default:
+      return isDaemonSupportedPlatform()
+        ? dim(String(status))
+        : dim("unavailable on this platform");
+  }
+}
+
+/** Printed after turning scheduling on, where the answer changes what to do. */
+function warnIfDaemonWontRun(): void {
+  const status = daemonServiceStatus();
+  if (status === "running") return;
+  // "unknown" is not "broken", and on macOS it is the ORDINARY reading.
+  // `daemonServiceStatus` needs `sudo -n` to interrogate a LaunchDaemon, and a
+  // Mac with no cached sudo credential — the overwhelmingly common state —
+  // answers "unknown" for a service that is running perfectly. Treating every
+  // non-`running` value as a fault told those users "nothing will run on the
+  // timer yet" in the same breath as confirming their schedule was on. The
+  // dashboard already special-cases it; this is the same call.
+  if (status === "unknown") return;
+  if (!isDaemonSupportedPlatform()) {
+    process.stderr.write(
+      `\n  ${pink("!")} The background service is not available on this platform,\n` +
+        `    so nothing will run on the timer here. \`failproofai audit\` still works.\n`,
+    );
+    return;
+  }
+  process.stderr.write(
+    `\n  ${pink("!")} The background service is ${status.replace("-", " ")}, ` +
+      `so nothing will run on the timer yet.\n` +
+      `    Run \`failproofai config\` to install or repair it.\n`,
+  );
+}
+
+function untilPhrase(ms: number): string {
+  const diff = ms - Date.now();
+  if (diff <= 0) return "due now";
+  const d = Math.floor(diff / 86_400_000);
+  const h = Math.floor((diff % 86_400_000) / 3_600_000);
+  if (d > 0) return `in ${d}d${h > 0 ? ` ${h}h` : ""}`;
+  if (h > 0) return `in ${h}h`;
+  return `in ${Math.max(1, Math.floor(diff / 60_000))}m`;
+}
+
+function agoPhrase(ms: number): string {
+  if (!Number.isFinite(ms)) return "unknown";
+  const diff = Date.now() - ms;
+  if (diff < 0) return "just now";
+  const d = Math.floor(diff / 86_400_000);
+  const h = Math.floor(diff / 3_600_000);
+  const m = Math.floor(diff / 60_000);
+  if (d > 0) return `${d}d ago`;
+  if (h > 0) return `${h}h ago`;
+  if (m > 0) return `${m}m ago`;
+  return "just now";
+}
+
+/** Turn a `LoginError` into the CLI's own error type, keeping its message. */
+export function asScheduleError(err: unknown): never {
+  if (err instanceof LoginError || err instanceof ScheduleCliError) {
+    throw new ScheduleCliError(err.message);
+  }
+  throw err;
+}

package/src/hooks/builtin-policies.ts

@@ -140,6 +140,32 @@ const PRIVATE_KEY_RE = /-----BEGIN (?:[A-Z]+ )?PRIVATE KEY-----/;
 // sanitizeBearerTokens
 const BEARER_TOKEN_RE = /Authorization:\s*Bearer\s+[A-Za-z0-9\-._~+/]{20,}/i;
 
+/**
+ * Every pattern the `sanitize-*` policies treat as a secret, as one list.
+ *
+ * Exported so the audit's harm reporter can redact against the SAME definition
+ * of "secret" that the engine blocks on, rather than growing a second pattern
+ * list beside this one. Two lists is the shape that eventually disagrees, and
+ * the direction it disagrees in here is a live credential leaving a machine.
+ *
+ * The `sanitize-*` FUNCTIONS cannot be reused for this — they are detectors that
+ * return a `deny` with a message, not transforms that return scrubbed text. The
+ * patterns are the reusable part, so the patterns are what is shared.
+ *
+ * Ordered most-specific first, which is load-bearing for the API keys: a
+ * generic `sk-[A-Za-z0-9]{20,}` placed before `sk-ant-…` would label an
+ * Anthropic key as an OpenAI one. (It does not currently MATCH one — the
+ * hyphens in `sk-ant-` break the character class — but the ordering is what
+ * makes that a design rather than a coincidence.)
+ */
+export const SECRET_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [
+  [PRIVATE_KEY_RE, "private key"],
+  [JWT_RE, "JWT"],
+  [BEARER_TOKEN_RE, "bearer token"],
+  [CONNECTION_STRING_RE, "database credentials"],
+  ...API_KEY_PATTERNS,
+];
+
 // warnDestructiveSql / warnSchemaAlteration
 const SQL_TOOL_RE = /\b(?:psql|mysql|sqlite3|pgcli|clickhouse-client)\b/;
 const DESTRUCTIVE_SQL_RE = /\b(?:DROP\s+(?:TABLE|DATABASE|SCHEMA)|TRUNCATE\b)/i;

package/src/hooks/daemon-service.ts

@@ -1797,3 +1797,79 @@ export function daemonServiceStatus(): DaemonServiceStatus {
     return "stopped";
   }
 }
+
+/**
+ * When the running daemon started, as epoch ms — the source for /settings'
+ * "up 11d" sub-line. Null whenever the answer isn't knowable.
+ *
+ * **From the MONOTONIC stamp, not the printed date.** `ActiveEnterTimestamp`
+ * renders in the host's locale and timezone abbreviation (`Fri 2026-08-14
+ * 19:45:13 IST`), which `Date.parse` reads as invalid on most abbreviations and,
+ * worse, silently mis-parses on the few it recognises — a settings page
+ * claiming the daemon started three hours in the future is a worse failure than
+ * one that says nothing. `ActiveEnterTimestampMonotonic` is microseconds since
+ * boot, locale-free, and pairs with a reading of the SAME clock to give the
+ * epoch time back.
+ *
+ * An EPOCH time rather than a duration, so the page keeps counting without
+ * re-fetching: a duration computed on the server is wrong the moment it renders.
+ *
+ * Linux only for now. launchd exposes no equivalent, so macOS would need the
+ * job's pid out of `launchctl print` and then `ps -o etime=` — a SECOND
+ * privileged call on every settings render, since reading a LaunchDaemon in the
+ * system domain needs elevation. The sub-line is not worth doubling the sudo
+ * traffic of the page; the status itself still renders there.
+ */
+export function daemonStartedAtMs(): number | null {
+  if (process.platform !== "linux") return null;
+  if (!existsSync(systemdUnitPath())) return null;
+  try {
+    const raw = execFileSync(
+      "systemctl",
+      ["show", systemdUnitName(), "-p", "ActiveEnterTimestampMonotonic", "--value"],
+      { stdio: ["ignore", "pipe", "ignore"], timeout: SERVICE_CMD_TIMEOUT_MS },
+    )
+      .toString()
+      .trim();
+    // `process.hrtime.bigint()`, not `os.uptime()`. See the note on the
+    // function below: the two count suspend differently, and mixing them is
+    // what produced "up 30d" for a daemon started yesterday.
+    return startedAtFromMonotonic(Number(raw), Math.floor(Number(process.hrtime.bigint()) / 1000), Date.now());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The arithmetic behind `daemonStartedAtMs`, split out so it can be tested
+ * without a systemd on the machine running the tests.
+ *
+ * BOTH arguments must be readings of the SAME clock. systemd's
+ * `ActiveEnterTimestampMonotonic` is `CLOCK_MONOTONIC`, which on Linux STOPS
+ * while the machine is suspended; `os.uptime()` reads `/proc/uptime`, which
+ * KEEPS COUNTING through suspend. Subtracting one from the other therefore adds
+ * every second the laptop ever spent asleep to the daemon's apparent age — a
+ * machine that suspends nightly read "up 30d" for a service started yesterday.
+ * The old `< 0` guard caught only the impossible direction; this error is
+ * always positive, so nothing rejected it.
+ *
+ * `process.hrtime.bigint()` is `CLOCK_MONOTONIC` on Linux (libuv's `uv_hrtime`),
+ * the same clock systemd stamped with, so the subtraction is between two points
+ * on one timeline.
+ *
+ * systemd writes 0 for a unit that has never been activated, and a stamp ahead
+ * of the current reading cannot be true — both mean "no answer" rather than a
+ * number, because a wrong uptime is indistinguishable from a right one to the
+ * person reading it.
+ */
+export function startedAtFromMonotonic(
+  activeEnterMonotonicUs: number,
+  monotonicNowUs: number,
+  nowMs: number,
+): number | null {
+  if (!Number.isFinite(activeEnterMonotonicUs) || activeEnterMonotonicUs <= 0) return null;
+  if (!Number.isFinite(monotonicNowUs) || monotonicNowUs <= 0) return null;
+  const activeForMs = (monotonicNowUs - activeEnterMonotonicUs) / 1000;
+  if (activeForMs < 0) return null;
+  return Math.round(nowMs - activeForMs);
+}

package/src/hooks/fp-config.ts

@@ -102,6 +102,20 @@ export function detectLayout(): LayoutState {
   // went missing is the exact failure this module exists to prevent, and it
   // announced itself as a routine "reorganised your home" message.
   if (existsSync(configFile())) {
+    // `config.json` proves layout 3 OR LATER — it cannot tell them apart, since
+    // layout 4 changed nothing about it. What separates the two is solely WHERE
+    // the audit's files sit, so ask that directly: any of layout 3's three
+    // root-level positions still occupied means the 3 → 4 move has not run.
+    //
+    // When none of them exist the two layouts are IDENTICAL on disk (the step
+    // would move nothing), and "current" is the correct, non-destructive answer.
+    const layoutThreePositions = [
+      legacy.authJson(),
+      legacy.nextAudit(),
+      legacy.auditSchedule(),
+    ];
+    if (layoutThreePositions.some((p) => existsSync(p))) return { kind: "stale", found: 3 };
+
     // `inferred`: the layout is right but the MARKER is missing, and nothing
     // else rewrites it — so every later command re-derives it from a landmark,
     // and the daemon version recorded in that file is gone for good
@@ -112,7 +126,16 @@ export function detectLayout(): LayoutState {
 
   // `config.toml` and no `config.json` is genuinely layout 2, and a reset is
   // right: its files are the ones being replaced.
-  if (existsSync(legacy.configToml())) return { kind: "stale", found: LAYOUT_VERSION - 1 };
+  //
+  // The literal 2, NOT `LAYOUT_VERSION - 1`. That expression was correct while
+  // current was 3 and became a data-loss bug the moment layout 4 landed: it
+  // reported a real layout-2 home as layout 3, so `planMigration` ran only the
+  // 3 → 4 step — which finds none of layout 3's files, moves nothing, and stamps
+  // the home as current. `config.toml` and `credentials.toml` would never be
+  // carried into JSON, orphaning the cloud token and `daemon.configured` on a
+  // machine that now reads as fully migrated. A landmark identifies ONE layout;
+  // it is never relative to whatever this build happens to speak.
+  if (existsSync(legacy.configToml())) return { kind: "stale", found: 2 };
 
   // Layout 1 if any of its landmarks are present, otherwise this is simply a
   // home that has not been set up yet.
@@ -187,12 +210,23 @@ export function readVersionFile(): VersionFile | null {
   }
 }
 
+/**
+ * Stamp `VERSION`.
+ *
+ * `layout` defaults to {@link LAYOUT_VERSION} — every ordinary caller is saying
+ * "this home now speaks what this build speaks". It is honoured when passed
+ * ONLY so a failed migration can put the marker back where the home actually
+ * is: the signature has always accepted `layout` (it is part of `VersionFile`)
+ * and the body used to ignore it, so a caller asking for 3 silently got 4, and
+ * the one place that needs to ask is the one place where being wrong strands a
+ * half-migrated home as "current" forever. See `runMigrations`.
+ */
 export function writeVersionFile(
   v: Partial<VersionFile> & { /** Erase the daemon version rather than keeping it. */ clearDaemon?: boolean } = {},
 ): void {
   const existing = readVersionFile();
   const next: VersionFile = {
-    layout: LAYOUT_VERSION,
+    layout: v.layout ?? LAYOUT_VERSION,
     cli: v.cli ?? cliVersion,
     // `undefined` means "leave whatever is there" — a CLI-only rewrite must not
     // drop a daemon version it never touched. Erasing it is therefore an
@@ -274,7 +308,22 @@ export interface FpConfig {
   };
   audit: {
     /**
-     * Scan this machine's agent history on a schedule.
+     * Scan this machine on a schedule, and mail a digest when a scan finds
+     * something harmful.
+     *
+     * ONE switch, not two. An earlier revision split this into `auto` (scan
+     * locally, no account) and `email_enabled` (mail me, sign in), and the two
+     * could only ever disagree — a machine scanning on a timer with nothing to
+     * report it to is a feature that looks on and does nothing visible. The
+     * reason to put a scan on a timer is to be TOLD, so scheduling and mailing
+     * are the same decision and take the same switch.
+     *
+     * A signed-out machine with this on is therefore a real, expected state
+     * rather than a contradiction: it keeps scanning and keeps its local
+     * dashboard current, and the UI says "signed out" until somebody signs back
+     * in. Auth gates SETTING it up, never the machine's ongoing work — a
+     * refresh token expiring must not silently switch off a background feature
+     * somebody configured months ago.
      *
      * OFF by default, and the asymmetry with `telemetry.enabled` above is
      * deliberate: the audit reads the CONTENTS of every session transcript on
@@ -282,6 +331,28 @@ export interface FpConfig {
      * timer until somebody asks for it.
      */
     auto: boolean;
+    /**
+     * When this machine's owner agreed that a scheduled scan may send what it
+     * finds off the box, as epoch ms. Absent means they never did.
+     *
+     * This does NOT reintroduce the second switch the comment above rejects,
+     * and it is never drawn as one. `auto` is what a person sets; this is a
+     * record of the disclosure they were shown when they set it. The two cannot
+     * drift, because every path that turns `auto` on stamps this in the same
+     * call and nothing stamps it alone.
+     *
+     * It exists because `auto` CHANGED MEANING. Through 1.0.0 it meant "scan
+     * this machine on a timer" and nothing more — no account, no network, and
+     * the toggle that wrote it said as much in as many words. Harm digests gave
+     * the same stored bit a second job: uploading redacted transcript excerpts
+     * to the api-server and mailing them. Without a separate record, every
+     * machine that opted into the old meaning would have started sending on
+     * upgrade, having agreed to nothing of the kind, with the only notice a
+     * line in the journal. Gating on the stamp rather than the switch is what
+     * keeps that upgrade silent in the safe direction: those machines keep
+     * scanning locally and send nothing until somebody opts in again.
+     */
+    reportsConsentedAt?: number;
     /** Days between scheduled runs. Wall clock, so it survives suspend. */
     intervalDays: number;
   };
@@ -458,7 +529,17 @@ export function projectConfig(parsed: Record<string, unknown>): FpConfig {
       // scheduled scan on. Absent, misspelled, or `"yes"` all read as off,
       // because the failure direction here is a machine that starts reading
       // every transcript it can find on a timer nobody set.
-      audit: { auto: audit.auto === true, intervalDays: readIntervalDays(audit.interval_days) },
+      audit: {
+        auto: audit.auto === true,
+        intervalDays: readIntervalDays(audit.interval_days),
+        // A finite number or nothing. A garbage value reads as absent, which is
+        // the direction that sends nothing.
+        reportsConsentedAt:
+          typeof audit.reports_consented_at === "number" &&
+          Number.isFinite(audit.reports_consented_at)
+            ? audit.reports_consented_at
+            : undefined,
+      },
       // Same shape as `audit.auto` above and for the same reason: only an
       // explicit `true` opts in. Anything else — absent, misspelled, `"yes"` —
       // reads as off, because the failure direction is a machine that starts
@@ -504,6 +585,7 @@ const OWNED_CONFIG_KEYS: readonly (readonly string[])[] = [
   ["telemetry", "enabled"],
   ["audit", "auto"],
   ["audit", "interval_days"],
+  ["audit", "reports_consented_at"],
 ];
 
 const isPlainObject = (v: unknown): v is Record<string, unknown> =>
@@ -604,7 +686,16 @@ export function writeConfig(config: FpConfig, raw?: Record<string, unknown>): vo
     // nobody can see is the same as a switch that does not exist. Emitting both
     // keys unconditionally also makes "a user's setting survives a rewrite"
     // total rather than conditional.
-    audit: { auto: config.audit.auto, interval_days: config.audit.intervalDays },
+    audit: {
+      auto: config.audit.auto,
+      interval_days: config.audit.intervalDays,
+      // Written only once there IS consent, so an untouched machine's config
+      // does not grow a key implying it was asked. It is in
+      // `OWNED_CONFIG_KEYS`, so omitting it here really removes it.
+      ...(config.audit.reportsConsentedAt === undefined
+        ? {}
+        : { reports_consented_at: config.audit.reportsConsentedAt }),
+    },
   };
   // Start from the previous bytes, strip the keys this build owns — so an
   // omission above really removes — then lay the projection on top. What is left