failproofai 1.0.2-beta.4 → 1.0.2-beta.5

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

@@ -15,7 +15,7 @@ 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 +87,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 +119,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 +200,7 @@ async function scanOneTranscript(meta: TranscriptMetadata): Promise<TranscriptAu
     }
   }
 
-  return result;
+  return { result, bytesScanned, detectorState: sessionState };
 }
 
 function formatPolicyExample(_policyName: string, event: NormalizedToolEvent): string {
@@ -159,6 +213,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,
@@ -300,14 +403,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 {

package/src/hooks/manager.ts

@@ -14,7 +14,7 @@ import { INTEGRATION_TYPES,
   type HookScope,
   type IntegrationType,
 } from "./types";
-import { claudeCode, getIntegration, settingsPathsFor } from "./integrations";
+import { claudeCode, getIntegration, settingsPathsFor, type Integration } from "./integrations";
 import { promptPolicySelection } from "./install-prompt";
 import { configuredCustomPolicyPaths, readMergedHooksConfig, readScopedHooksConfig, writeScopedHooksConfig, syncConventionPolicies, findProjectConfigDir } from "./hooks-config";
 import type { HooksConfig, ConventionPolicyRecord } from "./policy-types";
@@ -271,9 +271,44 @@ function deduplicateScopes(scopes: readonly HookScope[], cwd?: string): HookScop
  * rows of the listing already answer it.
  */
 export function hooksInstalledInSettings(scope: HookScope, cwd?: string): boolean {
-  return INTEGRATION_TYPES.some((id) => {
+  return integrationsInstalledAt(scope, cwd).length > 0;
+}
+
+/**
+ * Which integrations are wired at EXACTLY this scope — the honest form of the
+ * question above, and the one the multi-scope warning needs.
+ *
+ * Two ways an integration answers yes for a scope it is not actually installed
+ * at, both of which made `failproofai policies` warn about "hooks in multiple
+ * scopes" on a machine whose hooks are in exactly one file:
+ *
+ *  - It does not SUPPORT the scope. Hermes and OpenClaw are user-scope only
+ *    (`HERMES_HOOK_SCOPES = ["user"]`) and their `getSettingsPath` ignores the
+ *    scope argument entirely, so they hand back the user file — and report it
+ *    installed — for `project` and `local` alike. `scopes` already declares
+ *    this; nothing was reading it.
+ *  - Its project path RESOLVES to its user path. Run this from `$HOME` and
+ *    `<cwd>/.claude/settings.json` is `~/.claude/settings.json`: one file,
+ *    counted as two scopes. Cheap to detect and impossible to get right by
+ *    asking each integration separately.
+ */
+export function integrationsInstalledAt(scope: HookScope, cwd?: string): IntegrationType[] {
+  return INTEGRATION_TYPES.filter((id) => {
     try {
-      return getIntegration(id).hooksInstalledInSettings(scope, cwd);
+      const integration = getIntegration(id);
+      if (!integration.scopes.includes(scope)) return false;
+      if (!integration.hooksInstalledInSettings(scope, cwd)) return false;
+      // A narrower scope that lands on the same file as a wider one is that
+      // wider one, seen twice. Attribute it to the widest scope that resolves
+      // there so exactly one of them counts.
+      const here = integration.getSettingsPath(scope, cwd);
+      return !HOOK_SCOPES.some(
+        (other) =>
+          other !== scope &&
+          HOOK_SCOPES.indexOf(other) < HOOK_SCOPES.indexOf(scope) &&
+          integration.scopes.includes(other) &&
+          safeSettingsPath(integration, other, cwd) === here,
+      );
     } catch {
       // An integration whose settings file is unreadable is not evidence that
       // nothing is installed — keep asking the rest.
@@ -282,6 +317,18 @@ export function hooksInstalledInSettings(scope: HookScope, cwd?: string): boolea
   });
 }
 
+function safeSettingsPath(
+  integration: Integration,
+  scope: HookScope,
+  cwd?: string,
+): string | null {
+  try {
+    return integration.getSettingsPath(scope, cwd);
+  } catch {
+    return null;
+  }
+}
+
 export interface InstallHooksOptions {
   /** Replace the enabled set at this scope instead of unioning (default: additive). */
   replace?: boolean;