claude-code-session-manager 0.62.0 → 0.63.0

package/src/main/__tests__/scheduler-prd-missing-skip.test.cjs

@@ -23,6 +23,7 @@ const path = require('node:path');
 let tmpHome;
 let originalHome;
 let executeJob;
+let spawnJob;
 let PRDS_DIR;
 
 beforeAll(() => {
@@ -30,7 +31,7 @@ beforeAll(() => {
   tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-prd-missing-skip-'));
   process.env.HOME = tmpHome;
 
-  ({ executeJob, PRDS_DIR } = require('../scheduler.cjs'));
+  ({ executeJob, spawnJob, PRDS_DIR } = require('../scheduler.cjs'));
 
   if (!PRDS_DIR.startsWith(tmpHome)) {
     throw new Error(`refusing to run: PRDS_DIR (${PRDS_DIR}) is not under the temp HOME (${tmpHome})`);
@@ -87,3 +88,55 @@ test('a job whose PRD source exists but is unreadable for a non-ENOENT reason st
     fs.rmSync(runDir, { recursive: true, force: true });
   }
 });
+
+function registerActiveProject(cwd) {
+  const projectsDir = path.join(tmpHome, '.claude', 'projects');
+  const slugDir = path.join(projectsDir, `fake-project-slug-${path.basename(cwd)}`);
+  fs.mkdirSync(slugDir, { recursive: true });
+  fs.writeFileSync(path.join(slugDir, 'transcript.jsonl'), JSON.stringify({ cwd }) + '\n');
+}
+
+function writeProjectQueue(cwd, jobs) {
+  const stateDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'state');
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(path.join(stateDir, 'queue.json'), JSON.stringify({ jobs }, null, 2));
+  return path.join(stateDir, 'queue.json');
+}
+
+// This is the actual regression case: PRD 812's fix only covered executeJob's
+// own return value. The bug lived one layer up, in spawnJob's post-run
+// handler, which only short-circuited on skipped === 'prd-archived' and let
+// 'prd-missing' fall through into the verify path meant for real runs —
+// downgrading a stale-queue-entry retire into a needs_review with a bogus RCA
+// feedback item. Drive spawnJob itself (not just executeJob) so this covers
+// the actual defect, not just the classification it depends on.
+test("spawnJob's post-run handler retires a prd-missing skip as a plain completion, without running verify", async () => {
+  const projectCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-prd-missing-spawnjob-project-'));
+  registerActiveProject(projectCwd);
+  const runDir = fs.mkdtempSync(path.join(tmpHome, '.claude', 'sm-prd-missing-spawnjob-run-'));
+  try {
+    const slug = `812-test-spawnjob-missing-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+    const queuePath = writeProjectQueue(projectCwd, [
+      { slug, status: 'pending', cwd: projectCwd },
+    ]);
+
+    const job = { slug, cwd: projectCwd };
+    await spawnJob(job, 'run-spawnjob-missing', runDir, projectCwd);
+
+    const state = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
+    const row = state.jobs.find((j) => j.slug === slug);
+    expect(row).toBeDefined();
+    expect(row.status).toBe('completed');
+    expect(row.exitCode).toBe(0);
+    expect(row.error).toBeNull();
+    // No verify pass ran and no RCA feedback fired: a verified run always
+    // stamps a verify-derived status ('needs_review') or a landedCommit/verify
+    // field onto the row. Neither is present here — the row was completed by
+    // the early-return skip branch, not the verification block further down.
+    expect(row.status).not.toBe('needs_review');
+    expect(row.landedCommit).toBeUndefined();
+  } finally {
+    fs.rmSync(projectCwd, { recursive: true, force: true });
+    fs.rmSync(runDir, { recursive: true, force: true });
+  }
+});

package/src/main/__tests__/transcripts-batch-flush.test.cjs

@@ -0,0 +1,249 @@
+/**
+ * transcripts-batch-flush.test.cjs — unit tests for the batched IPC flush
+ * (PRD transcript-batch-flush): transcripts.cjs's doFlush now sends the
+ * events produced by ONE flush as a SINGLE `transcript:event:<tabId>` IPC
+ * message (an array), instead of one message per event, while still
+ * recording one OTEL span per event and preserving exact event order.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/transcripts-batch-flush.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 {
+  subscribe,
+  closeTab,
+  transcriptPath,
+  attachWindow,
+  __getSubForTest,
+  __doFlushForTest,
+  MAX_EVENTS_PER_BATCH,
+} = require('../transcripts.cjs');
+const otel = require('../otel.cjs');
+
+let cwd;
+
+beforeEach(() => {
+  cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-batch-flush-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(cwd, { recursive: true, force: true });
+  fs.rmSync(path.dirname(transcriptPath(cwd, 'x')), { recursive: true, force: true });
+  attachWindow(null);
+});
+
+function writeTranscript(cwdArg, sessionId, lines) {
+  const filePath = transcriptPath(cwdArg, sessionId);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, lines.map((l) => JSON.stringify(l)).join('\n') + '\n');
+  return filePath;
+}
+
+function appendTranscript(filePath, lines) {
+  fs.appendFileSync(filePath, lines.map((l) => JSON.stringify(l)).join('\n') + '\n');
+}
+
+/** A fake BrowserWindow that records every webContents.send call. */
+function makeFakeWindow() {
+  const sent = [];
+  return {
+    sent,
+    isDestroyed: () => false,
+    webContents: {
+      isDestroyed: () => false,
+      isCrashed: () => false,
+      send: (channel, payload) => sent.push({ channel, payload }),
+    },
+  };
+}
+
+function assistantLine(text, toolId) {
+  return {
+    type: 'assistant',
+    message: {
+      content: [
+        { type: 'text', text },
+        { type: 'tool_use', name: 'Bash', id: toolId, input: { command: 'ls' } },
+      ],
+    },
+  };
+}
+
+test('one flush with several multi-event lines sends exactly ONE IPC message carrying the whole ordered batch', async () => {
+  const sessionId = 'sess-one-batch';
+  const tabId = 'tab-one-batch';
+  const filePath = writeTranscript(cwd, sessionId, []);
+
+  const res = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res.ok).toBe(true);
+
+  const win = makeFakeWindow();
+  attachWindow(win);
+
+  // 5 lines * 2 events each = 10 events, well under MAX_EVENTS_PER_BATCH.
+  appendTranscript(
+    filePath,
+    Array.from({ length: 5 }, (_, i) => assistantLine(`line ${i}`, `tu-${i}`)),
+  );
+  const sub = __getSubForTest(tabId);
+  await sub.watcher?.close();
+  await __doFlushForTest(sub);
+
+  const messages = win.sent.filter((m) => m.channel === `transcript:event:${tabId}`);
+  expect(messages).toHaveLength(1);
+  expect(Array.isArray(messages[0].payload)).toBe(true);
+  expect(messages[0].payload).toHaveLength(10);
+  // Event order preserved: text/tool_use pairs in line order.
+  expect(messages[0].payload.map((e) => e.kind)).toEqual([
+    'assistant', 'tool_use', 'assistant', 'tool_use', 'assistant', 'tool_use', 'assistant', 'tool_use', 'assistant', 'tool_use',
+  ]);
+  expect(messages[0].payload.map((e) => e.data?.id ?? e.data).filter(Boolean)).toEqual(
+    expect.arrayContaining(['tu-0', 'tu-1', 'tu-2', 'tu-3', 'tu-4']),
+  );
+
+  closeTab(tabId);
+});
+
+test('order is preserved exactly across a multi-event flush (matches per-event order semantics)', async () => {
+  const sessionId = 'sess-order';
+  const tabId = 'tab-order';
+  const filePath = writeTranscript(cwd, sessionId, []);
+  const res = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res.ok).toBe(true);
+
+  const win = makeFakeWindow();
+  attachWindow(win);
+
+  appendTranscript(filePath, [
+    { type: 'user', message: { content: 'first' } },
+    assistantLine('second', 'tu-order-1'),
+    { type: 'user', message: { content: 'third' } },
+  ]);
+  const sub = __getSubForTest(tabId);
+  await sub.watcher?.close();
+  await __doFlushForTest(sub);
+
+  const messages = win.sent.filter((m) => m.channel === `transcript:event:${tabId}`);
+  expect(messages).toHaveLength(1);
+  const kinds = messages[0].payload.map((e) => e.kind);
+  const texts = messages[0].payload.map((e) =>
+    typeof e.data === 'string' ? e.data : e.data?.id ?? e.data?.message?.content,
+  );
+  expect(kinds).toEqual(['user', 'assistant', 'tool_use', 'user']);
+  expect(texts).toEqual(['first', 'second', 'tu-order-1', 'third']);
+
+  closeTab(tabId);
+});
+
+test('OTEL still records ONE span per event, not one per batch', async () => {
+  const sessionId = 'sess-otel-batch';
+  const tabId = 'tab-otel-batch';
+  const filePath = writeTranscript(cwd, sessionId, []);
+  const res = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res.ok).toBe(true);
+
+  const win = makeFakeWindow();
+  attachWindow(win);
+
+  const spy = vi.spyOn(otel, 'recordTranscriptEvent');
+  const before = spy.mock.calls.length;
+
+  appendTranscript(
+    filePath,
+    Array.from({ length: 6 }, (_, i) => assistantLine(`otel line ${i}`, `otel-tu-${i}`)),
+  );
+  const sub = __getSubForTest(tabId);
+  await sub.watcher?.close();
+  await __doFlushForTest(sub);
+
+  // 6 lines * 2 events = 12 spans, sent as one IPC batch.
+  expect(spy.mock.calls.length - before).toBe(12);
+  const messages = win.sent.filter((m) => m.channel === `transcript:event:${tabId}`);
+  expect(messages).toHaveLength(1);
+  expect(messages[0].payload).toHaveLength(12);
+
+  spy.mockRestore();
+  closeTab(tabId);
+});
+
+test('backpressure: a flush producing more than MAX_EVENTS_PER_BATCH events is sent as multiple ordered, capped batches', async () => {
+  const sessionId = 'sess-backpressure';
+  const tabId = 'tab-backpressure';
+  const filePath = writeTranscript(cwd, sessionId, []);
+  const res = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res.ok).toBe(true);
+
+  const win = makeFakeWindow();
+  attachWindow(win);
+
+  // Each line yields 2 events; pick a line count that produces more than
+  // 2x the cap so at least 3 batches are required.
+  const lineCount = Math.ceil((MAX_EVENTS_PER_BATCH * 2.5) / 2);
+  const totalEvents = lineCount * 2;
+  appendTranscript(
+    filePath,
+    Array.from({ length: lineCount }, (_, i) => assistantLine(`bp line ${i}`, `bp-tu-${i}`)),
+  );
+  const sub = __getSubForTest(tabId);
+  await sub.watcher?.close();
+  await __doFlushForTest(sub);
+
+  const messages = win.sent.filter((m) => m.channel === `transcript:event:${tabId}`);
+  expect(messages.length).toBeGreaterThan(1);
+  for (const m of messages) {
+    expect(m.payload.length).toBeLessThanOrEqual(MAX_EVENTS_PER_BATCH);
+  }
+  // Concatenating every batch in send order reproduces the full ordered
+  // event list — no event dropped, none duplicated, none reordered.
+  const flattened = messages.flatMap((m) => m.payload);
+  expect(flattened).toHaveLength(totalEvents);
+  const ids = flattened.map((e) => (e.kind === 'tool_use' ? e.data.id : null)).filter(Boolean);
+  expect(ids).toEqual(Array.from({ length: lineCount }, (_, i) => `bp-tu-${i}`));
+
+  closeTab(tabId);
+});
+
+test('benchmark: IPC message count drops from N-per-event to a small number of batches for a 20+ event flush', async () => {
+  const sessionId = 'sess-benchmark';
+  const tabId = 'tab-benchmark';
+  const filePath = writeTranscript(cwd, sessionId, []);
+  const res = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res.ok).toBe(true);
+
+  const win = makeFakeWindow();
+  attachWindow(win);
+
+  // 12 lines * 2 events = 24 events — at least 20, comfortably under one cap.
+  const lineCount = 12;
+  appendTranscript(
+    filePath,
+    Array.from({ length: lineCount }, (_, i) => assistantLine(`bench line ${i}`, `bench-tu-${i}`)),
+  );
+  const sub = __getSubForTest(tabId);
+  await sub.watcher?.close();
+  await __doFlushForTest(sub);
+
+  const messages = win.sent.filter((m) => m.channel === `transcript:event:${tabId}`);
+  const totalEvents = messages.reduce((n, m) => n + m.payload.length, 0);
+  expect(totalEvents).toBeGreaterThanOrEqual(20);
+
+  // BEFORE this PRD: doFlush sent one IPC message PER EVENT, so a 24-event
+  // flush meant 24 messages and (in the renderer) 24 store commits. AFTER:
+  // one message per flush (bounded by MAX_EVENTS_PER_BATCH), so the same
+  // flush is 1 message — a >20x reduction in IPC round-trips, and the
+  // renderer's live.ts/chat.ts now fold that one message into exactly one
+  // store commit each (see live.test.ts / chatTranscriptFeed.test.ts).
+  const beforeMessageCount = totalEvents; // one send per event, historically
+  const afterMessageCount = messages.length;
+  expect(afterMessageCount).toBeLessThan(beforeMessageCount);
+  expect(afterMessageCount).toBe(1);
+
+  closeTab(tabId);
+});

package/src/main/__tests__/transcripts-doFlush-array.test.cjs

@@ -29,6 +29,12 @@ beforeEach(() => {
 
 afterEach(() => {
   fs.rmSync(cwd, { recursive: true, force: true });
+  // writeTranscript mkdir -p's this run's folder under the REAL
+  // ~/.claude/projects (that's where transcriptPath resolves to), so leaving
+  // it behind accumulates one phantom project directory per test run — 1760
+  // of them had piled up before this cleanup existed, and Home counted every
+  // one as a project. Remove it with the tmp cwd it mirrors.
+  fs.rmSync(path.dirname(transcriptPath(cwd, 'x')), { recursive: true, force: true });
 });
 
 function writeTranscript(cwdArg, sessionId, lines) {

package/src/main/__tests__/transcripts-paged-reads.test.cjs

@@ -36,6 +36,12 @@ beforeEach(() => {
 
 afterEach(() => {
   fs.rmSync(cwd, { recursive: true, force: true });
+  // writeTranscript mkdir -p's this run's folder under the REAL
+  // ~/.claude/projects (that's where transcriptPath resolves to), so leaving
+  // it behind accumulates one phantom project directory per test run. Thousands
+  // had piled up before this cleanup existed, and Home counted every one as a
+  // project. Remove it with the tmp cwd it mirrors.
+  fs.rmSync(path.dirname(transcriptPath(cwd, 'x')), { recursive: true, force: true });
 });
 
 function writeTranscript(cwdArg, sessionId, lines) {

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

@@ -24,6 +24,12 @@ beforeEach(() => {
 
 afterEach(() => {
   fs.rmSync(cwd, { recursive: true, force: true });
+  // writeTranscript mkdir -p's this run's folder under the REAL
+  // ~/.claude/projects (that's where transcriptPath resolves to), so leaving
+  // it behind accumulates one phantom project directory per test run. Thousands
+  // had piled up before this cleanup existed, and Home counted every one as a
+  // project. Remove it with the tmp cwd it mirrors.
+  fs.rmSync(path.dirname(transcriptPath(cwd, 'x')), { recursive: true, force: true });
 });
 
 function writeTranscript(cwdArg, sessionId, lines) {

package/src/main/config.cjs

@@ -129,10 +129,7 @@ function validateWrite(realAbs) {
     (p) => realAbs === p || realAbs.startsWith(p + path.sep)
   );
   if (inWritePrefix) return;
-  // Also allowed inside a registered project root's .claude/ subtree, OR its
-  // tests/fixtures/browser-capture/ subtree (PRD 407 "PRD fixture" capture
-  // destination — narrowly scoped to that one path segment, not a general
-  // project-root write grant).
+  // Also allowed inside a registered project root's .claude/ subtree.
   for (const root of allowedRoots) {
     if (root === os.homedir()) continue;
     let realRoot;
@@ -142,24 +139,6 @@ function validateWrite(realAbs) {
       if (realAbs === claudeSub || realAbs.startsWith(claudeSub + path.sep)) {
         return;
       }
-      const fixturesSub = path.join(realRoot, 'tests', 'fixtures', 'browser-capture');
-      if (realAbs === fixturesSub || realAbs.startsWith(fixturesSub + path.sep)) {
-        return;
-      }
-      // PRD 410 Recorder → Playwright-spec export: narrowly scoped to
-      // tests/e2e/ (matches the repo's existing e2e spec location), not a
-      // general project-root write grant.
-      const e2eSub = path.join(realRoot, 'tests', 'e2e');
-      if (realAbs === e2eSub || realAbs.startsWith(e2eSub + path.sep)) {
-        return;
-      }
-      // Browser tab scratch saves (DOM captures, screenshots, recorded
-      // flows): narrowly scoped to session-manager-operations/browser/,
-      // this repo's existing per-project artifact-store convention.
-      const browserSub = path.join(realRoot, 'session-manager-operations', 'browser');
-      if (realAbs === browserSub || realAbs.startsWith(browserSub + path.sep)) {
-        return;
-      }
       // PromptSession persistence (active-index.json + per-session archives,
       // promptSessions.ts) and the scheduler's own read-modify-write of that
       // same active index (promptSessionEvents.cjs, PRD 814) — narrowly
@@ -220,17 +199,41 @@ async function readJson(abs) {
   }
 }
 
-async function readText(abs) {
+async function readText(abs, opts = {}) {
+  const { maxBytes } = opts;
   try {
     abs = validatePath(expandHome(abs));
-    const raw = await fsp.readFile(abs, 'utf8');
-    const stat = await fsp.stat(abs);
-    return { exists: true, text: raw, mtimeMs: stat.mtimeMs, error: null };
+    if (maxBytes == null) {
+      const raw = await fsp.readFile(abs, 'utf8');
+      const stat = await fsp.stat(abs);
+      return { exists: true, text: raw, mtimeMs: stat.mtimeMs, error: null, truncated: false };
+    }
+    const handle = await fsp.open(abs, 'r');
+    try {
+      const stat = await handle.stat();
+      const readLen = Math.min(maxBytes, stat.size);
+      const buf = Buffer.alloc(readLen);
+      if (readLen > 0) {
+        await handle.read(buf, 0, readLen, 0);
+      }
+      const truncated = stat.size > readLen;
+      let text = buf.toString('utf8');
+      if (truncated) {
+        // A byte-bounded read can split a multi-byte UTF-8 char or a JSONL
+        // line mid-way; drop the partial trailing line so callers never
+        // JSON.parse a truncated fragment.
+        const lastNewline = text.lastIndexOf('\n');
+        text = lastNewline === -1 ? '' : text.slice(0, lastNewline + 1);
+      }
+      return { exists: true, text, mtimeMs: stat.mtimeMs, error: null, truncated };
+    } finally {
+      await handle.close();
+    }
   } catch (e) {
     if (e.code === 'ENOENT') {
-      return { exists: false, text: '', mtimeMs: 0, error: null };
+      return { exists: false, text: '', mtimeMs: 0, error: null, truncated: false };
     }
-    return { exists: false, text: '', mtimeMs: 0, error: e.message };
+    return { exists: false, text: '', mtimeMs: 0, error: e.message, truncated: false };
   }
 }
 
@@ -459,7 +462,7 @@ function closeAllWatchers() {
 function registerConfigHandlers() {
   const { schemas: s, validated: v } = require('./ipcSchemas.cjs');
   ipcMain.handle('config:read-json', v(s.configPath, ({ path: p }) => readJson(p)));
-  ipcMain.handle('config:read-text', v(s.configPath, ({ path: p }) => readText(p)));
+  ipcMain.handle('config:read-text', v(s.configReadText, ({ path: p, maxBytes }) => readText(p, { maxBytes })));
   // `writer` is the renderer's declared owner id for the single-writer law
   // (lib/opsOwnership.cjs). Ignored outside the ops root; required inside it.
   ipcMain.handle('config:write-json', v(s.configWriteJson, ({ path: p, data, writer }) => {

package/src/main/files.cjs

@@ -318,6 +318,21 @@ async function deleteEntry(filePath) {
   }
 }
 
+/**
+ * Binary-safe atomic write (formerly browser:save-binary). Routes through
+ * config.cjs's writeBinaryAtomic so the single-writer law still applies to
+ * ops-root destinations; `writer` is the renderer's declared owner id.
+ */
+async function saveBinary(filePath, base64, writer) {
+  const { writeBinaryAtomic } = require('./config.cjs');
+  try {
+    await writeBinaryAtomic(filePath, Buffer.from(base64, 'base64'), { writer });
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e && e.message ? e.message : String(e) };
+  }
+}
+
 async function openExternal(filePath) {
   let resolved;
   try { resolved = validateHomePath(filePath); }
@@ -385,6 +400,10 @@ function registerFilesHandlers() {
     const { path: p } = filesPath.parse(payload);
     return deleteEntry(p);
   });
+  ipcMain.handle('files:save-binary', (_e, payload) => {
+    const { path: p, base64, writer } = schemas.filesSaveBinary.parse(payload);
+    return saveBinary(p, base64, writer);
+  });
   // files:open-external / files:show-in-finder consolidated into shell:open
   // (index.cjs, as: 'openPath' / 'revealPath'). The openExternal/showInFinder
   // functions are exported for that handler to call.
@@ -406,4 +425,5 @@ module.exports = {
   deleteEntry,
   duplicateEntry,
   duplicateNameFor,
+  saveBinary,
 };

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,
+};