failproofai 1.0.4-beta.2 → 1.0.4-beta.4

package/src/audit/cli.ts

@@ -37,7 +37,9 @@ import { openWhenReady } from "./open-browser";
 import { describeOutcome, reportHarm } from "./report-harm";
 import { notifyDesktop } from "./desktop-notify";
 import { macNotifierInstalled, pruneMacNotifyQueue, queueMacNotification } from "./macos-notifier";
-import { markLeakNoticeDelivered } from "./leak-notice";
+import { markLeakNoticeDelivered, releaseLeakNoticeClaims } from "./leak-notice";
+import { desktopLeakNotice } from "../hooks/notice";
+import { activeFindings, readLeakRecord } from "./leak-store";
 import { readConfig } from "../hooks/fp-config";
 import { brandAnsi, ANSI_RESET, ANSI_BOLD, ANSI_DIM, helpScreen, helpOptsFor } from "../hooks/tui";
 import { version } from "../../package.json";
@@ -96,19 +98,19 @@ export function helpText(): string {
     {
       command: "audit",
       version,
-      tagline: "review your agent CLIs for risky and wasteful patterns",
+      tagline: "find credentials your agents leaked into their own transcripts",
       sections: [
         {
           label: "usage",
           entries: [
-            ["(bare)", `Scan your session history, then open http://localhost:${DASHBOARD_PORT}/audit`],
-            ["--schedule [days]", "Scan on a timer and email the findings. Default 7 days, range 1-90. Signs you in the first time."],
+            ["(bare)", `Scan your session history for leaked keys, then open http://localhost:${DASHBOARD_PORT}/audit`],
+            ["--schedule [days]", "Scan on a timer, notify you on this machine, and email the findings. Default 7 days, range 1-90. Signs you in the first time."],
             // Its own row now, rather than a clause inside --schedule's. It
             // does not stand alone, which is why it used to be a clause — but
             // a clause wraps, and `--email <address>` landing with the flag at
             // the end of one line and its placeholder at the start of the next
             // is not a flag anybody can read or copy.
-            ["--email <address>", "With --schedule, skips the sign-in prompt."],
+            ["--email <address>", "With --schedule, fills in your address. A sign-in code is still emailed to you to paste."],
             ["--no-schedule", "Stop the timer. Leaves you signed in."],
             // Its own pair of flags rather than a clause on --schedule: whether
             // this machine scans and whether it may interrupt you are separate
@@ -121,7 +123,11 @@ export function helpText(): string {
           ],
         },
       ],
-      footer: ["Everything runs on this machine; only a scheduled digest ever leaves it."],
+      footer: [
+        "Everything runs on this machine. A scan tells you three ways: a desktop",
+        "notification, two lines in your agent session, and the emailed digest —",
+        "and only that digest ever leaves.",
+      ],
     },
     helpOptsFor(process.stdout),
   );
@@ -209,6 +215,18 @@ function startProgress(): Progress {
     const lines = Array.from({ length: n }, (_, i) => lineFor(i));
     // Move the cursor back up over the previously-drawn block, then clear and
     // rewrite each line in place.
+    //
+    // INVARIANT: nothing else may write to the terminal while this is running.
+    // The cursor-up is a fixed count, so any stray line pushes the cursor down
+    // and the next redraw repaints the block lower — stranding the top of the
+    // old frame above it, which reads as the audit having run twice. That is
+    // not hypothetical: Node's "SQLite is an experimental feature" warning did
+    // exactly this on every first run, two lines of it, and it is why
+    // `lib/sqlite-reader.ts` now filters that one warning at the source.
+    //
+    // There is no defensive fix from inside here — erasing to end of screen
+    // still leaves the stranded lines ABOVE the cursor. Keep the terminal
+    // quiet instead.
     if (printed) process.stdout.write(`\x1b[${n}A`);
     process.stdout.write(lines.map((l) => `\x1b[2K${l}`).join("\n") + "\n");
     printed = true;
@@ -390,66 +408,73 @@ async function announceLeaksOrThrow(result: AuditResult): Promise<void> {
   const claimed = markLeakNoticeDelivered(ids, undefined, "desktop");
   if (claimed.length === 0) return;
 
-  const n = claimed.length === 1 ? "a credential" : `${claimed.length} credentials`;
-  const title = "failproofai found a leaked credential";
-  // Fixed text with a count interpolated — the same rule as the in-CLI notice,
-  // for the same reason. A finding's own text comes from a repository this
-  // machine cloned, and notification bodies render markup on several Linux
-  // desktops.
-  //
-  // The second sentence is the only place most users are ever offered the
-  // digest. The scan is local and needs no account, so nothing else in the
-  // product has a reason to ask for an address — which is exactly why the
-  // audit's findings have historically reached nobody. A banner someone is
-  // already reading, about a key of their own, is the one moment the offer is
-  // worth anything.
+  // Report what SURVIVED into the record, not how many ids the scan minted.
+  // `writeLeakRecord` prunes to MAX_FINDINGS, so on a large history the two
+  // numbers diverge wildly — a real run announced "5703 credentials" while the
+  // dashboard it points at showed 500. A banner that disagrees with the page it
+  // sends you to is worse than no banner: it teaches you the number is noise.
+  const live = new Set(activeFindings(readLeakRecord()).map((f) => f.id));
+  const shown = claimed.filter((id) => live.has(id)).length || claimed.length;
+
+  const n = shown === 1 ? "a possible credential exposure" : `${shown} possible credential exposures`;
+  // Fixed text with no scanned content and no count. A finding's own text comes
+  // from a repository this machine cloned, and notification bodies render
+  // markup on several Linux desktops. The count is intentionally left to the
+  // report too: a banner must not turn detector candidates into a claim that
+  // the user leaked N real credentials.
   //
   // No action buttons, deliberately. `Notify` supports them, but a server
   // delivers the click back as an `ActionInvoked` signal to the sender — and
   // this process exits as soon as the scan finishes, so the button would be
-  // dead. Two plain commands the user can copy beat one button that does
-  // nothing.
-  const body =
-    `${n} in your agent transcripts. Run failproofai audit to see them — ` +
-    "or failproofai audit --schedule to get them by email.";
-
-  // The two platforms need opposite things, and the split is not cosmetic. On
-  // Linux this process can reach the session bus itself. On macOS it cannot
-  // reach Notification Center at all — it is a child of a LaunchDaemon, outside
-  // the GUI session — so it hands the message to an agent that lives inside
-  // one. See `macos-notifier.ts` for why that agent exists.
-  if (process.platform === "darwin") {
-    pruneMacNotifyQueue();
-    if (!queueMacNotification(claimed[0], title, body)) {
-      process.stderr.write(`failproofai: found ${n} but could not queue a notification\n`);
-    } else if (!macNotifierInstalled()) {
-      // Queued, but nothing will collect it: setup either never ran or could
-      // not compile the applet. Worth a line, because the symptom otherwise is
-      // simply silence.
-      process.stderr.write(
-        `failproofai: found ${n}; the notifier is not installed, so nothing will show it ` +
-          `(run \`failproofai config\`)\n`,
-      );
+  // dead. A plain command the user can copy beats a button that does nothing.
+  const { title, body } = desktopLeakNotice();
+  let delivered = false;
+
+  try {
+    // The two platforms need opposite things, and the split is not cosmetic. On
+    // Linux this process can reach the session bus itself. On macOS it cannot
+    // reach Notification Center at all — it is a child of a LaunchDaemon, outside
+    // the GUI session — so it hands the message to an agent that lives inside
+    // one. See `macos-notifier.ts` for why that agent exists.
+    if (process.platform === "darwin") {
+      pruneMacNotifyQueue();
+      if (!queueMacNotification(claimed[0], title, body)) {
+        process.stderr.write(`failproofai: found ${n} but could not queue a notification\n`);
+      } else {
+        delivered = true; // the durable queue owns delivery from here
+      }
+      if (delivered && !macNotifierInstalled()) {
+        // Queued, but nothing currently collects it. Keep the claim because the
+        // payload is durable and will be consumed when the LaunchAgent returns.
+        // Worth a line, because the immediate symptom is otherwise silence.
+        process.stderr.write(
+          `failproofai: found ${n}; the notifier is not installed, so nothing will show it ` +
+            `(run \`failproofai config\`)\n`,
+        );
+      }
+      return;
     }
-    return;
-  }
 
-  const outcome = await notifyDesktop(
-    title,
-    body,
-    // A stable id would let a repeat scan replace the previous bubble instead
-    // of stacking. We do not have one yet — the server assigns it and we would
-    // have to persist it — so a fresh notification is correct here, and it is
-    // bounded: at most one per distinct credential, ever.
-    0,
-  );
-  if (!outcome.ok) {
-    // stderr, so it lands in the journal beside the run it belongs to. Not a
-    // failure of the audit — but "we found a key and could not tell you" is
-    // exactly the sentence someone debugging this needs to find.
-    process.stderr.write(
-      `failproofai: found ${n} but could not raise a desktop notification (${outcome.reason})\n`,
+    const outcome = await notifyDesktop(
+      title,
+      body,
+      // A stable id would let a repeat scan replace the previous bubble instead
+      // of stacking. We do not have one yet — the server assigns it and we would
+      // have to persist it — so a fresh notification is correct here, and it is
+      // bounded: at most one per distinct credential, ever.
+      0,
     );
+    delivered = outcome.ok;
+    if (!outcome.ok) {
+      // stderr, so it lands in the journal beside the run it belongs to. Not a
+      // failure of the audit — but "we found a key and could not tell you" is
+      // exactly the sentence someone debugging this needs to find.
+      process.stderr.write(
+        `failproofai: found ${n} but could not raise a desktop notification (${outcome.reason})\n`,
+      );
+    }
+  } finally {
+    if (!delivered) releaseLeakNoticeClaims(claimed, undefined, "desktop");
   }
 }
 

package/src/audit/index.ts

@@ -19,7 +19,7 @@ import { severityForBuiltin } from "./features";
 import { findSecrets, flattenToolInput } from "./leak-scan";
 import { fingerprintSecret, fingerprintId } from "./leak-fingerprint";
 import { readLeakIdentity, readLeakRecord, writeLeakRecord } from "./leak-store";
-import { upsertFinding, describeMechanism } from "./leak-record";
+import { upsertFinding, describeMechanism, emptyRecord } from "./leak-record";
 import { shortenPaths } from "./redact-example";
 import { readCachedTranscript, writeCachedTranscriptResult } from "./cache";
 import { initReplay, replayEvent, restoreReplay } from "./replay";
@@ -37,6 +37,64 @@ import {
 
 const TRANSCRIPT_CONCURRENCY = 8;
 
+/**
+ * Raw transcript bytes allowed in flight at once.
+ *
+ * The concurrency above counts FILES, which is the wrong unit. `streamEventsFrom`
+ * returns an array — despite the name it materialises every event of a
+ * transcript into JS objects — and a 57 MB JSONL becomes several hundred MB of
+ * them. On a real 1.15 GB corpus, 7 files hold 224 MB and the largest is
+ * 57.5 MB, so eight workers could put a quarter of the corpus in memory
+ * simultaneously. That machine printed `Aborted(OOM)` 22 times in one run.
+ *
+ * This is NOT what fixed those lines, and the distinction is worth keeping
+ * honest: they were measured at ~22 per run, appear within the first two
+ * seconds, are unchanged by this budget at 48 MB or at 16 MB, and do not fail
+ * the run — its counts come back correct. Their source is still unidentified.
+ * This bounds a real and separate failure mode (eight of the seven largest
+ * files in flight at once); it should not be read as having fixed the other.
+ *
+ * 48 MB of raw input is the budget because the expansion factor from JSONL to
+ * parsed objects is roughly 5-10x, which keeps the peak inside a default heap
+ * with room for the eight small-file workers this is meant not to slow down.
+ * Chosen to bound memory, not to be exactly right: the failure it prevents is a
+ * crash, and the cost of being conservative is that one very large file scans
+ * alone for a moment.
+ */
+const TRANSCRIPT_BYTE_BUDGET = 48 * 1024 * 1024;
+
+/**
+ * Admission control by weight, so a worker waits for MEMORY as well as a slot.
+ *
+ * A file bigger than the whole budget is admitted alone rather than refused —
+ * otherwise the largest transcript on the machine could never be scanned, which
+ * is precisely the one most likely to hold something.
+ */
+class ByteGate {
+  private inFlight = 0;
+  private waiting: Array<() => void> = [];
+
+  constructor(private readonly budget: number) {}
+
+  async acquire(bytes: number): Promise<void> {
+    const want = Math.max(0, bytes);
+    while (this.inFlight > 0 && this.inFlight + want > this.budget) {
+      await new Promise<void>((resolve) => this.waiting.push(resolve));
+    }
+    this.inFlight += want;
+  }
+
+  release(bytes: number): void {
+    this.inFlight -= Math.max(0, bytes);
+    if (this.inFlight < 0) this.inFlight = 0;
+    // Wake everyone and let each re-test its own weight: a small task behind a
+    // large one should not be held by a queue position it does not need.
+    const waiters = this.waiting;
+    this.waiting = [];
+    for (const wake of waiters) wake();
+  }
+}
+
 /** Canonicalize a policy name to its short, qualified form for display
  *  (`failproofai/foo` → `foo`). */
 function shortPolicyName(name: string): string {
@@ -118,6 +176,50 @@ interface ScanOutcome {
   resumed: boolean;
 }
 
+const CREDENTIAL_RESEARCH_MARKERS: ReadonlyArray<RegExp> = [
+  /\b(?:secret|credential)[-_ ](?:scanner|detection|detector|pattern|regex|corpus)\b/i,
+  /\b(?:trufflehog|trufflesecurity|gitleaks|detect-secrets|secret-detection-rules)\b/i,
+  /\b(?:SECRET_PATTERNS|findSecrets|isDocsLiteral|leak-scan)\b/,
+  /\b(?:fixture|placeholder|synthetic|sample) (?:api )?(?:key|token|secret|credential)s?\b/i,
+  /\b(?:grep|rg|ripgrep|scan|hunt|search)\b[^\n]{0,240}\b(?:secret|credential|token)s?\b/i,
+];
+
+const CREDENTIAL_RESEARCH_PURPOSE =
+  /\b(?:hunt|scan|search|research|test)(?:ing)?\b[^\n]{0,80}\b(?:secret|credential|token)s?\b|\b(?:secret|credential|token)s?\b[^\n]{0,80}\b(?:scanner|detector|detection|research|fixtures?|corpus)\b/i;
+
+/**
+ * Deliberate secret-detector research is full of realistic fake credentials.
+ * Reporting those as leaks is the feedback loop that made one measured session
+ * contribute 455 of the 500 rows in its own audit.
+ *
+ * Require independent signals across tool INPUTS. Results are excluded from
+ * classification: a normal command can print hostile text, while commands and
+ * URLs state what the agent intentionally set out to inspect. Two signals keep
+ * an ordinary discussion that happens to say "secret scanner" from silencing a
+ * session; dedicated detector/test work reliably carries several.
+ */
+export function isCredentialResearchSession(
+  events: NormalizedToolEvent[],
+  sessionDescription?: string,
+): boolean {
+  if (sessionDescription && CREDENTIAL_RESEARCH_PURPOSE.test(sessionDescription)) return true;
+  const matched = new Set<number>();
+  let evidenceEvents = 0;
+  for (const event of events) {
+    const intent = flattenToolInput(event.toolInput);
+    let eventMatched = false;
+    for (let i = 0; i < CREDENTIAL_RESEARCH_MARKERS.length; i++) {
+      if (CREDENTIAL_RESEARCH_MARKERS[i].test(intent)) {
+        matched.add(i);
+        eventMatched = true;
+      }
+    }
+    if (eventMatched) evidenceEvents++;
+    if (matched.size >= 2 || evidenceEvents >= 3) return true;
+  }
+  return false;
+}
+
 async function scanOneTranscript(
   meta: TranscriptMetadata,
   resume?: { fromByte: number; detectorState: DetectorSessionState },
@@ -186,6 +288,8 @@ async function scanOneTranscript(
   // Capture the session's cwd from the first event that carried one — every
   // event in a single transcript shares the same cwd by construction.
   result.cwd = result.cwd || events[0].cwd || "";
+  const suppressLeakScan = isCredentialResearchSession(events, meta.sessionDescription);
+  if (suppressLeakScan) result.leakScanSuppressed = "credential-research";
 
   for (const event of events) {
     // The 8 behavioural detectors are switched off with the rest of the old
@@ -226,7 +330,7 @@ async function scanOneTranscript(
     // decision per policy, never the text that matched. Scanned separately so
     // the leak report can name WHICH key, and so detection can be tuned for
     // precision without dragging the redactor's recall down with it.
-    recordLeaks(result, event);
+    if (!suppressLeakScan) recordLeaks(result, event);
   }
 
   return { result, bytesScanned, detectorState: sessionState, resumed };
@@ -300,10 +404,19 @@ function leakSalt(): string | null {
  * human about. Never throws: a scan that finds leaks it cannot write down has
  * still found them, and the caller reports on the in-memory result either way.
  */
-function persistLeaks(perTranscript: TranscriptAuditResult[]): string[] {
+export function persistLeaks(perTranscript: TranscriptAuditResult[], replaceExisting: boolean): string[] {
   const fresh: string[] = [];
   try {
-    const record = readLeakRecord();
+    const previous = readLeakRecord();
+    const previousIds = new Set(previous.findings.map((f) => f.id));
+    // A successful all-history scan is authoritative. Rebuilding is what lets
+    // detector precision fixes remove findings they now reject; merging made
+    // every false positive live for 90 days even after the code was fixed.
+    // Scoped or incomplete scans still merge because absence outside their
+    // coverage says nothing.
+    const record = replaceExisting
+      ? emptyRecord(previous.salt, new Date().toISOString())
+      : previous;
     for (const t of perTranscript) {
       for (const leak of t.leaks ?? []) {
         const { isNew } = upsertFinding(record, {
@@ -322,7 +435,10 @@ function persistLeaks(perTranscript: TranscriptAuditResult[]): string[] {
             mechanism: describeMechanism(leak.toolName, leak.direction, leak.path),
           },
         });
-        if (isNew) fresh.push(leak.id);
+        // During an authoritative rebuild every insertion is new to the empty
+        // record, but only ids absent from the previous record are new to the
+        // HUMAN and eligible for a notification.
+        if (isNew && !previousIds.has(leak.id)) fresh.push(leak.id);
       }
     }
     writeLeakRecord(record);
@@ -351,7 +467,7 @@ function formatPolicyExample(_policyName: string, event: NormalizedToolEvent): s
  * came from the FIRST event in the file and the tail's came from the first
  * event after the offset, so the older one wins.
  */
-function mergeIncremental(
+export function mergeIncremental(
   cached: TranscriptAuditResult,
   tail: TranscriptAuditResult,
 ): TranscriptAuditResult {
@@ -365,6 +481,12 @@ function mergeIncremental(
     examplesByName: {},
     rangeByName: { ...cached.rangeByName },
   };
+  if (cached.leakScanSuppressed || tail.leakScanSuppressed) {
+    out.leakScanSuppressed = "credential-research";
+    out.leaks = [];
+  } else {
+    out.leaks = [...(cached.leaks ?? []), ...(tail.leaks ?? [])];
+  }
   for (const [name, list] of Object.entries(cached.examplesByName)) {
     out.examplesByName[name] = [...list];
   }
@@ -547,18 +669,22 @@ async function runAuditInner(opts: RunAuditOptions, startedAt: number): Promise<
 
   // 1. Discover transcripts across all selected CLIs.
   const allTranscripts: TranscriptMetadata[] = [];
+  let discoveryErrors = 0;
   for (const cli of clis) {
     const adapter = ADAPTERS[cli];
     let list: TranscriptMetadata[];
     try {
       list = await adapter.listTranscripts({ projects: opts.projects, sinceMs });
     } catch {
+      discoveryErrors++;
       continue; // adapter failures shouldn't kill the whole audit
     }
     allTranscripts.push(...list);
   }
 
-  // 2. Scan each transcript (cache-aware), 8 in parallel.
+  // 2. Scan each transcript (cache-aware), 8 at a time and within a memory
+  // budget — see TRANSCRIPT_BYTE_BUDGET for why a file count is the wrong unit.
+  const gate = new ByteGate(TRANSCRIPT_BYTE_BUDGET);
   let skipped = 0;
   let errors = 0;
   const tasks = allTranscripts.map((meta) => async (): Promise<TranscriptAuditResult> => {
@@ -572,6 +698,9 @@ async function runAuditInner(opts: RunAuditOptions, startedAt: number): Promise<
         : undefined;
       cachedPrefix = found?.kind === "resume" ? found.result : null;
     }
+    // Memory admission. Taken AFTER the cache check above, so a cache hit — the
+    // common case on a warm machine — never waits for a slot it does not use.
+    await gate.acquire(meta.sizeBytes);
     try {
       const scan = await scanOneTranscript(meta, resume);
       // A resumed scan produced hits for the TAIL only; the cached result holds
@@ -615,6 +744,11 @@ async function runAuditInner(opts: RunAuditOptions, startedAt: number): Promise<
         examplesByName: {},
         rangeByName: {},
       };
+    } finally {
+      // Released on every path, including the error one — a task that threw
+      // still freed its memory, and holding its weight would shrink the budget
+      // permanently over a long scan until nothing could be admitted at all.
+      gate.release(meta.sizeBytes);
     }
   });
 
@@ -652,7 +786,14 @@ async function runAuditInner(opts: RunAuditOptions, startedAt: number): Promise<
   // not alert again however many fresh sightings it accumulates, and a
   // credential seen for the first time must alert even though its rule has
   // fired a thousand times before.
-  const newFindingIds = persistLeaks(perTranscript);
+  const coversAllHistory =
+    opts.clis === undefined &&
+    opts.projects === undefined &&
+    opts.since === undefined &&
+    discoveryErrors === 0 &&
+    errors === 0 &&
+    skipped === 0;
+  const newFindingIds = persistLeaks(perTranscript, coversAllHistory);
 
   const auditResult: AuditResult = {
     version: 2,

package/src/audit/leak-notice.ts

@@ -36,7 +36,7 @@ import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync, rmSync } f
 import { resolve } from "node:path";
 
 import { auditDir } from "../hooks/fp-home";
-import { readLeakRecord, activeFindings } from "./leak-store";
+import { readLeakRecord, activeFindings, readLeakIdentity } from "./leak-store";
 import { isFindingId } from "./leak-fingerprint";
 
 /**
@@ -135,6 +135,25 @@ export function markLeakNoticeDelivered(
   return won;
 }
 
+/** Release claims this process won when delivery failed, so the next scheduled
+ * run retries instead of turning a transient missing desktop into permanent
+ * silence. Only validated ids in the requested channel are touched. */
+export function releaseLeakNoticeClaims(
+  ids: string[],
+  home?: string,
+  channel: NoticeChannel = "cli",
+): void {
+  try {
+    const dir = NOTICE_DIR(home, channel);
+    for (const id of ids) {
+      if (!isFindingId(id)) continue;
+      rmSync(resolve(dir, id), { force: true });
+    }
+  } catch {
+    // Retry bookkeeping must never turn a completed audit into a failure.
+  }
+}
+
 /** Drop markers for findings that no longer exist, and very old ones. */
 export function pruneNoticeMarkers(home?: string, nowMs = Date.now()): void {
   try {
@@ -159,3 +178,82 @@ export function pruneNoticeMarkers(home?: string, nowMs = Date.now()): void {
     // Housekeeping only.
   }
 }
+
+/**
+ * Should this session's agent tell the user about unviewed credentials?
+ *
+ * ## Why this is not the per-finding claim used for the desktop banner
+ *
+ * The per-finding marker answers "have we emitted this once?" — and emitting is
+ * not the same as arriving. Twice in one day it recorded every finding as
+ * delivered while the user saw nothing: once because the notice was attached to
+ * an event whose channel the host ignores (`SessionStart` takes
+ * `additionalContext`, not `systemMessage`), and once because hooks were
+ * disabled in the project under test. Neither is detectable from in here, and
+ * both were permanent — a claimed finding is never retried.
+ *
+ * So the in-CLI notice keys on the USER's action instead of on ours. It shows
+ * while findings exist that are newer than the last time the report was
+ * actually opened, and it stops when they open it. A dropped notice costs one
+ * session's silence rather than the alert; the only thing that silences it for
+ * good is the outcome we wanted anyway.
+ *
+ * Bounded by a per-SESSION marker so a long session gets one line, not one per
+ * turn. Sessions are cheap and few; findings are many and long-lived.
+ */
+export function sessionNoticePending(sessionId: string, home?: string): PendingNotice {
+  try {
+    if (!sessionId || !/^[\w.:-]{1,200}$/.test(sessionId)) return { ids: [], count: 0 };
+    const dir = resolve(auditDir(home), "notified-sessions");
+    if (existsSync(resolve(dir, sessionId))) return { ids: [], count: 0 };
+
+    const findings = activeFindings(readLeakRecord(home), home);
+    if (findings.length === 0) return { ids: [], count: 0 };
+
+    // Only what the user has not already looked at. `firstSeen`, not
+    // `lastSeen`: re-encountering a credential the user has already reviewed is
+    // not news, however recently the scan tripped over it again.
+    const viewedAt = readLeakIdentity(home).reportViewedAt ?? 0;
+    const unviewed = findings.filter((f) => {
+      const seen = Date.parse(f.firstSeen);
+      return !Number.isFinite(seen) || seen > viewedAt;
+    });
+    return { ids: unviewed.map((f) => f.id), count: unviewed.length };
+  } catch {
+    return { ids: [], count: 0 };
+  }
+}
+
+/**
+ * Claim this session, so the notice appears once rather than every turn.
+ *
+ * Returns whether this caller won. O_EXCL again, for the same reason as the
+ * per-finding markers: several agents run in one project at once.
+ */
+export function markSessionNoticed(sessionId: string, home?: string): boolean {
+  try {
+    if (!sessionId || !/^[\w.:-]{1,200}$/.test(sessionId)) return false;
+    const dir = resolve(auditDir(home), "notified-sessions");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(resolve(dir, sessionId), "", { flag: "wx", mode: 0o600 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Session markers outlive nothing useful — a session id never recurs. */
+export function pruneSessionMarkers(home?: string, nowMs = Date.now()): void {
+  try {
+    const dir = resolve(auditDir(home), "notified-sessions");
+    if (!existsSync(dir)) return;
+    for (const name of readdirSync(dir)) {
+      const path = resolve(dir, name);
+      try {
+        if (nowMs - statSync(path).mtimeMs > 30 * 86_400_000) rmSync(path, { force: true });
+      } catch { /* raced */ }
+    }
+  } catch {
+    // Housekeeping only.
+  }
+}