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

package/lib/opencode-db.ts

@@ -0,0 +1,77 @@
+/**
+ * Read-only access to OpenCode's SQLite database.
+ *
+ * This used to shell out: `opencode db --format json "<sql>"`, on the reasoning
+ * that going through the CLI avoided coupling us to opencode's internal schema.
+ * It did not — the SQL was ours either way, naming opencode's own tables and
+ * columns, so the schema coupling was identical and the subprocess bought
+ * nothing but its own cost.
+ *
+ * And that cost was the single largest component of `failproofai audit` on any
+ * machine with opencode installed. Each spawn is a full CLI start: ~1.5s
+ * measured. `getOpenCodeSessionExport` issues three queries, so a 30-session
+ * history spent ~135 seconds launching 90 processes — against a total audit
+ * time of ~140s. The audit sat at ~0% CPU throughout, which is why it read as
+ * "slow scanning" rather than as what it was: waiting on `execFileSync`.
+ *
+ * Reading the file directly is the same thing every other SQLite-backed
+ * integration already does through `openSqliteReadonly` — goose, devin, hermes,
+ * openclaw and antigravity. Opening the database costs microseconds, and one
+ * open now serves every query a caller needs instead of one process per query.
+ *
+ * Fail-open contract is unchanged: a missing file, an unreadable database or a
+ * query error yields `null`, and callers degrade to an empty result exactly as
+ * they did when the binary was absent from PATH.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { openSqliteReadonly, type SqliteReader } from "./sqlite-reader";
+
+/**
+ * Where the database lives.
+ *
+ * `OPENCODE_DB_PATH` names the file outright and `OPENCODE_HOME` the directory
+ * holding it — the same override shape `GOOSE_DB_PATH`/`GOOSE_HOME` and
+ * `DEVIN_DB_PATH`/`DEVIN_HOME` use, so tests point at a fixture the same way
+ * for every one of them.
+ */
+export function opencodeDbPath(): string {
+  if (process.env.OPENCODE_DB_PATH) return process.env.OPENCODE_DB_PATH;
+  const home = process.env.OPENCODE_HOME ?? join(homedir(), ".local", "share", "opencode");
+  return join(home, "opencode.db");
+}
+
+/**
+ * Open the database, hand it to `fn`, and always close it.
+ *
+ * Callers that need several queries take ONE of these and run them all inside
+ * it. That is the whole point: the shape being replaced ran a separate process
+ * per query, so three related reads cost three CLI starts.
+ */
+export async function withOpenCodeDb<T>(
+  fn: (db: SqliteReader) => T,
+): Promise<T | null> {
+  const db = await openSqliteReadonly(opencodeDbPath());
+  if (!db) return null;
+  try {
+    return fn(db);
+  } catch {
+    // A query error is indistinguishable from a missing database to every
+    // caller, and both mean "no opencode data" rather than "audit failed".
+    return null;
+  } finally {
+    try {
+      db.close();
+    } catch {
+      /* closing a read-only handle cannot fail in a way that matters here */
+    }
+  }
+}
+
+/** One query, for callers that genuinely need only one. */
+export async function queryOpenCodeDb<T = Record<string, unknown>>(
+  sql: string,
+  params: unknown[] = [],
+): Promise<T[] | null> {
+  return withOpenCodeDb((db) => db.query<T>(sql, params));
+}

package/lib/opencode-projects.ts

@@ -3,10 +3,15 @@
  *
  * Unlike the other agent CLIs that store sessions as filesystem JSONL trees,
  * OpenCode stores everything in a single SQLite database (managed by
- * Drizzle ORM) at `~/.local/share/opencode/opencode.db`. Rather than read
- * the DB directly with `bun:sqlite` (which would couple us to opencode's
- * internal schema), we shell out to `opencode db --format json "<sql>"` —
- * the same surface opencode itself documents as read-only safe.
+ * Drizzle ORM) at `~/.local/share/opencode/opencode.db`, read directly
+ * through `lib/opencode-db.ts`.
+ *
+ * This used to shell out to `opencode db --format json "<sql>"`, to avoid
+ * coupling to opencode's internal schema. That reasoning did not survive
+ * contact with the SQL: the queries name opencode's own tables and columns
+ * either way, so the coupling was identical and the subprocess bought only
+ * its own cost — see `lib/opencode-db.ts` for what that cost turned out to
+ * be.
  *
  * Verified live against opencode v1.14.31:
  *   • `session` columns: id, project_id, parent_id, slug, directory, title,
@@ -21,7 +26,7 @@
  * Refs: https://opencode.ai/docs/   (CLI reference)
  *       https://opencode.ai/docs/plugins/  (plugin model context)
  */
-import { execFileSync } from "node:child_process";
+import { queryOpenCodeDb, withOpenCodeDb } from "./opencode-db";
 import { encodeFolderName } from "./paths";
 import type { ProjectFolder, SessionFile } from "./projects";
 import { runtimeCache } from "./runtime-cache";
@@ -51,41 +56,34 @@ interface OpenCodeProjectRow {
 }
 
 /**
- * Run `opencode db --format json "<sql>"` and parse the result. Returns
- * `null` (not an empty array) when the binary is missing or the query fails
- * — callers can decide whether absent vs. empty is meaningful.
- */
-function runOpenCodeDb<T>(sql: string): T[] | null {
-  try {
-    const stdout = execFileSync("opencode", ["db", "--format", "json", sql], {
-      encoding: "utf8",
-      timeout: 5_000,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    if (!stdout.trim()) return [];
-    const parsed = JSON.parse(stdout) as unknown;
-    if (!Array.isArray(parsed)) return null;
-    return parsed as T[];
-  } catch {
-    // Binary missing, db locked, malformed JSON, or SQL error — fail open.
-    return null;
-  }
-}
-
-/**
- * Pull session rows directly from opencode's SQLite. Selects the columns the
- * dashboard needs and orders newest-first.
+ * Session rows the dashboard needs, newest first.
+ *
+ * One caller needs sessions alone; the other two need sessions and projects
+ * together and take `readBothRows`, which serves both from a single open
+ * rather than two.
  */
-function readSessionRows(): OpenCodeSessionRow[] | null {
-  return runOpenCodeDb<OpenCodeSessionRow>(
-    `SELECT id, project_id, slug, directory, title, time_created, time_updated FROM session ORDER BY time_updated DESC LIMIT ${SESSION_LIMIT}`,
+async function readSessionRows(): Promise<OpenCodeSessionRow[] | null> {
+  return queryOpenCodeDb<OpenCodeSessionRow>(
+    "SELECT id, project_id, slug, directory, title, time_created, time_updated FROM session ORDER BY time_updated DESC LIMIT ?",
+    [SESSION_LIMIT],
   );
 }
 
-function readProjectRows(): OpenCodeProjectRow[] | null {
-  return runOpenCodeDb<OpenCodeProjectRow>(
-    `SELECT id, worktree, vcs, name, time_created, time_updated FROM project`,
-  );
+/** Both tables from one open, for the callers that use them together. */
+async function readBothRows(): Promise<{
+  sessions: OpenCodeSessionRow[] | null;
+  projects: OpenCodeProjectRow[] | null;
+}> {
+  const rows = await withOpenCodeDb((db) => ({
+    sessions: db.query<OpenCodeSessionRow>(
+      "SELECT id, project_id, slug, directory, title, time_created, time_updated FROM session ORDER BY time_updated DESC LIMIT ?",
+      [SESSION_LIMIT],
+    ),
+    projects: db.query<OpenCodeProjectRow>(
+      "SELECT id, worktree, vcs, name, time_created, time_updated FROM project",
+    ),
+  }));
+  return { sessions: rows?.sessions ?? null, projects: rows?.projects ?? null };
 }
 
 /**
@@ -97,8 +95,7 @@ function readProjectRows(): OpenCodeProjectRow[] | null {
  * if no sessions exist yet).
  */
 export async function getOpenCodeProjects(): Promise<ProjectFolder[]> {
-  const sessions = readSessionRows();
-  const projects = readProjectRows();
+  const { sessions, projects } = await readBothRows();
   if (sessions === null && projects === null) {
     // Binary missing or query failed — silent degrade (no log spam).
     return [];
@@ -163,7 +160,7 @@ export async function getOpenCodeProjects(): Promise<ProjectFolder[]> {
 
 /** Sessions under a given absolute cwd. Used by the project detail page. */
 export async function getOpenCodeSessionsForCwd(cwd: string): Promise<SessionFile[]> {
-  const sessions = readSessionRows();
+  const sessions = await readSessionRows();
   if (!sessions) return [];
   const matches = sessions.filter((s) => s.directory === cwd);
   return matches.map((s) => {
@@ -193,8 +190,7 @@ export async function getOpenCodeSessionsByEncodedName(name: string): Promise<Op
   let projects: OpenCodeProjectRow[] | null;
   let sessions: OpenCodeSessionRow[] | null;
   try {
-    projects = readProjectRows();
-    sessions = readSessionRows();
+    ({ projects, sessions } = await readBothRows());
   } catch (error) {
     logWarn("Failed to read OpenCode DB:", error);
     return { cwd: null, sessions: [] };

package/lib/opencode-sessions.ts

@@ -2,9 +2,10 @@
  * OpenCode (sst/opencode) session transcript loader.
  *
  * Sessions live in opencode's SQLite DB (`~/.local/share/opencode/opencode.db`),
- * not on disk as JSONL like the other CLIs. We read them by shelling out to
- * `opencode db --format json "<sql>"` — same surface as `lib/opencode-projects.ts`
- * and the same fail-open contract (binary missing → return null).
+ * not on disk as JSONL like the other CLIs. Read directly through
+ * `lib/opencode-db.ts` — see there for why this stopped shelling out to
+ * `opencode db` — with the same fail-open contract as every other provider
+ * (database unreadable → return null).
  *
  * Schema verified live on opencode v1.14.31:
  *   • `session(id, project_id, parent_id, slug, directory, title, time_*, …)`
@@ -17,7 +18,7 @@
  *
  * Refs: https://opencode.ai/docs/   (CLI reference)
  */
-import { execFileSync } from "node:child_process";
+import { withOpenCodeDb } from "./opencode-db";
 import { runtimeCache } from "./runtime-cache";
 import {
   baseEntry,
@@ -59,19 +60,19 @@ interface OpenCodePartRow {
   data: string; // JSON-encoded
 }
 
-/** Run a parameter-free SELECT against opencode's DB. Returns `null` on any
- *  failure (binary missing, query error, malformed output). */
-function runOpenCodeDb<T>(sql: string): T[] | null {
+/**
+ * One query, with its failure isolated to itself.
+ *
+ * The three reads below used to be three separate processes, so one of them
+ * failing left the others' results intact — and the callers depend on that: a
+ * session row that loads while its messages do not yields an EMPTY log rather
+ * than a missing one. Running all three inside a single open would otherwise
+ * turn any one failure into a null for the whole session, which reads to the
+ * dashboard as "no such session" rather than "no messages".
+ */
+function safeQuery<T>(run: () => T[]): T[] | null {
   try {
-    const stdout = execFileSync("opencode", ["db", "--format", "json", sql], {
-      encoding: "utf8",
-      timeout: 5_000,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    if (!stdout.trim()) return [];
-    const parsed = JSON.parse(stdout) as unknown;
-    if (!Array.isArray(parsed)) return null;
-    return parsed as T[];
+    return run();
   } catch {
     return null;
   }
@@ -215,19 +216,33 @@ export interface OpenCodeSessionLogData {
  * or the binary is unavailable.
  */
 export async function getOpenCodeSessionLog(sessionId: string): Promise<OpenCodeSessionLogData | null> {
-  if (!sessionId || !/^[A-Za-z0-9_-]+$/.test(sessionId)) return null; // SQL-injection guard
-  const sessions = runOpenCodeDb<OpenCodeSessionRow>(
-    `SELECT id, project_id, slug, directory, title, time_created, time_updated FROM session WHERE id = '${sessionId}'`,
-  );
+  // Parameter binding already makes injection impossible, so this guard is no
+  // longer load-bearing for that — but an id that cannot match anything is
+  // still not worth a database open, and weakening an existing check while
+  // changing transport is how a regression gets in unnoticed.
+  if (!sessionId || !/^[A-Za-z0-9_-]+$/.test(sessionId)) return null;
+  // One open, three queries. Each of these was a separate `opencode db`
+  // process — and this function is called once per session by the audit, so
+  // the spawns were the audit.
+  const rows = await withOpenCodeDb((db) => ({
+    sessions: safeQuery(() => db.query<OpenCodeSessionRow>(
+      "SELECT id, project_id, slug, directory, title, time_created, time_updated FROM session WHERE id = ?",
+      [sessionId],
+    )),
+    messages: safeQuery(() => db.query<OpenCodeMessageRow>(
+      "SELECT id, session_id, time_created, time_updated, data FROM message WHERE session_id = ? ORDER BY time_created ASC",
+      [sessionId],
+    )),
+    parts: safeQuery(() => db.query<OpenCodePartRow>(
+      "SELECT id, message_id, session_id, time_created, time_updated, data FROM part WHERE session_id = ? ORDER BY time_created ASC",
+      [sessionId],
+    )),
+  }));
+  const sessions = rows?.sessions ?? null;
   if (!sessions || sessions.length === 0) return null;
   const session = sessions[0];
-
-  const messages = runOpenCodeDb<OpenCodeMessageRow>(
-    `SELECT id, session_id, time_created, time_updated, data FROM message WHERE session_id = '${sessionId}' ORDER BY time_created ASC`,
-  );
-  const parts = runOpenCodeDb<OpenCodePartRow>(
-    `SELECT id, message_id, session_id, time_created, time_updated, data FROM part WHERE session_id = '${sessionId}' ORDER BY time_created ASC`,
-  );
+  const messages = rows?.messages ?? null;
+  const parts = rows?.parts ?? null;
   if (!messages) return { entries: [], rawLines: [], cwd: session.directory ?? undefined, filePath: `opencode://${sessionId}` };
 
   // Group parts by message_id for O(1) lookup.
@@ -289,20 +304,28 @@ export interface OpenCodeSessionExportData {
 
 export async function getOpenCodeSessionExport(sessionId: string): Promise<OpenCodeSessionExportData | null> {
   if (!sessionId || !/^[A-Za-z0-9_-]+$/.test(sessionId)) return null;
-  const sessions = runOpenCodeDb<OpenCodeSessionRow>(
-    `SELECT id, project_id, slug, directory, title, time_created, time_updated FROM session WHERE id = '${sessionId}'`,
-  );
+  const rows = await withOpenCodeDb((db) => ({
+    sessions: safeQuery(() => db.query<OpenCodeSessionRow>(
+      "SELECT id, project_id, slug, directory, title, time_created, time_updated FROM session WHERE id = ?",
+      [sessionId],
+    )),
+    messages: safeQuery(() => db.query<OpenCodeMessageRow>(
+      "SELECT id, session_id, time_created, time_updated, data FROM message WHERE session_id = ? ORDER BY time_created ASC",
+      [sessionId],
+    )),
+    parts: safeQuery(() => db.query<OpenCodePartRow>(
+      "SELECT id, message_id, session_id, time_created, time_updated, data FROM part WHERE session_id = ? ORDER BY time_created ASC",
+      [sessionId],
+    )),
+  }));
+  const sessions = rows?.sessions ?? null;
   if (!sessions || sessions.length === 0) return null;
   // Don't coalesce a `null` return (query failure) into `[]` — that would
   // silently serve an "empty session" export. A genuinely empty session has
   // an `[]` from the DB; a query failure has `null`. Treat the latter as
   // not-found so the route returns 404 rather than a misleading 200.
-  const messages = runOpenCodeDb<OpenCodeMessageRow>(
-    `SELECT id, session_id, time_created, time_updated, data FROM message WHERE session_id = '${sessionId}' ORDER BY time_created ASC`,
-  );
-  const parts = runOpenCodeDb<OpenCodePartRow>(
-    `SELECT id, message_id, session_id, time_created, time_updated, data FROM part WHERE session_id = '${sessionId}' ORDER BY time_created ASC`,
-  );
+  const messages = rows?.messages ?? null;
+  const parts = rows?.parts ?? null;
   if (messages === null || parts === null) return null;
   return {
     session: sessions[0],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "failproofai",
-  "version": "1.0.2-beta.4",
+  "version": "1.0.2-beta.5",
   "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",
@@ -120,15 +120,15 @@
     "sharp": "0.35.0"
   },
   "optionalDependencies": {
-    "@failproofai/failproofaid-linux-x64": "1.0.2-beta.4",
-    "@failproofai/failproofaid-linux-arm64": "1.0.2-beta.4",
-    "@failproofai/failproofaid-darwin-x64": "1.0.2-beta.4",
-    "@failproofai/failproofaid-darwin-arm64": "1.0.2-beta.4"
+    "@failproofai/failproofaid-linux-x64": "1.0.2-beta.5",
+    "@failproofai/failproofaid-linux-arm64": "1.0.2-beta.5",
+    "@failproofai/failproofaid-darwin-x64": "1.0.2-beta.5",
+    "@failproofai/failproofaid-darwin-arm64": "1.0.2-beta.5"
   },
   "failproofaidBinaries": {
-    "linux-x64": "08bc00a7f8d7c80bf898471ce59c57f4e96c1420080009cc933b2ddeb4f23750",
-    "linux-arm64": "1167d809628cff04c38efbc0eaa83ca26ab8de2878bed0ef59ca43054173eea7",
-    "darwin-x64": "6ed32db21af6869c4475e753e524ad8e128436674209ad778421b240a4bd5c53",
-    "darwin-arm64": "3843de034c9d6b11f77c1f423e6201ad6a77b7eff3b3d4460ba324c5aeb62021"
+    "linux-x64": "e19a1cf9a254df830f205fac024b8a229c162c93ae73851b985d2794e09da035",
+    "linux-arm64": "fafcff01e4cce00809b5cd9ff2822705d7373acbab79444e0384cb058b6da921",
+    "darwin-x64": "d7bd609387e13f5e75287674d948c69d739bac8d6963aa731b93111d1bdd2ea2",
+    "darwin-arm64": "9a57c8eb0f23ed25328e0f7b06638a6ab7f51e1deebf479bac2c779bf9912941"
   }
 }

package/src/audit/cache.ts

@@ -10,11 +10,11 @@
  * sessions live in a SQLite DB rather than a file with a stable mtime).
  */
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, openSync, readSync, closeSync } from "node:fs";
 import { join } from "node:path";
 import { BUILTIN_POLICIES } from "../hooks/builtin-policies";
 import { AUDIT_DETECTORS } from "./detectors";
-import type { TranscriptAuditResult } from "./types";
+import type { TranscriptAuditResult, DetectorSessionState } from "./types";
 import { auditCacheDir } from "../hooks/fp-home";
 
 let cachedEngineVersion: string | null = null;
@@ -110,7 +110,29 @@ function getCachePathFor(transcriptPath: string): string {
  * accidentally on some paths) so we reject them outright and force a
  * re-scan.
  */
-export const CACHE_SCHEMA_VERSION = 3;
+/**
+ * v4: entries carry `bytesScanned`, `anchorHash` and `detectorState` so a
+ * transcript that GREW can be resumed from where the last scan stopped
+ * instead of being read from byte zero. v3 entries have none of the three;
+ * they are rejected rather than treated as "scanned 0 bytes", which would
+ * re-scan everything anyway but silently, and rather than as "scanned it
+ * all", which would drop every event appended since.
+ */
+export const CACHE_SCHEMA_VERSION = 4;
+
+/**
+ * How much of the head and of the resume boundary is hashed to decide the
+ * bytes already scanned are still the same bytes.
+ *
+ * A transcript is append-only in normal operation, so a grown file is
+ * ordinarily the same file plus more. "Ordinarily" is not a guarantee: a
+ * compaction can rewrite one in place. Re-reading the whole prefix to be sure
+ * would cost exactly what this change exists to avoid, so two cheap windows
+ * stand in for it — the first bytes of the file, and the last bytes before the
+ * offset being resumed from. A rewrite that leaves both intact and diverges
+ * only in between is not a shape any of these writers produce.
+ */
+const ANCHOR_WINDOW = 4096;
 
 /** Hard expiry: a cached transcript result is rejected on read once it's
  *  this old. Keeps the audit pipeline honest about long-lived results that
@@ -141,39 +163,163 @@ interface CacheEntry {
   engineVersion: string;
   detectorVersion: string;
   result: TranscriptAuditResult;
+  /**
+   * How far into the file the recorded result actually accounts for, at a LINE
+   * boundary. Not the same as `sizeBytes`: a transcript being appended to while
+   * the audit reads it ends in a partial line, which is not parsed and must not
+   * be counted as scanned or the events in it are lost forever.
+   */
+  bytesScanned?: number;
+  /** Head + boundary fingerprint of the bytes already scanned. */
+  anchorHash?: string;
+  /** Stateful detectors' session state at `bytesScanned`, Map-aware encoded. */
+  detectorState?: string;
 }
 
-export function readCachedTranscriptResult(
+/** What a cache lookup can say. */
+export type CacheLookup =
+  | { kind: "hit"; result: TranscriptAuditResult }
+  | {
+      kind: "resume";
+      result: TranscriptAuditResult;
+      fromByte: number;
+      detectorState: DetectorSessionState;
+    };
+
+/**
+ * `Map` does not survive `JSON.stringify` — it encodes as `{}`, silently. The
+ * one stateful detector keeps its state in one, so a plain round-trip would
+ * hand back an empty countdown and quietly change what the detector finds
+ * across a resume boundary. Encoded generically rather than per-detector so a
+ * detector added later cannot forget to do it.
+ */
+function encodeDetectorState(state: DetectorSessionState): string {
+  return JSON.stringify(state, (_k, v) =>
+    v instanceof Map ? { __map: [...v.entries()] } : v,
+  );
+}
+
+function decodeDetectorState(raw: string | undefined): DetectorSessionState {
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw, (_k, v) =>
+      v && typeof v === "object" && Array.isArray((v as { __map?: unknown }).__map)
+        ? new Map((v as { __map: [unknown, unknown][] }).__map)
+        : v,
+    ) as DetectorSessionState;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * A fingerprint of the head of the file and of the bytes immediately before
+ * `upTo`, which together stand in for "the prefix has not been rewritten".
+ * Returns null when the file cannot be read that far — which is itself an
+ * answer: do not resume.
+ */
+export function anchorHashFor(transcriptPath: string, upTo: number): string | null {
+  if (upTo <= 0) return null;
+  let fd: number | null = null;
+  try {
+    fd = openSync(transcriptPath, "r");
+    const head = Buffer.alloc(Math.min(ANCHOR_WINDOW, upTo));
+    readSync(fd, head, 0, head.length, 0);
+    const tailLen = Math.min(ANCHOR_WINDOW, upTo);
+    const tail = Buffer.alloc(tailLen);
+    readSync(fd, tail, 0, tailLen, upTo - tailLen);
+    return createHash("sha1")
+      .update(String(upTo))
+      .update(head)
+      .update(tail)
+      .digest("hex")
+      .slice(0, 32);
+  } catch {
+    return null;
+  } finally {
+    if (fd !== null) {
+      try { closeSync(fd); } catch { /* nothing useful to do */ }
+    }
+  }
+}
+
+/**
+ * What the cache can offer for this transcript: everything, the part before it
+ * grew, or nothing.
+ *
+ * The exact-match case is unchanged and still the common one. What is new is
+ * the middle answer. Keying validity on `(mtime, size)` alone made the cache
+ * all-or-nothing per FILE, so a session gaining a single line was re-parsed and
+ * re-replayed from byte zero — and the files that gain lines are the long-lived
+ * ones, which are also the largest. The cost of an audit tracked the size of
+ * whatever was still being written to, rather than the amount actually written
+ * since last time.
+ */
+export function readCachedTranscript(
   transcriptPath: string,
   mtimeMs: number,
   sizeBytes: number,
-): TranscriptAuditResult | null {
-  if (sizeBytes === 0) return null; // OpenCode and other DB-backed sources
+): CacheLookup | null {
+  if (sizeBytes === 0) return null; // DB-backed sources have no file to key on
   const cachePath = getCachePathFor(transcriptPath);
   if (!existsSync(cachePath)) return null;
   try {
     const raw = readFileSync(cachePath, "utf-8");
     const entry = JSON.parse(raw) as Partial<CacheEntry>;
     if (entry.schemaVersion !== CACHE_SCHEMA_VERSION) return null;
-    if (entry.mtimeMs !== mtimeMs) return null;
-    if (entry.sizeBytes !== sizeBytes) return null;
     if (entry.engineVersion !== getEngineVersion()) return null;
     if (entry.detectorVersion !== getDetectorVersion()) 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.
     if (!Number.isFinite(entry.cachedAt) || Date.now() - (entry.cachedAt as number) > CACHE_TTL_MS) return null;
-    return entry.result ?? null;
+    if (!entry.result) return null;
+
+    if (entry.mtimeMs === mtimeMs && entry.sizeBytes === sizeBytes) {
+      return { kind: "hit", result: entry.result };
+    }
+
+    // Grew. Everything below has to hold before any of the recorded result can
+    // be trusted, and each one failing means a full re-scan rather than a
+    // guess.
+    const from = entry.bytesScanned;
+    if (!Number.isFinite(from) || (from as number) <= 0) return null;
+    if ((from as number) > sizeBytes) return null; // truncated, or rewritten shorter
+    if (!entry.anchorHash) return null;
+    if (anchorHashFor(transcriptPath, from as number) !== entry.anchorHash) return null;
+
+    return {
+      kind: "resume",
+      result: entry.result,
+      fromByte: from as number,
+      detectorState: decodeDetectorState(entry.detectorState),
+    };
   } catch {
     return null;
   }
 }
 
+/**
+ * The exact-match half on its own, for callers that cannot resume.
+ *
+ * Kept because "is this transcript already fully accounted for" is a question
+ * worth being able to ask without also being handed a partial answer to merge.
+ */
+export function readCachedTranscriptResult(
+  transcriptPath: string,
+  mtimeMs: number,
+  sizeBytes: number,
+): TranscriptAuditResult | null {
+  const found = readCachedTranscript(transcriptPath, mtimeMs, sizeBytes);
+  return found?.kind === "hit" ? found.result : null;
+}
+
 export function writeCachedTranscriptResult(
   transcriptPath: string,
   mtimeMs: number,
   sizeBytes: number,
   result: TranscriptAuditResult,
+  resume?: { bytesScanned: number; detectorState: DetectorSessionState },
 ): void {
   if (sizeBytes === 0) return;
   const cachePath = getCachePathFor(transcriptPath);
@@ -188,6 +334,18 @@ export function writeCachedTranscriptResult(
       detectorVersion: getDetectorVersion(),
       result,
     };
+    if (resume && resume.bytesScanned > 0) {
+      const anchor = anchorHashFor(transcriptPath, resume.bytesScanned);
+      // No anchor means no way to prove the prefix later, so the entry is
+      // written WITHOUT resume data: still a valid exact-match entry, just not
+      // a resumable one. Recording an offset we cannot verify would be worse
+      // than recording none.
+      if (anchor) {
+        entry.bytesScanned = resume.bytesScanned;
+        entry.anchorHash = anchor;
+        entry.detectorState = encodeDetectorState(resume.detectorState);
+      }
+    }
     // Set 0o600 at file-creation time so there's no window where the file
     // exists with the umask default (typically 0o644). The chmodSync below is
     // a belt-and-suspenders pass for the case where the file already existed.
@@ -198,8 +356,6 @@ export function writeCachedTranscriptResult(
   }
 }
 
-/** Test helper: reset memoized version hashes (so they recompute after a
- *  detector or policy is monkey-patched in a test). */
 export function _resetVersionCache(): void {
   cachedEngineVersion = null;
   cachedDetectorVersion = null;