claude-code-session-manager 0.93.0 → 0.94.0

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/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/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);

package/src/main/lib/__tests__/childWithLog.test.cjs

@@ -139,3 +139,183 @@ describe('childWithLog onExit leakedDescendants reporting (PRD 1110)', () => {
     15000,
   );
 });
+
+// PRD 1353 — async enumeration must never block/alter the kill cascade, and a
+// throwing watchdog must not break the wall-clock kill path.
+describe('childWithLog async enumeration + guarded watchdog (PRD 1353)', () => {
+  const { _deps } = require('../childWithLog.cjs');
+  const realExecFile = _deps.execFile;
+  afterEach(() => { _deps.execFile = realExecFile; });
+
+  it.skipIf(process.platform !== 'linux')(
+    'enumeration failure omits the report, logs, and still kills the group',
+    async () => {
+      dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-child-enumfail-'));
+      const logPath = path.join(dir, 'job.log');
+      const pidFile = path.join(dir, 'grandchild.pid');
+      const { fd, safeLog, closeFd } = openLog(logPath);
+      _deps.execFile = (_c, _a, _o, cb) => { setImmediate(() => cb(new Error('ps boom'))); };
+
+      const exitInfo = await new Promise((resolve) => {
+        withChildAndLog({
+          fd, logPath, safeLog, closeFd,
+          spawn: {
+            command: 'sh',
+            args: ['-c', `sleep 30 & echo $! > ${pidFile}; exec sleep 0.2`],
+            options: { detached: true },
+          },
+          onExit: (info) => { info.safeLog('onExit-ran\n'); resolve(info); },
+        });
+      });
+      expect(exitInfo.leakedDescendants).toEqual([]);
+      for (let i = 0; i < 20 && !fs.existsSync(pidFile); i++) await new Promise((r) => setTimeout(r, 50));
+      const gc = Number(fs.readFileSync(pidFile, 'utf8').trim());
+      await new Promise((r) => setTimeout(r, 500)); // SIGTERM lands immediately, no grace wait
+      expect(() => process.kill(gc, 0)).toThrow();
+      expect(fs.readFileSync(logPath, 'utf8')).toContain('enumeration failed');
+    },
+    15000,
+  );
+
+  function runWatchdog(wd) {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-child-wd-'));
+    const logPath = path.join(dir, 'job.log');
+    const { fd, safeLog, closeFd } = openLog(logPath);
+    let handle;
+    const done = new Promise((resolve) => {
+      handle = withChildAndLog({
+        fd, logPath, safeLog, closeFd,
+        spawn: { command: 'sleep', args: ['5'], options: {} },
+        watchdogs: [{ label: 'w', intervalMs: 20, ...wd }],
+        onExit: resolve,
+      });
+    });
+    return { logPath, handle, done };
+  }
+
+  it('a throwing shouldFire does not stop a later tick firing the action', async () => {
+    let calls = 0;
+    let fired = 0;
+    const { handle, logPath, done } = runWatchdog({
+      shouldFire: () => { calls++; if (calls < 3) throw new Error('sf boom'); return true; },
+      action: (ctx) => { fired++; ctx.killedByWatchdog = 'w'; ctx.killTree('SIGTERM'); },
+    });
+    const info = await done;
+    expect(fired).toBe(1);
+    expect(info.killedByWatchdog).toBe('w');
+    expect(fs.readFileSync(logPath, 'utf8')).toContain('watchdog "w" threw: sf boom');
+    handle.cancel();
+  }, 10000);
+
+  it('a throwing action clears its interval and is logged', async () => {
+    let should = 0;
+    let acts = 0;
+    const { handle, logPath, done } = runWatchdog({
+      shouldFire: () => { should++; return true; },
+      action: () => { acts++; throw new Error('act boom'); },
+    });
+    await new Promise((r) => setTimeout(r, 200));
+    expect(acts).toBe(1);
+    expect(should).toBe(1);
+    expect(fs.readFileSync(logPath, 'utf8')).toContain('watchdog "w" threw: act boom');
+    handle.cancel();
+    await done;
+  }, 10000);
+});
+
+// PRD 1370 — enumerate BEFORE SIGTERM; no-enumeration paths stay synchronous.
+describe('childWithLog sweep ordering + sync paths (PRD 1370)', () => {
+  const { _deps } = require('../childWithLog.cjs');
+  const realExecFile = _deps.execFile;
+  const realKill = process.kill;
+  afterEach(() => { _deps.execFile = realExecFile; process.kill = realKill; });
+
+  function setup(name) {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), name));
+    const logPath = path.join(dir, 'job.log');
+    return { logPath, ...openLog(logPath) };
+  }
+
+  it.skipIf(process.platform !== 'linux').each([
+    ['successful', (cb) => cb(null, 'PID PGRP %CPU ELAPSED COMMAND\n')],
+    ['failing', (cb) => cb(new Error('ps boom'))],
+  ])('SIGTERM waits for the %s enumeration', async (label, respond) => {
+    const { logPath, fd, safeLog, closeFd } = setup('sm-child-order-');
+    let psCb;
+    _deps.execFile = (_c, _a, _o, cb) => { psCb = cb; };
+    const groupKills = [];
+    process.kill = (pid, sig) => {
+      if (pid < -1 && sig === 'SIGTERM') { groupKills.push(pid); return true; }
+      return realKill.call(process, pid, sig);
+    };
+    let info;
+    const done = new Promise((resolve) => {
+      withChildAndLog({
+        fd, logPath, safeLog, closeFd,
+        spawn: { command: 'sh', args: ['-c', 'exit 0'], options: { detached: true } },
+        onExit: (i) => { info = i; resolve(); },
+      });
+    });
+    for (let i = 0; i < 100 && !psCb; i++) await new Promise((r) => setTimeout(r, 20));
+    expect(psCb).toBeTruthy();
+    await new Promise((r) => setTimeout(r, 100));
+    expect(groupKills).toEqual([]);
+    respond(psCb);
+    await done; // onExit runs only after the kill was issued
+    expect(groupKills.length).toBe(1);
+    expect(info.leakedDescendants).toEqual([]);
+    if (label === 'failing') expect(fs.readFileSync(logPath, 'utf8')).toContain('enumeration failed');
+  }, 15000);
+
+  it('runs onExit synchronously when the spawn throws', () => {
+    const { logPath, fd, safeLog, closeFd } = setup('sm-child-spawnfail-');
+    let ran = false;
+    const r = withChildAndLog({
+      fd, logPath, safeLog, closeFd,
+      spawn: { command: 'sh', args: [], options: { cwd: '/nonexistent\0bad', detached: true } },
+      onExit: (i) => { ran = i.spawnFailed === true; },
+    });
+    expect(r.child).toBeNull();
+    expect(ran).toBe(true);
+  });
+
+  it.skipIf(process.platform !== 'linux')('a throwing deferred onExit is logged and still closes the fd', async () => {
+    const { logPath, fd, safeLog, closeFd } = setup('sm-child-throw-');
+    _deps.execFile = (_c, _a, _o, cb) => { setImmediate(() => cb(null, 'h\n')); };
+    const unhandled = [];
+    const h = (e) => unhandled.push(e);
+    process.on('unhandledRejection', h);
+    let closed = false;
+    const wrapClose = () => { closed = true; closeFd(); };
+    await new Promise((resolve) => {
+      withChildAndLog({
+        fd, logPath, safeLog, closeFd: wrapClose,
+        spawn: { command: 'sh', args: ['-c', 'exit 0'], options: { detached: true } },
+        onExit: () => { setImmediate(resolve); throw new Error('exit boom'); },
+      });
+    });
+    await new Promise((r) => setTimeout(r, 50));
+    process.off('unhandledRejection', h);
+    expect(unhandled).toEqual([]);
+    expect(closed).toBe(true);
+    expect(fs.readFileSync(logPath, 'utf8')).toContain('onExit threw: exit boom');
+  }, 15000);
+
+  it('a throwing synchronous onExit is logged, closes the fd, and is re-thrown', async () => {
+    const { logPath, fd, safeLog, closeFd } = setup('sm-child-throw-sync-');
+    let closed = false;
+    const wrapClose = () => { closed = true; closeFd(); };
+    const thrown = await new Promise((resolve) => {
+      const onUncaught = (e) => { process.off('uncaughtException', onUncaught); resolve(e); };
+      process.on('uncaughtException', onUncaught);
+      withChildAndLog({
+        fd, logPath, safeLog, closeFd: wrapClose,
+        spawn: { command: 'sh', args: ['-c', 'exit 0'] },
+        onExit: () => { throw new Error('exit boom'); },
+      });
+    });
+    expect(thrown.message).toBe('exit boom');
+    expect(closed).toBe(true);
+    expect(fs.readFileSync(logPath, 'utf8')).toContain('onExit threw: exit boom');
+  }, 15000);
+});

package/src/main/lib/__tests__/delegationReadiness.test.cjs

@@ -1154,3 +1154,22 @@ test('ensureGuardsInstalled: records every auto-install attempt in the ops error
   expect(delegationLines.every((l) => l.level === 'info')).toBe(true);
   expect(delegationLines.every((l) => l.meta?.action === 'installed')).toBe(true);
 }, 15_000);
+
+test('ensureGuardsInstalled: an already-installed re-run writes no new ops error-log rows', async () => {
+  const cwd = await mkTmp('sm-ensure-guards-noop-');
+  const homeDir = await mkTmp('sm-ensure-guards-noop-home-');
+
+  await ensureGuardsInstalled(cwd, { homeDir });
+  const logFile = opsErrorLogTodayFile(cwd);
+  const before = fs.readFileSync(logFile, 'utf8');
+
+  clearGuardsInstalledCache();
+  const again = await ensureGuardsInstalled(cwd, { homeDir });
+  expect(Object.values(again.guards).every((g) => g.action === 'already-installed')).toBe(true);
+  expect(fs.readFileSync(logFile, 'utf8')).toBe(before);
+}, 15_000);
+
+test('delegationReadiness.cjs source contains no raw NUL byte', () => {
+  const src = fs.readFileSync(path.join(__dirname, '..', 'delegationReadiness.cjs'));
+  expect(src.includes(0)).toBe(false);
+});

package/src/main/lib/__tests__/gitCacheBound.test.cjs

@@ -0,0 +1,69 @@
+/**
+ * gitCacheBound.test.cjs — git status caches are LRU-bounded and drop expired entries.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/gitCacheBound.test.cjs
+ */
+'use strict';
+
+import { test, expect, beforeEach, afterEach, vi } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { addAllowedRoot } = require('../../config.cjs');
+const git = require('../../git.cjs');
+
+const { statusCache, fileStatusCache, CACHE_MAX_CWDS } = git._caches;
+let root;
+beforeEach(() => {
+  git.clearCache();
+  root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'git-cache-bound-')));
+  addAllowedRoot(root);
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+function mkdirs(n) {
+  return Array.from({ length: n }, (_, i) => {
+    const d = path.join(root, `d${i}`);
+    fs.mkdirSync(d);
+    return fs.realpathSync(d);
+  });
+}
+
+test('50 distinct cwds never exceed the cap', async () => {
+  for (const d of mkdirs(50)) {
+    await git.getStatus(d);
+    await git.getFileStatus(d);
+  }
+  expect(statusCache.size).toBeLessThanOrEqual(CACHE_MAX_CWDS);
+  expect(fileStatusCache.size).toBeLessThanOrEqual(CACHE_MAX_CWDS);
+  expect(statusCache.size).toBe(CACHE_MAX_CWDS);
+});
+
+test('an expired entry is deleted when encountered', async () => {
+  const [d] = mkdirs(1);
+  const t0 = 1_000_000;
+  const now = vi.spyOn(Date, 'now').mockReturnValue(t0);
+  await git.getStatus(d);
+  await git.getFileStatus(d);
+  expect(statusCache.get(d).expiresAt).toBe(t0 + 5_000);
+
+  // Live entry: served from cache, untouched.
+  now.mockReturnValue(t0 + 4_999);
+  await git.getStatus(d);
+  expect(statusCache.get(d).expiresAt).toBe(t0 + 5_000);
+
+  // Expired: the stale entry is deleted and replaced by a fresh one.
+  now.mockReturnValue(t0 + 60_000);
+  const del = vi.spyOn(statusCache, 'delete');
+  await git.getStatus(d);
+  expect(del).toHaveBeenCalledWith(d);
+  expect(statusCache.get(d).expiresAt).toBe(t0 + 65_000);
+
+  const delFile = vi.spyOn(fileStatusCache, 'delete');
+  await git.getFileStatus(d);
+  expect(delFile).toHaveBeenCalledWith(d);
+  expect(fileStatusCache.get(d).expiresAt).toBe(t0 + 65_000);
+});

package/src/main/lib/agentPersonaSchema.cjs

@@ -1,3 +1,4 @@
+// @ts-check
 /**
  * Canonical runtime schema for an Agent persona WRITE payload, mirroring the
  * TS `AgentPersonaSaveInput` interface in src/preload/api.d.ts
@@ -67,6 +68,7 @@ const AgentPersonaSaveSchema = z.object({
  * Throws a clear, descriptive error (not a raw ZodError dump) when `persona`
  * doesn't match AgentPersonaSaveSchema. Mirrors assertValidPromptSession /
  * assertValidScheduleJob's shape and message format exactly.
+ * @param {unknown} persona
  */
 function assertValidAgentPersonaSave(persona) {
   const result = AgentPersonaSaveSchema.safeParse(persona);