failproofai 0.0.10 → 0.0.11-beta.2

package/src/audit/report.ts

@@ -0,0 +1,349 @@
+/**
+ * Output renderers for `failproofai audit`:
+ *   • formatText      — ANSI table to stdout (GTM-oriented "moment of truth")
+ *   • formatMarkdown  — shareable sectioned report written to a file
+ *   • formatJson      — machine-readable
+ *
+ * The text renderer is the user's first impression of the audit. It leads
+ * with a headline-box, splits findings into "already protected" vs "slipping
+ * through" so the conversion ask is obvious, and ends with a copy-pasteable
+ * install command + report path + star link.
+ */
+import type { AuditCount, AuditResult, RunAuditOptions } from "./types";
+
+const ANSI = {
+  reset: "\x1B[0m",
+  dim: "\x1B[2m",
+  bold: "\x1B[1m",
+  red: "\x1B[31m",
+  yellow: "\x1B[33m",
+  green: "\x1B[32m",
+  cyan: "\x1B[36m",
+  magenta: "\x1B[35m",
+};
+
+/** Honor https://no-color.org / NO_COLOR=1 and FORCE_COLOR=0 by stripping all
+ *  ANSI sequences from the final output. Detected once per renderer call. */
+function noColorEnabled(): boolean {
+  if (process.env.NO_COLOR && process.env.NO_COLOR !== "") return true;
+  if (process.env.FORCE_COLOR === "0") return true;
+  return false;
+}
+
+function stripAnsi(s: string): string {
+  // eslint-disable-next-line no-control-regex
+  return s.replace(/\x1B\[[0-9;]*m/g, "");
+}
+
+/** Human-readable "time ago" — "30m ago", "2h ago", "3d ago", "2w ago".
+ *  Returns "just now" for <1 minute. */
+function formatTimeAgo(iso: string | undefined): string {
+  if (!iso) return "—";
+  const ms = Date.now() - new Date(iso).getTime();
+  if (Number.isNaN(ms) || ms < 0) return "—";
+  const m = Math.floor(ms / 60_000);
+  if (m < 1) return "just now";
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  if (d < 14) return `${d}d ago`;
+  const w = Math.floor(d / 7);
+  if (w < 8) return `${w}w ago`;
+  return `${Math.floor(d / 30)}mo ago`;
+}
+
+/** Width of the headline box and section dividers. Adapts to narrow terminals
+ *  down to a 60-char floor. */
+function getWidth(): number {
+  const cols = process.stdout.columns ?? 80;
+  return Math.max(60, Math.min(78, cols));
+}
+
+/** Box-drawing helpers using unicode round-corner glyphs. */
+function topBorder(w: number): string { return `╭${"─".repeat(w - 2)}╮`; }
+function bottomBorder(w: number): string { return `╰${"─".repeat(w - 2)}╯`; }
+function boxLine(text: string, w: number): string {
+  const inner = w - 4; // 2 chars of border + 1 char padding each side
+  const visible = stripAnsi(text);
+  const pad = Math.max(0, inner - visible.length);
+  return `│ ${text}${" ".repeat(pad)} │`;
+}
+function divider(w: number): string { return "─".repeat(w); }
+
+/** Short, qualified policy slug — `failproofai/foo` → `foo` for display. */
+function shortName(name: string): string {
+  const slash = name.indexOf("/");
+  return slash >= 0 ? name.slice(slash + 1) : name;
+}
+
+/** Sum hits across an AuditCount[] subset. */
+function sumHits(rows: AuditCount[]): number {
+  return rows.reduce((acc, r) => acc + r.hits, 0);
+}
+
+/** Render one row in the table-of-findings form:
+ *      31× Tried to read files outside your project
+ *           Stops the agent from peeking at neighboring repos…
+ *           Last seen 2h ago · 6 projects
+ *           › Already enforced — failproofai is blocking these in real time.
+ *           Example: grep -n …
+ */
+function renderRow(r: AuditCount, opts: { showExamples?: boolean }): string[] {
+  const out: string[] = [];
+  const sev = r.severity;
+  const titleColor =
+    sev === "deny" ? ANSI.red
+      : sev === "warn" ? ANSI.red
+        : sev === "info" || sev === "instruct" ? ANSI.yellow
+          : ANSI.cyan;
+  const countStr = String(r.hits).padStart(4);
+  out.push(`  ${titleColor}${ANSI.bold}${countStr}×${ANSI.reset}  ${r.displayTitle}`);
+  if (r.impact) {
+    out.push(`        ${ANSI.dim}${r.impact}${ANSI.reset}`);
+  }
+  out.push(
+    `        ${ANSI.dim}Last seen ${formatTimeAgo(r.lastSeen)} · ${r.projects} project${r.projects === 1 ? "" : "s"}${ANSI.reset}`,
+  );
+  if (opts.showExamples && r.examples[0]) {
+    out.push(`        ${ANSI.dim}Example: ${r.examples[0].example}${ANSI.reset}`);
+  }
+  if (r.installHint) {
+    const arrowColor = r.enabledInConfig ? ANSI.green : ANSI.cyan;
+    out.push(`        ${arrowColor}›${ANSI.reset} ${r.installHint}`);
+  }
+  out.push("");
+  return out;
+}
+
+export function formatText(result: AuditResult, opts: RunAuditOptions = {}): string {
+  const w = getWidth();
+  const limit = opts.limit ?? 20;
+  const showExamples = !!opts.showExamples;
+
+  // Split rows by enforcement state.
+  const enabledRows = result.results.filter((r) => r.source === "builtin" && r.enabledInConfig);
+  const unenabledBuiltinRows = result.results.filter((r) => r.source === "builtin" && !r.enabledInConfig);
+  const detectorRows = result.results.filter((r) => r.source === "audit-detector");
+  // "Slipping through" combines unenabled-builtins + audit-detectors, ranked by hits.
+  const slippingRows = [...unenabledBuiltinRows, ...detectorRows].sort((a, b) => b.hits - a.hits);
+
+  const totalProtected = sumHits(enabledRows);
+  const totalSlipping = sumHits(slippingRows);
+  const totalHits = totalProtected + totalSlipping;
+  const sinceLabel = result.scope.since ? `the last ${result.scope.since}` : "all time";
+
+  const lines: string[] = [];
+
+  // ── Header ──────────────────────────────────────────────────────
+  lines.push(`${ANSI.cyan}🛡  failproofai audit${ANSI.reset} ${ANSI.dim}[beta]${ANSI.reset}  ·  ${sinceLabel}`);
+  lines.push(
+    `   ${ANSI.dim}${result.transcripts.scanned} sessions · ${result.totals.projectsWithHits} project${result.totals.projectsWithHits === 1 ? "" : "s"} with hits · scanned in ${(result.transcripts.durationMs / 1000).toFixed(1)}s${ANSI.reset}`,
+  );
+  lines.push("");
+
+  // ── Headline box ────────────────────────────────────────────────
+  if (totalHits === 0) {
+    lines.push(topBorder(w));
+    lines.push(boxLine(`${ANSI.green}🎉 Clean run!${ANSI.reset}  Nothing matched your policies in this window.`, w));
+    lines.push(bottomBorder(w));
+    lines.push("");
+    return noColorEnabled() ? stripAnsi(lines.join("\n")) : lines.join("\n");
+  }
+  lines.push(topBorder(w));
+  lines.push(boxLine(
+    `${ANSI.bold}Your agent did ${totalHits} wasteful or risky things in ${sinceLabel}.${ANSI.reset}`,
+    w,
+  ));
+  if (totalSlipping > 0) {
+    lines.push(boxLine(
+      `${totalSlipping} of those would've been caught if more policies were on.`,
+      w,
+    ));
+  }
+  lines.push(bottomBorder(w));
+  lines.push("");
+
+  // ── Section: ALREADY PROTECTED ──────────────────────────────────
+  if (enabledRows.length > 0) {
+    lines.push(
+      `${ANSI.green}✓ ALREADY PROTECTED${ANSI.reset}  ${ANSI.dim}(${totalProtected} action${totalProtected === 1 ? "" : "s"} stopped by your current policies)${ANSI.reset}`,
+    );
+    lines.push("");
+    for (const row of enabledRows.slice(0, limit)) {
+      lines.push(...renderRow(row, { showExamples }));
+    }
+    if (enabledRows.length > limit) {
+      lines.push(`  ${ANSI.dim}… ${enabledRows.length - limit} more (use --limit ${enabledRows.length})${ANSI.reset}`);
+      lines.push("");
+    }
+  }
+
+  // ── Section: SLIPPING THROUGH ───────────────────────────────────
+  if (slippingRows.length > 0) {
+    lines.push(
+      `${ANSI.yellow}○ SLIPPING THROUGH${ANSI.reset}  ${ANSI.dim}(${totalSlipping} action${totalSlipping === 1 ? "" : "s"} caught by audit, not blocked in real time)${ANSI.reset}`,
+    );
+    lines.push("");
+    for (const row of slippingRows.slice(0, limit)) {
+      lines.push(...renderRow(row, { showExamples }));
+    }
+    if (slippingRows.length > limit) {
+      lines.push(`  ${ANSI.dim}… ${slippingRows.length - limit} more (use --limit ${slippingRows.length})${ANSI.reset}`);
+      lines.push("");
+    }
+  }
+
+  // ── Footer / NEXT step ──────────────────────────────────────────
+  lines.push(divider(w));
+  if (unenabledBuiltinRows.length > 0) {
+    const installNames = unenabledBuiltinRows.map((r) => shortName(r.name));
+    lines.push(
+      `${ANSI.bold}NEXT${ANSI.reset}  Enable the ${installNames.length} unenabled real-time polic${installNames.length === 1 ? "y" : "ies"} in one command:`,
+    );
+    lines.push("");
+    lines.push(`      ${ANSI.cyan}failproofai policies --install ${installNames.join(" ")}${ANSI.reset}`);
+    lines.push("");
+  } else if (slippingRows.length > 0) {
+    lines.push(
+      `${ANSI.bold}NEXT${ANSI.reset}  Everything blockable is already enabled. Audit-only findings will show up in your next ${ANSI.cyan}failproofai audit${ANSI.reset}.`,
+    );
+    lines.push("");
+  } else {
+    lines.push(`${ANSI.bold}NEXT${ANSI.reset}  ${ANSI.green}You have the relevant policies enabled. failproofai is blocking these in real time.${ANSI.reset}`);
+    lines.push("");
+  }
+
+  // Mirror the actual --report path so the printed footer matches what was
+  // (or will be) written. Suppressed entirely with --no-report.
+  if (!opts.noReport) {
+    const reportPath = opts.reportPath ?? "./failproofai-audit.md";
+    lines.push(`      📄 Shareable report:  ${ANSI.cyan}${reportPath}${ANSI.reset}`);
+  }
+  lines.push(`      ⭐ Star us:           ${ANSI.cyan}https://github.com/FailproofAI/failproofai${ANSI.reset}`);
+  lines.push("");
+
+  return noColorEnabled() ? stripAnsi(lines.join("\n")) : lines.join("\n");
+}
+
+export function formatJson(result: AuditResult): string {
+  return JSON.stringify(result, null, 2);
+}
+
+/** Escape characters that would break a markdown table row. Pipes split
+ *  columns; backslashes escape the next char; leading newlines end the row. */
+function escapeTableCell(s: string): string {
+  return s.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/[\r\n]+/g, " ");
+}
+
+function escapeBackticks(s: string): string {
+  return s.replace(/`/g, "\\`");
+}
+
+export function formatMarkdown(result: AuditResult): string {
+  const out: string[] = [];
+
+  const enabledRows = result.results.filter((r) => r.source === "builtin" && r.enabledInConfig);
+  const unenabledBuiltinRows = result.results.filter((r) => r.source === "builtin" && !r.enabledInConfig);
+  const detectorRows = result.results.filter((r) => r.source === "audit-detector");
+  const slippingRows = [...unenabledBuiltinRows, ...detectorRows].sort((a, b) => b.hits - a.hits);
+
+  const totalProtected = sumHits(enabledRows);
+  const totalSlipping = sumHits(slippingRows);
+  const totalHits = totalProtected + totalSlipping;
+  const sinceLabel = result.scope.since ? `last ${result.scope.since}` : "all time";
+
+  out.push(`# Agent behavior audit · ${sinceLabel}`);
+  out.push("");
+  out.push("> _Generated by `failproofai audit` (**beta**) — flags and output may change between releases. Going live shortly._");
+  out.push("");
+  out.push(`*Generated ${result.scannedAt} — scanned ${result.transcripts.scanned} sessions across ${result.totals.projectsWithHits} project(s) in ${(result.transcripts.durationMs / 1000).toFixed(1)}s.*`);
+  out.push("");
+
+  // TL;DR — readable to someone who doesn't know failproofai.
+  out.push("## TL;DR");
+  out.push("");
+  if (totalHits === 0) {
+    out.push("Clean run — the AI coding agent didn't do anything `failproofai` catches in this window.");
+  } else {
+    out.push(
+      `Over ${result.transcripts.scanned} sessions, my AI coding agent did **${totalHits} things \`failproofai\` would have stopped**: ` +
+      `${totalProtected} were already blocked in real time by my current config; ` +
+      `**${totalSlipping} slipped through** (would've been caught if more policies were on).`,
+    );
+  }
+  out.push("");
+  out.push("> [failproofai](https://github.com/FailproofAI/failproofai) is a hook-based policy engine for Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, and Gemini CLI. The `audit` command replays past agent sessions through every builtin policy to surface patterns that were (or could've been) stopped.");
+  out.push("");
+
+  if (totalHits === 0) return out.join("\n");
+
+  // What was blocked
+  if (enabledRows.length > 0) {
+    out.push(`## ✓ Already protected (${totalProtected} action${totalProtected === 1 ? "" : "s"} stopped)`);
+    out.push("");
+    out.push("These are real-time policies you have on — `failproofai` blocked the agent before each action took effect.");
+    out.push("");
+    out.push("| Issue | Hits | Projects | Last seen | Policy |");
+    out.push("|---|---:|---:|---|---|");
+    for (const r of enabledRows) {
+      out.push(
+        `| ${escapeTableCell(r.displayTitle)} | ${r.hits} | ${r.projects} | ${formatTimeAgo(r.lastSeen)} | \`${escapeTableCell(shortName(r.name))}\` |`,
+      );
+    }
+    out.push("");
+  }
+
+  // What's slipping through
+  if (slippingRows.length > 0) {
+    out.push(`## ○ Slipping through (${totalSlipping} action${totalSlipping === 1 ? "" : "s"} caught by audit, not yet blocked)`);
+    out.push("");
+    out.push("Patterns the audit detected but real-time enforcement isn't on for. The CTA column shows how to fix each.");
+    out.push("");
+    out.push("| Issue | Hits | Projects | Last seen | Fix |");
+    out.push("|---|---:|---:|---|---|");
+    for (const r of slippingRows) {
+      const fix = r.source === "builtin"
+        ? `\`failproofai policies --install ${shortName(r.name)}\``
+        : "_audit-only_";
+      out.push(
+        `| ${escapeTableCell(r.displayTitle)} | ${r.hits} | ${r.projects} | ${formatTimeAgo(r.lastSeen)} | ${fix} |`,
+      );
+    }
+    out.push("");
+
+    if (unenabledBuiltinRows.length > 0) {
+      out.push(`### Enable everything in one command`);
+      out.push("");
+      out.push("```bash");
+      out.push(`failproofai policies --install ${unenabledBuiltinRows.map((r) => shortName(r.name)).join(" ")}`);
+      out.push("```");
+      out.push("");
+    }
+  }
+
+  // Examples appendix (only if non-trivial)
+  const rowsWithExamples = [...enabledRows, ...slippingRows].filter((r) => r.examples.length > 0);
+  if (rowsWithExamples.length > 0) {
+    out.push("## Examples");
+    out.push("");
+    for (const r of rowsWithExamples) {
+      out.push(`### ${escapeBackticks(r.displayTitle)} (\`${escapeBackticks(shortName(r.name))}\`)`);
+      out.push("");
+      if (r.impact) {
+        out.push(`> ${r.impact}`);
+        out.push("");
+      }
+      for (const e of r.examples) {
+        out.push(`- \`${escapeBackticks(e.example)}\` _(${e.cwd || "?"}, ${formatTimeAgo(e.timestamp)})_`);
+      }
+      out.push("");
+    }
+  }
+
+  out.push("---");
+  out.push("");
+  out.push("⭐ Star failproofai on GitHub: <https://github.com/FailproofAI/failproofai>");
+  out.push("");
+  return out.join("\n");
+}

package/src/audit/telemetry.ts

@@ -0,0 +1,113 @@
+/**
+ * PostHog telemetry for `failproofai audit`.
+ *
+ * Plugs into the existing `trackHookEvent` surface (src/hooks/hook-telemetry.ts)
+ * — same distinct ID strategy, same opt-out (`FAILPROOFAI_TELEMETRY_DISABLED=1`),
+ * same fail-open contract (never crash the CLI).
+ *
+ * **Privacy contract — strictly enforced:**
+ *   • Never send transcript paths, decoded project folder names, cwds,
+ *     example command strings, file paths, sessionIds, or tool inputs.
+ *   • Only ever send: policy/detector slugs (already public), counts,
+ *     booleans, bucketed ages, CLI tags, output mode tags.
+ *
+ * Events fired during one `audit` run:
+ *   1. `audit_started`           — once, before scanning
+ *   2. `audit_pattern_detected`  — one per AuditCount aggregated
+ *   3. `audit_install_cta_shown` — once, if there are unenabled builtins
+ *   4. `audit_completed`         — once, at the end
+ */
+import { trackHookEvent } from "../hooks/hook-telemetry";
+import { getInstanceId } from "../../lib/telemetry-id";
+import type { AuditCount, AuditResult, RunAuditOptions } from "./types";
+
+/** Bucketize an ISO timestamp into a coarse "days since" value to avoid
+ *  shipping anything that could correlate with a specific session timing.
+ *  Returns null when unknown. */
+function ageBucketDays(iso: string | undefined): number | null {
+  if (!iso) return null;
+  const ms = Date.now() - new Date(iso).getTime();
+  if (Number.isNaN(ms) || ms < 0) return null;
+  const days = Math.floor(ms / 86_400_000);
+  // Bucket to nearest expected reporting horizon, never raw days
+  if (days <= 0) return 0;
+  if (days <= 1) return 1;
+  if (days <= 7) return 7;
+  if (days <= 30) return 30;
+  if (days <= 90) return 90;
+  if (days <= 365) return 365;
+  return 366;
+}
+
+function shortName(name: string): string {
+  const slash = name.indexOf("/");
+  return slash >= 0 ? name.slice(slash + 1) : name;
+}
+
+/** Fire-and-forget — telemetry never blocks or fails the CLI. Promises are
+ *  awaited inside trackHookEvent (which has a 5s AbortSignal); callers can
+ *  `void` the return. */
+export function trackAuditStarted(opts: RunAuditOptions, outputMode: string): void {
+  void trackHookEvent(getInstanceId(), "audit_started", {
+    clis_requested: opts.clis ?? "all",
+    since_window: opts.since ?? null,
+    has_project_filter: !!opts.projects?.length,
+    has_policy_filter: !!opts.policies?.length,
+    no_cache: !!opts.noCache,
+    output_mode: outputMode,
+  });
+}
+
+export function trackAuditPatternDetected(count: AuditCount): void {
+  void trackHookEvent(getInstanceId(), "audit_pattern_detected", {
+    pattern_name: shortName(count.name),
+    pattern_source: count.source,
+    pattern_category: count.category,
+    hits: count.hits,
+    projects: count.projects,
+    enabled_in_config: count.enabledInConfig,
+    severity: count.severity,
+    first_seen_age_days: ageBucketDays(count.firstSeen),
+    last_seen_age_days: ageBucketDays(count.lastSeen),
+  });
+}
+
+export function trackAuditInstallCtaShown(unenabledNames: string[]): void {
+  if (unenabledNames.length === 0) return;
+  void trackHookEvent(getInstanceId(), "audit_install_cta_shown", {
+    unenabled_count: unenabledNames.length,
+    unenabled_pattern_names: unenabledNames.map(shortName),
+  });
+}
+
+export function trackAuditCompleted(
+  result: AuditResult,
+  outputMode: string,
+): void {
+  const enabledHits = result.results
+    .filter((r) => r.source === "builtin" && r.enabledInConfig)
+    .reduce((acc, r) => acc + r.hits, 0);
+  const unenabledHits = result.results
+    .filter((r) => r.source === "builtin" && !r.enabledInConfig)
+    .reduce((acc, r) => acc + r.hits, 0);
+  const detectorHits = result.results
+    .filter((r) => r.source === "audit-detector")
+    .reduce((acc, r) => acc + r.hits, 0);
+
+  void trackHookEvent(getInstanceId(), "audit_completed", {
+    duration_ms: result.transcripts.durationMs,
+    transcripts_scanned: result.transcripts.scanned,
+    transcripts_skipped: result.transcripts.skipped,
+    transcripts_errors: result.transcripts.errors,
+    total_hits: result.totals.hits,
+    projects_with_hits: result.totals.projectsWithHits,
+    enabled_builtin_hits: enabledHits,
+    unenabled_builtin_hits: unenabledHits,
+    audit_detector_hits: detectorHits,
+    result_count: result.results.length,
+    clis_scanned: result.scope.cli,
+    since_window: result.scope.since,
+    has_project_filter: result.scope.projects !== "all",
+    output_mode: outputMode,
+  });
+}

package/src/audit/types.ts

@@ -0,0 +1,193 @@
+/**
+ * Types for the `failproofai audit` command.
+ *
+ * The audit walks past agent-CLI transcripts, replays each tool-use event
+ * through the existing policy engine, and runs each event through a separate
+ * set of audit-only detectors. Counts are aggregated per (policy|detector) and
+ * rendered as a table to stdout plus a markdown report.
+ */
+import type { IntegrationType } from "../hooks/types";
+
+/**
+ * A single tool-use event extracted from a transcript, canonicalized to the
+ * shape failproofai's policy engine + audit detectors expect.
+ */
+export interface NormalizedToolEvent {
+  cli: IntegrationType;
+  sessionId: string;
+  transcriptPath: string;
+  /** Working directory of the session at the time of the event. */
+  cwd: string;
+  /** ISO-8601 timestamp from the transcript line. */
+  timestamp: string;
+  /** Canonical Claude PascalCase tool name (Bash, Read, Edit, …). */
+  toolName: string;
+  /** Canonicalized tool input (snake_case keys for OpenCode/Pi). */
+  toolInput: Record<string, unknown>;
+  /** Pre-canonicalization tool name (e.g. "run_shell_command" for Gemini). */
+  rawToolName: string;
+  /**
+   * Result text from the matching tool_result block, if present in the
+   * transcript. Used to synthesize PostToolUse events for sanitize-* policies.
+   * Truncated to AUDIT_TOOL_RESULT_MAX_BYTES at the adapter to bound memory.
+   */
+  toolResultText?: string;
+}
+
+/** Metadata about a single transcript (one session's JSONL file). */
+export interface TranscriptMetadata {
+  cli: IntegrationType;
+  /** Encoded project folder name (e.g. "-home-user-project"). */
+  projectName: string;
+  sessionId: string;
+  transcriptPath: string;
+  /** mtime of the transcript file. Used for cache invalidation + --since filtering. */
+  mtimeMs: number;
+  /** Byte size of the transcript file. Used for cache invalidation. */
+  sizeBytes: number;
+}
+
+/** Per-session detector state. Detectors mutate this freely. */
+export type DetectorSessionState = Record<string, unknown>;
+
+/** One detected occurrence of a "stupid behavior". */
+export interface DetectorHit {
+  /** A short, one-line summary of what triggered the detector. Used as the
+   *  example column in the table and the example list in the markdown report.
+   *  Truncated to 80 chars upstream. */
+  example: string;
+}
+
+/** A pure function over a normalized event (plus optional per-session state).
+ *  Returns a DetectorHit when the event matches, null otherwise. */
+export type DetectorFn = (
+  event: NormalizedToolEvent,
+  state: DetectorSessionState,
+) => DetectorHit | null;
+
+/** Audit-only detector definition. */
+export interface Detector {
+  name: string;
+  description: string;
+  /** Display group in the markdown report (Wasteful / Risky / …). */
+  category: string;
+  /** Severity tier — drives row color in the table. */
+  severity: "warn" | "info";
+  detect: DetectorFn;
+  /** User-facing past-tense phrase, e.g. "Re-read a file just edited". Falls
+   *  back to `description` when omitted. */
+  displayTitle?: string;
+  /** One short clause describing the consequence. */
+  impact?: string;
+}
+
+/** Aggregated count for one policy or detector. */
+export interface AuditCount {
+  /** Either a policy name ("failproofai/block-force-push") or a detector name
+   *  ("redundant-cd-cwd"). */
+  name: string;
+  /** "builtin" for replayed policies, "audit-detector" for audit-only patterns. */
+  source: "builtin" | "audit-detector";
+  category: string;
+  /** Decision label for builtin replays (deny|instruct|allow|sanitize). For
+   *  audit-detector entries this is the detector's severity. */
+  severity: string;
+  hits: number;
+  /** Number of distinct projects (transcript folders) where this fired. */
+  projects: number;
+  /** ISO-8601 timestamp of the first matching event seen. */
+  firstSeen?: string;
+  /** ISO-8601 timestamp of the last matching event seen. */
+  lastSeen?: string;
+  /** Up to N example commands/snippets that triggered this (80 chars each). */
+  examples: { sessionId: string; cwd: string; timestamp: string; example: string }[];
+  /** User-facing past-tense phrase used in the report. Always populated by the
+   *  orchestrator — falls back to the policy/detector description when no
+   *  `displayTitle` was authored. */
+  displayTitle: string;
+  /** One short clause describing the consequence. May be empty for legacy
+   *  policies without authored impact copy. */
+  impact: string;
+  /** Whether the user currently has this builtin enabled. Drives the
+   *  "already protected" vs "slipping through" split in the report. Always
+   *  `false` for audit-only detectors (they don't have a runtime enforcement
+   *  path today). */
+  enabledInConfig: boolean;
+  /** Pre-built one-line install command (or audit-only notice) the report
+   *  shows next to each row, so users can copy-paste to remediate. */
+  installHint: string;
+}
+
+/** Per-transcript scan result (also the per-transcript cache value). */
+export interface TranscriptAuditResult {
+  /** Cache key: matches TranscriptMetadata.transcriptPath. */
+  transcriptPath: string;
+  cli: IntegrationType;
+  projectName: string;
+  sessionId: string;
+  mtimeMs: number;
+  sizeBytes: number;
+  /** Per-policy/detector hit count for this one transcript. */
+  hitsByName: Record<string, number>;
+  /** Up to 3 example commands per policy/detector (later coalesced upstream). */
+  examplesByName: Record<string, { timestamp: string; cwd: string; example: string }[]>;
+  /** First/last timestamp per name. */
+  rangeByName: Record<string, { first: string; last: string }>;
+}
+
+/** Top-level result of `runAudit()`. */
+export interface AuditResult {
+  /** Schema version of this JSON shape. Increment on incompatible changes. */
+  version: number;
+  scannedAt: string;
+  scope: {
+    cli: IntegrationType[];
+    projects: string[] | "all";
+    since: string | null;
+  };
+  transcripts: {
+    scanned: number;
+    skipped: number;
+    errors: number;
+    durationMs: number;
+  };
+  results: AuditCount[];
+  totals: {
+    hits: number;
+    projectsWithHits: number;
+  };
+}
+
+/** CLI-supplied options for `runAudit()`. Set by `bin/failproofai.mjs`. */
+export interface RunAuditOptions {
+  /** Restrict to one or more CLIs. Default: all 7. */
+  clis?: IntegrationType[];
+  /** Restrict to sessions whose cwd matches one of these paths. */
+  projects?: string[];
+  /** "7d", "30d", or an ISO date. Filters on transcript mtime. */
+  since?: string;
+  /** Restrict to one or more policy/detector names. */
+  policies?: string[];
+  /** Top-N rows in the table output. */
+  limit?: number;
+  /** Include example column in the table. */
+  showExamples?: boolean;
+  /** Output path for the markdown report. Default: ./failproofai-audit.md */
+  reportPath?: string;
+  /** Skip writing the markdown report. */
+  noReport?: boolean;
+  /** Emit JSON to stdout instead of the table. */
+  json?: boolean;
+  /** Bypass the per-transcript cache. */
+  noCache?: boolean;
+}
+
+/** Truncation budget for `NormalizedToolEvent.toolResultText`. Bounds memory
+ *  for sanitize-* policy replay without losing the typical match window. */
+export const AUDIT_TOOL_RESULT_MAX_BYTES = 64 * 1024;
+
+/** Truncation budget for example strings shown in table + markdown. */
+export const AUDIT_EXAMPLE_MAX_CHARS = 80;
+
+/** Max examples kept per policy/detector in the final report. */
+export const AUDIT_MAX_EXAMPLES_PER_NAME = 3;