@drakulavich/zapara 0.7.4 → 0.8.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-09-26
+
+### Added
+- zapara caches each transcript's parsed events between runs, in
+  `~/.claude/zapara/cache.db`, and reparses a file only when it has changed.
+  A row is a hit when its size, modification time and the SHA-256 of its
+  last 4 KiB all match the cached one; the row is keyed by the transcript's
+  device and inode, never by its path. On one machine, with nothing changed
+  since the run before, `zapara card --json --verbose` went from 4362 ms
+  (816 files read, 0 cache hits) to 246 ms (0 files read, 816 hits).
+  `--no-cache` runs without reading or writing the cache, and `--verbose`
+  gains a `cache` line with the hit and miss counts, or `off`.
+
+### Changed
+- A PNG card renders in about 0.7 s instead of 1.1 s on macOS. zapara opens
+  one browser view instead of two, and writes WebKit's screenshot as it is
+  when it already has the card's size, instead of encoding the same PNG a
+  second time. The file is about 2.6 MB instead of 2.1 MB: WebKit's PNG
+  encoder compresses less, and the pixels are the same.
+
 ## [0.7.4] - 2026-09-26
 
 ### Changed

package/README.md

@@ -135,7 +135,8 @@ If your card told you something about your week, star [the repository](https://g
 | `--projects <dir>` | Read this directory instead of `~/.claude/projects`. |
 | `--out <path>` | Where `card` writes instead of `~/Downloads`; the extension picks the format. |
 | `--no-color` | Plain glyphs and peaks with no ANSI codes. `NO_COLOR` in the environment does the same. |
-| `--verbose` | After the output, prints to stderr where the time went: files scanned and read, megabytes, and milliseconds for scanning, reading, analysis and the card's render, plus the zapara and Bun versions, platform and CPU count. Numbers only, no path, so the lines are safe to paste into an issue when zapara is slow on your machine. |
+| `--no-cache` | Read and parse every transcript again instead of using `~/.claude/zapara/cache.db`. |
+| `--verbose` | After the output, prints to stderr where the time went: files scanned and read, megabytes, cache hits and misses (or `off` with `--no-cache`, or when the cache could not be opened, including an empty `HOME`), and milliseconds for scanning, reading, analysis and the card's render, plus the zapara and Bun versions, platform and CPU count. Numbers only, no path, so the lines are safe to paste into an issue when zapara is slow on your machine. |
 | `-h`, `--help` | Usage, exit 0. |
 | `-V`, `--version` | The version from `package.json`, exit 0. |
 
@@ -171,7 +172,9 @@ Refreshing is the reader's job, and zapara adds no hook, no timer and no daemon.
 
 zapara reads `~/.claude/projects/**/*.jsonl`, skipping subagent transcripts under `subagents/`. It picks files by modification time first, and opens one whose modification time is older than the window only to read the last timestamp in its final 64 KB; nothing from that tail is kept or printed. It compares message text against a few fixed markers, for interrupts, tool rejections and inbound agent messages, then discards it. What survives into an event is a timestamp, a session id, an event kind and a token count.
 
-zapara keeps, writes and prints no message text, prompt length, file path or session title. The CLI never prints a path it derived or read, not even the projects root when it cannot open it. It sends nothing anywhere, writes no file except the card or the status file you ask for, and installs nothing into Claude Code.
+zapara keeps, writes and prints no message text, prompt length, file path or session title. The CLI never prints a path it derived or read, not even the projects root when it cannot open it. It sends nothing anywhere, writes no file except the card, the status file and the cache below, and installs nothing into Claude Code.
+
+Between runs, zapara caches each transcript's parsed events in `~/.claude/zapara/cache.db`. A hit still reads the last 4 KiB of the file to confirm it matches the cached row, then skips reading and parsing the rest. A row is keyed by the transcript's device and inode, never by its path or a hash of it. Besides the device and inode, a row stores a fingerprint of the parser that wrote it, the file's size and modification time, a hash of its last 4 KiB, the cutoff its events were parsed with, when the row was last used, and the parsed events themselves. No message text, prompt length, path or title is stored. `--no-cache` runs without reading or writing it.
 
 ## Limits
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/zapara",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "description": "Cognitive load index for people driving Claude Code, computed locally from transcripts",
   "license": "MIT",
   "author": "Anton Yakutovich",

package/src/analyze.ts

@@ -1,6 +1,6 @@
 import { compareStrings, derive, windowBounds } from "./derive.ts";
 import { parseTranscript } from "./parse.ts";
-import type { Day, Transcript, Window } from "./types.ts";
+import type { Day, Event, Transcript, Window } from "./types.ts";
 
 // Sorted by path so file discovery order cannot change a result.
 export function analyze(transcripts: Transcript[], w: Window): Day[] {
@@ -8,5 +8,10 @@ export function analyze(transcripts: Transcript[], w: Window): Day[] {
   const events = [...transcripts]
     .sort((a, b) => compareStrings(a.path, b.path))
     .flatMap((t) => parseTranscript(t.text, cutoffMs));
+  return analyzeEvents(events, w);
+}
+
+// Events already parsed, concatenated in path order as `analyze` does.
+export function analyzeEvents(events: Event[], w: Window): Day[] {
   return derive(events, w);
 }

package/src/cache.ts

@@ -0,0 +1,207 @@
+// The only module that uses bun:sqlite or writes the cache. The transcripts are
+// the system of record: every doubt here resolves to a miss, and no error leaves.
+import { Database } from "bun:sqlite";
+import { createHash } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { open } from "node:fs/promises";
+import { join } from "node:path";
+import type { ScanEntry } from "./scan.ts";
+import type { Event, EventKind } from "./types.ts";
+
+export type Fresh = { entry: ScanEntry; tail: Uint8Array; fromMs: number; events: Event[] };
+export type TranscriptCache = {
+  hits(entries: ScanEntry[], cutoffMs: number): Promise<Map<string, Event[]>>;
+  save(hit: ScanEntry[], fresh: Fresh[], nowMs: number): void;
+  close(): void;
+};
+
+const USER_VERSION = 1;
+const TAIL_BYTES = 4096;
+const READERS = 16;
+const KEEP_MS = 90 * 86_400_000;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const KINDS: Record<EventKind, true> = { prompt: true, report: true, output: true, interrupt: true, reject: true, answer: true, question: true, plan_review: true, mode_change: true, activity: true };
+
+export function tailHash(bytes: Uint8Array): Uint8Array {
+  return createHash("sha256").update(bytes.subarray(Math.max(0, bytes.length - TAIL_BYTES))).digest();
+}
+
+function fingerprint(): Uint8Array {
+  const h = createHash("sha256");
+  h.update(readFileSync(new URL("./parse.ts", import.meta.url)));
+  h.update(readFileSync(new URL("./types.ts", import.meta.url)));
+  h.update(String((JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version?: unknown }).version));
+  return h.digest();
+}
+
+function encode(events: Event[]): Uint8Array {
+  const sessions: string[] = [];
+  const index = new Map<string, number>();
+  const rows = events.map((e) => {
+    let i = index.get(e.sessionId);
+    if (i === undefined) { i = sessions.length; index.set(e.sessionId, i); sessions.push(e.sessionId); }
+    return e.tokens === undefined ? [e.ts, e.kind, i] : [e.ts, e.kind, i, e.tokens];
+  });
+  return new TextEncoder().encode(JSON.stringify({ sessions, events: rows }));
+}
+
+function decode(blob: Uint8Array): Event[] | null {
+  try {
+    const d: unknown = JSON.parse(new TextDecoder().decode(blob));
+    if (typeof d !== "object" || d === null) return null;
+    const { sessions, events } = d as { sessions?: unknown; events?: unknown };
+    if (!Array.isArray(sessions) || !sessions.every((s) => typeof s === "string") || !Array.isArray(events)) return null;
+    const out: Event[] = [];
+    for (const r of events) {
+      if (!Array.isArray(r) || r.length < 3 || r.length > 4) return null;
+      const [ts, kind, i, tokens] = r as unknown[];
+      if (typeof ts !== "number" || typeof kind !== "string" || !Object.hasOwn(KINDS, kind) || typeof i !== "number" || sessions[i] === undefined) return null;
+      const e: Event = { ts, sessionId: sessions[i] as string, kind: kind as EventKind };
+      if (r.length === 4) {
+        if (kind !== "output" || typeof tokens !== "number") return null;
+        e.tokens = tokens;
+      }
+      out.push(e);
+    }
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+// The bytes just before the stored offset, like a log consumer's check; the
+// size comparison is what notices a file that grew.
+async function readTail(path: string, size: number): Promise<Uint8Array | null> {
+  try {
+    const fh = await open(path, "r");
+    try {
+      const n = Math.min(TAIL_BYTES, size);
+      const buf = new Uint8Array(n);
+      const { bytesRead } = await fh.read(buf, 0, n, size - n);
+      return bytesRead === n ? buf : null;
+    } finally {
+      await fh.close();
+    }
+  } catch {
+    return null;
+  }
+}
+
+const equal = (a: Uint8Array, b: Uint8Array): boolean => a.length === b.length && a.every((x, i) => x === b[i]);
+
+type Row = { dev: number; ino: number; size: number; mtime_ms: number; tail: Uint8Array; from_ms: number; events: Uint8Array };
+
+class Foreign extends Error {}
+
+// Only a file that is not ours is replaced; a locked or unopenable one is left alone.
+const replaceable = (e: unknown): boolean =>
+  e instanceof Foreign || /^SQLITE_(NOTADB|CORRUPT)/.test(String((e as { code?: unknown } | null)?.code));
+
+function connect(path: string): Database {
+  const db = new Database(path, { create: true, strict: true });
+  try {
+    chmodSync(path, 0o600);
+    db.run("PRAGMA busy_timeout = 2000");
+    db.run("PRAGMA journal_mode = WAL");
+    db.run("PRAGMA synchronous = NORMAL");
+    db.transaction(() => {
+      const { user_version } = db.query<{ user_version: number }, []>("PRAGMA user_version").get()!;
+      if (user_version === USER_VERSION) return;
+      if (user_version !== 0) throw new Foreign();
+      db.run(`CREATE TABLE transcript (
+        dev INTEGER NOT NULL, ino INTEGER NOT NULL, parser BLOB NOT NULL, size INTEGER NOT NULL, mtime_ms REAL NOT NULL,
+        tail BLOB NOT NULL, from_ms REAL NOT NULL, used_at INTEGER NOT NULL, events BLOB NOT NULL, PRIMARY KEY (dev, ino))`);
+      db.run(`PRAGMA user_version = ${USER_VERSION}`);
+    }).immediate();
+    return db;
+  } catch (e) {
+    try { db.close(); } catch {}
+    throw e;
+  }
+}
+
+export function openCache(env: NodeJS.ProcessEnv): TranscriptCache | null {
+  const home = env.HOME;
+  if (!home) return null;
+  try {
+    const parser = fingerprint();
+    process.umask(0o077);
+    const dir = join(home, ".claude", "zapara");
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    const path = join(dir, "cache.db");
+    try {
+      return cacheOn(connect(path), parser);
+    } catch (e) {
+      if (!replaceable(e)) return null;
+    }
+    for (const f of [path, `${path}-wal`, `${path}-shm`]) rmSync(f, { force: true });
+    return cacheOn(connect(path), parser);
+  } catch {
+    return null;
+  }
+}
+
+function cacheOn(db: Database, parser: Uint8Array): TranscriptCache {
+  let failed = false;
+  return {
+    async hits(entries, cutoffMs) {
+      const found = new Map<string, Event[]>();
+      try {
+        const keyed = entries.filter((e) => e.ino !== 0);
+        const rows = db.query<Row, [Uint8Array, string]>(
+          `SELECT dev, ino, size, mtime_ms, tail, from_ms, events FROM transcript
+           WHERE parser = ? AND (dev, ino) IN (SELECT json_extract(value, '$[0]'), json_extract(value, '$[1]') FROM json_each(?))`,
+        ).all(parser, JSON.stringify(keyed.map((e) => [e.dev, e.ino])));
+        const byKey = new Map(rows.map((r) => [`${r.dev}:${r.ino}`, r]));
+        const candidates = keyed.flatMap((entry) => {
+          const row = byKey.get(`${entry.dev}:${entry.ino}`);
+          return row && row.size === entry.size && row.mtime_ms === entry.mtimeMs && row.from_ms <= cutoffMs ? [{ entry, row }] : [];
+        });
+        let next = 0;
+        const reader = async (): Promise<void> => {
+          while (next < candidates.length) {
+            const { entry, row } = candidates[next++]!;
+            const tail = await readTail(entry.path, row.size);
+            if (tail === null || !equal(tailHash(tail), row.tail)) continue;
+            const events = decode(row.events);
+            if (events !== null) found.set(entry.path, events);
+          }
+        };
+        await Promise.all(Array.from({ length: Math.min(READERS, candidates.length) }, reader));
+      } catch {
+        failed = true;
+        found.clear();
+      }
+      return found;
+    },
+
+    save(hit, fresh, nowMs) {
+      if (failed) return;
+      try {
+        const upsert = db.query(
+          `INSERT INTO transcript (dev, ino, parser, size, mtime_ms, tail, from_ms, used_at, events)
+           VALUES ($dev, $ino, $parser, $size, $mtime, $tail, $from, $now, $events)
+           ON CONFLICT(dev, ino) DO UPDATE SET parser = excluded.parser, size = excluded.size, mtime_ms = excluded.mtime_ms,
+             tail = excluded.tail, from_ms = excluded.from_ms, used_at = excluded.used_at, events = excluded.events
+           WHERE NOT (transcript.parser = excluded.parser AND transcript.size = excluded.size
+                      AND transcript.mtime_ms = excluded.mtime_ms AND transcript.tail = excluded.tail
+                      AND transcript.from_ms <= excluded.from_ms)`,
+        );
+        const touch = db.query("UPDATE transcript SET used_at = $now WHERE dev = $dev AND ino = $ino");
+        db.transaction(() => {
+          for (const { entry: e, tail, fromMs, events } of fresh) {
+            if (e.ino === 0 || !events.every((ev) => UUID.test(ev.sessionId))) continue;
+            upsert.run({ dev: e.dev, ino: e.ino, parser, size: e.size, mtime: e.mtimeMs, tail, from: fromMs, now: nowMs, events: encode(events) });
+          }
+          for (const e of hit) if (e.ino !== 0) touch.run({ now: nowMs, dev: e.dev, ino: e.ino });
+          db.run("DELETE FROM transcript WHERE used_at < ?", [nowMs - KEEP_MS]);
+        }).immediate();
+      } catch {}
+    },
+
+    close() {
+      try { db.close(); } catch {}
+    },
+  };
+}

package/src/image.ts

@@ -45,20 +45,19 @@ export async function renderCard(html: string, out: string, timeoutMs = 15_000):
         // 4800-wide shot, 2.2 s of a 3 s render. The viewport and the page's zoom
         // (2 in cardHtml) shrink by the density, so the shot is 2400 wide already.
         // Headless Chrome (or Edge) shoots at 1x and cannot evaluate before a navigate.
-        let dpr = 1;
-        if (BACKEND === "webkit") {
-          const probe = new Bun.WebView({ width: 1, height: 1, backend: BACKEND });
-          try { dpr = await probe.evaluate<number>("devicePixelRatio"); } finally { probe.close(); }
-        }
-        const view = new Bun.WebView({ width: Math.round(WIDTH / dpr), height: Math.round(HEIGHT / dpr), backend: BACKEND });
+        const view = new Bun.WebView({ width: WIDTH, height: HEIGHT, backend: BACKEND });
         try {
+          const dpr = BACKEND === "webkit" ? await view.evaluate<number>("devicePixelRatio") : 1;
+          if (dpr !== 1) await view.resize(Math.round(WIDTH / dpr), Math.round(HEIGHT / dpr));
           await view.navigate("data:text/html;charset=utf-8," + encodeURIComponent(html));
           await view.evaluate(`document.documentElement.style.zoom = "${2 / dpr}"`);
           while (!(await view.evaluate<boolean>(READY))) await Bun.sleep(50);
           const shot = await view.screenshot({ encoding: "buffer", format: "png" });
           const image = new Bun.Image(shot);
           const meta = await image.metadata();
-          if (meta.width !== WIDTH || meta.height !== HEIGHT) image.resize(WIDTH, HEIGHT, { fit: "fill" });
+          const sized = meta.width === WIDTH && meta.height === HEIGHT;
+          if (sized && !lower.endsWith(".webp")) return shot;
+          if (!sized) image.resize(WIDTH, HEIGHT, { fit: "fill" });
           return lower.endsWith(".webp") ? await image.webp({ quality: 90 }).bytes() : await image.png().bytes();
         } finally {
           view.close();

package/src/index.ts

@@ -3,6 +3,7 @@
 import { readFileSync, statSync } from "node:fs";
 import { cpus, homedir } from "node:os";
 import { join } from "node:path";
+import { openCache, type TranscriptCache } from "./cache.ts";
 import { cardData, sentenceText } from "./card.ts";
 import { cardHtml } from "./cardhtml.ts";
 import { localDate } from "./derive.ts";
@@ -40,6 +41,7 @@ options:
   --json            the same data as JSON; a pipe gets JSON without asking
   --projects <dir>  read this directory instead of ~/.claude/projects
   --no-color        no ANSI colors; NO_COLOR does the same
+  --no-cache        parse every transcript again
   --verbose         timings and counts on stderr, for a slow run
   -h, --help  -V, --version
 
@@ -48,7 +50,7 @@ levels: calm 0-29  warming 30-59  heating 60-84  fried 85-100
 bugs, ideas and a star: github.com/drakulavich/zapara`;
 const HINT = "run 'zapara --help' for usage";
 
-type Args = { command: "grid" | "day" | "card" | "status"; to: string; days: number; explain: boolean; json: boolean; out: string | null; projects: string; color: boolean; verbose: boolean };
+type Args = { command: "grid" | "day" | "card" | "status"; to: string; days: number; explain: boolean; json: boolean; out: string | null; projects: string; color: boolean; verbose: boolean; cache: boolean };
 
 class UsageError extends Error {}
 // Thrown only at a flag position, never for a token consumed as another flag's
@@ -99,7 +101,7 @@ function windowOf(days: string | null, from: string | null, to: string | null, d
 }
 
 function parseArgs(argv: string[], now: Date, env: NodeJS.ProcessEnv, isTTY: boolean): Args {
-  const a: Args = { command: "grid", to: localDate(now), days: 7, explain: false, json: false, out: null, projects: join(homedir(), ".claude", "projects"), color: isTTY && !env.NO_COLOR, verbose: false };
+  const a: Args = { command: "grid", to: localDate(now), days: 7, explain: false, json: false, out: null, projects: join(homedir(), ".claude", "projects"), color: isTTY && !env.NO_COLOR, verbose: false, cache: true };
   let days: string | null = null;
   let from: string | null = null;
   let to: string | null = null;
@@ -136,6 +138,7 @@ function parseArgs(argv: string[], now: Date, env: NodeJS.ProcessEnv, isTTY: boo
       case "--explain": bare(); a.explain = true; break;
       case "--no-color": bare(); a.color = false; break;
       case "--verbose": bare(); a.verbose = true; break;
+      case "--no-cache": bare(); a.cache = false; break;
       case "--projects": a.projects = value(); break;
       case "--from": from = value(); break;
       case "--to": to = value(); break;
@@ -176,13 +179,18 @@ async function main(): Promise<number> {
   const now = new Date();
   const a = parseArgs(argv, now, process.env, process.stdout.isTTY === true);
   const timing = a.verbose ? ({} as Timing) : undefined;
-  const code = a.command === "card" ? await card(a, timing) : a.command === "status" ? await status(a, now, timing) : await table(a, now, timing);
-  if (timing) process.stderr.write(timingLines(timing));
-  return code;
+  const cache = a.cache ? openCache(process.env) : null;
+  try {
+    const code = a.command === "card" ? await card(a, cache, timing) : a.command === "status" ? await status(a, now, cache, timing) : await table(a, now, cache, timing);
+    if (timing) process.stderr.write(timingLines(timing));
+    return code;
+  } finally {
+    cache?.close();
+  }
 }
 
-async function table(a: Args, now: Date, timing?: Timing): Promise<number> {
-  const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days, now }, timing);
+async function table(a: Args, now: Date, cache: TranscriptCache | null, timing?: Timing): Promise<number> {
+  const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days, now }, timing, cache);
   const data = a.command === "day" ? days[0] : days;
   if (a.json) console.log(renderJson(data!));
   else if (a.command === "day") console.log(renderDay(days[0]!, { explain: a.explain, color: a.color }));
@@ -191,8 +199,8 @@ async function table(a: Args, now: Date, timing?: Timing): Promise<number> {
 }
 
 // The write comes first: a caller never reads a line that was not saved.
-async function status(a: Args, now: Date, timing?: Timing): Promise<number> {
-  const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days, now }, timing);
+async function status(a: Args, now: Date, cache: TranscriptCache | null, timing?: Timing): Promise<number> {
+  const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days, now }, timing, cache);
   const line = renderStatus(statusOf(days[0]!, now));
   await writeStatus(line, process.env);
   process.stdout.write(line);
@@ -209,8 +217,8 @@ function cardTarget(out: string | null): { path: string; label: string } {
   return { path: join(dir, "zapara-card.png"), label: "zapara-card.png to Downloads" };
 }
 
-async function card(a: Args, timing?: Timing): Promise<number> {
-  const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days }, timing);
+async function card(a: Args, cache: TranscriptCache | null, timing?: Timing): Promise<number> {
+  const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days }, timing, cache);
   const data = cardData(days, { days: a.days });
   if (data === null) throw new Error(`no activity in the last ${a.days} days`);
   if (a.json) {
@@ -251,10 +259,11 @@ function timingLines(t: Timing): string {
   let ver = "?";
   try { ver = version(); } catch {}
   const row = (label: string, what: string, ms: number) => `${label.padEnd(8)}${what.padEnd(44)}${String(Math.round(ms)).padStart(7)} ms\n`;
-  const plural = (n: number, one: string) => `${n} ${one}${n === 1 ? "" : "s"}`;
+  const plural = (n: number, one: string, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
   return `zapara ${ver} · bun ${Bun.version} · ${process.platform} ${process.arch} · ${cpus().length} cpus\n`
     + row("scan", `${plural(t.files, "file")}, ${t.inWindow} in window, ${plural(t.tailChecks, "tail check")}`, t.scanMs)
     + row("read", `${plural(t.read, "file")}, ${(t.bytes / 1e6).toFixed(1)} MB, ${READERS} at a time`, t.readMs)
+    + `${"cache".padEnd(8)}${t.cache ? `${plural(t.cache.hits, "hit")}, ${plural(t.cache.misses, "miss", "misses")}` : "off"}\n`
     + row("analyze", "", t.analyzeMs)
     + (t.render ? row("render", t.render.format, t.render.ms) : "")
     + row("total", "", t.totalMs ?? performance.now());

package/src/report.ts

@@ -1,43 +1,75 @@
-import { readFile } from "node:fs/promises";
-import { analyze } from "./analyze.ts";
+import { open } from "node:fs/promises";
+import { analyzeEvents } from "./analyze.ts";
+import { tailHash, type Fresh, type TranscriptCache } from "./cache.ts";
 import { windowBounds } from "./derive.ts";
-import { scan, type ScanStats } from "./scan.ts";
-import type { Day, Transcript } from "./types.ts";
+import { parseTranscript } from "./parse.ts";
+import { scan, type ScanEntry, type ScanStats } from "./scan.ts";
+import type { Day, Event } from "./types.ts";
 
 export type ReportOptions = { projects: string; to: string; days: number; now?: Date };
 // What --verbose prints about a run: counts and milliseconds, never a path.
-export type Timing = ScanStats & { inWindow: number; read: number; bytes: number; scanMs: number; readMs: number; analyzeMs: number; render?: { format: string; ms: number }; totalMs?: number };
+export type Timing = ScanStats & { inWindow: number; read: number; bytes: number; cache: { hits: number; misses: number } | null; scanMs: number; readMs: number; analyzeMs: number; render?: { format: string; ms: number }; totalMs?: number };
 
 // Reading one file at a time left the disk idle between files: 1.6 GB took 5.4 s
 // sequentially and 0.9 s in parallel. The cap keeps open files well under the limit.
 export const READERS = 16;
 
-export async function report(o: ReportOptions, timing?: Timing): Promise<Day[]> {
+type Read = { bytes: Buffer; stable: ScanEntry | null };
+
+// `stable` only when both fstat agree and every byte was read: a file written
+// during the read is used for this run and never cached.
+async function readWhole(entry: ScanEntry): Promise<Read> {
+  const fh = await open(entry.path, "r");
+  try {
+    const before = await fh.stat();
+    const bytes = await fh.readFile();
+    const after = await fh.stat();
+    const same = before.dev === after.dev && before.ino === after.ino && before.size === after.size && before.mtimeMs === after.mtimeMs && before.size === bytes.length;
+    return { bytes, stable: same ? { path: entry.path, dev: after.dev, ino: after.ino, size: after.size, mtimeMs: after.mtimeMs } : null };
+  } finally {
+    await fh.close();
+  }
+}
+
+export async function report(o: ReportOptions, timing?: Timing, cache?: TranscriptCache | null): Promise<Day[]> {
   const window = { to: o.to, days: o.days, now: o.now };
+  const { cutoffMs } = windowBounds(window);
   const stats: ScanStats = { files: 0, tailChecks: 0 };
   let t = performance.now();
-  const paths = await scan(o.projects, windowBounds(window).cutoffMs, stats);
+  const entries = await scan(o.projects, cutoffMs, stats);
   const scanMs = performance.now() - t;
   t = performance.now();
-  const texts: (string | null)[] = new Array(paths.length).fill(null);
+  const hits = cache ? await cache.hits(entries, cutoffMs) : new Map<string, Event[]>();
+  const misses = entries.filter((e) => !hits.has(e.path));
+  const reads = new Map<string, Read>();
   let next = 0;
   let bytes = 0;
   const reader = async (): Promise<void> => {
-    while (next < paths.length) {
-      const i = next++;
+    while (next < misses.length) {
+      const entry = misses[next++]!;
       try {
-        const buf = await readFile(paths[i]!);
-        bytes += buf.length;
-        texts[i] = buf.toString("utf8");
+        const r = await readWhole(entry);
+        bytes += r.bytes.length;
+        reads.set(entry.path, r);
       } catch { /* vanished or unreadable: skip */ }
     }
   };
-  await Promise.all(Array.from({ length: Math.min(READERS, paths.length) }, reader));
+  await Promise.all(Array.from({ length: Math.min(READERS, misses.length) }, reader));
   const readMs = performance.now() - t;
-  const transcripts: Transcript[] = [];
-  paths.forEach((path, i) => { if (texts[i] !== null) transcripts.push({ path, text: texts[i]! }); });
   t = performance.now();
-  const days = analyze(transcripts, window);
-  if (timing) Object.assign(timing, { ...stats, inWindow: paths.length, read: transcripts.length, bytes, scanMs, readMs, analyzeMs: performance.now() - t });
+  const fresh: Fresh[] = [];
+  const events = entries.flatMap((e) => {
+    const hit = hits.get(e.path);
+    if (hit) return hit;
+    const r = reads.get(e.path);
+    if (!r) return [];
+    const parsed = parseTranscript(r.bytes.toString("utf8"), cutoffMs);
+    if (r.stable) fresh.push({ entry: r.stable, tail: tailHash(r.bytes), fromMs: cutoffMs, events: parsed });
+    return parsed;
+  });
+  const days = analyzeEvents(events, window);
+  const analyzeMs = performance.now() - t;
+  cache?.save(entries.filter((e) => hits.has(e.path)), fresh, Date.now());
+  if (timing) Object.assign(timing, { ...stats, inWindow: entries.length, read: reads.size, bytes, cache: cache ? { hits: hits.size, misses: misses.length } : null, scanMs, readMs, analyzeMs });
   return days;
 }

package/src/scan.ts

@@ -1,13 +1,15 @@
 import type { Dirent } from "node:fs";
 import { open, readdir, stat } from "node:fs/promises";
 import { join } from "node:path";
+import { compareStrings } from "./derive.ts";
 
 // What --verbose reports about the walk: transcripts seen, and how many of them
 // were opened only to read the tail of a file older than the window by mtime.
 export type ScanStats = { files: number; tailChecks: number };
+export type ScanEntry = { path: string; dev: number; ino: number; size: number; mtimeMs: number };
 
 // A `subagents` directory holds the parent agent's conversation, not the human's.
-export async function scan(projects: string, cutoffMs: number, stats: ScanStats = { files: 0, tailChecks: 0 }): Promise<string[]> {
+export async function scan(projects: string, cutoffMs: number, stats: ScanStats = { files: 0, tailChecks: 0 }): Promise<ScanEntry[]> {
   // No path in either message: the CLI never prints one.
   let root;
   try {
@@ -18,14 +20,14 @@ export async function scan(projects: string, cutoffMs: number, stats: ScanStats
     if (code === "EACCES" || code === "EPERM") throw new Error("projects directory cannot be read (check its permissions)");
     throw new Error("projects directory not found (pass --projects <dir>)");
   }
-  const out: string[] = [];
+  const out: ScanEntry[] = [];
   await collect(projects, root, cutoffMs, out, stats);
-  return out.sort();
+  return out.sort((a, b) => compareStrings(a.path, b.path));
 }
 
 // One unreadable directory costs only itself. Symlinks are not followed: Claude
 // Code never writes one, and following one is how a loop or $HOME would get in.
-async function collect(dir: string, entries: Dirent[], cutoffMs: number, out: string[], stats: ScanStats): Promise<void> {
+async function collect(dir: string, entries: Dirent[], cutoffMs: number, out: ScanEntry[], stats: ScanStats): Promise<void> {
   for (const entry of entries) {
     const full = join(dir, entry.name);
     if (entry.isDirectory()) {
@@ -36,11 +38,12 @@ async function collect(dir: string, entries: Dirent[], cutoffMs: number, out: st
     } else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
       stats.files++;
       try {
-        if ((await stat(full)).mtimeMs >= cutoffMs) out.push(full);
-        else {
+        const st = await stat(full);
+        if (st.mtimeMs < cutoffMs) {
           stats.tailChecks++;
-          if ((await lastTimestampMs(full)) >= cutoffMs) out.push(full);
+          if ((await lastTimestampMs(full)) < cutoffMs) continue;
         }
+        out.push({ path: full, dev: st.dev, ino: st.ino, size: st.size, mtimeMs: st.mtimeMs });
       } catch {}
     }
   }