claude-code-session-manager 0.93.0 → 0.95.0

package/src/main/__tests__/transcriptsUsageFor.test.cjs

@@ -8,7 +8,7 @@
 
 'use strict';
 
-import { test, expect, beforeEach, afterEach } from 'vitest';
+import { test, expect, beforeEach, afterEach, vi } from 'vitest';
 
 const fs = require('node:fs');
 const os = require('node:os');
@@ -93,3 +93,114 @@ test('a growing transcript is re-summed after the file mtime/size change', async
   const after = await usageFor(cwd, [sessionId]);
   expect(after[sessionId]).toEqual({ inputTokens: 13, outputTokens: 6 });
 });
+
+// ── incremental tail parse + bounded cache ─────────────────────────────────
+
+const fsp = require('node:fs/promises');
+const transcripts = require('../transcripts.cjs');
+
+function fromScratch(filePath) {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  for (const line of fs.readFileSync(filePath, 'utf8').split('\n')) {
+    if (!line) continue;
+    let o;
+    try { o = JSON.parse(line); } catch { continue; }
+    const u = o.usage || {};
+    inputTokens += u.input_tokens ?? 0;
+    outputTokens += u.output_tokens ?? 0;
+  }
+  return { inputTokens, outputTokens };
+}
+
+test('incremental result equals a from-scratch parse across 5 appends (partial line + repeated id)', async () => {
+  const sessionId = 'sess-incr';
+  const filePath = writeTranscript(cwd, sessionId, [
+    { id: 'm1', usage: { input_tokens: 10, output_tokens: 1 } },
+  ]);
+  const check = async () => {
+    const r = await usageFor(cwd, [sessionId]);
+    expect(r[sessionId]).toEqual(fromScratch(filePath));
+  };
+  await check();
+  const l2 = JSON.stringify({ id: 'm2', usage: { input_tokens: 20, output_tokens: 2 } });
+  // 1: append ending mid-line
+  fs.appendFileSync(filePath, l2.slice(0, 15));
+  await check();
+  // 2: complete that line
+  fs.appendFileSync(filePath, l2.slice(15) + '\n');
+  await check();
+  // 3: repeat an earlier message id (full parse sums it again)
+  fs.appendFileSync(filePath, JSON.stringify({ id: 'm1', usage: { input_tokens: 10, output_tokens: 1 } }) + '\n');
+  await check();
+  // 4: non-usage + malformed line
+  fs.appendFileSync(filePath, JSON.stringify({ type: 'user' }) + '\nnot json\n');
+  await check();
+  // 5: multibyte content then usage
+  fs.appendFileSync(filePath, JSON.stringify({ t: 'héllo 日本', usage: { input_tokens: 4, output_tokens: 4 } }) + '\n');
+  await check();
+  expect((await usageFor(cwd, [sessionId]))[sessionId]).toEqual({ inputTokens: 44, outputTokens: 8 });
+});
+
+test('the call after a one-line append reads < 4 KB from disk', async () => {
+  const sessionId = 'sess-bytes';
+  const big = Array.from({ length: 2000 }, (_, i) => ({ i, pad: 'x'.repeat(100), usage: { input_tokens: 1, output_tokens: 1 } }));
+  const filePath = writeTranscript(cwd, sessionId, big);
+  await usageFor(cwd, [sessionId]);
+  expect(fs.statSync(filePath).size).toBeGreaterThan(200_000);
+
+  fs.appendFileSync(filePath, JSON.stringify({ usage: { input_tokens: 5, output_tokens: 5 } }) + '\n');
+  const fh = await fsp.open(filePath, 'r');
+  const proto = Object.getPrototypeOf(fh);
+  await fh.close();
+  const orig = proto.read;
+  const lengths = [];
+  const spy = vi.spyOn(proto, 'read').mockImplementation(function (buf, off, len, pos) {
+    lengths.push(len);
+    return orig.call(this, buf, off, len, pos);
+  });
+  try {
+    const r = await usageFor(cwd, [sessionId]);
+    expect(r[sessionId]).toEqual({ inputTokens: 2005, outputTokens: 2005 });
+  } finally {
+    spy.mockRestore();
+  }
+  expect(lengths.length).toBeGreaterThan(0);
+  expect(lengths.reduce((a, b) => a + b, 0)).toBeLessThan(4096);
+});
+
+test('truncation / replacement triggers a full re-parse', async () => {
+  const sessionId = 'sess-trunc';
+  const filePath = writeTranscript(cwd, sessionId, [
+    { usage: { input_tokens: 100, output_tokens: 100 } },
+    { usage: { input_tokens: 100, output_tokens: 100 } },
+  ]);
+  await usageFor(cwd, [sessionId]);
+  fs.writeFileSync(filePath, JSON.stringify({ usage: { input_tokens: 1, output_tokens: 2 } }) + '\n');
+  expect((await usageFor(cwd, [sessionId]))[sessionId]).toEqual({ inputTokens: 1, outputTokens: 2 });
+});
+
+test('usageCache is bounded and evicts the least-recently-used entry', async () => {
+  const cache = transcripts.__usageCacheForTest;
+  const max = transcripts.__usageCacheMaxForTest;
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-usage-lru-'));
+  try {
+    const files = [];
+    for (let i = 0; i < max + 5; i++) {
+      const f = path.join(dir, `s${i}.jsonl`);
+      fs.writeFileSync(f, JSON.stringify({ usage: { input_tokens: 1, output_tokens: 1 } }) + '\n');
+      files.push(f);
+    }
+    const before = cache.size;
+    for (const f of files) {
+      // usageForOne is reached through usageFor's path; call via a cwd-independent route.
+      await transcripts.__usageForOneForTest(f);
+    }
+    expect(cache.size).toBeLessThanOrEqual(max);
+    expect(before).toBeLessThanOrEqual(max);
+    expect(cache.has(files[0])).toBe(false);
+    expect(cache.has(files[files.length - 1])).toBe(true);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/main/build-info.json

@@ -1,8 +1,8 @@
 {
-  "version": "0.93.0",
-  "gitSha": "78fa526eb94e044b2c72c736681e956bee653451",
-  "gitShortSha": "78fa526",
+  "version": "0.95.0",
+  "gitSha": "42f7779080772b1b8432b6287aff06c52b9f0f90",
+  "gitShortSha": "42f77790",
   "gitBranch": "HEAD",
-  "builtAt": "2026-09-21T03:09:24.532Z",
+  "builtAt": "2026-09-21T22:01:57.972Z",
   "dirty": false
 }

package/src/main/chatRunner.cjs

@@ -56,6 +56,11 @@ const agentModelResolve = require('./lib/agentModelResolve.cjs');
 const { resolveEpicEffort, effortArgs } = require('./lib/agentEffortResolve.cjs');
 const { planEpicSpawn } = require('./lib/epicSpawnPlan.cjs');
 const logs = require('./logs.cjs');
+const { createHeadTailBuffer } = require('./lib/headTailBuffer.cjs');
+
+// Caps on per-run stream buffers (a run can last hours).
+const STDERR_TAIL_MAX = 64 * 1024;
+const LINE_BUFFER_MAX = 8 * 1024 * 1024;
 
 // The only two CLI errors that mean "wrong session flag" (verified against the
 // real CLI). "in use" → the transcript exists, so resume; "no conversation" →
@@ -317,6 +322,13 @@ const waiting = []; // [{ tabId, sessionId, prompt, cwd, resume, silent, onSilen
 // Closes the microtask-wide window in which per-tab exclusivity would
 // otherwise not hold. See pump().
 const dispatching = new Set();
+// sessionIds with a live CLI child: added when pump() dispatches a run, dropped
+// in the same .finally() that frees the lane — i.e. only after executeRun has
+// settled from `close`/`error`/spawn failure. A cancelled child still exiting
+// therefore keeps holding it. Two `claude -p` against one sessionId die with
+// "Session ID … is already in use", so pump() refuses to start a second run
+// for a held sessionId (it waits in `waiting` like any other blocked run).
+const liveSessions = new Set();
 let activeCount = 0;
 
 // Indirection so tests can stub the spawn without launching claude.
@@ -332,6 +344,7 @@ function __setExecutor(fn) { executor = fn || executeRun; }
 function __resetQueueForTests() {
   inFlight.clear();
   dispatching.clear();
+  liveSessions.clear();
   waiting.length = 0;
   activeCount = 0;
   sessionSlots.__resetForTests();
@@ -380,6 +393,7 @@ function run(opts) {
   // visible in `inFlight` — the same window pump() guards against.
   const tabBusy = inFlight.has(opts.tabId)
     || dispatching.has(opts.tabId)
+    || liveSessions.has(opts.sessionId)
     || waiting.some((w) => w.tabId === opts.tabId);
   if (tabBusy && opts.silent) {
     // Silent probes stay best-effort and invisible: a probe that collides is
@@ -402,7 +416,8 @@ function pump() {
     // it in `inFlight` (which happens a microtask later) — without it, one
     // synchronous sweep of this loop could start two runs for the same tab and
     // race two --resume processes against a single sessionId.
-    const idx = waiting.findIndex((w) => !inFlight.has(w.tabId) && !dispatching.has(w.tabId));
+    const idx = waiting.findIndex((w) => !inFlight.has(w.tabId) && !dispatching.has(w.tabId)
+      && !liveSessions.has(w.sessionId));
     // Everything queued is blocked behind its own tab's live run; the settle()
     // of that run re-pumps.
     if (idx === -1) break;
@@ -415,6 +430,7 @@ function pump() {
     const [job] = waiting.splice(idx, 1);
     activeCount += 1;
     dispatching.add(job.tabId);
+    liveSessions.add(job.sessionId);
     Promise.resolve()
       .then(() => {
         const donePromise = executor(job);
@@ -425,6 +441,7 @@ function pump() {
       .catch(() => { /* executeRun never rejects; defensive */ })
       .finally(() => {
         dispatching.delete(job.tabId);
+        liveSessions.delete(job.sessionId);
         sessionSlots.release(slotToken);
         activeCount -= 1;
         pump();
@@ -478,6 +495,7 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
     // funnels through here so the exit path can emit a fallback only when the
     // run settled without one.
     let terminalSent = false;
+    let lineOverflowLogged = false;
     const emitTerminal = (channel, payload) => {
       if (terminalSent) return;
       terminalSent = true;
@@ -700,7 +718,9 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
     // Per-attempt state — a retry starts from empty buffers.
     let lineBuffer = '';
     let finalAssistantText = '';
-    let stderrBuffer = '';
+    const stderrBuffer = createHeadTailBuffer(STDERR_TAIL_MAX);
+
+    const stderrText = () => stderrBuffer.matchText();
 
     const processLine = (line) => {
       if (!line) return;
@@ -792,10 +812,25 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
         processLine(lineBuffer.slice(0, nl).trim());
         lineBuffer = lineBuffer.slice(nl + 1);
       }
+      if (lineBuffer.length > LINE_BUFFER_MAX) {
+        // Un-terminated line past the cap: drop it rather than grow forever.
+        lineBuffer = '';
+        if (!lineOverflowLogged) {
+          lineOverflowLogged = true;
+          opsErrorLog.appendError({
+            cwd,
+            scope: 'chatRunner',
+            tabId,
+            tags: silent ? ['silent-probe'] : [],
+            message: `stdout line exceeded ${LINE_BUFFER_MAX} bytes without a newline; buffer dropped`,
+            meta: { sessionId, silent },
+          });
+        }
+      }
     });
 
     thisChild.stderr.on('data', (chunk) => {
-      stderrBuffer += chunk.toString('utf8');
+      stderrBuffer.append(chunk.toString('utf8'));
     });
 
     thisChild.on('error', (err) => {
@@ -824,10 +859,10 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
       // terminal latch stay at executeRun level, so this is still one turn.
       if (!terminalSent && !killed && code !== 0 && attemptNo === 1
           && finalAssistantText === '' && recentToolUses.length === 0
-          && !/rate.?limit/i.test(stderrBuffer)) {
+          && !/rate.?limit/i.test(stderrText())) {
         const swapTo = resumeFlag
-          ? (NO_CONVERSATION_RE.test(stderrBuffer) ? false : null)
-          : (SESSION_IN_USE_RE.test(stderrBuffer) ? true : null);
+          ? (NO_CONVERSATION_RE.test(stderrText()) ? false : null)
+          : (SESSION_IN_USE_RE.test(stderrText()) ? true : null);
         if (swapTo !== null) {
           if (!silent) {
             broadcast('chat:run:notice', {
@@ -856,7 +891,7 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
             sessionId,
             message: 'run cancelled',
           });
-        } else if (SESSION_IN_USE_RE.test(stderrBuffer) || NO_CONVERSATION_RE.test(stderrBuffer)) {
+        } else if (SESSION_IN_USE_RE.test(stderrText()) || NO_CONVERSATION_RE.test(stderrText())) {
           // A session-flag rejection that survived the one-shot swap (or was
           // not eligible for it). The raw stderr dump names neither the flag,
           // the cwd nor the transcript — a real report cost a full diagnostic
@@ -875,9 +910,8 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
               + 'the session-flag resolution logic lives in main, and a stale build resolves it with older rules.',
           });
         } else {
-          const errDetail = stderrBuffer.trim()
-            ? `: ${stderrBuffer.trim().slice(0, 300)}`
-            : '';
+          const preview = stderrBuffer.preview();
+          const errDetail = preview ? `: ${preview}` : '';
           emitTerminal('chat:run:error', {
             tabId,
             sessionId,
@@ -996,6 +1030,7 @@ module.exports = {
   run,
   cancel,
   __resetQueueForTests,
+  __liveSessionCount: () => liveSessions.size,
   attachWindow,
   registerChatHandlers,
   parseStopSignal,

package/src/main/crashDiagnostics.cjs

@@ -27,11 +27,13 @@ const { app, powerSaveBlocker, powerMonitor, crashReporter } = require('electron
 const fs = require('node:fs');
 const path = require('node:path');
 const { reportCrash } = require('./lib/crashTelemetry.cjs');
+const { createLoopDelayMonitor, stallVerdict } = require('./lib/loopDelay.cjs');
 
 let logs = null;
 let getPowerBlockerId = () => -1;
 let onSuspendWhileAlive = null;
 let heartbeatTimer = null;
+let loopMonitor = null;
 let sentinelPath = null;
 let startedAtIso = null;
 let lastSample = null;
@@ -118,6 +120,7 @@ function heartbeat() {
   persistSentinel(false);
   const top = [...lastSample.procs].sort((a, b) => b.mb - a.mb).slice(0, 4);
   const level = lastSample.totalMb >= MEM_WARN_MB ? 'warn' : 'debug';
+  const loop = loopMonitor ? loopMonitor.snapshot() : null;
   logs?.writeLine({
     scope: 'crash-diag',
     level,
@@ -127,8 +130,11 @@ function heartbeat() {
       mainRssMb: lastSample.main.rssMb,
       powerBlockerHeld: lastSample.powerBlockerHeld,
       top: top.map((p) => `${p.type}:${p.mb}MB`),
+      ...loop,
     },
   });
+  const stall = loop && stallVerdict(loop);
+  if (stall) logs?.writeLine({ scope: 'crash-diag', ...stall, meta: { ...loop } });
 }
 
 // Read the previous run's sentinel. If it was still `open`, the app died
@@ -242,6 +248,8 @@ function init(opts) {
   persistSentinel(false);   // mark this run as open
   registerCrashHooks();
 
+  loopMonitor = createLoopDelayMonitor();
+  loopMonitor.enable();
   heartbeat();              // immediate baseline sample
   heartbeatTimer = setInterval(heartbeat, HEARTBEAT_MS);
   if (heartbeatTimer.unref) heartbeatTimer.unref(); // don't keep the loop alive
@@ -250,6 +258,7 @@ function init(opts) {
 // Call from will-quit so a graceful exit is distinguishable from an OOM-kill.
 function markCleanShutdown() {
   if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; }
+  if (loopMonitor) { loopMonitor.disable(); loopMonitor = null; }
   persistSentinel(true);
 }
 

package/src/main/git.cjs

@@ -23,6 +23,7 @@ const { spawn } = require('node:child_process');
 const path = require('node:path');
 const { schemas } = require('./ipcSchemas.cjs');
 const { validatePath } = require('./config.cjs');
+const { LRUCache } = require('./lib/lruCache.cjs');
 
 const GIT_TIMEOUT_MS = 5_000;
 const CACHE_TTL_MS = 5_000;
@@ -30,8 +31,11 @@ const MAX_BUFFER = 10 * 1024 * 1024; // 10 MiB — same cap Unleashed uses
 
 // Per-cwd in-memory caches. Keyed by the realpath-validated cwd so symlinks
 // to the same repo dedupe. Each entry: { value, expiresAt }.
-const statusCache = new Map();
-const fileStatusCache = new Map();
+// Bounded LRU: worktree cwds are unique per Epic/job, so an unbounded Map grew
+// for the app's lifetime and pinned every files[] array.
+const CACHE_MAX_CWDS = 16;
+const statusCache = new LRUCache(CACHE_MAX_CWDS);
+const fileStatusCache = new LRUCache(CACHE_MAX_CWDS);
 
 /**
  * Run `git <args>` in cwd with a hard 5s SIGKILL ceiling. Resolves
@@ -241,6 +245,7 @@ async function getStatus(cwd) {
   const now = Date.now();
   const cached = statusCache.get(realCwd);
   if (cached && cached.expiresAt > now) return cached.value;
+  if (cached) statusCache.delete(realCwd);
 
   // Single porcelain call gets us branch + ahead/behind + files in one shot.
   const result = await runGit(
@@ -281,6 +286,7 @@ async function getFileStatus(cwd) {
   const now = Date.now();
   const cached = fileStatusCache.get(realCwd);
   if (cached && cached.expiresAt > now) return cached.value;
+  if (cached) fileStatusCache.delete(realCwd);
 
   const result = await runGit(
     ['status', '--porcelain=v1', '-u', '-z'],
@@ -330,4 +336,5 @@ module.exports = {
   parsePorcelain,
   mapStatus,
   clearCache,
+  _caches: { statusCache, fileStatusCache, CACHE_MAX_CWDS },
 };

package/src/main/health.cjs

@@ -39,6 +39,8 @@ const PROJECT_ROOT = path.resolve(__dirname, '../..');
 // outage goes unnoticed for hours (the 2026-07-14 incident sat stalled for
 // 16.5h before anything asserted on it).
 const TICK_STALL_MULTIPLIER = 3;
+// A utilization hold whose reset is further out than this is not a routine 5h pause.
+const LONG_HOLD_MS = 5 * 60 * 60_000;
 const TICK_STALL_THRESHOLD_MS = TICK_STALL_MULTIPLIER * POLL_INTERVAL_MS;
 // A heartbeat line older than this is treated as "the app isn't running /
 // we can't observe live utilization" rather than "utilization is low" —
@@ -139,7 +141,19 @@ function evaluateTickLiveness(queueState, heartbeat, now, runningCount) {
       };
     }
     if (typeof heartbeat.utilization === 'number' && heartbeat.utilization >= config.utilizationThreshold) {
-      return { stalled: false, reason: 'utilization-at-threshold', utilization: heartbeat.utilization };
+      // A hold on the binding window is benign only if it self-heals soon
+      // (reset within 5h). A weekly hold, or an unknown reset horizon, can
+      // last days — surface it rather than reading GREEN.
+      const resetMs = heartbeat.nextReset ? Date.parse(heartbeat.nextReset) : NaN;
+      const longHold = !Number.isFinite(resetMs) || resetMs - now > LONG_HOLD_MS;
+      return {
+        stalled: false,
+        reason: 'utilization-at-threshold',
+        utilization: heartbeat.utilization,
+        window: heartbeat.utilizationWindow ?? null,
+        nextReset: heartbeat.nextReset ?? null,
+        ...(longHold ? { longHold: true } : {}),
+      };
     }
   }
 
@@ -860,6 +874,16 @@ async function check(opts = {}) {
       })(),
       loadGateThreshold: loadGateThreshold(),
     };
+    if (liveness.longHold) {
+      status.components.scheduler_queue.longHold = {
+        window: liveness.window, utilization: liveness.utilization, nextReset: liveness.nextReset,
+      };
+      status.issues.push(
+        `Queue held on the ${liveness.window ?? 'binding'} usage window at ${liveness.utilization}% (≥ threshold); `
+        + (liveness.nextReset ? `resets ${liveness.nextReset}` : 'reset time unknown')
+        + ' — hold may last days, not a normal short pause'
+      );
+    }
     if (liveness.stalled) {
       const ageMin = Math.round(liveness.tickAgeMs / 60_000);
       status.components.scheduler_queue.stalledJob = liveness.oldestPendingSlug;

package/src/main/historyAggregator.cjs

@@ -49,25 +49,8 @@ function resolvePricingKey(modelId) {
 }
 
 // ── LRU cache ─────────────────────────────────────────────────────────────────
-// Backed by an insertion-order Map: delete+re-insert on access = O(1) LRU.
-class LRUCache {
-  constructor(max) {
-    this._max = max;
-    this._m = new Map();
-  }
-  get(k) {
-    if (!this._m.has(k)) return undefined;
-    const v = this._m.get(k);
-    this._m.delete(k);
-    this._m.set(k, v);
-    return v;
-  }
-  set(k, v) {
-    this._m.delete(k);
-    this._m.set(k, v);
-    if (this._m.size > this._max) this._m.delete(this._m.keys().next().value);
-  }
-}
+// Shared implementation: lib/lruCache.cjs (re-exported below for existing callers).
+const { LRUCache } = require('./lib/lruCache.cjs');
 
 /**
  * Cache for parseJSONL results.

package/src/main/index.cjs

@@ -82,6 +82,7 @@ const { registerHistoryAggregatorHandlers, finalizeClosedDays, refreshIntradayTo
 const runLogRetention = require('./lib/runLogRetention.cjs');
 const { registerHistoryDashboardHandlers } = require('./historyDashboard.cjs');
 const { tryAcquireLock, releaseLock, DEFAULT_LOCK_PATH } = require('./lib/watchdogHelpers.cjs');
+const { createIntradayRefresh } = require('./lib/intradayRefresh.cjs');
 const schedulerConfig = require('./lib/schedulerConfig.cjs');
 const memoryTool = require('./memoryTool.cjs');
 const { registerMemoryAggregateIpc } = require('./memoryAggregate.cjs');
@@ -204,14 +205,9 @@ const REBOOT_LOG = path.join(os.homedir(), '.claude', 'session-manager-reboot.lo
 // finalize pass never interleave writes to the rollup file. A contended lock
 // just means this tick is skipped — the next timer tick (or the next boot)
 // retries, so skipping is always safe.
-function runIntradayRefresh() {
-  if (!tryAcquireLock(DEFAULT_LOCK_PATH)) return;
-  refreshIntradayToday()
-    .catch((e) => {
-      logs.writeLine({ scope: 'history-rollup', level: 'error', message: 'refreshIntradayToday failed', meta: { error: e?.message } });
-    })
-    .finally(() => releaseLock(DEFAULT_LOCK_PATH));
-}
+const runIntradayRefresh = createIntradayRefresh({
+  tryAcquireLock, releaseLock, lockPath: DEFAULT_LOCK_PATH, refresh: refreshIntradayToday, logs,
+});
 
 function logReboot(line) {
   try {
@@ -444,6 +440,9 @@ function createWindow() {
       });
   });
 
+  // Bounded auto-recovery for a crashed / hung / failed-to-load renderer.
+  require('./lib/rendererRecovery.cjs').attachRendererRecovery(mainWindow.webContents, { logs });
+
   // Native right-click menu — Copy / Paste / Select All everywhere. Roles
   // hook into Electron's built-in clipboard/selection plumbing, which xterm.js
   // (and Monaco, and Tiptap) all participate in via the standard DOM

package/src/main/ipcSchemas.cjs

@@ -1,3 +1,4 @@
+// @ts-check
 /**
  * Zod schemas for all IPC handler payloads. Applied at the boundary between
  * renderer and main — rejects malformed data before it reaches any business
@@ -152,20 +153,22 @@ const PROMPT_SESSION_ID_RE = /^(?!__proto__$|constructor$|prototype$)[A-Za-z0-9_
 // renderer only logs the failure). Dropping just the offending row matches how
 // the rest of this pipeline already fails: per-id (activeIndexMerge.cjs's
 // tombstone/resurrection handling), never per-batch.
+/** @param {unknown} raw */
 const dropInvalidSessions = (raw) => {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return raw;
+  const rec = /** @type {Record<string, unknown>} */ (raw);
   const kept = Object.create(null);
-  for (const id of Object.keys(raw)) {
+  for (const id of Object.keys(rec)) {
     if (!PROMPT_SESSION_ID_RE.test(id)) {
       console.warn(`[ipc] merge-active-index: dropping session with invalid id ${JSON.stringify(id)}`);
       continue;
     }
-    const parsed = PromptSessionSchema.safeParse(raw[id]);
+    const parsed = PromptSessionSchema.safeParse(rec[id]);
     if (!parsed.success) {
       console.warn(`[ipc] merge-active-index: dropping malformed session ${id} — ${parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`);
       continue;
     }
-    kept[id] = raw[id];
+    kept[id] = rec[id];
   }
   return kept;
 };
@@ -1046,6 +1049,13 @@ const telemetrySetConfig = z.object({
  * call sites already rely on throw semantics for malformed input, so we keep
  * that behavior for backwards compatibility.
  */
+/**
+ * @template T
+ * @template R
+ * @param {{ parse: (payload: unknown) => T }} schema
+ * @param {(parsed: T) => R} handler
+ * @returns {(_event: unknown, payload: unknown) => R}
+ */
 function validated(schema, handler) {
   return (_event, payload) => {
     const parsed = schema.parse(payload);