claude-code-session-manager 0.94.0 → 0.96.0

package/src/main/health.cjs

@@ -23,7 +23,7 @@ const { computeStallSummary, computeDepHistorySatisfaction, FAILURE_STREAK_ESCAL
 const { findStarvedProjects, findUnresolvableDepRoots, DEFAULT_PROJECT_CWD, DEP_HISTORY_FAIL_OPEN } = require('./lib/schedulerBatch.cjs');
 const { auditLogPath, readTail } = require('./lib/auditLog.cjs');
 const { resolveBuildIdentity } = require('./lib/buildIdentity.cjs');
-const { DEFAULT_RUNS_DIR, computeReport, isRetentionEnabled, liveKeysFromJobs } = require('./lib/runLogRetention.cjs');
+const { computeReport, isRetentionEnabled, liveKeysFromJobs } = require('./lib/runLogRetention.cjs');
 const { allProjectCwds } = require('./lib/activeSessions.cjs');
 const { scanEpicTranscripts } = require('./lib/epicTranscriptDiagnostic.cjs');
 
@@ -39,6 +39,8 @@ const PROJECT_ROOT = path.resolve(__dirname, '../..');
 // outage goes unnoticed for hours (the 2026-07-14 incident sat stalled for
 // 16.5h before anything asserted on it).
 const TICK_STALL_MULTIPLIER = 3;
+// A utilization hold whose reset is further out than this is not a routine 5h pause.
+const LONG_HOLD_MS = 5 * 60 * 60_000;
 const TICK_STALL_THRESHOLD_MS = TICK_STALL_MULTIPLIER * POLL_INTERVAL_MS;
 // A heartbeat line older than this is treated as "the app isn't running /
 // we can't observe live utilization" rather than "utilization is low" —
@@ -139,7 +141,19 @@ function evaluateTickLiveness(queueState, heartbeat, now, runningCount) {
       };
     }
     if (typeof heartbeat.utilization === 'number' && heartbeat.utilization >= config.utilizationThreshold) {
-      return { stalled: false, reason: 'utilization-at-threshold', utilization: heartbeat.utilization };
+      // A hold on the binding window is benign only if it self-heals soon
+      // (reset within 5h). A weekly hold, or an unknown reset horizon, can
+      // last days — surface it rather than reading GREEN.
+      const resetMs = heartbeat.nextReset ? Date.parse(heartbeat.nextReset) : NaN;
+      const longHold = !Number.isFinite(resetMs) || resetMs - now > LONG_HOLD_MS;
+      return {
+        stalled: false,
+        reason: 'utilization-at-threshold',
+        utilization: heartbeat.utilization,
+        window: heartbeat.utilizationWindow ?? null,
+        nextReset: heartbeat.nextReset ?? null,
+        ...(longHold ? { longHold: true } : {}),
+      };
     }
   }
 
@@ -613,6 +627,50 @@ function evaluateBuildFreshness({ running = null, installedOnDisk = null, repoHe
   return { ok: true, running, installedOnDisk, repoHead, restartNeeded, publishNeeded, ...(notes.length ? { note: notes.join('; ') } : {}) };
 }
 
+/**
+ * evaluateCredentialHealth({ credState, now }) → { component, issues }
+ *
+ * Pure over its inputs — `credState` is the shape lib/credentials.cjs's
+ * refreshIfNeeded()/readCredentials() return ({ kind, message?, expiredAt? }),
+ * injected so this is testable without touching the Keychain. Surfaces the ONE
+ * failure that silently voids the whole scheduler on a user's machine: the
+ * OAuth token is expired (or missing) so every headless `claude -p` job fails
+ * to authenticate. The scheduler already pauses on a live 'auth' poll
+ * (scheduler.cjs setPaused('auth')), but nothing told the OPERATOR why the
+ * queue went quiet — `npm run health` read GREEN while no job could run. This
+ * names the cause and the fix (`claude login`).
+ *
+ * NON-CRITICAL by design: reported in components.credentials + issues so
+ * /local-project-health shows it, but it does not flip status.ok — health must
+ * not hard-fail a repo checkout just because THIS machine's token lapsed, and
+ * an expired token is an operator action (re-login), not a code defect. Maps:
+ *   kind 'auth'   → not ok, actionable `claude login` message (the real block)
+ *   kind 'config' → not ok, credentials unreadable/absent
+ *   kind 'ok'/'unsupported' → ok (token usable, or too-fresh-to-refresh)
+ */
+function evaluateCredentialHealth({ credState, now = Date.now() } = {}) {
+  const issues = [];
+  if (!credState || typeof credState !== 'object') {
+    return { component: { ok: true, state: 'unknown' }, issues };
+  }
+  const { kind } = credState;
+  if (kind === 'auth') {
+    const expiredAt = typeof credState.expiredAt === 'number' ? credState.expiredAt : null;
+    const agoMin = expiredAt ? Math.max(0, Math.round((now - expiredAt) / 60_000)) : null;
+    const when = expiredAt ? new Date(expiredAt).toISOString() : 'unknown';
+    const msg = `Claude credentials expired${agoMin !== null ? ` (${agoMin}m ago, at ${when})` : ''} — headless \`claude -p\` scheduler jobs cannot authenticate. Run \`claude login\` in a terminal to refresh.`;
+    issues.push(msg);
+    return { component: { ok: false, state: 'expired', expiredAt, message: msg }, issues };
+  }
+  if (kind === 'config') {
+    const msg = `Claude credentials unreadable: ${credState.message ?? 'unknown'} — scheduler jobs cannot authenticate. Run \`claude login\`.`;
+    issues.push(msg);
+    return { component: { ok: false, state: 'unreadable', message: msg }, issues };
+  }
+  // 'ok' (fresh) or 'unsupported' (auto-refresh unavailable but token still valid)
+  return { component: { ok: true, state: kind === 'unsupported' ? 'valid-no-refresh' : 'valid' }, issues };
+}
+
 /**
  * evaluateStarveEscalationHealth(jobs, now, thresholdMs, escalationReasons)
  *   → { ok, projects?, message? }
@@ -860,6 +918,16 @@ async function check(opts = {}) {
       })(),
       loadGateThreshold: loadGateThreshold(),
     };
+    if (liveness.longHold) {
+      status.components.scheduler_queue.longHold = {
+        window: liveness.window, utilization: liveness.utilization, nextReset: liveness.nextReset,
+      };
+      status.issues.push(
+        `Queue held on the ${liveness.window ?? 'binding'} usage window at ${liveness.utilization}% (≥ threshold); `
+        + (liveness.nextReset ? `resets ${liveness.nextReset}` : 'reset time unknown')
+        + ' — hold may last days, not a normal short pause'
+      );
+    }
     if (liveness.stalled) {
       const ageMin = Math.round(liveness.tickAgeMs / 60_000);
       status.components.scheduler_queue.stalledJob = liveness.oldestPendingSlug;
@@ -1114,15 +1182,16 @@ async function check(opts = {}) {
   // `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 runsDir = schedulerPaths.runsDir();
+    const liveKeys = liveKeysFromJobs(queueState?.jobs || [], { runsDir });
     const report = computeReport(
-      DEFAULT_RUNS_DIR,
+      runsDir,
       retentionCfg?.policy || {},
       { liveKeys }
     );
     status.components.run_log_retention = {
       ok: true,
-      path: DEFAULT_RUNS_DIR,
+      path: runsDir,
       totalBytes: report.usage.totalBytes,
       dirCount: report.usage.dirCount,
       runCount: report.usage.runCount,
@@ -1181,6 +1250,22 @@ async function check(opts = {}) {
     status.components.build = { ok: true, error: e.message };
   }
 
+  // 6.8. Credential health (informational-but-loud): is the Claude OAuth token
+  // usable? An expired/absent token silently voids every headless `claude -p`
+  // job — the queue "runs" but nothing authenticates. refreshIfNeeded() reads
+  // the Keychain/file and (post futile-refresh fix) never spawns a doomed CLI
+  // fallback for an expired-no-refresh-token creds, so this is a cheap read.
+  // Non-critical: names the cause + `claude login` fix without flipping ok.
+  try {
+    const { refreshIfNeeded } = require('./lib/credentials.cjs');
+    const credState = await refreshIfNeeded();
+    const { component, issues } = evaluateCredentialHealth({ credState, now: Date.now() });
+    status.components.credentials = component;
+    for (const i of issues) status.issues.push(i);
+  } catch (e) {
+    status.components.credentials = { ok: true, state: 'unknown', 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.
@@ -1207,6 +1292,7 @@ module.exports = {
   readFreshHeartbeat,
   evaluatePrdMigrationHealth,
   evaluateDelegationChainHealth,
+  evaluateCredentialHealth,
   computeEpicIndexDrift,
   evaluateEpicIndexHealth,
   computeProjectProblemCounts,

package/src/main/index.cjs

@@ -1027,7 +1027,7 @@ ipcMain.handle('exchanges:list', validated(schemas.exchangesList, async (payload
   }
 }));
 
-// OTEL telemetry export (opt-in via ~/.config/session-manager/otel.json).
+// OTEL telemetry export (opt-in via ~/.claude/session-manager/otel.json).
 ipcMain.handle('otel:get-config', async () => otelSettings.load());
 ipcMain.handle('otel:set-config', async (_e, cfg) => {
   if (!otelSettings.isValid(cfg)) {

package/src/main/ipcSchemas.cjs

@@ -632,10 +632,14 @@ const memoryStale = z.object({
 // the encoded cwd slug (memoryAggregate.cjs reads directly from
 // ~/.claude/projects/<workspace>/memory/), same regex as the other memory:*
 // handlers. `refresh: true` is the cost gate that fires the single claude -p
-// clustering pass; falsy returns the cached result.
+// clustering pass; falsy returns the cached result. `cwd` (PRD 1389,
+// optional — same shape as memory:stale's) addresses the per-project cache
+// at <cwd>/session-manager-operations/memory-clusters/clusters.json;
+// absent/invalid cwd just disables caching for that call.
 const memoryAggregate = z.object({
   workspace: z.string().regex(MEMORY_WORKSPACE_RE),
   refresh: z.boolean().optional(),
+  cwd: z.string().max(4096).optional(),
 }).strict();
 
 // ──────────────────────────────────────────── Project Brief (PRD 837)

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

@@ -35,7 +35,7 @@ async function mkHome() {
   process.env.HOME = dir;
   // Explicit opt-in: overrides the test-environment no-op guard so this
   // suite's real telemetryClient calls actually persist into an isolated dir.
-  process.env.SM_TELEMETRY_SPOOL = path.join(dir, '.config', 'session-manager');
+  process.env.SM_TELEMETRY_SPOOL = path.join(dir, '.claude', 'session-manager');
   return dir;
 }
 

package/src/main/lib/__tests__/credentials-futile-refresh.test.cjs

@@ -0,0 +1,115 @@
+/**
+ * credentials-futile-refresh.test.cjs — the 2026-09-23 credential-refresh
+ * storm. On this machine the OAuth creds were expired with NO refresh token
+ * (expiredAtMs 1775277875159). Every 15 s billing poll called refreshIfNeeded,
+ * which tried the OAuth grant (instant 'unsupported' — no refresh token),
+ * then spawned `claude --version` as a CLI fallback (which shares the same
+ * missing token, so it can't help either), then logged auth_failed_expired —
+ * the identical triple, forever, spawning a doomed child process each time.
+ *
+ * The fix: a futile-refresh short-circuit. When the token is expired AND has
+ * no refresh token, refreshIfNeeded re-reads once (to catch an out-of-band
+ * `claude login`) and otherwise returns the auth verdict WITHOUT the OAuth
+ * call or the CLI-fallback spawn, logging at most once per cooldown window.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/credentials-futile-refresh.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach, afterAll } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// credentials.cjs freezes CREDS_PATH and REFRESH_LOG_PATH from os.homedir() at
+// require time. os.homedir() honors $HOME on POSIX, so point HOME at a temp
+// dir BEFORE the require (not in beforeEach — that runs too late) so both the
+// creds file we write and the log the code writes resolve under our sandbox.
+const originalHome = process.env.HOME;
+const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-cred-futile-'));
+process.env.HOME = tmpHome;
+
+const credentials = require('../credentials.cjs');
+const { isRefreshFutile, refreshIfNeeded, __resetFutileRefreshThrottle } = credentials;
+
+const CREDS_FILE = path.join(tmpHome, '.claude', '.credentials.json');
+const LOG_FILE = path.join(tmpHome, '.claude', 'session-manager', 'credential-refresh.log');
+
+function writeCreds(oauth) {
+  fs.mkdirSync(path.dirname(CREDS_FILE), { recursive: true });
+  fs.writeFileSync(CREDS_FILE, JSON.stringify({ claudeAiOauth: oauth }), 'utf8');
+}
+
+function readLogLines() {
+  try {
+    return fs.readFileSync(LOG_FILE, 'utf8').trim().split('\n').filter(Boolean).map((l) => JSON.parse(l));
+  } catch {
+    return [];
+  }
+}
+
+beforeEach(() => {
+  // Clean slate per test: no stale creds file, no carried-over log or throttle.
+  try { fs.unlinkSync(CREDS_FILE); } catch { /* absent */ }
+  try { fs.unlinkSync(LOG_FILE); } catch { /* absent */ }
+  __resetFutileRefreshThrottle();
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+test('isRefreshFutile: expired + no refresh token is futile; anything else is not', () => {
+  const past = Date.now() - 60_000;
+  const future = Date.now() + 60 * 60_000;
+  expect(isRefreshFutile({ accessToken: 'a', expiresAt: past })).toBe(true);
+  // Has a refresh token → OAuth grant is worth attempting, not futile.
+  expect(isRefreshFutile({ accessToken: 'a', expiresAt: past, refreshToken: 'r' })).toBe(false);
+  // Not expired → not futile even without a refresh token.
+  expect(isRefreshFutile({ accessToken: 'a', expiresAt: future })).toBe(false);
+});
+
+test('a futile refresh returns an auth verdict without spawning the CLI fallback, and logs the no-refresh-token event once', async () => {
+  writeCreds({ accessToken: 'expired', expiresAt: Date.now() - 60_000 }); // expired, no refreshToken
+
+  const res = await refreshIfNeeded();
+
+  expect(res.kind).toBe('auth');
+  expect(res.message).toMatch(/no refresh token/i);
+  expect(typeof res.expiredAt).toBe('number');
+
+  const events = readLogLines().map((e) => e.event);
+  // The distinctive no-refresh-token event fires...
+  expect(events).toContain('auth_failed_expired_no_refresh_token');
+  // ...and the storm's spawn/oauth triple never runs.
+  expect(events).not.toContain('cli_fallback_ok');
+  expect(events).not.toContain('cli_fallback_failed');
+  expect(events).not.toContain('oauth_refresh_unsupported');
+});
+
+test('repeated polls in the cooldown window do NOT re-log — the every-15s storm is suppressed', async () => {
+  writeCreds({ accessToken: 'expired', expiresAt: Date.now() - 60_000 });
+
+  // Simulate several poll cycles back-to-back (as pollLoop would, every 15 s).
+  for (let i = 0; i < 5; i++) {
+    const res = await refreshIfNeeded();
+    expect(res.kind).toBe('auth');
+  }
+
+  const futileLogs = readLogLines().filter((e) => e.event === 'auth_failed_expired_no_refresh_token');
+  expect(futileLogs.length).toBe(1); // once, not five times
+});
+
+test('an out-of-band `claude login` (fresh creds on disk) is picked up on the next call', async () => {
+  writeCreds({ accessToken: 'expired', expiresAt: Date.now() - 60_000 });
+  expect((await refreshIfNeeded()).kind).toBe('auth');
+
+  // User runs `claude` in a terminal → fresh creds land on disk.
+  writeCreds({ accessToken: 'fresh', expiresAt: Date.now() + 60 * 60_000 });
+
+  const res = await refreshIfNeeded();
+  expect(res.kind).toBe('ok');
+  expect(res.creds.accessToken).toBe('fresh');
+});

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

@@ -1,9 +1,13 @@
 /**
- * epicWorktreeProjectConfig.test.cjs — PRD 1035: the per-project "disable
- * Epic worktree isolation" UI toggle. Points the module at a throwaway
- * tmpdir file via SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH so it never touches
- * the real ~/.claude/session-manager/epic-worktree-project-config.json on
- * the machine running the tests.
+ * epicWorktreeProjectConfig.test.cjs — PRD 1035/1390: the per-project "disable
+ * Epic worktree isolation" UI toggle, now stored at
+ * `<cwd>/session-manager-operations/prompt-sessions/epic-worktree-config.json`
+ * instead of a single machine-wide map. Uses real mkdtemp'd project cwds (the
+ * same convention as epicStatusMirror.test.cjs) since the file location is
+ * now derived from `cwd` via opsPath(), not from a single overridable path.
+ * SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH still points the LEGACY global map (the
+ * one-shot migration source) at a throwaway tmpdir file, so tests never touch
+ * the real ~/.claude/session-manager/epic-worktree-project-config.json.
  *
  * Run: timeout 120 npx vitest run src/main/lib/__tests__/epicWorktreeProjectConfig.test.cjs
  */
@@ -16,60 +20,79 @@ const os = require('node:os');
 const path = require('node:path');
 
 let tmpRoot;
-let configFile;
+let legacyConfigFile;
 let originalOverride;
+const projectDirs = [];
 
 beforeEach(() => {
   tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-epic-worktree-project-config-'));
-  configFile = path.join(tmpRoot, 'config.json');
+  legacyConfigFile = path.join(tmpRoot, 'legacy-config.json');
   originalOverride = process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH;
-  process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH = configFile;
+  process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH = legacyConfigFile;
 });
 
 afterEach(() => {
   if (originalOverride === undefined) delete process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH;
   else process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH = originalOverride;
   fs.rmSync(tmpRoot, { recursive: true, force: true });
+  while (projectDirs.length) fs.rmSync(projectDirs.pop(), { recursive: true, force: true });
 });
 
 function freshModule() {
   return require('../epicWorktreeProjectConfig.cjs');
 }
 
+function mkProjectCwd(name) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `sm-epic-worktree-project-${name}-`));
+  projectDirs.push(dir);
+  return dir;
+}
+
+function perProjectFile(m, cwd) {
+  return m.perProjectConfigPath(cwd);
+}
+
 test('defaults to not disabled for a project never touched', () => {
   const m = freshModule();
-  expect(m.isEpicWorktreeDisabledForProject('/some/project')).toBe(false);
+  const cwd = mkProjectCwd('a');
+  expect(m.isEpicWorktreeDisabledForProject(cwd)).toBe(false);
 });
 
-test('setEpicWorktreeDisabledForProject(true) persists across a fresh read', () => {
+test('setEpicWorktreeDisabledForProject(true) persists across a fresh read, in the per-project ops file', () => {
   const m = freshModule();
-  m.setEpicWorktreeDisabledForProject('/proj/a', true);
-  expect(m.isEpicWorktreeDisabledForProject('/proj/a')).toBe(true);
-  expect(fs.existsSync(configFile)).toBe(true);
-  const onDisk = JSON.parse(fs.readFileSync(configFile, 'utf8'));
-  expect(onDisk).toEqual({ '/proj/a': true });
+  const cwd = mkProjectCwd('a');
+  m.setEpicWorktreeDisabledForProject(cwd, true);
+  expect(m.isEpicWorktreeDisabledForProject(cwd)).toBe(true);
+  const file = perProjectFile(m, cwd);
+  expect(fs.existsSync(file)).toBe(true);
+  expect(JSON.parse(fs.readFileSync(file, 'utf8'))).toEqual({ disabled: true });
 });
 
 test('is scoped per cwd — a different project is unaffected', () => {
   const m = freshModule();
-  m.setEpicWorktreeDisabledForProject('/proj/a', true);
-  expect(m.isEpicWorktreeDisabledForProject('/proj/b')).toBe(false);
+  const cwdA = mkProjectCwd('a');
+  const cwdB = mkProjectCwd('b');
+  m.setEpicWorktreeDisabledForProject(cwdA, true);
+  expect(m.isEpicWorktreeDisabledForProject(cwdB)).toBe(false);
 });
 
-test('setEpicWorktreeDisabledForProject(false) clears the entry rather than writing false', () => {
+test('setEpicWorktreeDisabledForProject(false) writes disabled:false rather than deleting the file', () => {
   const m = freshModule();
-  m.setEpicWorktreeDisabledForProject('/proj/a', true);
-  m.setEpicWorktreeDisabledForProject('/proj/a', false);
-  expect(m.isEpicWorktreeDisabledForProject('/proj/a')).toBe(false);
-  const onDisk = JSON.parse(fs.readFileSync(configFile, 'utf8'));
-  expect(onDisk).toEqual({});
+  const cwd = mkProjectCwd('a');
+  m.setEpicWorktreeDisabledForProject(cwd, true);
+  m.setEpicWorktreeDisabledForProject(cwd, false);
+  expect(m.isEpicWorktreeDisabledForProject(cwd)).toBe(false);
+  const file = perProjectFile(m, cwd);
+  expect(JSON.parse(fs.readFileSync(file, 'utf8'))).toEqual({ disabled: false });
 });
 
-test('a missing or corrupt config file reads as not-disabled rather than throwing', () => {
+test('a missing or corrupt per-project config file reads as not-disabled rather than throwing', () => {
   const m = freshModule();
-  fs.mkdirSync(path.dirname(configFile), { recursive: true });
-  fs.writeFileSync(configFile, '{ not valid json');
-  expect(m.isEpicWorktreeDisabledForProject('/proj/a')).toBe(false);
+  const cwd = mkProjectCwd('a');
+  const file = perProjectFile(m, cwd);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, '{ not valid json');
+  expect(m.isEpicWorktreeDisabledForProject(cwd)).toBe(false);
 });
 
 test('isEpicWorktreeDisabledForProject rejects a non-string cwd instead of throwing', () => {
@@ -77,3 +100,38 @@ test('isEpicWorktreeDisabledForProject rejects a non-string cwd instead of throw
   expect(m.isEpicWorktreeDisabledForProject(null)).toBe(false);
   expect(m.isEpicWorktreeDisabledForProject(undefined)).toBe(false);
 });
+
+test('one-shot migration: a legacy global entry seeds the new per-project file on first read', () => {
+  const m = freshModule();
+  const cwd = mkProjectCwd('a');
+  fs.writeFileSync(legacyConfigFile, JSON.stringify({ [cwd]: true }));
+
+  expect(m.isEpicWorktreeDisabledForProject(cwd)).toBe(true);
+  const file = perProjectFile(m, cwd);
+  expect(fs.existsSync(file)).toBe(true);
+  expect(JSON.parse(fs.readFileSync(file, 'utf8'))).toEqual({ disabled: true });
+
+  // The legacy file itself is left in place, untouched.
+  expect(JSON.parse(fs.readFileSync(legacyConfigFile, 'utf8'))).toEqual({ [cwd]: true });
+});
+
+test('migration leaves the legacy map intact for OTHER, still-unmigrated projects', () => {
+  const m = freshModule();
+  const cwdA = mkProjectCwd('a');
+  const cwdB = mkProjectCwd('b');
+  fs.writeFileSync(legacyConfigFile, JSON.stringify({ [cwdA]: true, [cwdB]: true }));
+
+  // Touching cwdA migrates only cwdA's own per-project file.
+  expect(m.isEpicWorktreeDisabledForProject(cwdA)).toBe(true);
+  expect(fs.existsSync(perProjectFile(m, cwdB))).toBe(false);
+
+  // cwdB still resolves correctly straight from the untouched legacy map.
+  expect(m.isEpicWorktreeDisabledForProject(cwdB)).toBe(true);
+});
+
+test('a project with no legacy entry migrates to disabled:false without throwing', () => {
+  const m = freshModule();
+  const cwd = mkProjectCwd('a');
+  fs.writeFileSync(legacyConfigFile, JSON.stringify({ '/some/other/project': true }));
+  expect(m.isEpicWorktreeDisabledForProject(cwd)).toBe(false);
+});

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

@@ -847,34 +847,28 @@ test('[epic] SM_EPIC_WORKTREE_DISABLE=1 restores in-place behaviour independentl
 
 test('[epic] the per-project UI toggle (epicWorktreeProjectConfig.cjs) disables isolation for just that cwd', async () => {
   const projectConfig = require('../epicWorktreeProjectConfig.cjs');
-  const originalOverride = process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH;
-  process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH = path.join(tmpRoot, 'epic-worktree-project-config.json');
-  try {
-    projectConfig.setEpicWorktreeDisabledForProject(repoCwd, true);
-    expect(projectConfig.isEpicWorktreeDisabledForProject(repoCwd)).toBe(true);
+  projectConfig.setEpicWorktreeDisabledForProject(repoCwd, true);
+  expect(projectConfig.isEpicWorktreeDisabledForProject(repoCwd)).toBe(true);
 
-    const result = await gitWorktree.createEpicWorktree({ cwd: repoCwd, epicId: 'toggle-x' });
-    expect(result.ok).toBe(false);
-    expect(result.reason).toMatch(/isolation toggle/);
-
-    // A different, untouched project cwd is unaffected — the toggle is
-    // per-project, not machine-wide like the env var.
-    const otherCwd = path.join(tmpRoot, 'other-repo');
-    initRepo(otherCwd);
-    const otherResult = await gitWorktree.createEpicWorktree({ cwd: otherCwd, epicId: 'toggle-y' });
-    expect(otherResult.ok).toBe(true);
-    await gitWorktree.cleanupEpicWorktree({ cwd: otherCwd, dir: otherResult.dir, branch: otherResult.branch });
-
-    // Turning it back off restores isolation for the original project.
-    projectConfig.setEpicWorktreeDisabledForProject(repoCwd, false);
-    expect(projectConfig.isEpicWorktreeDisabledForProject(repoCwd)).toBe(false);
-    const restored = await gitWorktree.createEpicWorktree({ cwd: repoCwd, epicId: 'toggle-z' });
-    expect(restored.ok).toBe(true);
-    await gitWorktree.cleanupEpicWorktree({ cwd: repoCwd, dir: restored.dir, branch: restored.branch });
-  } finally {
-    if (originalOverride === undefined) delete process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH;
-    else process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH = originalOverride;
-  }
+  const result = await gitWorktree.createEpicWorktree({ cwd: repoCwd, epicId: 'toggle-x' });
+  expect(result.ok).toBe(false);
+  expect(result.reason).toMatch(/isolation toggle/);
+
+  // A different, untouched project cwd is unaffected — the toggle is
+  // per-project (its own <cwd>/session-manager-operations/prompt-sessions/
+  // epic-worktree-config.json), not machine-wide like the env var.
+  const otherCwd = path.join(tmpRoot, 'other-repo');
+  initRepo(otherCwd);
+  const otherResult = await gitWorktree.createEpicWorktree({ cwd: otherCwd, epicId: 'toggle-y' });
+  expect(otherResult.ok).toBe(true);
+  await gitWorktree.cleanupEpicWorktree({ cwd: otherCwd, dir: otherResult.dir, branch: otherResult.branch });
+
+  // Turning it back off restores isolation for the original project.
+  projectConfig.setEpicWorktreeDisabledForProject(repoCwd, false);
+  expect(projectConfig.isEpicWorktreeDisabledForProject(repoCwd)).toBe(false);
+  const restored = await gitWorktree.createEpicWorktree({ cwd: repoCwd, epicId: 'toggle-z' });
+  expect(restored.ok).toBe(true);
+  await gitWorktree.cleanupEpicWorktree({ cwd: repoCwd, dir: restored.dir, branch: restored.branch });
 });
 
 test('[epic] reconcileWorktreesOnBoot removes a leaked epic worktree with no liveness predicate given', async () => {

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

@@ -112,14 +112,21 @@ test('writeGuardShims: rewriting the pointer to a DIFFERENT app root lets an alr
   const shimBytesBefore = fs.readFileSync(shimFile, 'utf8');
 
   // Simulate an app upgrade: a second "app root" at a brand-new path, with
-  // its own copy of scripts/hooks/guard-prd-writes.cjs (this is the ONLY file
-  // guardShims ever reads through the pointer at invocation time).
+  // its own copy of scripts/hooks/guard-prd-writes.cjs — the file guardShims
+  // reads through the pointer at invocation time — plus the sibling policy
+  // module it `require()`s at load time (guard-prd-writes-policy.cjs, PRD
+  // 1415); a real upgrade ships both since both are listed in package.json's
+  // "files".
   const secondAppRoot = await mkTmp('sm-guard-shims-upgraded-app-');
-  await fsp.mkdir(path.join(secondAppRoot, 'scripts', 'hooks'), { recursive: true });
+  await fsp.mkdir(path.join(secondAppRoot, 'scripts', 'hooks', 'lib'), { recursive: true });
   await fsp.copyFile(
     path.join(APP_ROOT, 'scripts', 'hooks', 'guard-prd-writes.cjs'),
     path.join(secondAppRoot, 'scripts', 'hooks', 'guard-prd-writes.cjs'),
   );
+  await fsp.copyFile(
+    path.join(APP_ROOT, 'scripts', 'hooks', 'lib', 'guard-prd-writes-policy.cjs'),
+    path.join(secondAppRoot, 'scripts', 'hooks', 'lib', 'guard-prd-writes-policy.cjs'),
+  );
 
   const r = await writeGuardShims({ homeDir, appRoot: secondAppRoot });
   expect(r.ok).toBe(true);

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

@@ -9,7 +9,7 @@
 // batteries. These tests pin the pure decision, the audit rate-limit and the
 // escalation, with loadavg/cores/clock all injected.
 const assert = require('node:assert/strict');
-const { isLoadGated, createLoadGate, AUDIT_INTERVAL_MS } = require('../loadGate.cjs');
+const { isLoadGated, createLoadGate, topCpuConsumers, AUDIT_INTERVAL_MS } = require('../loadGate.cjs');
 const { loadGateThreshold, LOAD_GATE_PER_CORE } = require('../schedulerConfig.cjs');
 
 const ORIGINAL_ENV = process.env.SM_LOAD_GATE_PER_CORE;
@@ -65,6 +65,49 @@ test('SM_LOAD_GATE_PER_CORE is honored and clamped to [0.25, 4]; 0 disables; gar
   assert.equal(loadGateThreshold(), 0.85);
 });
 
+// ─── topCpuConsumers: platform-correct ps invocation ───────────────────────
+//
+// The audit line the scheduler warn-logs when the load gate escalates. Purely
+// diagnostic (nothing branches on it) but it was blank on macOS: the code only
+// ran the GNU `ps --sort` form, which BSD ps rejects with "illegal option",
+// so every Mac logged `top CPU: n/a` exactly when the operator needed to know
+// what was saturating the box.
+
+test('Linux uses the GNU ps form (-eo … --sort=-pcpu) and skips the header row', () => {
+  const calls = [];
+  const fakeExec = (bin, args) => {
+    calls.push({ bin, args });
+    return 'PID %CPU COMMAND\n  1 90.0 node\n  2 10.0 tsc\n';
+  };
+  const rows = topCpuConsumers(2, { execImpl: fakeExec, platform: 'linux' });
+  assert.deepEqual(calls[0], { bin: 'ps', args: ['-eo', 'pid,pcpu,comm', '--sort=-pcpu'] });
+  assert.deepEqual(rows, ['1 90.0 node', '2 10.0 tsc']);
+});
+
+test('macOS uses the BSD ps form (-Aco … -r), NOT the GNU --sort that BSD ps rejects', () => {
+  const calls = [];
+  const fakeExec = (bin, args) => {
+    calls.push({ bin, args });
+    return '  PID %CPU COMM\n  847 94.4 suggestd\n  443 15.1 WindowServer\n';
+  };
+  const rows = topCpuConsumers(3, { execImpl: fakeExec, platform: 'darwin' });
+  assert.deepEqual(calls[0].args, ['-Aco', 'pid,pcpu,comm', '-r']);
+  assert.ok(!calls[0].args.some((a) => String(a).includes('--sort')), 'must not pass the GNU --sort to BSD ps');
+  assert.deepEqual(rows, ['847 94.4 suggestd', '443 15.1 WindowServer']);
+});
+
+test('an unsupported platform returns [] without ever spawning ps', () => {
+  let spawned = false;
+  const rows = topCpuConsumers(3, { execImpl: () => { spawned = true; return ''; }, platform: 'win32' });
+  assert.deepEqual(rows, []);
+  assert.equal(spawned, false);
+});
+
+test('a ps failure (throw) degrades to [] rather than propagating — the audit line is best-effort', () => {
+  const rows = topCpuConsumers(3, { execImpl: () => { throw new Error('boom'); }, platform: 'darwin' });
+  assert.deepEqual(rows, []);
+});
+
 // ─── createLoadGate: decision, 1-minute-only, bypass ───────────────────────
 
 function gateWith({ l1 = 12.95, l5 = 0, l15 = 0, cores = 14, threshold = 0.85, clock }) {