failproofai 1.0.4-beta.1 → 1.0.4-beta.4

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/cache.ts

@@ -14,6 +14,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, openSync
 import { join } from "node:path";
 import { BUILTIN_POLICIES } from "../hooks/builtin-policies";
 import { AUDIT_DETECTORS } from "./detectors";
+import { LEAK_SCAN_VERSION } from "./leak-scan";
 import type { TranscriptAuditResult, DetectorSessionState } from "./types";
 import { auditCacheDir } from "../hooks/fp-home";
 
@@ -162,6 +163,9 @@ interface CacheEntry {
   sizeBytes: number;
   engineVersion: string;
   detectorVersion: string;
+  /** Separate because leak detection is neither a builtin policy nor one of
+   * the behavioural AUDIT_DETECTORS hashed above. */
+  leakScanVersion: number;
   result: TranscriptAuditResult;
   /**
    * How far into the file the recorded result actually accounts for, at a LINE
@@ -269,6 +273,7 @@ export function readCachedTranscript(
     if (entry.schemaVersion !== CACHE_SCHEMA_VERSION) return null;
     if (entry.engineVersion !== getEngineVersion()) return null;
     if (entry.detectorVersion !== getDetectorVersion()) return null;
+    if (entry.leakScanVersion !== LEAK_SCAN_VERSION) return null;
     // Number.isFinite (not typeof) so a malformed JSON `Infinity` /
     // `NaN` is rejected — those would otherwise bypass the TTL check
     // and pin a stale entry as valid forever.
@@ -332,6 +337,7 @@ export function writeCachedTranscriptResult(
       sizeBytes,
       engineVersion: getEngineVersion(),
       detectorVersion: getDetectorVersion(),
+      leakScanVersion: LEAK_SCAN_VERSION,
       result,
     };
     if (resume && resume.bytesScanned > 0) {

package/src/audit/cli-adapters/claude.ts

@@ -6,6 +6,7 @@
  * parses each via lib/log-entries.ts.
  */
 import { readFile, open, type FileHandle } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import {
   listClaudeProjects,
   listClaudeTranscripts,
@@ -40,6 +41,17 @@ export async function listClaudeTranscriptMetadata(
     }
     for (const t of transcripts) {
       if (t.mtimeMs < sinceMs) continue;
+      let sessionDescription: string | undefined;
+      if (t.isSubagent) {
+        try {
+          const meta = JSON.parse(
+            readFileSync(t.transcriptPath.replace(/\.jsonl$/, ".meta.json"), "utf8"),
+          ) as { description?: unknown };
+          if (typeof meta.description === "string") sessionDescription = meta.description;
+        } catch {
+          // Sidecars are optional (journal transcripts do not have one).
+        }
+      }
       out.push({
         cli: "claude",
         projectName: project.name,
@@ -47,6 +59,7 @@ export async function listClaudeTranscriptMetadata(
         transcriptPath: t.transcriptPath,
         mtimeMs: t.mtimeMs,
         sizeBytes: t.sizeBytes,
+        sessionDescription,
       });
     }
   }

package/src/audit/cli-adapters/index.ts

@@ -23,10 +23,6 @@ import { listFactoryTranscriptMetadata, streamFactoryEvents } from "./factory";
 import { listAntigravityTranscriptMetadata, streamAntigravityEvents } from "./antigravity";
 import { listDevinTranscriptMetadata, streamDevinEvents } from "./devin";
 import { listGooseTranscriptMetadata, streamGooseEvents } from "./goose";
-import { listGrokTranscriptMetadata, streamGrokEvents } from "./grok";
-import { listQwenTranscriptMetadata, streamQwenEvents } from "./qwen";
-import { listOriTranscriptMetadata, streamOriEvents } from "./ori";
-import { listClineTranscriptMetadata, streamClineEvents } from "./cline";
 
 export type { ListOpts };
 
@@ -127,26 +123,6 @@ export const ADAPTERS: Record<IntegrationType, CliAdapter> = {
     listTranscripts: listGooseTranscriptMetadata,
     streamEvents: streamGooseEvents,
   },
-  grok: {
-    cli: "grok",
-    listTranscripts: listGrokTranscriptMetadata,
-    streamEvents: streamGrokEvents,
-  },
-  qwen: {
-    cli: "qwen",
-    listTranscripts: listQwenTranscriptMetadata,
-    streamEvents: streamQwenEvents,
-  },
-  ori: {
-    cli: "ori",
-    listTranscripts: listOriTranscriptMetadata,
-    streamEvents: streamOriEvents,
-  },
-  cline: {
-    cli: "cline",
-    listTranscripts: listClineTranscriptMetadata,
-    streamEvents: streamClineEvents,
-  },
 };
 
 export function getAdapter(cli: IntegrationType): CliAdapter {

package/src/audit/cli-login.ts

@@ -173,7 +173,10 @@ export async function ensureSignedIn(preset?: string): Promise<EnsureSignedIn> {
     throw new LoginError(
       "Signing in needs an interactive terminal, and this one is not.\n" +
         "Run `failproofai audit --schedule` from a shell you are sitting at,\n" +
-        "or sign in from the dashboard — both write the same session file.",
+        "or sign in from the dashboard — both write the same session file.\n" +
+        "\n" +
+        "`--email` does not avoid this: it fills in the address so you are not\n" +
+        "asked for it, but a one-time code is still sent there for you to paste.",
     );
   }
 

package/src/audit/cli.ts

@@ -35,6 +35,12 @@ 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, 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";
 
@@ -92,26 +98,36 @@ 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
+            // 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."],
           ],
         },
       ],
-      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),
   );
@@ -199,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;
@@ -334,6 +362,122 @@ 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;
+
+  // 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. 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;
+    }
+
+    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");
+  }
+}
+
 // ── Headless (scheduled) audit ───────────────────────────────────────────────
 
 /**
@@ -404,6 +548,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 +701,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}).`);