fix(usage): stop retaining full session-file text forever, root cause of the crash

Root cause of the "closes for no reason, kills every session" crash, found while the
crash was reproducing live: usageScan's per-file cache stored the FULL TEXT of every
Claude session .jsonl file forever (keyed by path, replaced on mtime change, but never
evicted otherwise, and never bounded by size). projectsView.ts calls usage:report(0)
(all-time, unconditionally) on every deck load to fill in each card's cost badge — so
on a cold start this cache gets populated with EVERY BYTE of the user's entire history.

Measured on the real data: ~/.claude/projects held 5,070 session files totaling 2.5GB
on disk (one single transcript was 347MB). Live process inspection during an actual
crash cycle showed the main process ballooning to ~3.8GB within ~2 minutes of a cold
start — a V8 "JavaScript heap out of memory" abort at that size bypasses uncaughtException/
unhandledRejection entirely (nothing was ever logged to devdeck-errors.log despite v1.12.1's
new traps) and takes every cockpit terminal down with the main process.

Fix: files over MAX_CACHED_FILE_BYTES (5MB) are still read and aggregated correctly, but
never RETAINED in the cache — trading a bounded, transient re-parse cost on future calls
for eliminating the multi-GB permanent footprint. Verified against the real 2.5GB dataset
(same repro as the live crash): peak transient rss during a full all-time scan is ~933MB
(vs. ~3.8GB+ permanently held before), settling to ~263MB after GC. Global totals unchanged
(249M tokens, matching the pre-fix count) — correctness preserved, only retention changed.

342 tests (+2, TDD).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: writingdeveloper

README.md

@@ -11,7 +11,7 @@ See every repo's state at a glance — git status, how long it's been neglected,
 ![License](https://img.shields.io/badge/license-MIT-blue)
 ![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-0078D6)
 ![Built with Electron](https://img.shields.io/badge/Electron-31-47848F)
-![Tests](https://img.shields.io/badge/tests-340%20passing-3fb950)
+![Tests](https://img.shields.io/badge/tests-342%20passing-3fb950)
 ![CI](https://github.com/writingdeveloper/devdeck/actions/workflows/ci.yml/badge.svg)
 
 <img src="docs/demo/demo.gif" width="820" alt="DevDeck demo" />

package.json

@@ -1,6 +1,6 @@
 {
   "name": "devdeck",
-  "version": "1.12.1",
+  "version": "1.12.2",
   "description": "Project command deck — at-a-glance state + claude -c resume",
   "main": "dist/main/main.js",
   "type": "commonjs",

src/main/usageScan.test.ts

@@ -2,10 +2,10 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { scanUsage } from './usageScan';
+import { scanUsage, _cacheHasFile, _clearFileCache, MAX_CACHED_FILE_BYTES } from './usageScan';
 
 let root: string;
-beforeEach(() => { root = mkdtempSync(join(tmpdir(), 'devdeck-usage-')); });
+beforeEach(() => { root = mkdtempSync(join(tmpdir(), 'devdeck-usage-')); _clearFileCache(); });
 afterEach(() => rmSync(root, { recursive: true, force: true }));
 
 function asst(model: string, u: Record<string, number>, ts = '2026-06-01T10:00:00.000Z') {
@@ -78,6 +78,31 @@ describe('scanUsage', () => {
     expect(r.global.input).toBe(10); // deleted project's tokens included in the honest total
   });
 
+  it('caches a small session file (memory-bounded perf cache still works for the common case)', () => {
+    const d = join(root, 'C--g-small');
+    mkdirSync(d, { recursive: true });
+    const f = join(d, 's.jsonl');
+    writeFileSync(f, asst('claude-opus-4-8', { input_tokens: 1 }));
+    scanUsage([{ path: 'C:\\g\\small', name: 'small' }], root, Infinity);
+    expect(_cacheHasFile(f)).toBe(true);
+  });
+
+  it('does NOT cache a session file over MAX_CACHED_FILE_BYTES — a huge transcript must never be held in memory forever', () => {
+    // Real-world trigger: a multi-hundred-MB Claude session file, held forever in a module-level Map,
+    // ballooned the main process to multiple GB within ~1 minute of a cold start (the eager,
+    // unfiltered projectsView.ts per-project cost fill calls usage:report(0) = every file, all time)
+    // and crashed it with no catchable exception. Oversized files must be processed but NOT retained.
+    const d = join(root, 'C--g-huge');
+    mkdirSync(d, { recursive: true });
+    const f = join(d, 's.jsonl');
+    const line = asst('claude-opus-4-8', { input_tokens: 1 });
+    const pad = 'x'.repeat(MAX_CACHED_FILE_BYTES); // one line alone already exceeds the cap
+    writeFileSync(f, line + '\n// ' + pad);
+    const r = scanUsage([{ path: 'C:\\g\\huge', name: 'huge' }], root, Infinity);
+    expect(_cacheHasFile(f)).toBe(false);
+    expect(r.global.input).toBe(1); // still processed correctly even though not cached
+  });
+
   it('sums active time from message gaps, capping idle stretches', () => {
     const d = join(root, 'C--g-time');
     mkdirSync(d, { recursive: true });

src/main/usageScan.ts

@@ -6,9 +6,21 @@ import type { UsageReport, ProjectUsage, ModelUsage } from '../shared/types';
 
 // Cache: filepath -> { mtime, parsed lines }. Keyed by PATH (not path+mtime), with the mtime stored
 // in the value, so a modified file REPLACES its entry instead of leaking a new key per modification
-// in this long-lived process. One entry per session file; bounded by the number of distinct files.
+// in this long-lived process. Bounded by the number of distinct files — BUT that bound is only on
+// entry COUNT, not total bytes: a power user's ~/.claude/projects can hold thousands of session
+// files, some hundreds of MB (one real transcript was 347MB). Caching every one's full text forever
+// ballooned the main process to several GB within ~1 minute of a cold start (projectsView.ts's
+// per-project cost fill calls usage:report(0) = every file, all time, unconditionally on every deck
+// load) and crashed it with a V8 "out of memory" abort that bypasses every JS exception handler.
+// Files over MAX_CACHED_FILE_BYTES are still read and aggregated correctly — just never RETAINED.
+export const MAX_CACHED_FILE_BYTES = 5 * 1024 * 1024; // 5MB — generous for the vast majority of sessions
 const _fileCache = new Map<string, { mtimeMs: number; lines: string[] }>();
 
+/** Test-only introspection: does the cache currently hold an entry for this file path? */
+export function _cacheHasFile(path: string): boolean { return _fileCache.has(path); }
+/** Test-only: reset cache state between tests so assertions aren't affected by cross-test leakage. */
+export function _clearFileCache(): void { _fileCache.clear(); }
+
 interface RepoRef { path: string; name: string; status?: 'active' | 'deleted'; }
 
 function dayKey(ts: string | undefined, fallbackMs: number): string {
@@ -46,8 +58,8 @@ export function scanUsage(repos: RepoRef[], claudeProjectsDir: string, sinceMs:
       try { files = readdirSync(dir).filter((f) => f.endsWith('.jsonl')); } catch { files = []; }
       for (const f of files) {
         const full = join(dir, f);
-        let fileMs = Date.now();
-        try { fileMs = statSync(full).mtimeMs; } catch { /* keep now */ }
+        let fileMs = Date.now(), fileSize = 0;
+        try { const st = statSync(full); fileMs = st.mtimeMs; fileSize = st.size; } catch { /* keep defaults */ }
         const cached = _fileCache.get(full);
         let lines: string[];
         if (cached && cached.mtimeMs === fileMs) {
@@ -56,7 +68,8 @@ export function scanUsage(repos: RepoRef[], claudeProjectsDir: string, sinceMs:
           let text = '';
           try { text = readFileSync(full, 'utf8'); } catch { continue; }
           lines = text.split('\n');
-          _fileCache.set(full, { mtimeMs: fileMs, lines }); // replaces any stale entry for this path
+          if (fileSize <= MAX_CACHED_FILE_BYTES) _fileCache.set(full, { mtimeMs: fileMs, lines }); // replaces any stale entry
+          else _fileCache.delete(full); // a previously-small, now-grown file must not linger in the cache
         }
         projSessions++;
         const stamps: number[] = []; // in-range message timestamps, for active-time gaps