claude-code-session-manager 0.62.1 → 0.63.0

package/src/main/health.cjs

@@ -14,6 +14,7 @@ const { checkPersonaImports } = require('./lib/personaImportHealth.cjs');
 const { resolvePrdsDirs } = require('./lib/prdLocations.cjs');
 const { migratePrds } = require('./lib/prdMigration.cjs');
 const queueStore = require('./lib/queueStore.cjs');
+const { DEFAULT_RUNS_DIR, computeReport, isRetentionEnabled, liveKeysFromJobs } = require('./lib/runLogRetention.cjs');
 
 const MAX_LOG_AGE_MS = 5 * 60_000; // 5 min — warn if no logs this old
 const PROJECT_ROOT = path.resolve(__dirname, '../..');
@@ -370,6 +371,37 @@ async function check() {
     }
   }
 
+  // 6.6. Run-log retention report (informational only — never blocks health).
+  // Read-only against the REAL scheduled-plans/runs/ dir: reports current
+  // usage + what the configured policy (if any) would remove. Nothing is
+  // ever deleted here; see runLogRetention.cjs's header for the safety
+  // model. schedulerRunLogRetention lives in scheduler-machine.json's
+  // `config`, same home as every other scheduler machine setting.
+  try {
+    const retentionCfg = queueState?.config?.schedulerRunLogRetention;
+    const liveKeys = liveKeysFromJobs(queueState?.jobs || [], { runsDir: DEFAULT_RUNS_DIR });
+    const report = computeReport(
+      DEFAULT_RUNS_DIR,
+      retentionCfg?.policy || {},
+      { liveKeys }
+    );
+    status.components.run_log_retention = {
+      ok: true,
+      path: DEFAULT_RUNS_DIR,
+      totalBytes: report.usage.totalBytes,
+      dirCount: report.usage.dirCount,
+      runCount: report.usage.runCount,
+      oldestRunAt: report.usage.oldestRunAt,
+      policyConfigured: !!retentionCfg?.policy,
+      retentionEnabled: isRetentionEnabled(queueState?.config || {}),
+      wouldRemoveCount: report.eligibleSummary.count,
+      wouldRemoveBytes: report.eligibleSummary.bytes,
+      wouldRemoveDirs: report.removableDirs.length,
+    };
+  } catch (e) {
+    status.components.run_log_retention = { ok: true, error: e.message };
+  }
+
   // 7. Summary scoring: ok if all critical components pass.
   // Critical: nodejs, config dir, typescript, build artifact, test infrastructure.
   // Non-fatal: scheduler/transcripts dirs may not exist on fresh install.

package/src/main/heapSnapshot.cjs

@@ -0,0 +1,122 @@
+/**
+ * heapSnapshot.cjs — on-demand V8 heap snapshot of the RENDERER process,
+ * written to disk without restarting the app and without opening a
+ * `--remote-debugging-port`.
+ *
+ * Gated behind SM_HEAP_SNAPSHOT=1 (read fresh on every call, never cached at
+ * require time, so a test can flip it per-case). With the flag unset:
+ *   - registerIpc() registers no IPC channel.
+ *   - buildMenuItem() returns null (nothing spliced into the Dev menu).
+ *   - No timer, listener, or allocation is added anywhere.
+ *
+ * Uses webContents.takeHeapSnapshot(filePath) (Electron's own DevTools-
+ * protocol capture) rather than a debugging port — this stays off by
+ * default and never listens on a socket. capture() races the write against
+ * a hard timeout so a stuck capture can't hang the caller (or a scheduler
+ * job waiting on the same event loop) forever; it does not and cannot
+ * cancel Electron's in-flight write, it only stops *waiting* on it.
+ *
+ * Kept free of `require('electron')` at module scope so it can be unit
+ * tested with fake ipcMain/webContents objects, no Electron runtime needed.
+ */
+
+'use strict';
+
+const path = require('node:path');
+const os = require('node:os');
+const fsp = require('node:fs/promises');
+
+const CHANNEL = 'diagnostics:heap-snapshot';
+const DEFAULT_TIMEOUT_MS = 3 * 60 * 1000; // 3 min — snapshots can be multi-hundred-MB
+
+function isEnabled() {
+  return process.env.SM_HEAP_SNAPSHOT === '1';
+}
+
+function snapshotDir() {
+  return path.join(os.homedir(), '.claude', 'session-manager');
+}
+
+function timestampedFilename(now = new Date()) {
+  return `heap-${now.toISOString().replace(/[:.]/g, '-')}.heapsnapshot`;
+}
+
+/**
+ * @param {{ webContents: { takeHeapSnapshot(filePath: string): Promise<void> } }} win
+ * @param {{ dir?: string, now?: Date, timeoutMs?: number }} [opts]
+ * @returns {Promise<{ filePath: string, bytes: number|null, ms: number }>}
+ */
+async function captureSnapshot(win, opts = {}) {
+  if (!isEnabled()) {
+    throw new Error('Heap snapshot capture is disabled — set SM_HEAP_SNAPSHOT=1 and restart to enable.');
+  }
+  if (!win || win.isDestroyed?.() || !win.webContents) {
+    throw new Error('No renderer window available to snapshot.');
+  }
+  const dir = opts.dir || snapshotDir();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  await fsp.mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, timestampedFilename(opts.now));
+
+  const started = Date.now();
+  let timer;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(new Error(`Heap snapshot timed out after ${timeoutMs}ms (still writing ${filePath})`));
+    }, timeoutMs);
+  });
+  try {
+    await Promise.race([win.webContents.takeHeapSnapshot(filePath), timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+
+  const stat = await fsp.stat(filePath).catch(() => null);
+  const result = { filePath, bytes: stat ? stat.size : null, ms: Date.now() - started };
+  console.log(`[heapSnapshot] wrote ${filePath}${stat ? ` (${stat.size} bytes, ${result.ms}ms)` : ''}`);
+  return result;
+}
+
+/**
+ * Registers the IPC handler ONLY when SM_HEAP_SNAPSHOT=1. No-op otherwise —
+ * this is the whole default-off contract for the renderer-facing trigger.
+ * @param {{ ipcMain: { handle(channel: string, listener: Function): void } }} deps
+ * @param {() => any} getWindow
+ */
+function registerIpc({ ipcMain, getWindow }) {
+  if (!isEnabled()) return false;
+  ipcMain.handle(CHANNEL, () => captureSnapshot(getWindow()));
+  return true;
+}
+
+/**
+ * Menu item template for the Dev menu, or null when disabled. index.cjs
+ * splices this into its existing template — never builds a menu unless the
+ * flag is set.
+ * @param {() => any} getWindow
+ */
+function buildMenuItem(getWindow) {
+  if (!isEnabled()) return null;
+  return {
+    label: 'Take Heap Snapshot (renderer)',
+    click: async () => {
+      try {
+        const result = await captureSnapshot(getWindow());
+        console.log(`[heapSnapshot] menu capture complete: ${result.filePath}`);
+      } catch (err) {
+        console.error('[heapSnapshot] menu capture failed:', err && err.message);
+      }
+    },
+  };
+}
+
+module.exports = {
+  CHANNEL,
+  DEFAULT_TIMEOUT_MS,
+  isEnabled,
+  snapshotDir,
+  timestampedFilename,
+  captureSnapshot,
+  registerIpc,
+  buildMenuItem,
+};

package/src/main/historyAggregator.cjs

@@ -74,6 +74,34 @@ class LRUCache {
  */
 const aggrCache = new LRUCache(CACHE_MAX);
 
+// ── bounded concurrency helper ───────────────────────────────────────────────
+
+/**
+ * Run async fn(item) over items with at most `limit` in flight at once, via a
+ * pull-based worker pool (not chunked batches, so a slow item never stalls
+ * the rest of a batch). Node's fs promise APIs are backed by libuv's
+ * fixed-size threadpool (UV_THREADPOOL_SIZE, default 4) — firing every call
+ * at once via a single Promise.all still queues behind that pool one way or
+ * another, so bounding `limit` mainly avoids building thousands of pending
+ * promises/Buffers at once for a 25k+-file walk. Results are returned in
+ * input order; a thrown fn(item) rejects the whole call (callers here always
+ * catch inside fn instead).
+ */
+async function mapWithConcurrency(items, limit, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  async function worker() {
+    for (;;) {
+      const i = next++;
+      if (i >= items.length) return;
+      results[i] = await fn(items[i], i);
+    }
+  }
+  const workers = Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker);
+  await Promise.all(workers);
+  return results;
+}
+
 // ── date helpers ──────────────────────────────────────────────────────────────
 
 function decodeCwd(encoded) {
@@ -558,63 +586,171 @@ async function finalizeClosedDays({ budgetMs, dryRun = false } = {}) {
   return { finalizedDates: partial ? [] : Array.from(dates), partial };
 }
 
+// ── intraday fast-walk state ──────────────────────────────────────────────────
+//
+// Two persistent (in-memory only, process-lifetime) caches make repeat ticks
+// cheap:
+//
+// 1. `intradayDirRegistry` — encodedCwd -> { mtimeMs, fileNames }. Verified
+//    empirically on this machine (ext4): appending to an EXISTING file does
+//    NOT change its parent directory's mtime — only creating/removing/
+//    renaming a directory entry does. So a directory's mtime is a safe signal
+//    for "no file was added or removed here since last tick", letting us skip
+//    re-`readdir()`ing it (2,044 directories on the dev machine — this alone
+//    doesn't bound the file-level stat count).
+//
+// 2. `intradayNotToday` — a permanent Set<filePath> of files CONFIRMED to
+//    belong to a day other than today, so they can never contribute to
+//    today's bucket again. This is the lever that makes the walk actually
+//    proportional to files modified today, and it's safe only because of an
+//    existing, unrelated invariant this PRD does not change: a transcript's
+//    `sessionDate` is fixed by its FIRST message's timestamp and never
+//    updates on later appends (see parseJSONL's cache — `merged.sessionDate
+//    = prev.sessionDate`), so `aggregate()`/`refreshIntradayToday()` already
+//    attribute 100% of a file's activity to its original day no matter how
+//    many later days it's appended on. A file whose mtime is confirmed to
+//    predate today can have no content newer than that mtime, so its
+//    sessionDate can't be today either — that classification is exclusion
+//    forever, not just for the rest of today. Combined with #1 (a file
+//    relevant to today must have been CREATED today, which does bump its
+//    directory's mtime and is therefore always discovered), the walk over
+//    time shrinks to: files still active today (small, must keep re-stat-ing
+//    to catch growth) + any brand-new file since the last tick. Everything
+//    else is skipped without even a stat(2) call. Remaining stat/readdir
+//    calls run with bounded concurrency instead of one sequential await per
+//    call, since that was the other half of the sequential-walk cost
+//    (29,625 stats + 2,044 readdirs, 589ms measured on this machine).
+let intradayDirRegistry = new Map(); // encodedCwd -> { mtimeMs, fileNames: string[] }
+let intradayNotToday = new Set(); // filePath -> confirmed not-today, forever
+
+const INTRADAY_STAT_CONCURRENCY = 64;
+const INTRADAY_STRATEGY = 'directory-mtime skips re-readdir of unchanged dirs (new-file detection); ' +
+  'a file confirmed to belong to a past day (mtime, then sessionDate) is excluded from every future tick ' +
+  '(sessionDate is pinned to a transcript\'s first message and never changes on later appends); ' +
+  `remaining stat/readdir calls run with bounded concurrency (${INTRADAY_STAT_CONCURRENCY} in flight)`;
+
+/** Test-only: clears the in-memory directory/exclusion registries between fixtures. */
+function resetIntradayRegistryForTests() {
+  intradayDirRegistry = new Map();
+  intradayNotToday = new Set();
+}
+
 /**
- * Refresh TODAY's rollup buckets from a live (LRU-warm, cheap) parse of every
- * transcript touched today, and upsert them as provisional lines (v2, no
- * finalizedAt) so the History dashboard's "today" row stays current without
- * the renderer ever triggering a transcript scan itself. Meant to be called
- * on a timer (HISTORY_INTRADAY_REFRESH_MS) plus once at app start.
- *
- * readRollup/appendRollupDays last-write-wins per (date, projectDir, modelId)
- * key, so re-running this simply replaces today's previous provisional lines
- * with fresher ones — no separate "clear provisional" step needed.
+ * Pure walk-and-parse step (no rollup write) — split out from
+ * refreshIntradayToday() so it can be benchmarked read-only against the real
+ * ~/.claude/projects (see scripts/bench-intraday-walk.cjs) without touching
+ * the rollup file on disk.
  */
-async function refreshIntradayToday() {
+async function computeIntradayBuckets() {
   const today = localDate(new Date());
 
   let projectDirs;
   try {
     projectDirs = await fsp.readdir(PROJECTS_DIR, { withFileTypes: true });
   } catch {
-    return { date: today, projectsUpdated: 0 };
+    return { today, buckets: new Map() };
   }
 
-  const buckets = new Map();
-  for (const projEntry of projectDirs) {
-    if (!projEntry.isDirectory()) continue;
-    const encodedCwd = projEntry.name;
-    const projectDir = path.join(PROJECTS_DIR, encodedCwd);
+  const dirEntries = projectDirs.filter((e) => e.isDirectory());
 
-    let files;
-    try { files = await fsp.readdir(projectDir, { withFileTypes: true }); } catch { continue; }
+  // Directory count (thousands) is far smaller than file count (tens of
+  // thousands), so stat-ing every directory concurrently is cheap and tells
+  // us which ones had an entry added/removed since we last looked.
+  const dirStats = await mapWithConcurrency(dirEntries, INTRADAY_STAT_CONCURRENCY, async (entry) => {
+    const dirPath = path.join(PROJECTS_DIR, entry.name);
+    try {
+      const stat = await fsp.stat(dirPath);
+      return { encodedCwd: entry.name, dirPath, mtimeMs: stat.mtimeMs };
+    } catch {
+      return null;
+    }
+  });
 
-    for (const fileEntry of files) {
-      if (!fileEntry.name.endsWith('.jsonl')) continue;
-      const filePath = path.join(projectDir, fileEntry.name);
+  // Resolve the jsonl file list per directory — reuse the cached list (no
+  // readdir syscall) when the directory's mtime hasn't moved since the last
+  // tick; re-enumerate only directories that are new or changed. Files
+  // already known to be irrelevant to any future "today" are dropped here so
+  // they never reach the stat step below.
+  const fileCandidates = []; // { filePath, encodedCwd }
+  await mapWithConcurrency(dirStats.filter(Boolean), INTRADAY_STAT_CONCURRENCY, async (d) => {
+    const cached = intradayDirRegistry.get(d.encodedCwd);
+    let fileNames;
+    if (cached && cached.mtimeMs === d.mtimeMs) {
+      fileNames = cached.fileNames;
+    } else {
+      let files;
+      try { files = await fsp.readdir(d.dirPath, { withFileTypes: true }); } catch { files = []; }
+      fileNames = files.filter((f) => f.isFile() && f.name.endsWith('.jsonl')).map((f) => f.name);
+      intradayDirRegistry.set(d.encodedCwd, { mtimeMs: d.mtimeMs, fileNames });
+    }
+    for (const name of fileNames) {
+      const filePath = path.join(d.dirPath, name);
+      if (intradayNotToday.has(filePath)) continue;
+      fileCandidates.push({ filePath, encodedCwd: d.encodedCwd });
+    }
+  });
 
-      let stat;
-      try { stat = await fsp.stat(filePath); } catch { continue; }
+  // Known caveat: parseJSONL separately detects a same-path file replacement
+  // (inode change — e.g. a `claude --resume` compaction rewriting a
+  // transcript from scratch) and re-parses it in full. If that happens to a
+  // path already in intradayNotToday, this walk will never look at it again
+  // to notice its (hypothetical) new sessionDate, since exclusion here skips
+  // the stat entirely. This is safe in practice: the History dashboard's
+  // actual reads (aggregate()) don't consult this cache at all and always
+  // re-walk live for "today", so the only blast radius is a stale PROVISIONAL
+  // rollup line for the affected project until the next app restart resets
+  // this cache — never a wrong number on the dashboard itself.
+  const buckets = new Map();
+  await mapWithConcurrency(fileCandidates, INTRADAY_STAT_CONCURRENCY, async ({ filePath, encodedCwd }) => {
+    let stat;
+    try { stat = await fsp.stat(filePath); } catch { return; }
+
+    // A file whose mtime is before today can't have any content from today —
+    // and per the sessionDate-pinning invariant above, can never gain any —
+    // so it's excluded forever, with no parse ever needed.
+    const mtimeDate = localDate(new Date(stat.mtimeMs));
+    if (mtimeDate < today) {
+      intradayNotToday.add(filePath);
+      return;
+    }
 
-      // A file whose mtime is before today can't have been touched today —
-      // skip it without even reading it (matches aggregate()'s fast-skip).
-      const mtimeDate = localDate(new Date(stat.mtimeMs));
-      if (mtimeDate < today) continue;
+    const { result: parsed } = await parseJSONL(filePath, stat);
+    if (parsed.skipped) return;
+    if (parsed.sessionDate !== today) {
+      intradayNotToday.add(filePath);
+      return;
+    }
 
-      const { result: parsed } = await parseJSONL(filePath, stat);
-      if (parsed.skipped) continue;
-      if (parsed.sessionDate !== today) continue;
+    const key = `${today}|${encodedCwd}`;
+    if (!buckets.has(key)) buckets.set(key, emptyBucket(today, encodedCwd));
+    foldParsedIntoBucket(buckets.get(key), parsed);
+  });
 
-      const key = `${today}|${encodedCwd}`;
-      if (!buckets.has(key)) buckets.set(key, emptyBucket(today, encodedCwd));
-      foldParsedIntoBucket(buckets.get(key), parsed);
-    }
-  }
+  return { today, buckets };
+}
+
+/**
+ * Refresh TODAY's rollup buckets from a live (LRU-warm, cheap) parse of every
+ * transcript touched today, and upsert them as provisional lines (v2, no
+ * finalizedAt) so the History dashboard's "today" row stays current without
+ * the renderer ever triggering a transcript scan itself. Meant to be called
+ * on a timer (HISTORY_INTRADAY_REFRESH_MS) plus once at app start.
+ *
+ * readRollup/appendRollupDays last-write-wins per (date, projectDir, modelId)
+ * key, so re-running this simply replaces today's previous provisional lines
+ * with fresher ones — no separate "clear provisional" step needed.
+ *
+ * See INTRADAY_STRATEGY / intradayDirRegistry's comment above for why this is
+ * both faster and no less correct than the old unconditional full walk.
+ */
+async function refreshIntradayToday() {
+  const { today, buckets } = await computeIntradayBuckets();
 
   const entries = [];
   for (const b of buckets.values()) entries.push(...bucketToRollupLines(b));
   if (entries.length) await historyRollup.appendRollupDays(entries);
 
-  return { date: today, projectsUpdated: buckets.size };
+  return { date: today, projectsUpdated: buckets.size, strategy: INTRADAY_STRATEGY };
 }
 
 // ── aggregate ─────────────────────────────────────────────────────────────────
@@ -821,6 +957,7 @@ module.exports = {
   MODEL_PRICING,
   finalizeClosedDays,
   refreshIntradayToday,
+  computeIntradayBuckets,
   // exported for tests
   scanAggrLines,
   parseJSONL,
@@ -828,6 +965,9 @@ module.exports = {
   CACHE_MAX,
   LRUCache,
   computeActiveMinutes,
+  mapWithConcurrency,
+  resetIntradayRegistryForTests,
+  INTRADAY_STAT_CONCURRENCY,
   // exported for historyDashboard.cjs (pure, no I/O at require-time; reused
   // rather than re-implemented so date-range math stays in one place)
   localDate,

package/src/main/index.cjs

@@ -58,6 +58,7 @@ const { registerBilkoHostIpc } = require('./bilkoHost.cjs');
 const promptSessionTranscript = require('./promptSessionTranscript.cjs');
 const agentMemory = require('./agentMemory.cjs');
 const git = require('./git.cjs');
+const heapSnapshot = require('./heapSnapshot.cjs');
 const filesIpc = require('./files.cjs');
 const { registerDocEditHandlers, attachWindow: attachDocEditWindow } = require('./docEdit.cjs');
 const { listExchanges } = require('./exchanges.cjs');
@@ -830,6 +831,10 @@ ipcMain.handle('otel:set-config', async (_e, cfg) => {
 ipcMain.handle('otel:status', () => otel.status());
 ipcMain.handle('otel:config-path', () => otelSettings.storePath());
 
+// Diagnostic-only renderer heap snapshot. No-op unless SM_HEAP_SNAPSHOT=1 —
+// see heapSnapshot.cjs for why this stays off by default.
+heapSnapshot.registerIpc({ ipcMain, getWindow: () => mainWindow });
+
 // --- App lifecycle ---
 
 // E2E under xvfb-run has no working GPU; the GPU process exits ~15 seconds
@@ -1037,6 +1042,8 @@ app.whenReady().then(async () => {
     try { await systemPreferences.askForMediaAccess('microphone'); } catch { /* */ }
   }
 
+  const heapSnapshotMenuItem = heapSnapshot.buildMenuItem(() => mainWindow);
+
   const template = [
     {
       label: 'Session Manager',
@@ -1073,6 +1080,8 @@ app.whenReady().then(async () => {
       submenu: [
         { label: 'Toggle DevTools', accelerator: 'F12', role: 'toggleDevTools' },
         { label: 'Reload', accelerator: 'CmdOrCtrl+R', role: 'reload' },
+        // Diagnostic-only; absent unless SM_HEAP_SNAPSHOT=1 (see heapSnapshot.cjs).
+        ...(heapSnapshotMenuItem ? [heapSnapshotMenuItem] : []),
       ],
     },
     {

package/src/main/ipcSchemas.cjs

@@ -89,6 +89,14 @@ const transcriptReadRef = z.object({
 // ──────────────────────────────────────────── Config
 const configPath = z.object({ path: z.string().min(1).max(4096) });
 
+// maxBytes: optional bounded prefix-read length in bytes. Capped at 8 MiB —
+// generous for any legitimate "peek at the start of a file" caller while
+// still blocking a renderer from asking for an effectively-unbounded read.
+const configReadText = z.object({
+  path: z.string().min(1).max(4096),
+  maxBytes: z.number().int().min(1).max(8 * 1024 * 1024).optional(),
+});
+
 // `writer` carries the renderer's declared owner id for the single-writer law
 // (lib/opsOwnership.cjs). Optional on the wire because most writes target
 // ~/.claude, not a project ops root; writes INSIDE the ops root are refused
@@ -790,6 +798,7 @@ module.exports = {
     transcriptPage,
     transcriptReadRef,
     configPath,
+    configReadText,
     configWriteJson,
     configWriteText,
     configListDir,