failproofai 1.0.2-beta.4 → 1.0.2-beta.6

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

@@ -5,7 +5,7 @@
  * transcripts under <sessionId>/subagents/) via lib/claude-sessions.ts, then
  * parses each via lib/log-entries.ts.
  */
-import { readFile } from "node:fs/promises";
+import { readFile, open, type FileHandle } from "node:fs/promises";
 import {
   listClaudeProjects,
   listClaudeTranscripts,
@@ -14,6 +14,7 @@ import {
 import { parseLogContent, type LogSource } from "../../../lib/log-entries";
 import type { NormalizedToolEvent, TranscriptMetadata } from "../types";
 import { logEntriesToEvents } from "./shared";
+import type { IncrementalEvents } from "./index";
 
 export interface ListOpts {
   /** Restrict to sessions whose decoded cwd matches one of these paths. */
@@ -95,3 +96,112 @@ export async function streamClaudeEvents(
     cwd,
   });
 }
+
+/**
+ * The events after `fromByte`, and nothing before it.
+ *
+ * Claude writes session transcripts as append-only JSONL, which is what makes
+ * this sound: the bytes before `fromByte` were parsed on an earlier run and
+ * have not moved. The caller has already established that — see
+ * `anchorHashFor` in the audit cache — so this reads from the offset and does
+ * not re-verify it.
+ *
+ * Two details carry the correctness:
+ *
+ *  - The read starts at `fromByte`, which the caller only ever sets to a
+ *    position it previously reported through `bytesConsumed`, so it always
+ *    lands at the start of a line.
+ *  - It stops at the last NEWLINE, not at end-of-file. A transcript is
+ *    frequently being written while the audit reads it, so the tail is often
+ *    half a line; parsing it would drop or mangle that event, and reporting
+ *    the file size as consumed would mean the next run started after it and
+ *    lost it for good.
+ */
+export async function streamClaudeEventsFrom(
+  meta: TranscriptMetadata,
+  fromByte: number,
+): Promise<IncrementalEvents | null> {
+  if (!Number.isFinite(fromByte) || fromByte < 0) return null;
+  let handle: FileHandle | null = null;
+  let chunk: string;
+  try {
+    handle = await open(meta.transcriptPath, "r");
+    const { size } = await handle.stat();
+    if (fromByte > size) return null; // truncated under us; caller re-scans
+    if (fromByte === size) {
+      return { events: [], bytesConsumed: fromByte };
+    }
+    const buf = Buffer.alloc(size - fromByte);
+    await handle.read(buf, 0, buf.length, fromByte);
+    chunk = buf.toString("utf-8");
+  } catch {
+    return null;
+  } finally {
+    if (handle) {
+      try { await handle.close(); } catch { /* nothing useful to do */ }
+    }
+  }
+
+  // Everything up to the last newline is unambiguously complete. What follows
+  // it is either a line still being written, or the last line of a file that
+  // simply does not end in a newline — and those need opposite treatment:
+  // dropping the first is required, dropping the second loses the final event
+  // of every completed transcript.
+  //
+  // The only signal available in the bytes is whether the remainder PARSES. A
+  // half-written JSONL record does not (its braces are unclosed); a whole one
+  // missing only its newline does. So a parseable tail is taken and counted,
+  // and an unparseable one is left for the next run to pick up whole — which
+  // is also what stops it being counted twice when it arrives.
+  const lastNewline = chunk.lastIndexOf("\n");
+  const head = lastNewline === -1 ? "" : chunk.slice(0, lastNewline + 1);
+  const tail = chunk.slice(lastNewline + 1);
+  const tailIsWholeLine = tail.trim().length > 0 && (() => {
+    try {
+      JSON.parse(tail);
+      return true;
+    } catch {
+      return false;
+    }
+  })();
+  const complete = tailIsWholeLine ? head + tail : head;
+  if (complete.length === 0) {
+    // Nothing whole to parse, and the offset does not move.
+    return { events: [], bytesConsumed: fromByte };
+  }
+  // Byte length, not string length — a multi-byte character in the tail would
+  // otherwise put the next resume offset mid-character.
+  const bytesConsumed = fromByte + Buffer.byteLength(complete, "utf-8");
+
+  let entries;
+  try {
+    entries = await parseLogContent(complete, "session" as LogSource);
+  } catch {
+    return null;
+  }
+
+  let cwd = "";
+  for (const line of complete.split("\n", 50)) {
+    if (!line.trim()) continue;
+    try {
+      const parsed = JSON.parse(line) as { cwd?: unknown };
+      if (typeof parsed.cwd === "string" && parsed.cwd.length > 0) {
+        cwd = parsed.cwd;
+        break;
+      }
+    } catch {
+      // skip malformed lines
+    }
+  }
+
+  return {
+    events: logEntriesToEvents(entries, {
+      cli: "claude",
+      sessionId: meta.sessionId,
+      transcriptPath: meta.transcriptPath,
+      cwd,
+    }),
+    bytesConsumed,
+    cwd: cwd || undefined,
+  };
+}

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

@@ -11,7 +11,7 @@ import type { IntegrationType } from "../../hooks/types";
 import type { NormalizedToolEvent, TranscriptMetadata } from "../types";
 import type { ListOpts } from "./claude";
 
-import { listClaudeTranscriptMetadata, streamClaudeEvents } from "./claude";
+import { listClaudeTranscriptMetadata, streamClaudeEvents, streamClaudeEventsFrom } from "./claude";
 import { listCodexTranscriptMetadata, streamCodexEvents } from "./codex";
 import { listCopilotTranscriptMetadata, streamCopilotEvents } from "./copilot";
 import { listCursorTranscriptMetadata, streamCursorEvents } from "./cursor";
@@ -26,10 +26,39 @@ import { listGooseTranscriptMetadata, streamGooseEvents } from "./goose";
 
 export type { ListOpts };
 
+/** What an append-only source can hand back when asked to resume. */
+export interface IncrementalEvents {
+  events: NormalizedToolEvent[];
+  /**
+   * How far into the file `events` accounts for, at a LINE boundary — which is
+   * NOT the file size when a transcript is being appended to as it is read. The
+   * trailing partial line is left unparsed and uncounted so the next run picks
+   * it up whole; recording the file size instead would skip it permanently.
+   */
+  bytesConsumed: number;
+  /** The session cwd, when the resumed region carried one. */
+  cwd?: string;
+}
+
 export interface CliAdapter {
   cli: IntegrationType;
   listTranscripts: (opts?: ListOpts) => Promise<TranscriptMetadata[]>;
   streamEvents: (meta: TranscriptMetadata) => Promise<NormalizedToolEvent[]>;
+  /**
+   * Read only the events after `fromByte`, for sources whose transcripts are
+   * append-only files.
+   *
+   * OPTIONAL, and deliberately a separate method rather than a parameter on
+   * `streamEvents`. A parameter an adapter ignored would return the WHOLE
+   * transcript to a caller that is about to merge it into an existing partial
+   * result — every event counted twice, quietly, on exactly the sources that
+   * had not been updated. Absence of this method is what tells the caller it
+   * cannot resume, and there is no way to be wrong about that by omission.
+   */
+  streamEventsFrom?: (
+    meta: TranscriptMetadata,
+    fromByte: number,
+  ) => Promise<IncrementalEvents | null>;
 }
 
 export const ADAPTERS: Record<IntegrationType, CliAdapter> = {
@@ -37,6 +66,7 @@ export const ADAPTERS: Record<IntegrationType, CliAdapter> = {
     cli: "claude",
     listTranscripts: listClaudeTranscriptMetadata,
     streamEvents: streamClaudeEvents,
+    streamEventsFrom: streamClaudeEventsFrom,
   },
   codex: {
     cli: "codex",

package/src/audit/cli.ts

@@ -25,6 +25,8 @@
  * an exit code. See `runScheduledAudit`.
  */
 import { runAudit } from "./index";
+import { hasInstalledPacks } from "../hooks/pack-manifest";
+import { CORE_SOURCE } from "../hooks/pack-store";
 import { acquireAuditLock, type AuditLockInfo } from "./audit-lock";
 import { writeDashboardCache } from "./dashboard-cache";
 import type { AuditResult, RunAuditOptions } from "./types";
@@ -504,6 +506,16 @@ export async function runPostSetupAudit(): Promise<void> {
     writeDashboardCache({}, result);
     printSummary(result);
     process.stdout.write("\n");
+    // The audit says what ALREADY happened; nothing here says how to stop it
+    // happening again. This is the first thing a new machine runs, and setup
+    // installs no policies by design, so without this the whole first session
+    // ends on a count of findings and no way to act on it.
+    if (!hasInstalledPacks()) {
+      process.stdout.write(
+        `  ${c(DIM, "none of this is being enforced yet. take ours, or anyone's:")}\n` +
+          `    ${c(CYAN, `failproofai policies add ${CORE_SOURCE}`)}\n\n`,
+      );
+    }
   } finally {
     attempt.lock.release();
   }

package/src/audit/index.ts

@@ -10,12 +10,13 @@
 import { batchAll } from "../../lib/concurrency";
 import { BUILTIN_POLICIES } from "../hooks/builtin-policies";
 import { readMergedHooksConfig } from "../hooks/hooks-config";
+import { readInstalledPacks } from "../hooks/pack-manifest";
 import { normalizePolicyName } from "../hooks/policy-registry";
 import { INTEGRATION_TYPES, type IntegrationType } from "../hooks/types";
 import { ADAPTERS } from "./cli-adapters";
 import { AUDIT_DETECTORS } from "./detectors";
 import { severityForBuiltin } from "./features";
-import { readCachedTranscriptResult, writeCachedTranscriptResult } from "./cache";
+import { readCachedTranscript, writeCachedTranscriptResult } from "./cache";
 import { initReplay, replayEvent, restoreReplay } from "./replay";
 import {
   AUDIT_EXAMPLE_MAX_CHARS,
@@ -87,7 +88,24 @@ function parseSinceOpt(since: string | undefined): number | undefined {
   throw new Error(`Invalid --since value: "${since}" (expected e.g. "7d", "30d", or "2026-04-01")`);
 }
 
-async function scanOneTranscript(meta: TranscriptMetadata): Promise<TranscriptAuditResult> {
+/**
+ * What a scan covered, alongside the result — so the caller can record a resume
+ * point without re-deriving it.
+ *
+ * `bytesScanned` is 0 when the source cannot be resumed at all (a database, or
+ * an adapter with no `streamEventsFrom`), which is what stops a resume point
+ * being written for something that has no bytes to resume from.
+ */
+interface ScanOutcome {
+  result: TranscriptAuditResult;
+  bytesScanned: number;
+  detectorState: DetectorSessionState;
+}
+
+async function scanOneTranscript(
+  meta: TranscriptMetadata,
+  resume?: { fromByte: number; detectorState: DetectorSessionState },
+): Promise<ScanOutcome> {
   const empty: TranscriptAuditResult = {
     transcriptPath: meta.transcriptPath,
     cli: meta.cli,
@@ -102,17 +120,54 @@ async function scanOneTranscript(meta: TranscriptMetadata): Promise<TranscriptAu
     rangeByName: {},
   };
 
+  const adapter = ADAPTERS[meta.cli];
   // Stream failures must propagate so the orchestrator counts them in
   // `errors` rather than silently returning an empty hits map.
-  const events = await ADAPTERS[meta.cli].streamEvents(meta);
-  if (events.length === 0) return empty;
+  let events: NormalizedToolEvent[];
+  let bytesScanned = 0;
+  // A resumed scan carries the stateful detectors' state forward across the
+  // boundary. Starting them empty would silently change what they find — the
+  // re-read detector's countdown spans tool calls, so an edit before the offset
+  // and its wasteful re-read after it would stop being a pair.
+  const sessionState: DetectorSessionState = resume?.detectorState ?? {};
+
+  if (adapter.streamEventsFrom) {
+    // A full scan is a resume from zero, deliberately — not a separate branch.
+    //
+    // The separate branch is what got this wrong: it recorded `meta.sizeBytes`
+    // as scanned, which is the whole FILE, including a trailing partial line
+    // that was never parsed. Transcripts are appended to while the audit reads
+    // them, so that tail is routinely half a line — and the next run then
+    // resumed past an event nobody had read. Only the reader knows where the
+    // last complete line ended, so only the reader gets to say.
+    const scan = await adapter.streamEventsFrom(meta, resume?.fromByte ?? 0);
+    // Null means it could not be read from there after all — truncated,
+    // unreadable, unparseable. A thrown error would count as a scan failure,
+    // so fall back to a full read instead and keep the transcript scannable.
+    if (!scan) {
+      events = await adapter.streamEvents(meta);
+      bytesScanned = 0;
+    } else {
+      events = scan.events;
+      bytesScanned = scan.bytesConsumed;
+      empty.cwd = scan.cwd ?? "";
+    }
+  } else {
+    // A source with no byte offsets to speak of — a database. Scanned whole,
+    // every time, and given no resume point to mislead the next run with.
+    events = await adapter.streamEvents(meta);
+    bytesScanned = 0;
+  }
+
+  if (events.length === 0) {
+    return { result: empty, bytesScanned, detectorState: sessionState };
+  }
 
   const result = empty;
   result.eventsScanned = events.length;
   // 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 = events[0].cwd || "";
-  const sessionState: DetectorSessionState = {};
+  result.cwd = result.cwd || events[0].cwd || "";
 
   for (const event of events) {
     // Run audit detectors first (stateful, must see every event).
@@ -146,7 +201,7 @@ async function scanOneTranscript(meta: TranscriptMetadata): Promise<TranscriptAu
     }
   }
 
-  return result;
+  return { result, bytesScanned, detectorState: sessionState };
 }
 
 function formatPolicyExample(_policyName: string, event: NormalizedToolEvent): string {
@@ -159,6 +214,55 @@ function formatPolicyExample(_policyName: string, event: NormalizedToolEvent): s
   return `${event.toolName}`;
 }
 
+/**
+ * Fold a tail-scan into the result the cache already held for the same
+ * transcript.
+ *
+ * Mirrors `recordHit` exactly, and has to: counts add, examples stay capped at
+ * the same limit, ranges widen. The one asymmetry is `cwd` — the cached value
+ * 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(
+  cached: TranscriptAuditResult,
+  tail: TranscriptAuditResult,
+): TranscriptAuditResult {
+  const out: TranscriptAuditResult = {
+    ...cached,
+    mtimeMs: tail.mtimeMs,
+    sizeBytes: tail.sizeBytes,
+    cwd: cached.cwd || tail.cwd || "",
+    eventsScanned: (cached.eventsScanned ?? 0) + (tail.eventsScanned ?? 0),
+    hitsByName: { ...cached.hitsByName },
+    examplesByName: {},
+    rangeByName: { ...cached.rangeByName },
+  };
+  for (const [name, list] of Object.entries(cached.examplesByName)) {
+    out.examplesByName[name] = [...list];
+  }
+  for (const [name, count] of Object.entries(tail.hitsByName)) {
+    out.hitsByName[name] = (out.hitsByName[name] ?? 0) + count;
+  }
+  for (const [name, list] of Object.entries(tail.examplesByName)) {
+    const exs = out.examplesByName[name] ?? [];
+    for (const ex of list) {
+      if (exs.length >= AUDIT_MAX_EXAMPLES_PER_NAME) break;
+      exs.push(ex);
+    }
+    out.examplesByName[name] = exs;
+  }
+  for (const [name, range] of Object.entries(tail.rangeByName)) {
+    const existing = out.rangeByName[name];
+    if (!existing) {
+      out.rangeByName[name] = { ...range };
+    } else {
+      if (range.first < existing.first) existing.first = range.first;
+      if (range.last > existing.last) existing.last = range.last;
+    }
+  }
+  return out;
+}
+
 function recordHit(
   result: TranscriptAuditResult,
   name: string,
@@ -276,12 +380,42 @@ async function runAuditInner(opts: RunAuditOptions, startedAt: number): Promise<
   const clis = (opts.clis ?? Array.from(INTEGRATION_TYPES)) as IntegrationType[];
   const sinceMs = parseSinceOpt(opts.since);
 
-  // Snapshot which builtin policies the user currently has enabled — drives
-  // the "already protected" vs "slipping through" split in the report.
+  // What the user actually has switched on — drives the "already protected"
+  // vs "slipping through" split.
+  //
+  // Read from BOTH places it can live, because it moved and this only followed
+  // it half way. `enabledPolicies` is the pre-packs key, still written by
+  // `policies add <name>` and still true on a machine running the migration
+  // shim. Everything installed as a PACK records its selection in
+  // `installed.json` instead, and `pack-store` never writes `enabledPolicies`
+  // at all — so reading that key alone meant installing a pack could not move
+  // this split. Every policy read as slipping through no matter what was
+  // enforcing, and the number the audit leads with never changed however many
+  // policies you installed. Verified: same 302 hits, same 17 findings, before
+  // and after installing all 38.
+  //
+  // The split, not the REPLAY. What gets replayed stays the compiled builtins
+  // on purpose — see `initReplay`: an audit is a fixed yardstick, and one that
+  // changed shape with whatever pack a machine happened to have could not be
+  // compared against its own history. A pack policy sharing a builtin's name
+  // marks that builtin protected, which is exactly right: the same rule is
+  // enforcing, whichever artifact carries it.
   const userConfig = readMergedHooksConfig();
   const enabledBuiltins = new Set(
     (userConfig.enabledPolicies ?? []).map((n) => normalizePolicyName(n)),
   );
+  try {
+    for (const pack of readInstalledPacks().packs) {
+      // `enabled: null` means the whole pack was taken, so every policy in its
+      // catalog counts — the field records a SELECTION, and its absence is not
+      // an empty one.
+      const taken = pack.enabled ?? pack.policies.map((entry) => entry.name);
+      for (const name of taken) enabledBuiltins.add(normalizePolicyName(name));
+    }
+  } catch {
+    // An unreadable manifest must not fail the audit. It costs the split its
+    // pack half, which is the same answer this gave for every machine before.
+  }
 
   // 1. Discover transcripts across all selected CLIs.
   const allTranscripts: TranscriptMetadata[] = [];
@@ -300,14 +434,31 @@ async function runAuditInner(opts: RunAuditOptions, startedAt: number): Promise<
   let skipped = 0;
   let errors = 0;
   const tasks = allTranscripts.map((meta) => async (): Promise<TranscriptAuditResult> => {
+    let resume: { fromByte: number; detectorState: DetectorSessionState } | undefined;
+    let cachedPrefix: TranscriptAuditResult | null = null;
     if (!opts.noCache) {
-      const cached = readCachedTranscriptResult(meta.transcriptPath, meta.mtimeMs, meta.sizeBytes);
-      if (cached) return cached;
+      const found = readCachedTranscript(meta.transcriptPath, meta.mtimeMs, meta.sizeBytes);
+      if (found?.kind === "hit") return found.result;
+      resume = found?.kind === "resume"
+        ? { fromByte: found.fromByte, detectorState: found.detectorState }
+        : undefined;
+      cachedPrefix = found?.kind === "resume" ? found.result : null;
     }
     try {
-      const fresh = await scanOneTranscript(meta);
+      const scan = await scanOneTranscript(meta, resume);
+      // A resumed scan produced hits for the TAIL only; the cached result holds
+      // everything before it. Merging is what makes the two halves one answer.
+      const fresh = cachedPrefix ? mergeIncremental(cachedPrefix, scan.result) : scan.result;
       if (!opts.noCache) {
-        writeCachedTranscriptResult(meta.transcriptPath, meta.mtimeMs, meta.sizeBytes, fresh);
+        writeCachedTranscriptResult(
+          meta.transcriptPath,
+          meta.mtimeMs,
+          meta.sizeBytes,
+          fresh,
+          scan.bytesScanned > 0
+            ? { bytesScanned: scan.bytesScanned, detectorState: scan.detectorState }
+            : undefined,
+        );
       }
       return fresh;
     } catch {