@promptctl/cc-candybar 1.17.4 → 1.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.17.4",
+  "version": "1.18.0",
   "description": "Statusline renderer for Claude Code — a JSON5-configurable DSL with daemon-cached data sources, byte-clean palette-aware composition, and OSC8 click verbs.",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -24,6 +24,10 @@
     "test:coverage": "jest --coverage",
     "demo": "tsx src/demo/dsl.ts",
     "benchmark:timing": "scripts/benchmark_timing.sh",
+    "preloadtest": "pnpm build",
+    "loadtest": "node --import tsx scripts/daemon-load-harness.ts",
+    "preloadtest:gate": "pnpm build",
+    "loadtest:gate": "node --import tsx scripts/daemon-load-harness.ts --sessions 25 --interval 300 --duration 20 --churn --transcript-lines 5000",
     "check:protocol": "node scripts/check-protocol.mjs",
     "gen:schema": "tsx scripts/gen-schema.ts",
     "check:schema": "tsx scripts/check-schema.ts",
@@ -91,10 +95,10 @@
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.17.4",
-    "@promptctl/cc-candybar-darwin-x64": "1.17.4",
-    "@promptctl/cc-candybar-linux-x64": "1.17.4",
-    "@promptctl/cc-candybar-linux-arm64": "1.17.4"
+    "@promptctl/cc-candybar-darwin-arm64": "1.18.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.18.0",
+    "@promptctl/cc-candybar-linux-x64": "1.18.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.18.0"
   },
   "pnpm": {
     "supportedArchitectures": {

package/src/config/default-dsl-config.ts

@@ -627,15 +627,18 @@ export const DEFAULT_DSL_CONFIG = {
       fg: "foreground",
       when: '{{ or (ne .git.prUrl "") (ne .git.prError "") }}',
     },
-    // Quick-action tray — copy the session id / cwd, open the project dir /
-    // transcript in the editor. [LAW:locality-or-seam] The glyph is the
-    // REPRESENTATION; the named action (below) is the BEHAVIOR; the action
-    // name is the seam between them. Re-glyph without touching behavior;
-    // re-target without touching this template. Each `{{ action … }}` emits
-    // one OSC-8 clickable region whose URL the wire codec owns end-to-end.
+    // Quick-action tray — the default bar's interactivity: copy the session id,
+    // open the project dir / transcript (this session's jsonl) in the editor.
+    // (copyDir — copy the cwd — stays declared as an action below for users who
+    // want a fourth glyph; it is simply not in the default tray.)
+    // [LAW:locality-or-seam] The glyph is the REPRESENTATION; the named action
+    // (below) is the BEHAVIOR; the action name is the seam between them. Re-glyph
+    // without touching behavior; re-target without touching this template. Each
+    // `{{ action … }}` emits one OSC-8 clickable region whose URL the wire codec
+    // owns end-to-end.
     toolbar: {
       template:
-        '{{ action "copySession" "⎘ id" }} {{ action "copyDir" "⎘ cwd" }}' +
+        '{{ action "copySession" "⎘ id" }}' +
         ' {{ action "openProject" "↗ proj" }} {{ action "openTranscript" "↗ log" }}',
       bg: "surface",
       fg: "foreground",
@@ -808,11 +811,24 @@ export const DEFAULT_DSL_CONFIG = {
   // Default layout — the canonical LayoutNode tree (`satisfies DslConfig`
   // requires the lowered form here; the terse Option-A `{ h/v/seg }` grammar is
   // the loader's authoring surface for user JSON, not this typed literal).
-  // [LAW:dataflow-not-control-flow] One always-on control row. The styleControl's
-  // {{ menu }} disclosure drops its picker body onto the line directly below this
-  // row when open — openness is the value of the derived menus.* key, NOT a when-
-  // gated reveal row. The picker draws the ✕/←/→ affordances from the page + term
-  // width; the vertical container stacks the dropped body under row 0.
+  //
+  // Two rows stacked by the vertical container: an IDENTITY + ACTIONS row
+  // (where am I / what can I do here — the directory, the verbose `gitaculous`
+  // line (repo, sha, working-tree, upstream, stash, time-since-commit), then the
+  // quick-action tray: copy session id, open project / transcript in the editor)
+  // over a STATUS row (what's happening now — model, context-window fill,
+  // prompt-cache warmth, and the 5h / 7d rate-limit quotas). The tray sits on
+  // the identity row because its actions are workspace-scoped (this session,
+  // this project), not usage metrics. Each row zips its segments through the
+  // powerline joiner; `\n` separates the rows.
+  //
+  // [LAW:dataflow-not-control-flow] Every status segment is when-gated on its
+  // own signal (no repo → the identity row is just the directory + tray; no
+  // active rate-limit window → block/weekly drop; no cache activity → cacheTimer
+  // drops). A row therefore only ever shows the segments that have real data —
+  // the layout is chosen by the data, not by branches — so the default never
+  // paints an empty or placeholder cell. The directory and the tray have no
+  // `when`, so row 1 always anchors the bar.
   root: {
     kind: "container",
     direction: "vertical",
@@ -822,13 +838,19 @@ export const DEFAULT_DSL_CONFIG = {
         direction: "horizontal",
         children: [
           { kind: "segment", name: "directory" },
-          { kind: "segment", name: "git" },
+          { kind: "segment", name: "gitaculous" },
+          { kind: "segment", name: "toolbar" },
+        ],
+      },
+      {
+        kind: "container",
+        direction: "horizontal",
+        children: [
           { kind: "segment", name: "model" },
-          { kind: "segment", name: "session" },
-          { kind: "segment", name: "today" },
           { kind: "segment", name: "context" },
-          { kind: "segment", name: "toolbar" },
-          { kind: "segment", name: "styleControl" },
+          { kind: "segment", name: "cacheTimer" },
+          { kind: "segment", name: "block" },
+          { kind: "segment", name: "weekly" },
         ],
       },
     ],

package/src/daemon/cache/session-usage-store.ts

@@ -1,23 +1,26 @@
-import fs from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 
 import {
-  SessionProvider,
   type SessionInfo,
-  type SessionUsage,
   type UsageInfo,
   type TokenBreakdown,
 } from "../../segments/session";
+import { PricingService } from "../../segments/pricing";
 import {
   getClaudePaths,
   findProjectPaths,
+  findAgentTranscripts,
+  readAppendedEntries,
   type ClaudeHookData,
+  type ParsedEntry,
+  type TranscriptCursor,
 } from "../../utils/claude";
 // [LAW:single-enforcer] The once-per-day seed's directory walk shares the same
 // in-flight-I/O budget (gn4.2) as every other transcript scan.
 import {
   readdir as gatedReaddir,
   stat as gatedStat,
+  statMtimeMs,
 } from "../../utils/transcript-fs";
 import { SingleFlight } from "../../utils/single-flight";
 import { ABSENT, failed, ok, type Outcome } from "../../utils/outcome";
@@ -105,6 +108,10 @@ interface DayUsage {
 }
 
 interface SessionRecord {
+  // [LAW:one-source-of-truth] `files` is canonical (main transcript + agent
+  // sidechains, each its own incremental FileFold); `sessionInfo`/`days` are
+  // derived from mergeFolds and re-synced on every ingest — the single writer.
+  files: Map<string, FileFold>;
   sessionInfo: SessionInfo;
   days: Map<string, DayUsage>;
   transcriptMtime: number;
@@ -152,33 +159,119 @@ function seedCutoffMs(): number {
   return d.getTime();
 }
 
-function statMtimeMs(filePath: string | undefined): number {
-  if (!filePath) return 0;
-  try {
-    return fs.statSync(filePath).mtimeMs;
-  } catch {
-    return 0;
-  }
+function emptyBreakdown(): TokenBreakdown {
+  return { input: 0, output: 0, cacheCreation: 0, cacheRead: 0 };
+}
+
+// [LAW:one-source-of-truth] The incremental fold of ONE append-only transcript
+// file (a session's main transcript or one agent sidechain). `cursor` marks the
+// bytes already folded; the sums run over every usage-bearing entry seen so far.
+// The session aggregate is the MERGE of its files' folds (mergeFolds), so a file
+// rewritten by /compact re-folds in isolation without disturbing the others.
+interface FileFold {
+  cursor: TranscriptCursor;
+  entries: number; // usage-bearing entries folded (0 ⇒ empty session, all-null)
+  cost: number;
+  breakdown: TokenBreakdown;
+  days: Map<string, DayUsage>; // keys >= seed cutoff only (pruned on fold)
 }
 
-// dayKey strings sort lexically == chronologically, so "keep recent" is a
-// string comparison against yesterday's key.
-function bucketByDay(usage: SessionUsage): Map<string, DayUsage> {
+// [LAW:effects-at-boundaries] Pure fold of NEW entries onto a prior file fold.
+// Returns a FRESH FileFold (prior is never mutated) so two concurrent refolds
+// sharing one prior snapshot can't corrupt each other. `reset` (file rewritten)
+// discards the prior sums and folds `entries` — the whole new file — from zero.
+//
+// [LAW:one-source-of-truth] Session cost and day cost use the SAME priced value:
+// an entry lacking costUSD is priced once (PricingService) and that figure feeds
+// BOTH the session total and its day bucket. This matches the old path exactly —
+// it mutated entry.costUSD to the priced cost before bucketByDay read it — so
+// `today` is not silently under-counted for un-costed entries.
+async function foldFile(
+  prior: FileFold | undefined,
+  reset: boolean,
+  entries: readonly ParsedEntry[],
+  cursor: TranscriptCursor,
+): Promise<FileFold> {
+  // dayKey strings sort lexically == chronologically, so "keep recent" is a
+  // string comparison against yesterday's key.
   const keep = dayKey(new Date(seedCutoffMs()));
+  const base = prior && !reset ? prior : undefined;
+  let count = base?.entries ?? 0;
+  let cost = base?.cost ?? 0;
+  const breakdown = base ? { ...base.breakdown } : emptyBreakdown();
   const days = new Map<string, DayUsage>();
-  for (const entry of usage.entries) {
+  if (base) {
+    for (const [k, v] of base.days) if (k >= keep) days.set(k, { ...v });
+  }
+  for (const entry of entries) {
+    const u = entry.message?.usage;
+    if (!u) continue;
+    count++;
+    const priced =
+      entry.costUSD ?? (await PricingService.calculateCostForEntry(entry.raw));
+    cost += priced;
+    breakdown.input += u.input_tokens || 0;
+    breakdown.output += u.output_tokens || 0;
+    breakdown.cacheCreation += u.cache_creation_input_tokens || 0;
+    breakdown.cacheRead += u.cache_read_input_tokens || 0;
     const key = dayKey(new Date(entry.timestamp));
     if (key < keep) continue;
     const d = days.get(key) ?? { ...EMPTY_DAY };
-    const u = entry.message.usage;
-    d.cost += entry.costUSD ?? 0;
+    // [LAW:one-source-of-truth] Day cost uses the PRICED value, same as session
+    // cost — the old path mutated entry.costUSD to the priced cost before
+    // bucketByDay read it, so an un-costed entry contributed its priced value to
+    // `today`, not 0. Using `priced` here preserves that (session and day agree).
+    d.cost += priced;
     d.input += u.input_tokens || 0;
     d.output += u.output_tokens || 0;
     d.cacheCreation += u.cache_creation_input_tokens || 0;
     d.cacheRead += u.cache_read_input_tokens || 0;
     days.set(key, d);
   }
-  return days;
+  return { cursor, entries: count, cost, breakdown, days };
+}
+
+// [LAW:effects-at-boundaries] Pure merge of a session's file folds into the
+// derived record shape the read path serves. `entries === 0` across all files is
+// the empty session (all-null SessionInfo, whose fields the payload drops) — the
+// same distinction the old `entries.length === 0` arm carried.
+function mergeFolds(files: ReadonlyMap<string, FileFold>): {
+  sessionInfo: SessionInfo;
+  days: Map<string, DayUsage>;
+} {
+  let count = 0;
+  let cost = 0;
+  const bd = emptyBreakdown();
+  const days = new Map<string, DayUsage>();
+  for (const f of files.values()) {
+    count += f.entries;
+    cost += f.cost;
+    bd.input += f.breakdown.input;
+    bd.output += f.breakdown.output;
+    bd.cacheCreation += f.breakdown.cacheCreation;
+    bd.cacheRead += f.breakdown.cacheRead;
+    for (const [k, v] of f.days) {
+      const d = days.get(k) ?? { ...EMPTY_DAY };
+      d.cost += v.cost;
+      d.input += v.input;
+      d.output += v.output;
+      d.cacheCreation += v.cacheCreation;
+      d.cacheRead += v.cacheRead;
+      days.set(k, d);
+    }
+  }
+  if (count === 0) return { sessionInfo: EMPTY_SESSION_INFO, days };
+  const tokens = bd.input + bd.output + bd.cacheCreation + bd.cacheRead;
+  return {
+    sessionInfo: {
+      cost,
+      calculatedCost: cost,
+      officialCost: null,
+      tokens,
+      tokenBreakdown: bd,
+    },
+    days,
+  };
 }
 
 // Bounded-concurrency fan-out for the seed: at most `limit` parses in flight.
@@ -201,7 +294,6 @@ async function mapPool<T>(
 }
 
 export class SessionUsageStore {
-  private readonly sessions = new SessionProvider();
   private readonly entries = new Map<string, SessionRecord>();
   // [LAW:one-source-of-truth] Coalesces concurrent MISSES for the same
   // (session, observed mtime) onto one parse; cleared on settle (a coalescer,
@@ -424,15 +516,49 @@ export class SessionUsageStore {
     if (!transcriptPath) return existing ? ok(existing) : ABSENT;
 
     this.misses++;
-    const aggregate = await this.flight.run(`${sessionId}:${mtime}`, () =>
-      this.aggregate(sessionId, transcriptPath),
-    );
-    if (aggregate.kind !== "ok") return aggregate;
-    // Tag with the mtime observed AFTER the read so the next render that sees
-    // the same mtime is a safe hit.
+    // [LAW:no-ambient-temporal-coupling] The flight thunk snapshots the prior
+    // record when it RUNS (first caller); coalesced callers share that one
+    // refold. Two concurrent DIFFERENT-mtime refolds each read the same prior and
+    // last-writer-wins. This is safe — and specifically NOT a double-count —
+    // because `refold` writes the byte cursor and the fold as ONE atomic pair
+    // (both from a single refold result), and the fold always covers exactly
+    // [0, cursor). A losing writer's fold is discarded WITH its cursor, not left
+    // beside a stale one. So even when last-writer-wins rewinds the stored cursor,
+    // it rewinds the paired fold with it; the next refold folds [cursor, end) onto
+    // a fold that lacks those bytes — each byte folded once. `foldFile` is pure
+    // (fresh FileFold, prior never mutated), so the shared prior can't corrupt.
+    // Pinned by the concurrency test in test/transcript-incremental.test.ts.
+    // The prior is read when the thunk RUNS. If evictIfNeeded dropped this
+    // session between thunk creation and run, prior is undefined and refold does
+    // one whole-file re-fold — still correct, just non-incremental that once.
+    // (Eviction only fires after a successful write, so this can bite only on a
+    // first miss under cap pressure.)
+    // [LAW:no-silent-failure] ingest MUST stay total — every caller reads
+    // `.kind`, so a rejected promise (e.g. PricingService.calculateCostForEntry
+    // throwing on a bad rate table or network hiccup inside foldFile) would
+    // escape the Outcome contract entirely. The deleted getSessionUsageFromPath
+    // wrapped this; keep that guarantee by mapping any throw to `failed`.
+    let outcome: Outcome<{
+      files: Map<string, FileFold>;
+      sessionInfo: SessionInfo;
+      days: Map<string, DayUsage>;
+      mainMtime: number;
+    }>;
+    try {
+      outcome = await this.flight.run(`${sessionId}:${mtime}`, () =>
+        this.refold(sessionId, transcriptPath, this.entries.get(sessionId)),
+      );
+    } catch (error) {
+      return failed(
+        `usage refold (${sessionId}): ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+    if (outcome.kind !== "ok") return outcome;
     const record: SessionRecord = {
-      ...aggregate.value,
-      transcriptMtime: statMtimeMs(transcriptPath),
+      files: outcome.value.files,
+      sessionInfo: outcome.value.sessionInfo,
+      days: outcome.value.days,
+      transcriptMtime: outcome.value.mainMtime,
       transcriptPath,
       lastSeenAt: Date.now(),
     };
@@ -442,23 +568,54 @@ export class SessionUsageStore {
     return ok(record);
   }
 
-  private async aggregate(
+  // [LAW:dataflow-not-control-flow] Re-fold ONLY the bytes appended since the
+  // prior record — the transcript (and each agent sidechain) is append-only, so
+  // per-render work is O(new bytes), not O(file). The whole-file case (cold
+  // record, or a first-ever read) is the same path with an empty prior: the
+  // reader yields the whole file from offset 0. A `failed` read on any file
+  // fails the fold (the boundary logs it); an `absent` file (not yet written /
+  // agent removed) keeps its prior fold and contributes nothing new.
+  private async refold(
     sessionId: string,
     transcriptPath: string,
+    prior: SessionRecord | undefined,
   ): Promise<
-    Outcome<{ sessionInfo: SessionInfo; days: Map<string, DayUsage> }>
+    Outcome<{
+      files: Map<string, FileFold>;
+      sessionInfo: SessionInfo;
+      days: Map<string, DayUsage>;
+      mainMtime: number;
+    }>
   > {
-    const usage = await this.sessions.getSessionUsageFromPath(
+    // File set for this fold: the main transcript plus the session's current
+    // agent sidechains. Files no longer in the set (a removed sidechain) drop
+    // out of `newFiles`, so a rewritten/renamed file cannot linger in the merge.
+    // Pass the prior file set so already-verified agent sidechains skip their
+    // first-line re-read — per-render agent discovery is O(new sidechains).
+    const agentPaths = await findAgentTranscripts(
       sessionId,
-      transcriptPath,
+      dirname(transcriptPath),
+      prior === undefined ? undefined : new Set(prior.files.keys()),
     );
-    // getSessionUsageFromPath never produces absent (an empty transcript is a
-    // real zero-entry usage); failed passes through to the boundary.
-    if (usage.kind !== "ok") return usage;
-    return ok({
-      sessionInfo: this.sessions.toSessionInfo(usage.value),
-      days: bucketByDay(usage.value),
-    });
+    const newFiles = new Map<string, FileFold>();
+    let mainMtime = 0;
+    for (const filePath of [transcriptPath, ...agentPaths]) {
+      const priorFold = prior?.files.get(filePath);
+      const read = await readAppendedEntries(filePath, priorFold?.cursor);
+      if (read.kind === "failed") return read;
+      if (read.kind === "absent") {
+        // The file has no bytes yet (fresh main) or vanished (removed agent
+        // sidechain). Carry a prior fold forward; otherwise it contributes
+        // nothing. The main transcript's absence leaves mainMtime 0, so the next
+        // render's mtime gate re-attempts rather than caching an empty read.
+        if (priorFold) newFiles.set(filePath, priorFold);
+        continue;
+      }
+      const { entries, cursor, reset } = read.value;
+      newFiles.set(filePath, await foldFile(priorFold, reset, entries, cursor));
+      if (filePath === transcriptPath) mainMtime = cursor.mtimeMs;
+    }
+    return ok({ files: newFiles, ...mergeFolds(newFiles), mainMtime });
   }
 
   private ensureSeeded(day: string): Promise<void> {

package/src/segments/metrics.ts

@@ -1,10 +1,14 @@
 import type { ClaudeHookData, ParsedEntry } from "../utils/claude";
 
-// [LAW:one-source-of-truth] Metrics reads the transcript through the shared
-// mtime-keyed parse LRU — the same parse the session/context segments already
-// performed this render — instead of a private readFile+parse. One parse path,
-// one cache; the multi-MB content arrays are dropped at parse time.
-import { parseJsonlFile } from "../utils/claude";
+// [LAW:one-source-of-truth] Metrics reads the transcript through the SAME
+// incremental append reader the usage store uses, folding only the bytes added
+// since last render into a running message count + a bounded recent-entry ring —
+// never a whole-file re-parse. Before this, metrics re-parsed the entire growing
+// transcript every render (free only while it piggybacked the store's cache hit);
+// once the store went incremental, a full re-parse here would have re-inherited
+// the very stall the store fix removed. Now both consumers are O(new bytes).
+import { readAppendedEntries, type TranscriptCursor } from "../utils/claude";
+import { statMtimeMs } from "../utils/transcript-fs";
 import { debug } from "../utils/logger";
 import { ABSENT, failed, ok, type Outcome } from "../utils/outcome";
 
@@ -21,6 +25,25 @@ export interface MetricsInfo {
   linesRemoved: number;
 }
 
+// lastResponseTime only inspects the most recent turns for a user→assistant
+// pair; a bounded tail of non-sidechain entries is all it needs. The ring caps
+// per-session retained memory at O(1) regardless of transcript length.
+const RECENT_WINDOW = 20;
+// Bound the per-session fold map like the usage store's records — a long-lived
+// daemon sees many sessions; the ring is tiny, but the map must not grow without
+// limit. LRU by insertion order (delete+set on write), evict oldest past the cap.
+const MAX_SESSIONS = 256;
+
+// [LAW:one-source-of-truth] The incremental fold of one session's metrics: the
+// byte cursor already consumed, the running real-user message count, and the
+// recent-entry ring. Canonical; MetricsInfo's transcript-derived fields derive
+// from it, the hookData-derived fields (durations, lines) are always fresh.
+interface MetricsState {
+  cursor: TranscriptCursor;
+  messageCount: number;
+  recent: ParsedEntry[];
+}
+
 // A real user turn vs. a tool_result echoed back as a "user" line. The
 // discriminator is metrics-local policy over the shared ParsedEntry scalars.
 function isRealUserMessage(entry: ParsedEntry): boolean {
@@ -31,19 +54,17 @@ function isRealUserMessage(entry: ParsedEntry): boolean {
 }
 
 export class MetricsProvider {
-  private calculateMessageCount(entries: ParsedEntry[]): number {
-    return entries.filter(isRealUserMessage).length;
-  }
+  // [LAW:no-shared-mutable-globals] Single owner, hard cap, LRU eviction — the
+  // per-session incremental fold state. One instance per daemon.
+  private readonly state = new Map<string, MetricsState>();
 
   private calculateLastResponseTime(entries: ParsedEntry[]): number | null {
     if (entries.length === 0) return null;
 
-    const recentEntries = entries.slice(-20);
-
     let lastUserTime: Date | null = null;
     let bestResponseTime: number | null = null;
 
-    for (const entry of recentEntries) {
+    for (const entry of entries) {
       const messageType =
         entry.type || entry.message?.role || entry.message?.type;
 
@@ -61,6 +82,80 @@ export class MetricsProvider {
     return bestResponseTime;
   }
 
+  // [LAW:dataflow-not-control-flow] Fold the appended entries onto the prior
+  // state, producing a FRESH state (prior is never mutated) so two concurrent
+  // renders of one session both fold from the same prior and last-writer-wins is
+  // a correct answer, never a double-count. `reset` (a /compact rewrite) folds
+  // from empty. Returns the transcript-derived fields the caller composes with
+  // the always-fresh hookData fields.
+  private async foldMetrics(
+    sessionId: string,
+    transcriptPath: string,
+  ): Promise<
+    // [LAW:types-are-the-program] Never `absent` — a missing transcript is a real
+    // zero-count fold (ok), so the caller has exactly two arms to handle.
+    | { kind: "ok"; value: { messageCount: number; recent: ParsedEntry[] } }
+    | { kind: "failed"; reason: string }
+  > {
+    const prior = this.state.get(sessionId);
+    const mtime = statMtimeMs(transcriptPath);
+    // [LAW:no-ambient-temporal-coupling] Fast hit: the transcript is unchanged
+    // since we last folded it, so the message count + ring stand.
+    if (prior && mtime !== 0 && prior.cursor.mtimeMs === mtime) {
+      // [LAW:no-ambient-temporal-coupling] Re-order on the hit so LRU eviction
+      // reflects READ recency, not just write recency — an active session whose
+      // transcript is momentarily unchanged must not be evicted ahead of idle
+      // ones (matches the usage store's hit path).
+      this.state.delete(sessionId);
+      this.state.set(sessionId, prior);
+      // [LAW:no-shared-mutable-globals] Return a COPY of the stored ring, never
+      // the reference — a caller mutating the returned array would silently
+      // corrupt the retained state (a heisenbug in the next render's
+      // lastResponseTime). Every path (hit/miss/absent) copies. 20 entries.
+      return {
+        kind: "ok",
+        value: { messageCount: prior.messageCount, recent: [...prior.recent] },
+      };
+    }
+
+    const read = await readAppendedEntries(transcriptPath, prior?.cursor);
+    if (read.kind === "failed") return read;
+    if (read.kind === "absent") {
+      // No transcript yet (fresh session) — keep prior if any, don't cache a
+      // cursor so the next render retries when the file appears. Copy the ring
+      // (like the hit/miss paths) so no stored reference escapes.
+      return {
+        kind: "ok",
+        value: {
+          messageCount: prior?.messageCount ?? 0,
+          recent: [...(prior?.recent ?? [])],
+        },
+      };
+    }
+
+    const { entries, cursor, reset } = read.value;
+    const base = prior && !reset ? prior : undefined;
+    let messageCount = base?.messageCount ?? 0;
+    let recent = base ? [...base.recent] : [];
+    for (const entry of entries) {
+      if (entry.isSidechain) continue;
+      if (isRealUserMessage(entry)) messageCount++;
+      recent.push(entry);
+    }
+    if (recent.length > RECENT_WINDOW) recent = recent.slice(-RECENT_WINDOW);
+
+    this.state.delete(sessionId);
+    this.state.set(sessionId, { cursor, messageCount, recent });
+    while (this.state.size > MAX_SESSIONS) {
+      const oldest = this.state.keys().next().value;
+      if (oldest === undefined) break;
+      this.state.delete(oldest);
+    }
+    // [LAW:no-shared-mutable-globals] `recent` is now the STORED array — copy it
+    // out so the returned value shares no reference with retained state.
+    return { kind: "ok", value: { messageCount, recent: [...recent] } };
+  }
+
   // [LAW:no-silent-failure] A hook payload with no cost block is `absent`
   // (old clients); a transcript parse error is `failed`, carried to the
   // payload boundary — the old catch dressed it as the same all-null record
@@ -69,33 +164,24 @@ export class MetricsProvider {
     sessionId: string,
     hookData: ClaudeHookData,
   ): Promise<Outcome<MetricsInfo>> {
-    try {
-      debug(`Getting metrics from hook data for session: ${sessionId}`);
+    debug(`Getting metrics from hook data for session: ${sessionId}`);
 
-      if (!hookData.cost) {
-        return ABSENT;
-      }
+    if (!hookData.cost) {
+      return ABSENT;
+    }
 
-      // parseJsonlFile keeps sidechain entries (usage needs them); metrics
-      // counts only main-thread turns, so the sidechain exclusion is local.
-      const entries = (await parseJsonlFile(hookData.transcript_path)).filter(
-        (entry) => !entry.isSidechain,
-      );
-      const messageCount = this.calculateMessageCount(entries);
-      const lastResponseTime = this.calculateLastResponseTime(entries);
-
-      return ok({
-        responseTime: hookData.cost.total_api_duration_ms / 1000,
-        lastResponseTime,
-        sessionDuration: hookData.cost.total_duration_ms / 1000,
-        messageCount,
-        linesAdded: hookData.cost.total_lines_added,
-        linesRemoved: hookData.cost.total_lines_removed,
-      });
-    } catch (error) {
-      return failed(
-        `metrics (${sessionId}): ${error instanceof Error ? error.message : String(error)}`,
-      );
+    const folded = await this.foldMetrics(sessionId, hookData.transcript_path);
+    if (folded.kind === "failed") {
+      return failed(`metrics (${sessionId}): ${folded.reason}`);
     }
+
+    return ok({
+      responseTime: hookData.cost.total_api_duration_ms / 1000,
+      lastResponseTime: this.calculateLastResponseTime(folded.value.recent),
+      sessionDuration: hookData.cost.total_duration_ms / 1000,
+      messageCount: folded.value.messageCount,
+      linesAdded: hookData.cost.total_lines_added,
+      linesRemoved: hookData.cost.total_lines_removed,
+    });
   }
 }