claude-code-session-manager 0.86.0 → 0.88.0

package/src/main/__tests__/health-build-freshness.test.cjs

@@ -0,0 +1,39 @@
+/**
+ * health-build-freshness.test.cjs — evaluateBuildFreshness separates
+ * restart-needed (installed differs from running) from publish-needed
+ * (repo HEAD differs from installed); both reported, never critical.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/health-build-freshness.test.cjs
+ */
+'use strict';
+
+import { test, expect } from 'vitest';
+const { evaluateBuildFreshness } = require('../health.cjs');
+
+test('all shas equal → nothing needed', () => {
+  const r = evaluateBuildFreshness({ running: 'abc1234', installedOnDisk: 'abc1234', repoHead: 'abc1234' });
+  expect(r).toMatchObject({ ok: true, restartNeeded: false, publishNeeded: false });
+});
+
+test('installed differs from running → restart needed only', () => {
+  const r = evaluateBuildFreshness({ running: 'aaa1111', installedOnDisk: 'bbb2222', repoHead: 'bbb2222' });
+  expect(r).toMatchObject({ ok: true, restartNeeded: true, publishNeeded: false });
+});
+
+test('repo HEAD differs from installed → publish needed only', () => {
+  const r = evaluateBuildFreshness({ running: 'bbb2222', installedOnDisk: 'bbb2222', repoHead: 'ccc3333' });
+  expect(r).toMatchObject({ ok: true, restartNeeded: false, publishNeeded: true });
+});
+
+test('both differ → both reported, still ok (non-critical)', () => {
+  const r = evaluateBuildFreshness({ running: 'aaa1111', installedOnDisk: 'bbb2222', repoHead: 'ccc3333' });
+  expect(r).toMatchObject({ ok: true, restartNeeded: true, publishNeeded: true });
+  expect(r.note).toMatch(/restart needed/);
+  expect(r.note).toMatch(/publish needed/);
+});
+
+test('unknown inputs never claim a difference; short/long sha prefixes match', () => {
+  expect(evaluateBuildFreshness({})).toMatchObject({ restartNeeded: false, publishNeeded: false });
+  expect(evaluateBuildFreshness({ running: null, installedOnDisk: 'abc1234', repoHead: 'abc1234567890' }))
+    .toMatchObject({ restartNeeded: false, publishNeeded: false });
+});

package/src/main/__tests__/health-delegation-chain.test.cjs

@@ -84,9 +84,23 @@ test('failing check with no fix omits the "(fix: ...)" suffix', () => {
 });
 
 test('end-to-end: check() reports delegation_chain for this repo, expected to pass here', async () => {
-  const status = await check();
+  // Probes THIS machine's real user-scope config (~/.claude.json MCP registration, guard
+  // shims), so it reads the real home — not the per-run sandbox HOME. Read-only: scheduler
+  // state stays redirected to the sandbox (SM_SCHEDULER_HOME re-pinned after the HOME swap).
+  const sandboxHome = process.env.HOME;
+  const sandboxSchedulerHome = process.env.SM_SCHEDULER_HOME;
+  process.env.HOME = require('node:os').userInfo().homedir;
+  if (sandboxSchedulerHome !== undefined) process.env.SM_SCHEDULER_HOME = sandboxSchedulerHome;
+  process.env.SM_ALLOW_LIVE_ROOT_READS = '1';
+  let status;
+  try {
+    status = await check();
+  } finally {
+    delete process.env.SM_ALLOW_LIVE_ROOT_READS;
+    process.env.HOME = sandboxHome;
+  }
   expect(status.components.delegation_chain).toBeDefined();
-  expect(status.components.delegation_chain.checks).toHaveLength(8);
+  expect(status.components.delegation_chain.checks).toHaveLength(9);
   const ids = status.components.delegation_chain.checks.map((c) => c.id);
   expect(ids).toEqual([
     'scheduler-mcp',
@@ -97,6 +111,7 @@ test('end-to-end: check() reports delegation_chain for this repo, expected to pa
     'prd-write-guard',
     'destructive-git-guard',
     'inline-implementation-guard',
+    'self-schedule-guard',
   ]);
   // This repo registers the scheduler MCP at user scope (~/.claude.json) and
   // wires guard-prd-writes in .claude/settings.json, and no longer carries a

package/src/main/__tests__/health-queue-dispatch.test.cjs

@@ -2,7 +2,7 @@
  * health-queue-dispatch.test.cjs — `npm run health` must report non-GREEN
  * when there is at least one DISPATCHABLE pending job (reusing
  * classifyQueueStarvation's own 'starved' verdict, not merely "pending"),
- * nothing running, and no dispatch attempt in a long time — the exact shape
+ * nothing running, and no launch in a long time — the exact shape
  * of the 2026-09-11 incident (27 pending across two projects, 0 running, for
  * days, every other health surface reporting green). A dependsOn-blocked
  * queue must NOT trip this the same way: ticking can't fix a blocked chain,
@@ -18,7 +18,7 @@
 'use strict';
 
 import { test, expect } from 'vitest';
-const { evaluateQueueDispatchHealth, DISPATCH_STALL_THRESHOLD_MS } = require('../health.cjs');
+const { evaluateQueueDispatchHealth, DISPATCH_STALL_THRESHOLD_MS, DISPATCH_WARN_THRESHOLD_MS } = require('../health.cjs');
 
 const CWD = '/home/bilko/Projects/starry-night-ships';
 const NOW = Date.parse('2026-09-11T12:00:00.000Z');
@@ -28,7 +28,7 @@ test('a dispatchable pending job, 0 running, stale past the threshold — non-GR
   const state = {
     jobs: [{ slug: 'a', cwd: CWD, status: 'pending', dependsOn: [] }],
     paused: null,
-    lastDispatchAttemptAt: idleFor(DISPATCH_STALL_THRESHOLD_MS + 60_000),
+    lastRunAt: idleFor(DISPATCH_STALL_THRESHOLD_MS + 60_000),
   };
   const result = evaluateQueueDispatchHealth(state, 0, NOW);
   expect(result.ok).toBe(false);
@@ -44,7 +44,7 @@ test('every pending row behind a blocked dependsOn chain stays GREEN, reported a
       { slug: 'blocked-child', cwd: CWD, status: 'pending', dependsOn: ['dead'] },
     ],
     paused: null,
-    lastDispatchAttemptAt: idleFor(DISPATCH_STALL_THRESHOLD_MS + 60_000),
+    lastRunAt: idleFor(DISPATCH_STALL_THRESHOLD_MS + 60_000),
   };
   const result = evaluateQueueDispatchHealth(state, 0, NOW);
   expect(result.ok).toBe(true);
@@ -57,7 +57,7 @@ test('healthy queue (recent dispatch attempt) is GREEN with no verdict', () => {
   const state = {
     jobs: [{ slug: 'a', cwd: CWD, status: 'pending', dependsOn: [] }],
     paused: null,
-    lastDispatchAttemptAt: idleFor(60_000),
+    lastRunAt: idleFor(60_000),
   };
   const result = evaluateQueueDispatchHealth(state, 0, NOW);
   expect(result).toEqual({ ok: true });
@@ -67,7 +67,7 @@ test('nothing pending is GREEN regardless of how stale the dispatch timestamp is
   const state = {
     jobs: [{ slug: 'a', cwd: CWD, status: 'completed' }],
     paused: null,
-    lastDispatchAttemptAt: idleFor(DISPATCH_STALL_THRESHOLD_MS + 60_000),
+    lastRunAt: idleFor(DISPATCH_STALL_THRESHOLD_MS + 60_000),
   };
   const result = evaluateQueueDispatchHealth(state, 0, NOW);
   expect(result).toEqual({ ok: true });
@@ -77,8 +77,59 @@ test('work already running is GREEN — the queue is flowing', () => {
   const state = {
     jobs: [{ slug: 'a', cwd: CWD, status: 'pending', dependsOn: [] }],
     paused: null,
-    lastDispatchAttemptAt: idleFor(DISPATCH_STALL_THRESHOLD_MS + 60_000),
+    lastRunAt: idleFor(DISPATCH_STALL_THRESHOLD_MS + 60_000),
   };
   const result = evaluateQueueDispatchHealth(state, 1, NOW);
   expect(result).toEqual({ ok: true });
 });
+
+test('the two tiers are exported: 15-minute warn, 2-hour cold report', () => {
+  expect(DISPATCH_WARN_THRESHOLD_MS).toBe(15 * 60_000);
+  expect(DISPATCH_STALL_THRESHOLD_MS).toBe(2 * 60 * 60_000);
+});
+
+test('starved between the warn and cold thresholds — ok:true but flagged warn', () => {
+  const state = {
+    jobs: [{ slug: 'a', cwd: CWD, status: 'pending', dependsOn: [] }],
+    paused: null,
+    lastRunAt: idleFor(DISPATCH_WARN_THRESHOLD_MS + 60_000),
+  };
+  const result = evaluateQueueDispatchHealth(state, 0, NOW);
+  expect(result.ok).toBe(true);
+  expect(result.warn).toBe(true);
+  expect(result.starved).toBeUndefined();
+  expect(result.dispatchable).toBe(1);
+});
+
+test('below the warn threshold is plain GREEN', () => {
+  const state = {
+    jobs: [{ slug: 'a', cwd: CWD, status: 'pending', dependsOn: [] }],
+    paused: null,
+    lastRunAt: idleFor(DISPATCH_WARN_THRESHOLD_MS - 60_000),
+  };
+  expect(evaluateQueueDispatchHealth(state, 0, NOW)).toEqual({ ok: true });
+});
+
+test('ticks that launch nothing (fresh lastDispatchAttemptAt, stale lastRunAt) still go non-GREEN', () => {
+  const state = {
+    jobs: [{ slug: 'a', cwd: CWD, status: 'pending', dependsOn: [] }],
+    paused: null,
+    lastDispatchAttemptAt: idleFor(5_000),
+    lastRunAt: idleFor(DISPATCH_STALL_THRESHOLD_MS + 60_000),
+  };
+  const result = evaluateQueueDispatchHealth(state, 0, NOW);
+  expect(result.ok).toBe(false);
+  expect(result.starved).toBe(true);
+});
+
+test('rows held by an open launch breaker read blocked, not starved', () => {
+  const state = {
+    jobs: [{ slug: 'a', cwd: CWD, status: 'pending', dependsOn: [] }],
+    paused: null,
+    lastRunAt: idleFor(DISPATCH_STALL_THRESHOLD_MS + 60_000),
+    launchBlocks: { default: { kind: 'auth', at: NOW - 1000 } },
+  };
+  const result = evaluateQueueDispatchHealth(state, 0, NOW);
+  expect(result.ok).toBe(true);
+  expect(result.blocked).toBe(true);
+});

package/src/main/__tests__/health-tick-liveness.test.cjs

@@ -6,12 +6,12 @@
  * since they're pure/fs-isolated — no need to mock os.homedir() through the
  * full check() to cover the liveness logic.
  *
- * Run: timeout 120 node --test src/main/__tests__/health-tick-liveness.test.cjs
+ * Run: timeout 300 npx vitest run src/main/__tests__/health-tick-liveness.test.cjs
  */
 
 'use strict';
 
-const { test } = require('node:test');
+import { test } from 'vitest';
 const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const os = require('node:os');
@@ -72,6 +72,7 @@ test('no false positive: running is already at concurrencyCap', () => {
       { slug: '544-stuck-job', status: 'pending' },
     ],
   });
+  q.slotCap = 3; // machine-wide sessionSlots pool is the only cap now
   const result = evaluateTickLiveness(q, null, NOW);
   assert.strictEqual(result.stalled, false);
   assert.strictEqual(result.reason, 'at-capacity');
@@ -105,9 +106,16 @@ test('degrades honestly: heartbeat missing/stale means utilization cannot be rul
   assert.strictEqual(result.reason, 'cannot-verify-utilization');
 });
 
-test('does not caveat when firePolicy is not when-available (utilization is irrelevant, so no heartbeat needed)', () => {
+test('manual firePolicy: pending work with free capacity is configured behaviour, not a stall', () => {
   const q = baseQueue({ config: { ...baseQueue().config, firePolicy: 'manual' } });
   const result = evaluateTickLiveness(q, null, NOW);
+  assert.strictEqual(result.stalled, false);
+  assert.strictEqual(result.reason, 'manual-fire-policy');
+});
+
+test('does not caveat when firePolicy is neither when-available nor manual (no heartbeat needed)', () => {
+  const q = baseQueue({ config: { ...baseQueue().config, firePolicy: 'always' } });
+  const result = evaluateTickLiveness(q, null, NOW);
   assert.strictEqual(result.stalled, true);
 });
 

package/src/main/__tests__/health-usage-poller.test.cjs

@@ -1,12 +1,15 @@
 /**
- * health-usage-poller.test.cjs — `npm run health` must report non-GREEN when
- * the usage/rate-limit poller's (scheduler.cjs pollLoop) consecutiveFailures
- * streak, persisted to ~/.claude/session-manager/scheduler-state.json,
- * reaches FAILURE_STREAK_WARN_THRESHOLD — the SAME count that gates the
- * one-time opsErrorLog WARN (rateLimitPollerStreak.test.cjs shouldWarnFailureStreak
- * fires at `>= threshold`), so the log line and the health-GREEN flip happen
- * on the exact same failure, not one apart. Exercises evaluateUsagePollerHealth()
- * and loadUsagePollerState() directly since both are pure/file-scoped, matching
+ * health-usage-poller.test.cjs — `npm run health` must report GREEN / YELLOW
+ * / RED for the usage/rate-limit poller (scheduler.cjs pollLoop), driven by
+ * the shared usageCircuit's OWN open/closed state and how long it's been
+ * open (usageCircuitState/usageCircuitOpenedAt, persisted to
+ * ~/.claude/session-manager/scheduler-state.json by persistSchedulerState —
+ * this is a separate `npm run health` process, so it reads the PERSISTED
+ * circuit fields rather than holding the live in-memory breaker) — not the
+ * old binary consecutiveFailures<5 check, which read flatly non-GREEN
+ * forever after the fifth failure with no way to distinguish "just tripped"
+ * from "down for hours." Exercises evaluateUsagePollerHealth() and
+ * loadUsagePollerState() directly since both are pure/file-scoped, matching
  * every other evaluate* helper's test pattern in this file — deliberately NOT
  * driving the full (slow, machine-state-coupled) check() for this.
  *
@@ -20,44 +23,88 @@ import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 const { evaluateUsagePollerHealth, loadUsagePollerState } = require('../health.cjs');
-const { FAILURE_STREAK_WARN_THRESHOLD } = require('../scheduler.cjs');
+const { FAILURE_STREAK_ESCALATION_MS } = require('../scheduler.cjs');
 
 test('missing state (fresh install / poller never ran) is ok, not applicable', () => {
   expect(evaluateUsagePollerHealth(null)).toEqual({ ok: true, applicable: false });
   expect(evaluateUsagePollerHealth(undefined)).toEqual({ ok: true, applicable: false });
 });
 
-test('consecutiveFailures below the threshold is GREEN', () => {
-  const result = evaluateUsagePollerHealth({ consecutiveFailures: FAILURE_STREAK_WARN_THRESHOLD - 1, backoffMs: 240_000, lastPollAt: Date.now() });
+test('circuit closed is GREEN, regardless of a nonzero consecutiveFailures count', () => {
+  const result = evaluateUsagePollerHealth({ usageCircuitState: 'closed', consecutiveFailures: 2, backoffMs: 60_000, lastPollAt: Date.now() });
   expect(result.ok).toBe(true);
   expect(result.applicable).toBe(true);
+  expect(result.color).toBe('GREEN');
   expect(result.message).toBeUndefined();
 });
 
-test('consecutiveFailures AT the threshold is already non-GREEN — same count the WARN fires at', () => {
-  // Must match shouldWarnFailureStreak's `>= threshold` exactly (scheduler.cjs)
-  // so the opsErrorLog WARN and this health flip happen on the same failure.
-  const result = evaluateUsagePollerHealth({ consecutiveFailures: FAILURE_STREAK_WARN_THRESHOLD, backoffMs: 480_000, lastPollAt: Date.now() });
-  expect(result.ok).toBe(false);
-  expect(result.message).toMatch(new RegExp(`${FAILURE_STREAK_WARN_THRESHOLD} consecutive failures`));
+test('no usageCircuitState field at all (pre-upgrade sidecar) defaults to closed -> GREEN', () => {
+  const result = evaluateUsagePollerHealth({ consecutiveFailures: 0, backoffMs: null, lastPollAt: Date.now() });
+  expect(result.ok).toBe(true);
+  expect(result.color).toBe('GREEN');
 });
 
-test('consecutiveFailures well past the threshold is non-GREEN with a diagnostic message', () => {
-  const result = evaluateUsagePollerHealth({ consecutiveFailures: 57, backoffMs: 480_000, lastPollAt: Date.now() });
+test('circuit open for under FAILURE_STREAK_ESCALATION_MS (30 min) is YELLOW, not GREEN — but still ok:true, not yet critical', () => {
+  const now = Date.now();
+  const result = evaluateUsagePollerHealth({
+    usageCircuitState: 'open',
+    usageCircuitOpenedAt: now - 5 * 60_000, // 5 minutes ago
+    consecutiveFailures: 6,
+    backoffMs: 480_000,
+    lastPollAt: now,
+  });
+  // ok:true is deliberate — the circuit's own open threshold (3 consecutive
+  // failures) is LOWER than the old 5-failure WARN, so an ok:false YELLOW
+  // would silently tighten the overall `npm run health` rollup's failure bar
+  // from 5 down to 3. Graceful degradation must not itself read as critical.
+  expect(result.ok).toBe(true);
+  expect(result.color).toBe('YELLOW');
+  expect(result.message).toMatch(/YELLOW/);
+});
+
+test('circuit open for AT LEAST FAILURE_STREAK_ESCALATION_MS (30 min) is RED — ok:false, this is the critical state', () => {
+  const now = Date.now();
+  const result = evaluateUsagePollerHealth({
+    usageCircuitState: 'open',
+    usageCircuitOpenedAt: now - FAILURE_STREAK_ESCALATION_MS,
+    consecutiveFailures: 57,
+    backoffMs: 480_000,
+    lastPollAt: now,
+  });
   expect(result.ok).toBe(false);
+  expect(result.color).toBe('RED');
   expect(result.consecutiveFailures).toBe(57);
   expect(result.backoffMs).toBe(480_000);
-  expect(result.message).toMatch(/57 consecutive failures/);
+  expect(result.message).toMatch(/RED/);
+});
+
+test('half_open (mid-probe) is treated the same as open — not GREEN just because a probe is in flight', () => {
+  const now = Date.now();
+  const result = evaluateUsagePollerHealth({
+    usageCircuitState: 'half_open',
+    usageCircuitOpenedAt: now - 60_000,
+    consecutiveFailures: 5,
+    lastPollAt: now,
+  });
+  expect(result.ok).toBe(true); // still YELLOW-shaped (under the red threshold), so still ok:true
+  expect(result.color).toBe('YELLOW');
 });
 
-test('respects a custom threshold argument', () => {
-  expect(evaluateUsagePollerHealth({ consecutiveFailures: 3 }, 3).ok).toBe(false);
-  expect(evaluateUsagePollerHealth({ consecutiveFailures: 2 }, 3).ok).toBe(true);
+test('respects a custom redThresholdMs argument', () => {
+  const now = Date.now();
+  const openedAt = now - 10_000;
+  const red = evaluateUsagePollerHealth({ usageCircuitState: 'open', usageCircuitOpenedAt: openedAt, consecutiveFailures: 5 }, 5_000);
+  expect(red.color).toBe('RED');
+  expect(red.ok).toBe(false);
+  const yellow = evaluateUsagePollerHealth({ usageCircuitState: 'open', usageCircuitOpenedAt: openedAt, consecutiveFailures: 5 }, 60_000);
+  expect(yellow.color).toBe('YELLOW');
+  expect(yellow.ok).toBe(true);
 });
 
 test('tolerates a malformed/partial state object without throwing', () => {
   const result = evaluateUsagePollerHealth({});
   expect(result.ok).toBe(true);
+  expect(result.color).toBe('GREEN');
   expect(result.consecutiveFailures).toBe(0);
 });
 

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

@@ -135,7 +135,7 @@ test('appendRollupDays: compacts (dedupes) once file exceeds threshold', async (
     { date: '2026-07-01', projectDir: 'p', modelId: 'sonnet', inputTokens: 2 },
   ]);
   await historyRollup.compact();
-  const raw = fs.readFileSync(historyRollup.ROLLUP_PATH, 'utf8');
+  const raw = fs.readFileSync(historyRollup.historyRollupPath(), 'utf8');
   const nonEmptyLines = raw.split('\n').filter((l) => l.trim());
   expect(nonEmptyLines.length).toBe(1);
   expect(JSON.parse(nonEmptyLines[0]).inputTokens).toBe(2);
@@ -305,7 +305,7 @@ test('refreshIntradayToday: upserts a provisional (non-finalized) line for today
   // duplicates — today's line for the same key once the file is compacted.
   await historyAggregator.refreshIntradayToday();
   await historyRollup.compact();
-  const raw = fs.readFileSync(historyRollup.ROLLUP_PATH, 'utf8');
+  const raw = fs.readFileSync(historyRollup.historyRollupPath(), 'utf8');
   const matchingLines = raw.split('\n').filter((l) => {
     if (!l.trim()) return false;
     const obj = JSON.parse(l);

package/src/main/__tests__/kg-augment.test.cjs

@@ -14,10 +14,10 @@
  *      differences between log sources don't break the match.
  *
  * Does NOT spawn claude -p. Run:
- *   timeout 120 node --test src/main/__tests__/kg-augment.test.cjs
+ *   timeout 300 npx vitest run src/main/__tests__/kg-augment.test.cjs
  */
 
-const { test, describe, before, after } = require('node:test');
+import { test, describe, beforeAll as before, afterAll as after } from 'vitest';
 const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const fsp = require('node:fs/promises');

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

@@ -1,12 +1,12 @@
 /**
  * mcpStatus.test.cjs — unit tests for the `claude mcp list` output parser.
  *
- * Run: timeout 120 node --test src/main/__tests__/mcpStatus.test.cjs
+ * Run: timeout 300 npx vitest run src/main/__tests__/mcpStatus.test.cjs
  */
 
 'use strict';
 
-const { test } = require('node:test');
+import { test } from 'vitest';
 const assert = require('node:assert/strict');
 const { parseMcpList } = require('../mcpStatus.cjs');
 

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

@@ -1,6 +1,6 @@
 'use strict';
 
-const test = require('node:test');
+import { test } from 'vitest';
 const assert = require('node:assert/strict');
 const { parseClusters } = require('../memoryAggregate.cjs');
 

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

@@ -1,6 +1,6 @@
 'use strict';
 
-const test = require('node:test');
+import { test } from 'vitest';
 const assert = require('node:assert/strict');
 const { scoreMemories } = require('../lib/memoryStale.cjs');
 

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

@@ -0,0 +1,162 @@
+/**
+ * needsReviewLedger.test.cjs — unit tests for src/main/lib/needsReviewLedger.cjs's
+ * pure ladder-rung classification, line builders, and rollup reduction.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/needsReviewLedger.test.cjs
+ */
+'use strict';
+
+import { test, expect } from 'vitest';
+const {
+  LADDER_RUNGS,
+  classifyLadderRung,
+  buildNeedsReviewEntryLine,
+  buildNeedsReviewResolutionLine,
+  reduceNeedsReviewLedger,
+} = require('../lib/needsReviewLedger.cjs');
+
+// ---------- classifyLadderRung ----------
+
+test('classifyLadderRung maps every known automated source to its named rung', () => {
+  expect(classifyLadderRung({ source: 'scheduler:mechanicalRecovery' })).toBe('mechanical-recovery');
+  expect(classifyLadderRung({ source: 'spawnJob:dispatch', reason: 'dispatched for resume-recovery' })).toBe('resume-recovery');
+  expect(classifyLadderRung({ source: 'spawnInvestigation:start' })).toBe('auto-fix');
+  expect(classifyLadderRung({ source: 'spawnJob:auto-promote' })).toBe('auto-fix');
+  expect(classifyLadderRung({ source: 'reverifyNeedsReview:auto-promote' })).toBe('auto-fix');
+  expect(classifyLadderRung({ source: 'reverifyNeedsReview:heal' })).toBe('reverify');
+  expect(classifyLadderRung({ source: 'needsReviewAutoResolve' })).toBe('reverify');
+});
+
+test('classifyLadderRung: ordinary spawnJob:dispatch (no resume-recovery reason) is NOT resume-recovery', () => {
+  // 'spawnJob:dispatch' is shared with the everyday pending->running dispatch
+  // — only the resume-recovery REASON text distinguishes the two.
+  expect(classifyLadderRung({ source: 'spawnJob:dispatch', reason: 'dispatched for execution' })).toBe('manual-reset');
+});
+
+test('classifyLadderRung: unrecognized/explicit-reset sources default to manual-reset', () => {
+  expect(classifyLadderRung({ source: 'ipc:schedule:reset-job' })).toBe('manual-reset');
+  expect(classifyLadderRung({ source: 'remote:resetJob' })).toBe('manual-reset');
+  expect(classifyLadderRung({ source: 'clear-queue' })).toBe('manual-reset');
+  expect(classifyLadderRung({})).toBe('manual-reset');
+});
+
+test('LADDER_RUNGS names exactly the 6 documented rungs', () => {
+  expect(LADDER_RUNGS).toEqual(['mechanical-recovery', 'resume-recovery', 'quarantine', 'auto-fix', 'reverify', 'manual-reset']);
+});
+
+// ---------- buildNeedsReviewEntryLine / buildNeedsReviewResolutionLine ----------
+
+test('buildNeedsReviewEntryLine: park reason prefers verifierVerdict, then heldReason, then error', () => {
+  const entry = { to: 'needs_review', source: 'spawnJob:finalize', at: '2026-09-13T00:00:00.000Z' };
+  expect(buildNeedsReviewEntryLine({ slug: 's1', verifierVerdict: 'uncommitted_changes', heldReason: 'held', error: 'err' }, entry).reason).toBe('uncommitted_changes');
+  expect(buildNeedsReviewEntryLine({ slug: 's1', heldReason: 'held', error: 'err' }, entry).reason).toBe('held');
+  expect(buildNeedsReviewEntryLine({ slug: 's1', error: 'err' }, entry).reason).toBe('err');
+  expect(buildNeedsReviewEntryLine({ slug: 's1' }, entry).reason).toBeNull();
+});
+
+test('buildNeedsReviewEntryLine: carries slug/cwd/epicId/runId/at/source verbatim', () => {
+  const job = { slug: '42-x', cwd: '/proj', epicId: 'epic-1', runId: 'run-9' };
+  const entry = { to: 'needs_review', source: 'spawnJob:finalize', at: '2026-09-13T00:00:00.000Z' };
+  const line = buildNeedsReviewEntryLine(job, entry);
+  expect(line).toEqual({
+    kind: 'needs_review_entry',
+    slug: '42-x',
+    cwd: '/proj',
+    epicId: 'epic-1',
+    runId: 'run-9',
+    at: '2026-09-13T00:00:00.000Z',
+    reason: null,
+    source: 'spawnJob:finalize',
+  });
+});
+
+test('buildNeedsReviewResolutionLine: references the EPISODE runId, not job.runId, and computes dwellMs', () => {
+  const job = { slug: '42-x', cwd: '/proj', epicId: 'epic-1', runId: 'run-LATER' };
+  const entry = { to: 'completed', source: 'reverifyNeedsReview:heal', at: '2026-09-13T00:10:00.000Z' };
+  const episode = { runId: 'run-ORIGINAL', enteredAt: '2026-09-13T00:00:00.000Z' };
+  const line = buildNeedsReviewResolutionLine(job, entry, episode);
+  expect(line.runId).toBe('run-ORIGINAL');
+  expect(line.resolvedTo).toBe('completed');
+  expect(line.ladderRung).toBe('reverify');
+  expect(line.dwellMs).toBe(10 * 60_000);
+});
+
+test('buildNeedsReviewResolutionLine: dwellMs is null when the episode has no enteredAt (defensive — should not happen in practice)', () => {
+  const job = { slug: '42-x', runId: 'run-1' };
+  const entry = { to: 'failed', source: 'ipc:schedule:reset-job', at: '2026-09-13T00:00:00.000Z' };
+  const line = buildNeedsReviewResolutionLine(job, entry, { runId: 'run-1', enteredAt: null });
+  expect(line.dwellMs).toBeNull();
+});
+
+// ---------- reduceNeedsReviewLedger ----------
+
+function entryLine({ slug, runId, at, reason = 'uncommitted_changes', source = 'spawnJob:finalize' }) {
+  return { kind: 'needs_review_entry', slug, cwd: null, epicId: null, runId, at, reason, source };
+}
+function resolutionLine({ slug, runId, at, resolvedTo = 'completed', ladderRung = 'reverify', source = 'reverifyNeedsReview:heal', dwellMs = 1000 }) {
+  return { kind: 'needs_review_resolution', slug, cwd: null, epicId: null, runId, at, resolvedTo, ladderRung, source, dwellMs };
+}
+
+test('reduceNeedsReviewLedger: entry-only (unresolved) episode counts toward byReason and unresolvedCount, not byLadderRung', () => {
+  const lines = [entryLine({ slug: 'a', runId: 'r1', at: '2026-09-13T00:00:00.000Z', reason: 'silent_no_op' })];
+  const rollup = reduceNeedsReviewLedger(lines);
+  expect(rollup.byReason).toEqual({ silent_no_op: 1 });
+  expect(rollup.byLadderRung).toEqual({});
+  expect(rollup.unresolvedCount).toBe(1);
+  expect(rollup.dwellMsP50).toBeNull();
+  expect(rollup.dwellMsP90).toBeNull();
+});
+
+test('reduceNeedsReviewLedger: entry+resolution pair resolves and contributes dwell', () => {
+  const lines = [
+    entryLine({ slug: 'a', runId: 'r1', at: '2026-09-13T00:00:00.000Z' }),
+    resolutionLine({ slug: 'a', runId: 'r1', at: '2026-09-13T00:00:05.000Z', dwellMs: 5000, ladderRung: 'mechanical-recovery' }),
+  ];
+  const rollup = reduceNeedsReviewLedger(lines);
+  expect(rollup.unresolvedCount).toBe(0);
+  expect(rollup.byLadderRung).toEqual({ 'mechanical-recovery': 1 });
+  expect(rollup.dwellMsP50).toBe(5000);
+  expect(rollup.dwellMsP90).toBe(5000);
+});
+
+test('reduceNeedsReviewLedger: repeated entries for the same slug (different runIds) count as independent episodes', () => {
+  const lines = [
+    entryLine({ slug: 'a', runId: 'r1', at: '2026-09-13T00:00:00.000Z', reason: 'uncommitted_changes' }),
+    resolutionLine({ slug: 'a', runId: 'r1', at: '2026-09-13T00:00:10.000Z', dwellMs: 10_000, ladderRung: 'manual-reset' }),
+    entryLine({ slug: 'a', runId: 'r2', at: '2026-09-13T01:00:00.000Z', reason: 'uncommitted_changes' }),
+    // r2 never resolves.
+  ];
+  const rollup = reduceNeedsReviewLedger(lines);
+  expect(rollup.byReason).toEqual({ uncommitted_changes: 2 });
+  expect(rollup.unresolvedCount).toBe(1);
+  expect(rollup.byLadderRung).toEqual({ 'manual-reset': 1 });
+  expect(rollup.dwellMsP50).toBe(10_000);
+});
+
+test('reduceNeedsReviewLedger: p50/p90 over several resolved episodes', () => {
+  const dwells = [1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10_000];
+  const lines = dwells.flatMap((d, i) => [
+    entryLine({ slug: `s${i}`, runId: `r${i}`, at: '2026-09-13T00:00:00.000Z' }),
+    resolutionLine({ slug: `s${i}`, runId: `r${i}`, at: '2026-09-13T00:00:00.000Z', dwellMs: d }),
+  ]);
+  const rollup = reduceNeedsReviewLedger(lines);
+  expect(rollup.dwellMsP50).toBe(5000);
+  expect(rollup.dwellMsP90).toBe(9000);
+});
+
+test('reduceNeedsReviewLedger: ignores unrelated (terminal) rows mixed into the same lines array', () => {
+  const lines = [
+    { kind: 'terminal', slug: 'a', status: 'completed', runId: 'r1' },
+    { slug: 'b', status: 'failed', runId: 'r2' }, // legacy row, no kind at all
+    entryLine({ slug: 'c', runId: 'r3', at: '2026-09-13T00:00:00.000Z' }),
+  ];
+  const rollup = reduceNeedsReviewLedger(lines);
+  expect(rollup.unresolvedCount).toBe(1);
+  expect(Object.keys(rollup.byReason)).toEqual(['uncommitted_changes']);
+});
+
+test('reduceNeedsReviewLedger: empty/non-array input returns a zeroed rollup, never throws', () => {
+  expect(reduceNeedsReviewLedger([])).toEqual({ byReason: {}, byLadderRung: {}, unresolvedCount: 0, dwellMsP50: null, dwellMsP90: null });
+  expect(reduceNeedsReviewLedger(null)).toEqual({ byReason: {}, byLadderRung: {}, unresolvedCount: 0, dwellMsP50: null, dwellMsP90: null });
+  expect(reduceNeedsReviewLedger(undefined)).toEqual({ byReason: {}, byLadderRung: {}, unresolvedCount: 0, dwellMsP50: null, dwellMsP90: null });
+});