claude-code-session-manager 0.104.1 → 0.104.2

package/src/main/lib/activeSessions.cjs

@@ -9,6 +9,7 @@
 // which PRD 356-retire purges along with its capture hook.
 
 const fs = require('node:fs');
+const fsp = require('node:fs/promises');
 const os = require('node:os');
 const path = require('node:path');
 const { KIND_CONFIG: WORKTREE_KIND_CONFIG } = require('./gitWorktree.cjs');
@@ -43,13 +44,14 @@ const TAIL_BYTES = 64 * 1024;
 // Safety cap on distinct cwds to bound result set size. O(1) extra space.
 const MAX_CWDS = 50;
 
-// activeProjectCwds' scan is a readdirSync of every dir under ~/.claude
-// /projects (2209 dirs / 8.8 GB observed) plus a statSync per transcript —
-// ~270 ms warm. reconcile() calls into it (directly or via allProjectCwds)
-// several times per pass, so cache the resolved cwd list keyed on the
-// resolved argument TUPLE (projectsDir, maxAgeMin, maxCwds) — never on
-// `!opts`, since allProjectCwds always constructs an options object and that
-// guard would cache nothing on the hottest path.
+// The disk scan (readdirSync of every dir under ~/.claude/projects — 2209
+// dirs / 8.8 GB observed — plus a statSync per transcript, ~270 ms warm) is
+// the expensive part. allProjectCwds() and activeProjectCwds() used to each
+// pay their own full scan under separate (projectsDir, maxAgeMin, maxCwds)
+// cache keys even though they read the same on-disk facts. Now the scan runs
+// ONCE per projectsDir and is cached as a flat per-project record
+// {rawCwd, newestMtimeMs}; every view (any maxAgeMin/maxCwds combination)
+// filters/sorts that one record in memory instead of touching disk again.
 //
 // Invalidation: projectsDir's own mtime (bumps when a project DIRECTORY is
 // added/removed — NOT when an existing transcript gains a line, which is
@@ -58,13 +60,20 @@ const MAX_CWDS = 50;
 // scheduler/prdParser.cjs's dirCache and queueHistory.cjs's historyCacheKey.
 // TTL sits above the 60 s dispatch-loop interval (scheduler POLL_INTERVAL_MS) so
 // one pass never re-scans cold. Cached arrays are frozen — shared, never mutated.
+// Stale-while-revalidate: once a projectsDir has been scanned at least once,
+// an expired cache entry is served to the (synchronous) caller as-is, and at
+// most one background fs.promises rescan is kicked off to refresh it. Only
+// the very first scan of a given projectsDir pays the synchronous cost —
+// every expiry after that is a cache read plus a fire-and-forget refresh.
 const CACHE_TTL_MS = 120_000;
+// Bounds how many project dirs the async rescan reads concurrently.
+const RESCAN_CONCURRENCY = 32;
 const EMPTY_CWDS = Object.freeze([]);
-const cwdScanCache = new Map(); // key -> { dirMtimeMs, cachedAt, result }
+const rawScanCache = new Map(); // projectsDir -> { dirMtimeMs, cachedAt, records, refreshPromise }
 
 /** Forces the next activeProjectCwds/allProjectCwds call to rescan. */
 function bustProjectCwdCache() {
-  cwdScanCache.clear();
+  rawScanCache.clear();
 }
 
 // The ops-root folder name. A transcript's `cwd` can point INSIDE it whenever
@@ -120,42 +129,231 @@ function readTailLines(filePath, maxBytes) {
 }
 
 /**
- * activeProjectCwds(maxAgeMin = 90, opts?) → string[]
- *
- * Returns distinct, on-disk project cwds that have an open/active session
- * within the last maxAgeMin minutes.
- *
- * Sole detection path: scan ~/.claude/projects/*​/  for transcript *.jsonl
- *   files modified within maxAgeMin, read `cwd` from the last parseable line
- *   of the newest transcript per project dir.
- *   Complexity: O(P × L) over P project dirs, each bounded-tail read (64 KB).
+ * scanOneProjectDirSync(projDir) → {rawCwd, newestMtimeMs} | null
+ * Newest *.jsonl's mtime plus its last parseable `cwd`, for one project dir.
+ */
+function scanOneProjectDirSync(projDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(projDir).filter((f) => f.endsWith('.jsonl'));
+  } catch { return null; }
+
+  let newestPath = null;
+  let newestMtimeMs = 0;
+  for (const tf of entries) {
+    const fp = path.join(projDir, tf);
+    try {
+      const st = fs.statSync(fp);
+      if (st.mtimeMs > newestMtimeMs) {
+        newestMtimeMs = st.mtimeMs;
+        newestPath = fp;
+      }
+    } catch { continue; }
+  }
+  if (!newestPath) return null;
+
+  const tlines = readTailLines(newestPath, TAIL_BYTES);
+  let rawCwd = null;
+  for (let i = tlines.length - 1; i >= 0; i--) {
+    let row;
+    try { row = JSON.parse(tlines[i]); } catch { continue; }
+    if (row.cwd) { rawCwd = row.cwd; break; }
+  }
+  return rawCwd ? { rawCwd, newestMtimeMs } : null;
+}
+
+/**
+ * scanProjectsDir(projectsDir) → {rawCwd, newestMtimeMs}[] | null
  *
- * opts (for testing):
- *   projectsDir   — override the default ~/.claude/projects path
- *   tmpDropRoots  — override the tmp guard's drop roots (default TMP_DROP_ROOTS)
+ * The first scan of a given projectsDir is synchronous (readdirSync of
+ * projectsDir, then per project dir as above) and its result is cached.
+ * A fresh cache entry (same dirMtimeMs, within TTL) is returned as-is.
+ * Once the dir's own mtime changes (a project dir was added/removed), the
+ * next call rescans synchronously and returns the new result — a stale
+ * record would otherwise hide a just-registered project from this caller.
+ * Only when dirMtimeMs is unchanged and the TTL has expired is the stale
+ * record returned as-is, with startAsyncRefresh kicking off at most one
+ * background fs.promises rescan to refresh it for the next caller. Returns
+ * null when projectsDir is missing/unreadable and no record has ever been
+ * cached for it.
  */
-function activeProjectCwds(maxAgeMin = 90, {
-  projectsDir = path.join(HOME, '.claude', 'projects'),
-  maxCwds = MAX_CWDS,
-  tmpDropRoots = TMP_DROP_ROOTS,
-} = {}) {
-  const cacheKey = [projectsDir, maxAgeMin, maxCwds].join('|');
+function scanProjectsDir(projectsDir) {
   let dirMtimeMs;
   try {
     dirMtimeMs = fs.statSync(projectsDir).mtimeMs;
   } catch {
-    // Missing/unreadable dir: nothing to scan, and any prior cache entry for
-    // this key must not survive to be handed back once the dir later
-    // appears — drop it rather than caching this empty result.
-    cwdScanCache.delete(cacheKey);
-    return EMPTY_CWDS;
+    // Missing/unreadable dir: any prior cache entry must not survive to be
+    // handed back once the dir later appears — drop it rather than caching
+    // this empty result.
+    rawScanCache.delete(projectsDir);
+    return null;
   }
-  const cached = cwdScanCache.get(cacheKey);
+  const cached = rawScanCache.get(projectsDir);
   const now0 = Date.now();
   if (cached && cached.dirMtimeMs === dirMtimeMs && now0 - cached.cachedAt < CACHE_TTL_MS) {
-    return cached.result;
+    return cached.records;
+  }
+
+  // Same mtime, TTL expired: a prior successful scan exists and the dir
+  // itself hasn't changed, so serve it stale and refresh in the background
+  // rather than blocking this synchronous caller.
+  if (cached && cached.dirMtimeMs === dirMtimeMs) {
+    startAsyncRefresh(projectsDir);
+    return cached.records;
+  }
+
+  // Either the first-ever scan of this projectsDir, or the dir's mtime
+  // changed (a project was added/removed) — must be synchronous, since a
+  // stale record would hide the change from this caller.
+  let slugs;
+  try { slugs = fs.readdirSync(projectsDir); } catch { rawScanCache.delete(projectsDir); return null; }
+
+  const records = [];
+  for (const slug of slugs) {
+    const rec = scanOneProjectDirSync(path.join(projectsDir, slug));
+    if (rec) records.push(rec);
+  }
+
+  Object.freeze(records);
+  rawScanCache.set(projectsDir, { dirMtimeMs, cachedAt: now0, records, refreshPromise: null });
+  return records;
+}
+
+/**
+ * readTailLinesAsync(filePath, maxBytes) → Promise<string[]>
+ * fs.promises counterpart of readTailLines, used only by the async rescan.
+ */
+async function readTailLinesAsync(filePath, maxBytes) {
+  let buf;
+  let fh;
+  try {
+    const stat = await fsp.stat(filePath);
+    if (stat.size === 0) return [];
+    const readSize = Math.min(maxBytes, stat.size);
+    fh = await fsp.open(filePath, 'r');
+    buf = Buffer.alloc(readSize);
+    await fh.read(buf, 0, readSize, stat.size - readSize);
+  } catch {
+    return [];
+  } finally {
+    if (fh) await fh.close().catch(() => {});
+  }
+  return buf.toString('utf8').split('\n').filter((l) => l.trim());
+}
+
+/**
+ * scanOneProjectDirAsync(projDir) → Promise<{rawCwd, newestMtimeMs} | null>
+ * fs.promises counterpart of scanOneProjectDirSync, used only by the async rescan.
+ */
+async function scanOneProjectDirAsync(projDir) {
+  let entries;
+  try {
+    entries = (await fsp.readdir(projDir)).filter((f) => f.endsWith('.jsonl'));
+  } catch { return null; }
+
+  let newestPath = null;
+  let newestMtimeMs = 0;
+  for (const tf of entries) {
+    const fp = path.join(projDir, tf);
+    try {
+      const st = await fsp.stat(fp);
+      if (st.mtimeMs > newestMtimeMs) {
+        newestMtimeMs = st.mtimeMs;
+        newestPath = fp;
+      }
+    } catch { continue; }
   }
+  if (!newestPath) return null;
 
+  const tlines = await readTailLinesAsync(newestPath, TAIL_BYTES);
+  let rawCwd = null;
+  for (let i = tlines.length - 1; i >= 0; i--) {
+    let row;
+    try { row = JSON.parse(tlines[i]); } catch { continue; }
+    if (row.cwd) { rawCwd = row.cwd; break; }
+  }
+  return rawCwd ? { rawCwd, newestMtimeMs } : null;
+}
+
+/**
+ * rescanProjectsDirAsync(projectsDir) → Promise<{dirMtimeMs, records}>
+ * The background counterpart of the first-scan branch in scanProjectsDir:
+ * same semantics, entirely fs.promises, with the per-project-dir reads
+ * bounded to RESCAN_CONCURRENCY in flight at once. A top-level failure
+ * (missing dir, unreadable) is left to throw/reject — startAsyncRefresh's
+ * caller catches it, logs once, and keeps the old cached record.
+ */
+async function rescanProjectsDirAsync(projectsDir) {
+  const dirMtimeMs = (await fsp.stat(projectsDir)).mtimeMs;
+  const slugs = await fsp.readdir(projectsDir);
+
+  const records = [];
+  let nextIdx = 0;
+  async function worker() {
+    for (;;) {
+      const i = nextIdx++;
+      if (i >= slugs.length) return;
+      const rec = await scanOneProjectDirAsync(path.join(projectsDir, slugs[i]));
+      if (rec) records.push(rec);
+    }
+  }
+  const workerCount = Math.min(RESCAN_CONCURRENCY, slugs.length);
+  await Promise.all(Array.from({ length: workerCount }, worker));
+
+  Object.freeze(records);
+  return { dirMtimeMs, records };
+}
+
+/**
+ * startAsyncRefresh(projectsDir) → Promise<void>
+ * Kicks off at most one in-flight background rescan per projectsDir — later
+ * calls while one is in flight get back the same promise instead of starting
+ * another. On success the cache entry is swapped atomically; on failure the
+ * old record is kept and the error is logged once. Never throws/rejects
+ * into a synchronous caller — scanProjectsDir never awaits this.
+ */
+function startAsyncRefresh(projectsDir) {
+  const entry = rawScanCache.get(projectsDir);
+  if (!entry) return Promise.resolve();
+  if (entry.refreshPromise) return entry.refreshPromise;
+
+  const promise = rescanProjectsDirAsync(projectsDir)
+    .then((result) => {
+      const current = rawScanCache.get(projectsDir);
+      if (!current) return; // busted mid-flight; nothing to swap into
+      rawScanCache.set(projectsDir, {
+        dirMtimeMs: result.dirMtimeMs, cachedAt: Date.now(), records: result.records, refreshPromise: null,
+      });
+    })
+    .catch((err) => {
+      console.error(`[activeSessions] async rescan of ${projectsDir} failed, keeping stale record: ${err.message}`);
+      const current = rawScanCache.get(projectsDir);
+      if (current) current.refreshPromise = null;
+    });
+
+  entry.refreshPromise = promise;
+  return promise;
+}
+
+/**
+ * __waitForPendingRefresh(projectsDir) → Promise<void>
+ * Test-only hook: awaits the in-flight async rescan for projectsDir, if any.
+ * Resolves immediately when no refresh is in flight.
+ */
+function __waitForPendingRefresh(projectsDir) {
+  const entry = rawScanCache.get(projectsDir);
+  return entry && entry.refreshPromise ? entry.refreshPromise : Promise.resolve();
+}
+
+/**
+ * deriveCwds(records, maxAgeMin, maxCwds, tmpDropRoots) → string[]
+ *
+ * Filters/sorts a scanProjectsDir() record into the view activeProjectCwds/
+ * allProjectCwds promise: age cutoff, ops-root/worktree normalization,
+ * dedup, existence check, and the maxCwds cap — identical semantics to the
+ * old per-call scan, now performed in memory against the shared record.
+ */
+function deriveCwds(records, maxAgeMin, maxCwds, tmpDropRoots) {
   // maxAgeMin === Infinity means "every project ever seen, no recency filter"
   // (allProjectCwds below). Date.now() - Infinity is -Infinity, which every
   // mtime clears — spelled out here because it reads like an accident.
@@ -199,46 +397,39 @@ function activeProjectCwds(maxAgeMin = 90, {
     result.push(cwd);
   }
 
-  // Scan ~/.claude/projects/*/  transcript *.jsonl files.
-  let slugs;
-  try { slugs = fs.readdirSync(projectsDir); } catch { cwdScanCache.delete(cacheKey); return Object.freeze(result); }
-
-  for (const slug of slugs) {
+  for (const { rawCwd, newestMtimeMs } of records) {
     if (result.length >= maxCwds) break;
-    const projDir = path.join(projectsDir, slug);
-    let entries;
-    try {
-      entries = fs.readdirSync(projDir).filter((f) => f.endsWith('.jsonl'));
-    } catch { continue; }
-
-    // Find the most recently modified transcript in this project dir.
-    let newestPath = null;
-    let newestMtimeMs = 0;
-    for (const tf of entries) {
-      const fp = path.join(projDir, tf);
-      try {
-        const st = fs.statSync(fp);
-        if (st.mtimeMs > newestMtimeMs) {
-          newestMtimeMs = st.mtimeMs;
-          newestPath = fp;
-        }
-      } catch { continue; }
-    }
-
-    if (!newestPath || newestMtimeMs < cutoffMs) continue;
-
-    // Read `cwd` from the last parseable line of the transcript.
-    const tlines = readTailLines(newestPath, TAIL_BYTES);
-    for (let i = tlines.length - 1; i >= 0; i--) {
-      let row;
-      try { row = JSON.parse(tlines[i]); } catch { continue; }
-      if (row.cwd) { addCwd(row.cwd); break; }
-    }
+    if (newestMtimeMs < cutoffMs) continue;
+    addCwd(rawCwd);
   }
 
-  Object.freeze(result);
-  cwdScanCache.set(cacheKey, { dirMtimeMs, cachedAt: now0, result });
-  return result;
+  return Object.freeze(result);
+}
+
+/**
+ * activeProjectCwds(maxAgeMin = 90, opts?) → string[]
+ *
+ * Returns distinct, on-disk project cwds that have an open/active session
+ * within the last maxAgeMin minutes.
+ *
+ * Sole detection path: scan ~/.claude/projects/*​/  for transcript *.jsonl
+ *   files modified within maxAgeMin, read `cwd` from the last parseable line
+ *   of the newest transcript per project dir.
+ *   Complexity: O(P × L) over P project dirs, each bounded-tail read (64 KB) —
+ *   paid once per TTL window (see scanProjectsDir), shared across views.
+ *
+ * opts (for testing):
+ *   projectsDir   — override the default ~/.claude/projects path
+ *   tmpDropRoots  — override the tmp guard's drop roots (default TMP_DROP_ROOTS)
+ */
+function activeProjectCwds(maxAgeMin = 90, {
+  projectsDir = path.join(HOME, '.claude', 'projects'),
+  maxCwds = MAX_CWDS,
+  tmpDropRoots = TMP_DROP_ROOTS,
+} = {}) {
+  const records = scanProjectsDir(projectsDir);
+  if (!records) return EMPTY_CWDS;
+  return deriveCwds(records, maxAgeMin, maxCwds, tmpDropRoots);
 }
 
 /**
@@ -266,4 +457,5 @@ module.exports = {
   projectRootOf,
   worktreeMainRootOf,
   bustProjectCwdCache,
+  __waitForPendingRefresh,
 };

package/src/main/lib/prdMigration.cjs

@@ -166,13 +166,55 @@ function slugForPrdFile(name) {
   return name.slice(0, -3);
 }
 
+/**
+ * Per-cwd cache of the flat prds/ dir's last-swept state, keyed by cwd.
+ * {exists, mtimeMs, failed, skipped} — failed/skipped are the RESIDUAL
+ * (still-in-place) files from the last real sweep, so a cache hit can report
+ * them again without re-reading anything. `moved` is deliberately NOT cached:
+ * it is a count of actions taken during a pass, and a pass that does no work
+ * (cache hit) always reports moved: 0, never replays a stale move count.
+ *
+ * Perf win (PRD: flatPrdSweep phase, p50 1.3s/max 5.7s over up to 500 cwds
+ * per reconcile): a cwd whose flat dir is absent or whose mtime hasn't
+ * changed since the last successful sweep skips the readdir AND the
+ * liveSlugsForCwd() queue.json parse entirely — only a cheap stat runs.
+ */
+const flatDirSweepCache = new Map();
+
+/** Test-only: clear the per-cwd flat-dir sweep cache between test cases. */
+function resetFlatDirSweepCacheForTests() {
+  flatDirSweepCache.clear();
+}
+
 async function consolidateFlatPrds(cwd, opts = {}) {
   const flatDir = resolvePrdWriteDir(cwd);
   const archiveDir = path.join(path.dirname(flatDir), 'prds-archived');
+
+  let mtimeMs;
+  try {
+    mtimeMs = (await fsp.stat(flatDir)).mtimeMs;
+  } catch (e) {
+    if (e?.code !== 'ENOENT') throw e;
+    mtimeMs = null;
+  }
+
+  if (mtimeMs === null) {
+    flatDirSweepCache.set(cwd, { exists: false, mtimeMs: null, failed: [], skipped: [] });
+    return { moved: 0, failed: [], skipped: [] };
+  }
+
+  const cached = flatDirSweepCache.get(cwd);
+  if (cached && cached.exists && cached.mtimeMs === mtimeMs) {
+    // Unchanged since the last successful sweep — no readdir, no queue.json
+    // parse. Report the same residual (still-blocked/still-failed) files.
+    return { moved: 0, failed: cached.failed, skipped: cached.skipped };
+  }
+
   let entries;
   try {
     entries = await fsp.readdir(flatDir);
   } catch {
+    flatDirSweepCache.set(cwd, { exists: false, mtimeMs: null, failed: [], skipped: [] });
     return { moved: 0, failed: [], skipped: [] };
   }
 
@@ -188,6 +230,8 @@ async function consolidateFlatPrds(cwd, opts = {}) {
       if (!name.endsWith('.md') || name.startsWith('.')) continue;
       skipped.push({ file: name, reason: 'queue state unreadable — cannot prove no live job' });
     }
+    // Never cache a fail-closed read as settled — queue state may become
+    // readable on the very next pass and must be re-parsed, not replayed.
     return { moved: 0, failed, skipped };
   }
 
@@ -211,6 +255,19 @@ async function consolidateFlatPrds(cwd, opts = {}) {
       failed.push({ file: name, reason: e?.message ?? 'move failed' });
     }
   }
+
+  // Re-stat after the sweep: renames just mutated the dir's own mtime, so the
+  // cached value must reflect the post-sweep state, not the one we read in.
+  let postMtimeMs = null;
+  try {
+    postMtimeMs = (await fsp.stat(flatDir)).mtimeMs;
+  } catch { /* removed concurrently — leave uncached, next pass re-checks */ }
+  if (postMtimeMs !== null) {
+    flatDirSweepCache.set(cwd, { exists: true, mtimeMs: postMtimeMs, failed, skipped });
+  } else {
+    flatDirSweepCache.delete(cwd);
+  }
+
   return { moved, failed, skipped };
 }
 
@@ -275,4 +332,10 @@ async function legacyAdoptExistingPrds() {
   return { stamped, failed };
 }
 
-module.exports = { migratePrds, consolidateFlatPrds, legacyAdoptExistingPrds, LIVE_JOB_STATUSES };
+module.exports = {
+  migratePrds,
+  consolidateFlatPrds,
+  legacyAdoptExistingPrds,
+  LIVE_JOB_STATUSES,
+  resetFlatDirSweepCacheForTests,
+};

package/src/main/lib/queueHistory.cjs

@@ -236,11 +236,96 @@ async function readHistoryFile(target, cap) {
 let historyCacheKey = null;
 let historyCacheMap = null;
 
+// Per-file byte-offset cache backing historyTerminalBySlug's incremental
+// read: path -> { ino, size, offset, map }. `map` is this file's own
+// slug -> record result as of `offset` bytes; `offset` always sits on a
+// line boundary (the byte right after the last consumed '\n') so a partial
+// trailing line never gets counted as consumed.
+const perFileCache = new Map();
+
+/**
+ * needs_review_entry/needs_review_resolution lines (needsReviewLedger.cjs)
+ * share this file but aren't a job's terminal record — skip them, or a
+ * needs_review episode logged for a slug AFTER its real terminal row (e.g.
+ * it re-parked on a later run) would overwrite a true 'completed' with a
+ * kind-less, status-less row read as "not terminal".
+ */
+function applyTerminalLines(text, map) {
+  if (!text) return;
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const j = JSON.parse(line);
+      if (j?.kind && j.kind !== 'terminal') continue;
+      if (j?.slug) map.set(j.slug, { status: j.status, finishedAt: j.finishedAt, landedCommit: j.landedCommit ?? null });
+    } catch {
+      // corrupt/partial line — ignore
+    }
+  }
+}
+
+/**
+ * Returns this one file's slug -> record map, reading only the bytes
+ * appended since the last call when possible. Falls back to a full
+ * re-parse when the file is new to the cache, its inode changed, or its
+ * size went backwards (rotation/truncation).
+ */
+async function readFileTerminalMap(target, stat) {
+  const cached = perFileCache.get(target);
+  const { ino, size } = stat;
+
+  if (cached && cached.ino === ino && size >= cached.size) {
+    if (size === cached.size) return cached.map;
+
+    const len = size - cached.offset;
+    const fh = await fsp.open(target, 'r');
+    let buf;
+    try {
+      buf = Buffer.alloc(len);
+      await fh.read(buf, 0, len, cached.offset);
+    } finally {
+      await fh.close();
+    }
+
+    // Stop at the last complete newline — a partial trailing line (still
+    // being written) is left unconsumed so the next pass re-reads it once
+    // it's whole, instead of permanently skipping or mis-parsing it.
+    const lastNl = buf.lastIndexOf(0x0a);
+    const map = new Map(cached.map);
+    let offset = cached.offset;
+    if (lastNl !== -1) {
+      applyTerminalLines(buf.subarray(0, lastNl + 1).toString('utf8'), map);
+      offset = cached.offset + lastNl + 1;
+    }
+    const updated = { ino, size, offset, map };
+    perFileCache.set(target, updated);
+    return map;
+  }
+
+  // Full (re)parse: first time seeing this path, its inode changed, or it
+  // shrank (log rotation/truncation) — the existing offset is no longer
+  // trustworthy.
+  let text = '';
+  try {
+    text = await fsp.readFile(target, 'utf8');
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  const map = new Map();
+  applyTerminalLines(text, map);
+  const lastNl = Buffer.from(text, 'utf8').lastIndexOf(0x0a);
+  const offset = lastNl === -1 ? 0 : lastNl + 1;
+  perFileCache.set(target, { ino, size, offset, map });
+  return map;
+}
+
 /**
  * Full-file scan of history.jsonl, returning slug -> { status, finishedAt }
  * for the most recently appended record of each slug. O(H) where H is the
  * line count of history.jsonl; cached by the file's mtime so a reconcile()
- * pass with no new archives since the last call is O(1).
+ * pass with no new archives since the last call is O(1). When the mtime
+ * check misses, each file is re-read incrementally via readFileTerminalMap
+ * rather than re-parsed from byte zero.
  *
  * Exists so reconcile() can tell "this on-disk PRD's job row already left
  * jobs[] into history — do not resurrect it as a fresh pending job" apart
@@ -248,36 +333,22 @@ let historyCacheMap = null;
  */
 async function historyTerminalBySlug() {
   const paths = historyPaths();
-  const mtimes = await Promise.all(paths.map(async (p2) => {
-    try { return (await fsp.stat(p2)).mtimeMs; } catch { return -1; }
+  const stats = await Promise.all(paths.map(async (p2) => {
+    try { return await fsp.stat(p2); } catch { return null; }
   }));
-  const cacheKey = paths.map((p2, i) => `${p2}:${mtimes[i]}`).join('|');
+  const cacheKey = paths.map((p2, i) => `${p2}:${stats[i] ? stats[i].mtimeMs : -1}`).join('|');
   if (cacheKey === historyCacheKey && historyCacheMap) return historyCacheMap;
 
   const map = new Map();
-  for (const p2 of paths) {
-    let text = '';
-    try {
-      text = await fsp.readFile(p2, 'utf8');
-    } catch (e) {
-      if (e.code !== 'ENOENT') throw e;
-    }
-    if (!text) continue;
-    for (const line of text.split('\n')) {
-      if (!line.trim()) continue;
-      try {
-        const j = JSON.parse(line);
-        // needs_review_entry/needs_review_resolution lines (needsReviewLedger.cjs)
-        // share this file but aren't a job's terminal record — skip them, or a
-        // needs_review episode logged for a slug AFTER its real terminal row
-        // (e.g. it re-parked on a later run) would overwrite a true 'completed'
-        // with a kind-less, status-less row read as "not terminal".
-        if (j?.kind && j.kind !== 'terminal') continue;
-        if (j?.slug) map.set(j.slug, { status: j.status, finishedAt: j.finishedAt, landedCommit: j.landedCommit ?? null });
-      } catch {
-        // corrupt/partial line — ignore
-      }
+  for (let i = 0; i < paths.length; i++) {
+    const p2 = paths[i];
+    const stat = stats[i];
+    if (!stat) {
+      perFileCache.delete(p2);
+      continue;
     }
+    const fileMap = await readFileTerminalMap(p2, stat);
+    for (const [slug, rec] of fileMap) map.set(slug, rec);
   }
   historyCacheKey = cacheKey;
   historyCacheMap = map;