claude-code-session-manager 0.87.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,7 +84,21 @@ 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(9);
   const ids = status.components.delegation_chain.checks.map((c) => c.id);

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__/opsErrorLogTelemetryTap.test.cjs

@@ -18,10 +18,15 @@ const opsErrorLog = require('../lib/opsErrorLog.cjs');
 const tmpDirs = [];
 let originalHome;
 let originalSmTelemetrySpool;
+let originalWorktreeRoot;
 
 afterEach(async () => {
   if (originalHome !== undefined) process.env.HOME = originalHome;
   if (originalSmTelemetrySpool === undefined) delete process.env.SM_TELEMETRY_SPOOL; else process.env.SM_TELEMETRY_SPOOL = originalSmTelemetrySpool;
+  if (originalWorktreeRoot !== undefined) {
+    if (originalWorktreeRoot === null) delete process.env.SM_WORKTREE_ROOT; else process.env.SM_WORKTREE_ROOT = originalWorktreeRoot;
+    originalWorktreeRoot = undefined;
+  }
   const telemetryPath = require.resolve('../lib/telemetryClient.cjs');
   delete require.cache[telemetryPath];
   const activeSessionsPath = require.resolve('../lib/activeSessions.cjs');
@@ -85,6 +90,17 @@ test('level "warn" routes to telemetryClient.logLine, default "error" routes to
 // ─── ephemeral cwd: local refused, telemetry still fires ─────────────────
 
 test('an ephemeral cwd yields zero local lines but one telemetry record, with a normalized projectHash', () => {
+  // Why this test depends on the process tmpdir: ephemeral classification
+  // (cwdClassify.classifyCwd, via ephemeralCwd.isEphemeralCwd) is an exact match
+  // on os.tmpdir() plus a prefix match on the managed job/epic worktree roots,
+  // and those roots are <SM_WORKTREE_ROOT || os.tmpdir()>/session-manager-*-worktrees
+  // (schedulerPaths.worktreeRoot). The sandbox globalSetup mkdtemp's that base under
+  // the tmpdir it saw at startup, so a relocated TMPDIR / prior env mutation changes
+  // where KIND_CONFIG.epic.root points. Pin SM_WORKTREE_ROOT to a fixture dir this
+  // test owns and derive the cwd from KIND_CONFIG, so expected and actual roots
+  // resolve through the same code path regardless of TMPDIR.
+  originalWorktreeRoot = process.env.SM_WORKTREE_ROOT === undefined ? null : process.env.SM_WORKTREE_ROOT;
+  process.env.SM_WORKTREE_ROOT = mkTmpProject();
   const { KIND_CONFIG } = require('../lib/gitWorktree.cjs');
   const worktreeCwd = path.join(KIND_CONFIG.epic.root, 'fakehash', 'fake-epic-id');
   const realRoot = '/home/bilko/Projects/real-project';
@@ -103,7 +119,9 @@ test('an ephemeral cwd yields zero local lines but one telemetry record, with a
 
   opsErrorLog.appendError({ cwd: worktreeCwd, scope: 'chatRunner', message: 'worktree err' });
 
-  expect(fs.existsSync(opsErrorLog.todayFile(worktreeCwd))).toBe(false);
+  // resolveProjectRoot now consumes cwdClassify (not the stubbed projectRootOf):
+  // an ephemeral worktree cwd is refused outright, so no local path is even built.
+  expect(() => opsErrorLog.todayFile(worktreeCwd)).toThrow(/ephemeral/);
   expect(reportErrorCalls).toHaveLength(1);
   expect(reportErrorCalls[0].context.cwd).toBe(realRoot);
   expect(reportErrorCalls[0].context.cwd).not.toBe(worktreeCwd);
@@ -139,6 +157,12 @@ test('a realistic error with an absolute path and a prompt-like string never rea
     message: `run failed while processing "${promptLike}" at ${absPath}`,
   });
 
+  // The telemetry write is fire-and-forget async; poll (bounded) for the queue
+  // file instead of a fixed sleep, which raced under load.
+  const deadline = Date.now() + 5000;
+  while (!fs.existsSync(client.queuePath()) && Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 25));
+  }
   await new Promise((r) => setTimeout(r, 50));
 
   const raw = await fsp.readFile(client.queuePath(), 'utf8');

package/src/main/__tests__/pollLoop-dispatch-on-failure.test.cjs

@@ -16,6 +16,16 @@
  * whether that pass ends in an actual job launch (see classifyQueueStarvation's
  * header for why this must be distinct from `lastRunAt`).
  *
+ * Usage-meter circuit PRD update: pollLoop no longer fires blind at a hard-
+ * coded cachedUtilization=0 on failure — it falls back to
+ * usageCircuit.degradedBudget(), which carries forward the last known-good
+ * BINDING window's utilization (or conservatively assumes 100/no-headroom
+ * when there's no known-good reading yet at all). So each test below first
+ * drives ONE successful ('ok') poll — with the queue still empty, so it
+ * can't itself cause a dispatch — to seed that known-good low-utilization
+ * reading, THEN seeds the pending job and drives the failure. This proves
+ * dispatch proceeds under the CARRIED-FORWARD degraded budget, not a blind 0.
+ *
  * No existing test in this repo mocks a module import (see
  * pty-epic-worktree-spawn-cwd.test.cjs's header) — this monkey-patches
  * usage.cjs's cached module object directly instead, same pattern.
@@ -110,11 +120,23 @@ async function flushPendingTick() {
   await scheduler.tickQueue();
 }
 
-test('pollLoop still attempts a dispatch after a transient billing failure', async () => {
+test('pollLoop still attempts a dispatch after a transient billing failure, using the degraded budget (not utilization 0)', async () => {
+  // Seed a known-good low-utilization reading via an 'ok' poll first.
+  process.env.SM_E2E = '1';
+  process.env.SM_MOCK_BILLING_KIND = 'ok';
+  await scheduler.pollLoop();
+  // A prior test's leftover project (a REAL, still-registered project cwd —
+  // readQueue() merges every such cwd) can still hold its own permanently-
+  // pending job, so this seed poll's own maybeLaunchWhenAvailable may itself
+  // spawn a fire-and-forget tick; drain it before resetting/reseeding so
+  // that stray tick's async mutate() can't land AFTER (and clobber) the
+  // reset below.
+  await flushPendingTick();
+  await scheduler.writeQueue({ jobs: [], config: {}, paused: null });
+
   await seedOnePendingJob();
   expect(await lastDispatchAttemptAt()).toBeNull();
 
-  process.env.SM_E2E = '1';
   process.env.SM_MOCK_BILLING_KIND = 'transient';
   await scheduler.pollLoop();
   await flushPendingTick();
@@ -122,10 +144,18 @@ test('pollLoop still attempts a dispatch after a transient billing failure', asy
   expect(await lastDispatchAttemptAt()).not.toBeNull();
 });
 
-test('pollLoop still attempts a dispatch after the billing poll throws', async () => {
+test('pollLoop still attempts a dispatch after the billing poll throws, using the degraded budget (not utilization 0)', async () => {
+  process.env.SM_E2E = '1';
+  process.env.SM_MOCK_BILLING_KIND = 'ok';
+  await scheduler.pollLoop(); // seed a known-good low-utilization reading
+  await flushPendingTick();
+  await scheduler.writeQueue({ jobs: [], config: {}, paused: null });
+
   await seedOnePendingJob();
   expect(await lastDispatchAttemptAt()).toBeNull();
 
+  delete process.env.SM_E2E;
+  delete process.env.SM_MOCK_BILLING_KIND;
   billing.fetchUsage = async () => { throw new Error('simulated IPC transport failure'); };
   await scheduler.pollLoop();
   await flushPendingTick();

package/src/main/__tests__/prd-group-allocator.test.cjs

@@ -8,12 +8,12 @@
  * so a collision silently merges two unrelated projects' PRDs into one
  * group.
  *
- * Run: timeout 120 node --test src/main/__tests__/prd-group-allocator.test.cjs
+ * Run: timeout 300 npx vitest run src/main/__tests__/prd-group-allocator.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 fsp = require('node:fs/promises');

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

@@ -40,6 +40,8 @@ const REQUIRED_CAPABILITIES = [
   { capability: 'retag a PRD (parallelGroup/estimateMinutes)', ipcChannel: 'schedule:retag-prd', adminRoute: 'POST /admin/scheduler/retag-prd' },
   { capability: 'list scheduler jobs', ipcChannel: null, adminRoute: 'GET /admin/scheduler/jobs' },
   { capability: 'reset a stuck job', ipcChannel: 'schedule:reset-job', adminRoute: 'POST /admin/scheduler/reset-job' },
+  { capability: 'pause new dispatch (user-initiated)', ipcChannel: 'schedule:pause', adminRoute: 'POST /admin/scheduler/pause' },
+  { capability: 'resume a paused scheduler', ipcChannel: 'schedule:resume', adminRoute: 'POST /admin/scheduler/resume' },
   { capability: 'cancel a not-yet-terminal job', ipcChannel: null, adminRoute: 'POST /admin/scheduler/cancel-job' },
 ];
 

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

@@ -499,6 +499,12 @@ test('POST /admin/scheduler/reset-job with cwd resets the SAME-slug job belongin
   bustCwdCache();
   const slug = uniqueSlug('collision-slug');
   const epicId = 'epic-reset-collision';
+  // Both projects' rows need a real PRD source — a 'needs_review' row whose
+  // PRD is invisible to reconcile()'s onDisk scan is silently dropped (never
+  // backfilled to history.jsonl the way a completed/failed/skipped orphan
+  // is), which would make jobA vanish for a reason unrelated to what this
+  // test actually verifies (cwd-scoped job lookup).
+  await writePrdFixture({ cwd: cwdA, epicId, slug });
   await writePrdFixture({ cwd: cwdB, epicId, slug });
   await scheduler.writeQueue({
     jobs: [
@@ -518,8 +524,14 @@ test('POST /admin/scheduler/reset-job with cwd resets the SAME-slug job belongin
     expect(res.json).toEqual({ ok: true, slug, status: 'pending' });
 
     const state = await scheduler.remote.listJobs();
-    const jobA = state.find((j) => j.cwd === cwdA);
-    const jobB = state.find((j) => j.cwd === cwdB);
+    // Filter by slug too, not just cwd: cwdA is a shared fixture directory
+    // reused by many tests in this file, each of which leaves its own
+    // never-archived PRD file behind (only the queue row is cleared in
+    // `finally`) — reconcile()'s fresh-discovery pass can quarantine one of
+    // those leftovers as a NEW row under this same cwd on any later pass, so
+    // `cwd` alone no longer uniquely identifies this test's own job.
+    const jobA = state.find((j) => j.cwd === cwdA && j.slug === slug);
+    const jobB = state.find((j) => j.cwd === cwdB && j.slug === slug);
     expect(jobA.status).toBe('needs_review'); // untouched
     expect(jobB.status).toBe('pending'); // the one actually targeted
   } finally {

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

@@ -0,0 +1,39 @@
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { seedAuthoringGuide } = require('../lib/prdAuthoringSeed.cjs');
+
+const write = async (abs, text) => fs.writeFileSync(abs, text, 'utf8');
+
+describe('seedAuthoringGuide', () => {
+  let dir, src, dest;
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'prd-seed-'));
+    src = path.join(dir, 'src.md');
+    dest = path.join(dir, 'dest.md');
+    fs.writeFileSync(src, '<!-- PRD_AUTHORING.md v3 -->\nnew body\n');
+  });
+  afterEach(() => fs.rmSync(dir, { recursive: true, force: true }));
+
+  it('seeds an absent destination', async () => {
+    expect(await seedAuthoringGuide({ src, dest, write })).toBe(true);
+    expect(fs.readFileSync(dest, 'utf8')).toContain('new body');
+  });
+  it('overwrites a stale stamp', async () => {
+    fs.writeFileSync(dest, '<!-- PRD_AUTHORING.md v2 -->\nold\n');
+    expect(await seedAuthoringGuide({ src, dest, write })).toBe(true);
+    expect(fs.readFileSync(dest, 'utf8')).toContain('v3');
+  });
+  it('leaves a matching stamp untouched', async () => {
+    const same = '<!-- PRD_AUTHORING.md v3 -->\nlocal edit\n';
+    fs.writeFileSync(dest, same);
+    expect(await seedAuthoringGuide({ src, dest, write })).toBe(false);
+    expect(fs.readFileSync(dest, 'utf8')).toBe(same);
+  });
+  it('overwrites a destination with no stamp', async () => {
+    fs.writeFileSync(dest, '# no stamp\n');
+    expect(await seedAuthoringGuide({ src, dest, write })).toBe(true);
+    expect(fs.readFileSync(dest, 'utf8')).toContain('v3');
+  });
+});