failproofai 1.0.3 → 1.0.4-beta.2

package/lib/auth/api-server-client.ts

@@ -253,6 +253,34 @@ export interface AuditReportBody {
     last_seen?: string;
     examples: string[];
   }[];
+  /**
+   * Credentials this machine found in its own transcripts.
+   *
+   * Optional on the wire, so a CLI newer than the api-server sends a field the
+   * server ignores rather than failing the whole digest — the harmful counts
+   * are the older half of the contract and must keep arriving either way.
+   *
+   * Every field here is a mask, a label, a length or a location. There is no
+   * shape of this object that carries a secret, because the record it is built
+   * from never stores one: `recordLeaks` fingerprints at detection time and
+   * keeps only the masked rendering.
+   */
+  leaks?: {
+    id: string;
+    display: string;
+    label: string;
+    length: number;
+    attributed: boolean;
+    name: string | null;
+    confidence: string;
+    first_seen: string;
+    last_seen: string;
+    occurrences: number;
+    cli: string;
+    project: string;
+    mechanism: string;
+    direction: "input" | "result";
+  }[];
 }
 
 export interface AuditReportResult {

package/lib/claude-sessions.ts

@@ -4,8 +4,14 @@
  * Claude stores transcripts at:
  *   <CLAUDE_PROJECTS_PATH>/<encoded-cwd>/<sessionId>.jsonl
  *
- * Subagent transcripts (when a session spawned subagents) live alongside:
+ * Subagent transcripts (when a session spawned subagents) live alongside, in two
+ * shapes — a direct child, and one nested per workflow run:
  *   <CLAUDE_PROJECTS_PATH>/<encoded-cwd>/<sessionId>/subagents/<agentId>.jsonl
+ *   <CLAUDE_PROJECTS_PATH>/<encoded-cwd>/<sessionId>/subagents/workflows/<runId>/<agentId>.jsonl
+ *
+ * Everything below `subagents/` is walked to a bounded depth rather than one
+ * level, because the second shape arrived after this module was written and the
+ * miss was most of the corpus. See `collectSubagentTranscripts`.
  *
  * The parser for these files lives in `lib/log-entries.ts` (`parseLogContent`,
  * `parseSessionLog`). This module exposes discovery only — the audit pipeline
@@ -70,6 +76,99 @@ export function listClaudeProjects(): ClaudeProjectFolder[] {
 /** Lists every JSONL transcript under one Claude project folder, including
  *  subagent transcripts under `<sessionId>/subagents/`. Returns [] on missing
  *  or unreadable paths. */
+/**
+ * Depth of nesting allowed below `subagents/`.
+ *
+ * The two shapes that exist today need 0 and 2 (`<agent>.jsonl` and
+ * `workflows/<runId>/<agent>.jsonl`). The cap is here so an unexpected layout —
+ * or a symlink cycle a future Claude build introduces — costs a bounded walk
+ * rather than an audit that never returns, and it is deliberately loose enough
+ * that a third shape lands inside it without another release.
+ */
+const MAX_SUBAGENT_DEPTH = 5;
+
+/**
+ * Collect every `.jsonl` beneath a session's `subagents/` directory.
+ *
+ * This used to read only the DIRECT children of `subagents/`, which was correct
+ * for the layout Claude shipped when it was written and silently wrong the day
+ * workflow runs started nesting their agents one level further down. On a
+ * machine that uses them the miss is most of the corpus: 1,839 transcripts on
+ * disk, 1,741 under `subagents/`, and 1,679 of those inside
+ * `subagents/workflows/<runId>/` — so the audit was walking 160 files, 8.7% of
+ * the evidence, and reporting the result as though it had read everything.
+ *
+ * ## Session ids come from the relative path, not the basename
+ *
+ * Every workflow run writes a `journal.jsonl` beside its agents, so basenames
+ * are NOT unique below this directory — 1,741 files share 1,613 distinct names
+ * on the machine this was found on. A basename id would collide those 128 files
+ * onto ~one row each, and `sessionId` is what the cache, the per-session
+ * detector state and the example attribution are keyed by, so the collision
+ * would silently merge unrelated sessions rather than fail.
+ *
+ * Nor is the path below `subagents/` unique on its own. A workflow run id is
+ * reused when its session is resumed, so `wf_3d609e92-a38/journal.jsonl` exists
+ * under two different parent sessions in the same project — found by asserting
+ * uniqueness over the real corpus, not by reasoning about it.
+ *
+ * The id is therefore the PARENT SESSION id followed by the path relative to
+ * `subagents/`, minus the extension, joined with `__`:
+ * `<parentUuid>__workflows__wf_123__agent-abc`. That is a filesystem path
+ * within the project, so it is unique by construction rather than by argument,
+ * and it names the session the subagent belongs to. `__` is safe as the joiner
+ * because no id Claude generates contains one — verified against 1,741 real
+ * files, zero hits. Top-level session ids are untouched.
+ *
+ * Symlinks are not followed. Nothing in the layout uses them, and following one
+ * is how a directory walk turns into an infinite loop.
+ */
+function collectSubagentTranscripts(
+  dir: string,
+  relPrefix: string,
+  project: ClaudeProjectFolder,
+  out: ClaudeTranscriptFile[],
+  depth: number,
+): void {
+  if (depth > MAX_SUBAGENT_DEPTH) return;
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) continue;
+    if (entry.isDirectory()) {
+      collectSubagentTranscripts(
+        join(dir, entry.name),
+        relPrefix ? `${relPrefix}__${entry.name}` : entry.name,
+        project,
+        out,
+        depth + 1,
+      );
+      continue;
+    }
+    if (!entry.isFile() || !entry.name.endsWith(".jsonl")) continue;
+    const stem = entry.name.slice(0, -".jsonl".length);
+    const transcriptPath = join(dir, entry.name);
+    try {
+      const s = statSync(transcriptPath);
+      out.push({
+        projectName: project.name,
+        cwd: project.cwd,
+        sessionId: relPrefix ? `${relPrefix}__${stem}` : stem,
+        transcriptPath,
+        mtimeMs: s.mtimeMs,
+        sizeBytes: s.size,
+        isSubagent: true,
+      });
+    } catch {
+      // unreadable — skip
+    }
+  }
+}
+
 export function listClaudeTranscripts(project: ClaudeProjectFolder): ClaudeTranscriptFile[] {
   const out: ClaudeTranscriptFile[] = [];
   let entries: import("node:fs").Dirent[];
@@ -99,34 +198,9 @@ export function listClaudeTranscripts(project: ClaudeProjectFolder): ClaudeTrans
         // unreadable — skip
       }
     } else if (entry.isDirectory() && UUID_RE.test(entry.name)) {
-      // Subagent transcripts at <sessionId>/subagents/<agentId>.jsonl
       const subDir = join(project.path, entry.name, "subagents");
       if (!existsSync(subDir)) continue;
-      let subEntries: import("node:fs").Dirent[];
-      try {
-        subEntries = readdirSync(subDir, { withFileTypes: true });
-      } catch {
-        continue;
-      }
-      for (const sub of subEntries) {
-        if (!sub.isFile() || !sub.name.endsWith(".jsonl")) continue;
-        const agentId = sub.name.slice(0, -".jsonl".length);
-        const transcriptPath = join(subDir, sub.name);
-        try {
-          const s = statSync(transcriptPath);
-          out.push({
-            projectName: project.name,
-            cwd: project.cwd,
-            sessionId: agentId,
-            transcriptPath,
-            mtimeMs: s.mtimeMs,
-            sizeBytes: s.size,
-            isSubagent: true,
-          });
-        } catch {
-          // unreadable — skip
-        }
-      }
+      collectSubagentTranscripts(subDir, entry.name, project, out, 0);
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "failproofai",
-  "version": "1.0.3",
+  "version": "1.0.4-beta.2",
   "description": "Observability and enforcement for AI agent harnesses. 39 built-in policies hooked into 12 of them — Claude Code, Codex, Cursor, Hermes, OpenClaw and more — blocking the tool call before it runs. Local dashboard included, no account needed.",
   "bin": {
     "failproofai": "./dist/cli.mjs",
@@ -80,14 +80,14 @@
     "access": "public"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.120.0",
+    "@anthropic-ai/sdk": "^0.123.0",
     "@mdx-js/mdx": "^3.1.1",
     "@tailwindcss/postcss": "^4.3.1",
     "@tanstack/react-virtual": "^3.14.10",
     "@testing-library/jest-dom": "^7.0.0",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.5",
-    "@types/node": "26.2.0",
+    "@types/node": "26.4.1",
     "@types/react": "19.2.18",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.1.0",
@@ -102,7 +102,7 @@
     "tailwind-merge": "^3.4.0",
     "tailwindcss": "^4.3.1",
     "typescript": "6.0.3",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.0"
   },
   "dependencies": {
     "html-to-image": "^1.11.13",
@@ -117,18 +117,19 @@
     "vite": "8.0.16",
     "undici": "7.29.0",
     "brace-expansion": "5.0.9",
-    "sharp": "0.35.0"
+    "sharp": "0.35.0",
+    "browserslist": "4.28.8"
   },
   "optionalDependencies": {
-    "@failproofai/failproofaid-linux-x64": "1.0.3",
-    "@failproofai/failproofaid-linux-arm64": "1.0.3",
-    "@failproofai/failproofaid-darwin-x64": "1.0.3",
-    "@failproofai/failproofaid-darwin-arm64": "1.0.3"
+    "@failproofai/failproofaid-linux-x64": "1.0.4-beta.2",
+    "@failproofai/failproofaid-linux-arm64": "1.0.4-beta.2",
+    "@failproofai/failproofaid-darwin-x64": "1.0.4-beta.2",
+    "@failproofai/failproofaid-darwin-arm64": "1.0.4-beta.2"
   },
   "failproofaidBinaries": {
-    "linux-x64": "2a4164e88792f2cd8616868eb63a52011e110b8b13643e1082ad3af982730226",
-    "linux-arm64": "c995f896183ba54b596535687b94bfd52efaa56736a36016d2de987bccdaa810",
-    "darwin-x64": "a56c871ce0d460683a2e57cb6eed2f91a329c2f03889612fef62191fcb57868a",
-    "darwin-arm64": "dab3246a917dc32869dfb36b5b682beaa87330c8cd2797027c9b9adc4084ceab"
+    "linux-x64": "3039575242ff240c68a79c4ebd4e0e35e865da99c6d8a46d1a17b2d7962cb47b",
+    "linux-arm64": "02fe993dca0faccb528c48472ca1d637274c562992ba7da1bc8d439103dbcc13",
+    "darwin-x64": "2be5a422007a773253611f24f2ad9e2a301f075392ed7bc2dc0f6354d3186696",
+    "darwin-arm64": "5882a4acd7317289346934290ac8277ca79edadb009e284c9fc0b23b74d321d7"
   }
 }

package/pi-extension/index.ts

@@ -25,7 +25,7 @@
  * spawns extensions with an undefined cwd contract, so paths are resolved
  * relative to this file via `import.meta.url`, NOT process.cwd().
  */
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { resolve, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { existsSync, readdirSync, statSync } from "node:fs";
@@ -64,6 +64,44 @@ function debug(msg: string): void {
   }
 }
 
+/**
+ * Forward an event whose VERDICT NOBODY READS, without blocking Pi.
+ *
+ * `callPolicy` is `spawnSync`, and Pi awaits its handlers serially on the
+ * startup path — so a `session_start` forward froze the whole TUI for as long
+ * as the subprocess took (measured floor 1.0-1.6s just to boot the binary,
+ * ceiling the full 60s timeout) and then threw the answer away. Three call
+ * sites are like that by design: `session_start`, `tool_result` and
+ * `session_shutdown` forward for the activity feed and for session-id
+ * continuity, and Pi cannot act on their return in any case
+ * (`ToolResultEventResult` has no `block`; the other two have no Result type
+ * at all).
+ *
+ * So they get a detached `spawn` instead. The event still reaches failproofai,
+ * the policies still run and still log, and Pi keeps rendering. Deliberately
+ * NOT used for `tool_call`, `user_bash`, `input` or `agent_end`: those four
+ * consume the decision, and blocking is what enforcement means.
+ */
+function forwardPolicy(eventName: string, payload: unknown): void {
+  const { cmd, args } = resolveSpawn();
+  debug(`forwardPolicy (detached) event=${eventName} cmd=${cmd}`);
+  try {
+    const child = spawn(cmd, [...args, "--hook", eventName, "--cli", "pi"], {
+      stdio: ["pipe", "ignore", "ignore"],
+      detached: false,
+    });
+    // A child that outlives its parent's interest must not keep the event loop
+    // alive, or Pi cannot exit until the subprocess does.
+    child.unref();
+    // EPIPE if the child died before stdin was consumed — fail-open, silently.
+    child.on("error", (err) => debug(`forward error ${err.message}`));
+    child.stdin.on("error", () => {});
+    child.stdin.end(JSON.stringify(payload));
+  } catch (err) {
+    debug(`FORWARD EXCEPTION ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
 function callPolicy(eventName: string, payload: unknown): { block: boolean; reason: string } {
   const { cmd, args } = resolveSpawn();
   debug(`callPolicy event=${eventName} cmd=${cmd}`);
@@ -417,7 +455,7 @@ export default function failproofaiBridge(pi: PiExtensionApi) {
   // need session_id continuity see the metadata.
   pi.on("session_start", (event: unknown): unknown => {
     const e = event as PiSessionStartEvent;
-    callPolicy("session_start", {
+    forwardPolicy("session_start", {
       session_id: resolveSessionId(e.sessionId, resolveCwd(e.cwd)),
       cwd: resolveCwd(e.cwd),
       reason: e.reason,
@@ -435,7 +473,7 @@ export default function failproofaiBridge(pi: PiExtensionApi) {
   pi.on("tool_result", (event: unknown): unknown => {
     const e = event as PiToolResultEvent;
     const canonicalTool = canonicalizeToolName(e.toolName);
-    callPolicy("tool_result", {
+    forwardPolicy("tool_result", {
       tool_name: canonicalTool,
       tool_input: canonicalizeToolInput(canonicalTool, e.input) ?? {},
       tool_response: { content: e.content, isError: e.isError },
@@ -500,7 +538,7 @@ export default function failproofaiBridge(pi: PiExtensionApi) {
   pi.on("session_shutdown", (event: unknown): unknown => {
     const e = event as PiSessionShutdownEvent;
     const cwd = resolveCwd(e.cwd);
-    callPolicy("session_shutdown", {
+    forwardPolicy("session_shutdown", {
       session_id: resolveSessionId(e.sessionId, cwd),
       cwd,
       reason: e.reason,

package/scripts/changelog-open.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""Open a stub CHANGELOG section for the version a release just moved to.
+
+    changelog-open.py <changelog> <version> <published> [<date>]
+
+The companion to `changelog-section.py`, which REFUSES a release whose version has
+no section. Both PyPI publish workflows call this from `bump`, in the same commit
+that moves `_version.py`, so the two files can never disagree about which version
+`main` is open on.
+
+WHY THIS EXISTS AS AUTOMATION RATHER THAN A RULE. `bump` used to move the version
+alone, which left `main` on a version with no section — the exact state
+`changelog-section.py` refuses at release time and that
+`__tests__/ci/python-version-pipeline.test.ts` asserts against. Bump commits carry
+a skip-ci marker, so nothing went red until the next unrelated PR ran CI and came
+back failing for a reason that had nothing to do with it. That happened at the
+first publish (repaired by hand in #755, which named the recurrence and left it),
+and again at the second. It is not a rule a maintainer can be asked to remember:
+the commit that creates the state is written by a workflow, not a person.
+
+IDEMPOTENT ON PURPOSE. A re-run of `bump` against a `main` that already carries
+the section must be a no-op, not a second heading — two `## <version>` headings
+would put only the first one's body in the GitHub Release, silently. The version
+is matched with the same trailing word boundary the extractor uses, so `0.0.1b1`
+is not answered by `0.0.1b10`.
+
+The stub is deliberately non-empty prose, not a bare heading: an empty section
+fails `changelog-section.py` just as a missing one does, so a stub that could not
+release would only move the failure.
+
+Stdlib only, same reason as its two siblings: it runs in a job that installs
+nothing precisely because it is handed a token.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from datetime import datetime, timezone
+
+# The heading grammar CLAUDE.md fixes for the root changelog and both per-package
+# files follow — an EM DASH, and a date. Matched with `\b` after the version so a
+# request to open `0.0.1b1` is not satisfied by an existing `0.0.1b10`.
+_HEADING = "## {version} — {date}"
+
+#: What lands under the new heading. Non-empty by construction (see the module
+#: docstring), and it says who wrote it so the next reader does not go looking for
+#: the human who did not.
+_STUB = """Open for the next release. `{published}` published on {date} and the `bump` job
+moved the version here automatically; nothing has landed against `{version}` yet.
+Add entries as changes merge — this section becomes the GitHub Release body when
+it ships.
+"""
+
+
+class ChangelogError(Exception):
+    """A message a maintainer can act on, printed without a traceback."""
+
+
+def has_section(text: str, version: str) -> bool:
+    return re.search(rf"^##[ \t]+{re.escape(version)}\b", text, re.MULTILINE) is not None
+
+
+def open_section(text: str, version: str, published: str, date: str) -> str:
+    """`text` with a stub section for `version` above the topmost existing one."""
+    if has_section(text, version):
+        return text
+
+    block = _HEADING.format(version=version, date=date) + "\n\n" + _STUB.format(
+        published=published, version=version, date=date
+    )
+
+    # Above the newest existing section, never at the end: the file is
+    # reverse-chronological, and its preamble (title, and the grammar note the
+    # extractor depends on) sits above the first heading and must stay there.
+    first = re.search(r"^##[ \t]", text, re.MULTILINE)
+    if first:
+        return text[: first.start()] + block + "\n" + text[first.start() :]
+
+    # No sections yet — the first release off a fresh file. Keep the preamble and
+    # append, with exactly one blank line between.
+    return text.rstrip("\n") + "\n\n" + block
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 4:
+        print(__doc__ or "", file=sys.stderr)
+        return 2
+    path, version, published = argv[1], argv[2], argv[3]
+    date = argv[4] if len(argv) >= 5 else datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    if not re.fullmatch(r"\d{4}-\d{2}-\d{2}", date):
+        raise ChangelogError(f"'{date}' is not a YYYY-MM-DD date")
+
+    try:
+        with open(path, encoding="utf-8") as handle:
+            text = handle.read()
+    except OSError as exc:
+        raise ChangelogError(f"cannot read {path}: {exc}") from exc
+
+    if has_section(text, version):
+        print(f"{path} already has a '## {version}' section — nothing to open.")
+        return 0
+
+    with open(path, "w", encoding="utf-8") as handle:
+        handle.write(open_section(text, version, published, date))
+    print(f"opened '## {version} — {date}' in {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main(sys.argv))
+    except ChangelogError as error:
+        print(f"error: {error}", file=sys.stderr)
+        raise SystemExit(1) from None

package/src/audit/cli.ts

@@ -35,6 +35,10 @@ import { getInstanceId } from "../../lib/telemetry-id";
 import { sanitizeErrorMessage } from "../../lib/telemetry-sanitize";
 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 { readConfig } from "../hooks/fp-config";
 import { brandAnsi, ANSI_RESET, ANSI_BOLD, ANSI_DIM, helpScreen, helpOptsFor } from "../hooks/tui";
 import { version } from "../../package.json";
 
@@ -106,6 +110,12 @@ export function helpText(): string {
             // is not a flag anybody can read or copy.
             ["--email <address>", "With --schedule, skips the sign-in prompt."],
             ["--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
+            // decisions, and nobody silencing a banner should have to re-state
+            // their schedule to do it.
+            ["--notify", "Show a desktop notification when a scan finds a credential. On by default."],
+            ["--no-notify", "Stop those notifications. Scans and the digest are unaffected."],
             ["--status", "Whether scheduling is on, where reports go, the daemon's state, and when the next scan is due."],
             ["-h, --help", "Show this help."],
           ],
@@ -334,6 +344,115 @@ function heldByLine(held: AuditLockInfo | null): string {
   return `another audit is already running (pid ${held.pid}, started by ${held.source} ${ageS}s ago)`;
 }
 
+/**
+ * Raise a desktop banner for credentials this scan found and nothing has
+ * announced yet.
+ *
+ * Scheduled runs only, and the reason is the same one that keeps `reportHarm`
+ * here: an interactive `failproofai audit` prints its findings to a person who
+ * is already looking at them, so a banner on top is noise. The scheduled run is
+ * the one with nobody watching, which is exactly when a notification is the
+ * only thing that reaches anyone.
+ *
+ * Every failure is swallowed on purpose. This is an announcement about a
+ * completed scan, not part of the scan: a machine with no desktop, a locked
+ * session, a bus that hung — none of those make the audit itself a failure, and
+ * turning a good scan into exit 1 would make the scheduler back off from
+ * running the thing that actually matters.
+ */
+async function announceLeaksOnDesktop(result: AuditResult): Promise<void> {
+  try {
+    await announceLeaksOrThrow(result);
+  } catch (err) {
+    // The catch is not decoration. `notifyDesktop` documents that it never
+    // throws, but it is doing socket I/O, and so are the config read and the
+    // marker write beside it — depending on three modules' promises to keep a
+    // completed scan from reporting failure is a dependency this does not need
+    // to have.
+    process.stderr.write(
+      `failproofai: could not announce a leak on the desktop: ` +
+        `${err instanceof Error ? err.message : String(err)}\n`,
+    );
+  }
+}
+
+async function announceLeaksOrThrow(result: AuditResult): Promise<void> {
+  const ids = result.newLeakIds ?? [];
+  if (ids.length === 0) return;
+  // Read at fire time, not at scan time: the switch answers "should this
+  // interrupt me", and it is the user's most recent answer that counts.
+  if (!readConfig().audit.notify) return;
+
+  // Claimed BEFORE the call goes out, and in the desktop channel only. Before,
+  // because a process that dies mid-notify would otherwise re-announce the same
+  // finding on every scheduled run forever; desktop-only, because a banner the
+  // user may never have seen must not also silence the in-session notice.
+  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.
+  //
+  // 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`,
+      );
+    }
+    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`,
+    );
+  }
+}
+
 // ── Headless (scheduled) audit ───────────────────────────────────────────────
 
 /**
@@ -404,6 +523,11 @@ export async function runScheduledAudit(): Promise<number> {
         `${num(result.transcripts.scanned)} sessions, ${num(result.totals.hits)} hits\n`,
     );
 
+    // Tell whoever owns this machine, on the machine, before anything is sent
+    // anywhere. Local first: this is the channel that works with no account, no
+    // email and no network, which describes most users.
+    await announceLeaksOnDesktop(result);
+
     // Report harmful findings upstream, if the user switched emailed reports on.
     //
     // AFTER the dashboard cache is written and AFTER the success line, because
@@ -552,6 +676,16 @@ export async function runAuditCli(args: string[]): Promise<void> {
     process.exit(0);
   }
 
+  for (const [flag, enable] of [["--notify", true], ["--no-notify", false]] as const) {
+    if (args.includes(flag)) {
+      const extra = args.find((a) => a !== flag);
+      if (extra) die(`\`audit ${flag}\` takes no other arguments (got: ${extra}).`);
+      const { runNotifyToggle } = await import("./schedule-cli");
+      runNotifyToggle(enable);
+      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}).`);