claude-code-session-manager 0.94.0 → 0.96.0

package/scripts/hooks/lib/guard-prd-writes-policy.cjs

@@ -0,0 +1,100 @@
+/**
+ * guard-prd-writes-policy.cjs — decision logic for
+ * scripts/hooks/guard-prd-writes.cjs, split out so it can be `require()`d
+ * in-process (by tests, notably) with no CLI-level side effects.
+ *
+ * guard-prd-writes.cjs itself runs its CLI as a require-time side effect
+ * (stdin -> decision -> process.exit, not gated on `require.main === module`
+ * — see its header for why). Requiring THIS module never reads stdin or
+ * calls `process.exit`. `decide()` is fully I/O-free — it only does path
+ * arithmetic on `payload` — so calling it directly from a test is equivalent
+ * to the real CLI decision, without a child-process spawn per case.
+ */
+'use strict';
+
+const path = require('node:path');
+
+const SCHEDULER_SEGMENT = `${path.sep}session-manager-operations${path.sep}scheduler${path.sep}`;
+const FIX_PLAN_RE = /^\d+-fix-.*\.md$/;
+
+/** Extract the single filesystem path a Write/Edit/NotebookEdit call targets. */
+function targetPathFor(toolName, toolInput) {
+  if (!toolInput || typeof toolInput !== 'object') return null;
+  if (toolName === 'NotebookEdit') return toolInput.notebook_path ?? null;
+  return toolInput.file_path ?? null;
+}
+
+/** MCP tool name to point the agent at, based on the attempted operation. */
+function suggestedToolFor(toolName, absPath) {
+  const isArchived = absPath.includes(`${path.sep}prds-archived${path.sep}`);
+  if (isArchived) return 'mcp__session-manager-scheduler__scheduler_archive_prd';
+  // Write = the file doesn't exist yet from the agent's point of view (a
+  // brand-new PRD); Edit/NotebookEdit = mutating an existing file in place.
+  if (toolName === 'Write') return 'mcp__session-manager-scheduler__scheduler_create_prd';
+  return 'mcp__session-manager-scheduler__scheduler_update_prd';
+}
+
+function buildAllow() {
+  return { continue: true };
+}
+
+function buildDeny(reason) {
+  return {
+    continue: true,
+    decision: 'block',
+    reason,
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
+/**
+ * Decision function: PreToolUse payload in, hook-response object out. No
+ * stdin/stdout and no `process.exit` — safe to call in-process (e.g. from
+ * tests), and fully I/O-free.
+ */
+function decide(payload) {
+  try {
+    const toolName = payload.tool_name;
+    if (toolName !== 'Write' && toolName !== 'Edit' && toolName !== 'NotebookEdit') {
+      return buildAllow();
+    }
+
+    const rawPath = targetPathFor(toolName, payload.tool_input);
+    if (!rawPath || typeof rawPath !== 'string') return buildAllow();
+
+    const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
+    const absPath = path.isAbsolute(rawPath) ? rawPath : path.resolve(cwd, rawPath);
+
+    if (!absPath.includes(SCHEDULER_SEGMENT)) return buildAllow();
+
+    const base = path.basename(absPath);
+    if (FIX_PLAN_RE.test(base)) return buildAllow();
+
+    const suggested = suggestedToolFor(toolName, absPath);
+    const reason = [
+      `Direct ${toolName} to a session-manager-operations/scheduler/ path is blocked.`,
+      `PRDs must be authored through the scheduler API, not a raw file write — use the "${suggested}" MCP tool instead.`,
+      'If the Session Manager app is not running (the admin API this MCP tool talks to only exists while it is), the degraded fallback documented in the develop skill applies: hand-write the file as a last resort and say so visibly in your report.',
+    ].join(' ');
+    return buildDeny(reason);
+  } catch (e) {
+    console.error(`[guard-prd-writes] internal error, failing open: ${e?.message}`);
+    return buildAllow();
+  }
+}
+
+/** Mirrors the CLI's stdin-JSON handling so it can be exercised without a spawn. */
+function parsePayload(raw) {
+  try {
+    return raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    console.error(`[guard-prd-writes] malformed stdin JSON, failing open: ${e?.message}`);
+    return {};
+  }
+}
+
+module.exports = { decide, parsePayload };

package/scripts/hooks/lib/guard-self-schedule-policy.cjs

@@ -0,0 +1,89 @@
+/**
+ * guard-self-schedule-policy.cjs — decision logic for
+ * scripts/hooks/guard-self-schedule.cjs, split out so it can be `require()`d
+ * in-process (by tests, notably) with no CLI-level side effects.
+ *
+ * guard-self-schedule.cjs itself runs its CLI as a require-time side effect
+ * (stdin -> decision -> process.exit, not gated on `require.main === module`
+ * — see its header for why). Requiring THIS module never reads stdin or
+ * calls `process.exit`. `decide()` is fully I/O-free — it only reads
+ * `payload` and `process.env.SM_SCHEDULER_JOB_SLUG` — so calling it directly
+ * from a test is equivalent to the real CLI decision, without a child-process
+ * spawn per case.
+ */
+'use strict';
+
+const ALWAYS_DENY_TOOLS = new Set(['ScheduleWakeup', 'CronCreate']);
+const BACKGROUNDABLE_AGENT_TOOLS = new Set(['Task', 'Agent']);
+
+const STANDARDS_QUOTE = 'You ARE the executor — never re-queue or self-schedule.';
+const STANDARDS_CITE = 'plugins/session-manager-dev/skills/develop/standards.md:85 (Execution discipline)';
+
+function buildAllow() {
+  return { continue: true };
+}
+
+function buildDeny(reason) {
+  return {
+    continue: true,
+    decision: 'block',
+    reason,
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
+/**
+ * Decision function: PreToolUse payload in, hook-response object out. No
+ * stdin/stdout and no `process.exit` — safe to call in-process (e.g. from
+ * tests). Reads `process.env.SM_SCHEDULER_JOB_SLUG` at call time, not at
+ * module-load time, so a test can set/restore it around each call.
+ */
+function decide(payload) {
+  try {
+    const jobSlug = process.env.SM_SCHEDULER_JOB_SLUG;
+    if (!jobSlug) return buildAllow(); // interactive session — this guard is inert here
+
+    const toolName = payload.tool_name;
+
+    if (ALWAYS_DENY_TOOLS.has(toolName)) {
+      const reason = [
+        `Blocked: \`${toolName}\` from inside a headless scheduler-spawned run (job '${jobSlug}').`,
+        `${STANDARDS_CITE}: "${STANDARDS_QUOTE}"`,
+        'A headless run has no next turn — nothing will ever deliver this wakeup, so the job exits with its work stranded and parks in needs_review even if it was already correct.',
+        'Do it now instead: commit what you have, then run any required review synchronously inline (call the reviewer and read its result in this same turn) before the finish protocol — never schedule it for later.',
+      ].join(' ');
+      return buildDeny(reason);
+    }
+
+    if (BACKGROUNDABLE_AGENT_TOOLS.has(toolName) && payload.tool_input && payload.tool_input.run_in_background) {
+      const reason = [
+        `Blocked: a backgrounded ${toolName} call (run_in_background: true) from inside a headless scheduler-spawned run (job '${jobSlug}').`,
+        `${STANDARDS_CITE}: "${STANDARDS_QUOTE}"`,
+        'A headless run has no later turn to collect a background agent\'s result, so waiting on it (ListAgents, Monitor, ScheduleWakeup) strands the job in needs_review with its work already done but uncommitted.',
+        'Call it synchronously instead — omit run_in_background (or set it to false) and read its result in this same turn, before the finish protocol.',
+      ].join(' ');
+      return buildDeny(reason);
+    }
+
+    return buildAllow();
+  } catch (e) {
+    console.error(`[guard-self-schedule] internal error, failing open: ${e?.message}`);
+    return buildAllow();
+  }
+}
+
+/** Mirrors the CLI's stdin-JSON handling so it can be exercised without a spawn. */
+function parsePayload(raw) {
+  try {
+    return raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    console.error(`[guard-self-schedule] malformed stdin JSON, failing open: ${e?.message}`);
+    return {};
+  }
+}
+
+module.exports = { decide, parsePayload };

package/scripts/scheduler-mcp-server.cjs

@@ -514,7 +514,14 @@ async function handleCallTool(request) {
       const note = result?.ok !== false
         ? ' — PRD file written; the queue row is derived on the next scheduler reconcile pass, not by this call.'
         : '';
-      return { content: [{ type: 'text', text: JSON.stringify(result) + note }] };
+      let text = JSON.stringify(result) + note;
+      // Sizing warnings (PRD 1403) are advisory only — never block the write,
+      // just surfaced here so the authoring session can decide to split the
+      // PRD before confirming it. See prdSizing.cjs.
+      if (Array.isArray(result?.warnings) && result.warnings.length > 0) {
+        text += `\nSizing warnings:\n${result.warnings.map((w) => `- ${w}`).join('\n')}`;
+      }
+      return { content: [{ type: 'text', text }] };
     }
     if (name === 'feedback_list_projects') {
       const result = await adminRequest('GET', '/admin/feedback/targets');

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

@@ -0,0 +1,59 @@
+/**
+ * configWriteBoundaryOwners.test.cjs — validateWrite's ops-subtree exemption
+ * (config.cjs ~line 166) must derive its writable-namespace list from
+ * opsOwnership.cjs's OWNERS map, not a separately hand-maintained array. PRD
+ * 1398 declared 'ui-prefs' owned in OWNERS but config.cjs's own array was
+ * never updated, so every real ui-prefs write threw "Write outside allowed
+ * write boundaries" before assertOpsWrite's per-writer check ever ran (PRD
+ * 1410). This test exercises the REAL validateWrite (via writeJson) for
+ * every OWNERS namespace so that class of drift can never reoccur silently.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/configWriteBoundaryOwners.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, afterEach } from 'vitest';
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const config = require('../config.cjs');
+const { OWNERS } = require('../lib/opsOwnership.cjs');
+
+// Real-homedir-rooted (not os.tmpdir()) so the fixture root is classified as
+// a plain project, not an ephemeral cwd — opsPath() throws for roots under
+// os.tmpdir(), which would make every namespace's exemption silently
+// evaporate (opsSubs = []) and the test would pass for the wrong reason. Same
+// pattern as prdCreate.test.cjs's real-homedir-rooted tests.
+const roots = [];
+afterEach(async () => {
+  while (roots.length) {
+    const r = roots.pop();
+    await fsp.rm(r, { recursive: true, force: true });
+  }
+});
+
+async function mkProjectRoot(tag) {
+  const root = await fsp.mkdtemp(path.join(os.homedir(), `.sm-configwriteboundary-${tag}-`));
+  config.addAllowedRoot(root);
+  roots.push(root);
+  return root;
+}
+
+for (const [namespace, owner] of Object.entries(OWNERS)) {
+  test(`OWNERS namespace '${namespace}' is writable by its declared owner '${owner}'`, async () => {
+    const root = await mkProjectRoot(namespace);
+    const target = path.join(root, 'session-manager-operations', namespace, 'probe.json');
+    const result = await config.writeJson(target, { probe: 1 }, { writer: owner });
+    expect(result.ok).toBe(true);
+    expect(fs.existsSync(target)).toBe(true);
+  });
+}
+
+test('a namespace not declared in OWNERS is still rejected', async () => {
+  const root = await mkProjectRoot('undeclared');
+  const target = path.join(root, 'session-manager-operations', 'not-a-real-namespace', 'probe.json');
+  await expect(config.writeJson(target, { probe: 1 }, { writer: 'anyone' }))
+    .rejects.toThrow(/Write outside allowed write boundaries/);
+});

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

@@ -3,84 +3,61 @@
 /**
  * Unit test for exchanges.cjs.
  *
- * Runs against a tmp HOME so no real files are touched.
+ * PRD 1391: exchanges now write to <cwd>/session-manager-operations/
+ * prompt-sessions/exchanges.jsonl instead of the old global
+ * ~/.claude/knowledge-log/exchanges/<encodeCwd(cwd)>.jsonl store — each test
+ * uses a fresh tmp directory as its project `cwd` so no real project state is
+ * touched.
+ *
  * Stubs summarize.cjs to avoid any network calls.
  *
  * Run: timeout 300 npx vitest run src/main/__tests__/exchanges.test.cjs
  */
 
-import { test, describe, beforeAll as before, afterAll as after } from 'vitest';
+import { test, describe, beforeEach } from 'vitest';
 const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const fsp = require('node:fs/promises');
 const path = require('node:path');
 const os = require('node:os');
 
-// ─── Tmp HOME setup ─────────────────────────────────────────────────────────
-
-let tmpHome;
-let origHome;
-
-before(() => {
-  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'exchanges-test-'));
-  origHome = process.env.HOME;
-  // node:os.homedir() reads HOME on Linux
-  process.env.HOME = tmpHome;
-});
-
-after(async () => {
-  process.env.HOME = origHome;
-  await fsp.rm(tmpHome, { recursive: true, force: true });
-});
+function mkTmpProject() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'exchanges-test-'));
+}
 
-// ─── Module loading under tmp HOME ──────────────────────────────────────────
+function exchangesLogPath(cwd) {
+  return path.join(cwd, 'session-manager-operations', 'prompt-sessions', 'exchanges.jsonl');
+}
 
-// Clear module cache so encodeCwd / config / exchanges pick up the new HOME
-function freshRequire(mod) {
-  delete require.cache[require.resolve(mod)];
-  return require(mod);
+function stubSummarize(fn) {
+  const summarizePath = require.resolve('../lib/summarize.cjs');
+  delete require.cache[summarizePath];
+  require.cache[summarizePath] = {
+    id: summarizePath,
+    filename: summarizePath,
+    loaded: true,
+    exports: { summarize: fn },
+  };
 }
 
-// ─── Tests ───────────────────────────────────────────────────────────────────
+beforeEach(() => {
+  delete require.cache[require.resolve('../exchanges.cjs')];
+});
 
 describe('recordExchange', () => {
   test('writes a complete record when summarize succeeds', async () => {
-    // Stub summarize to return a fixed summary without a network call
-    const summarizePath = require.resolve('../lib/summarize.cjs');
-    delete require.cache[summarizePath];
-    require.cache[summarizePath] = {
-      id: summarizePath,
-      filename: summarizePath,
-      loaded: true,
-      exports: {
-        summarize: async () => ({ summary: 'Test summary.', model: 'claude-haiku-4-5' }),
-      },
-    };
-
-    // Clear exchanges so it picks up the stub
-    const exchangesPath = require.resolve('../exchanges.cjs');
-    delete require.cache[exchangesPath];
-    // Also clear config so it re-reads the new HOME
-    const configPath = require.resolve('../config.cjs');
-    delete require.cache[configPath];
-    const encodeCwdPath = require.resolve('../lib/encodeCwd.cjs');
-    delete require.cache[encodeCwdPath];
-
-    const { recordExchange, EXCHANGES_DIR } = require('../exchanges.cjs');
+    stubSummarize(async () => ({ summary: 'Test summary.', model: 'claude-haiku-4-5' }));
+
+    const { recordExchange } = require('../exchanges.cjs');
 
+    const cwd = mkTmpProject();
     const sessionId = 'sess-abc-123';
-    const cwd = '/home/user/myproject';
     const prompt = 'What is 2+2?';
     const result = 'The answer is 4.';
 
     await recordExchange({ sessionId, cwd, prompt, result });
 
-    // Re-resolve the exchanges dir using the actual module's path (under tmpHome)
-    const { encodeCwd } = require('../lib/encodeCwd.cjs');
-    const encoded = encodeCwd(cwd);
-    const logPath = path.join(tmpHome, '.claude', 'knowledge-log', 'exchanges', `${encoded}.jsonl`);
-
-    const content = await fsp.readFile(logPath, 'utf8');
+    const content = await fsp.readFile(exchangesLogPath(cwd), 'utf8');
     const lines = content.trim().split('\n').filter(Boolean);
     assert.equal(lines.length, 1, 'should write exactly one line');
 
@@ -96,38 +73,21 @@ describe('recordExchange', () => {
   });
 
   test('still writes a record when summarize degrades (no_api_key)', async () => {
-    // Stub summarize to return a degraded result
-    const summarizePath = require.resolve('../lib/summarize.cjs');
-    delete require.cache[summarizePath];
-    require.cache[summarizePath] = {
-      id: summarizePath,
-      filename: summarizePath,
-      loaded: true,
-      exports: {
-        summarize: async (text) => ({
-          summary: text.slice(0, 600),
-          model: 'raw',
-          degraded: 'no_api_key',
-        }),
-      },
-    };
-
-    const exchangesPath = require.resolve('../exchanges.cjs');
-    delete require.cache[exchangesPath];
+    stubSummarize(async (text) => ({
+      summary: text.slice(0, 600),
+      model: 'raw',
+      degraded: 'no_api_key',
+    }));
 
     const { recordExchange } = require('../exchanges.cjs');
-    const { encodeCwd } = require('../lib/encodeCwd.cjs');
 
+    const cwd = mkTmpProject();
     const sessionId = 'sess-degrade-456';
-    const cwd = '/home/user/anotherproject';
     const result = 'Some verbatim result text from the assistant.';
 
     await recordExchange({ sessionId, cwd, prompt: 'do something', result });
 
-    const encoded = encodeCwd(cwd);
-    const logPath = path.join(tmpHome, '.claude', 'knowledge-log', 'exchanges', `${encoded}.jsonl`);
-
-    const content = await fsp.readFile(logPath, 'utf8');
+    const content = await fsp.readFile(exchangesLogPath(cwd), 'utf8');
     const lines = content.trim().split('\n').filter(Boolean);
     assert.equal(lines.length, 1);
 
@@ -141,31 +101,16 @@ describe('recordExchange', () => {
   });
 
   test('appends multiple records to the same file', async () => {
-    // Stub summarize
-    const summarizePath = require.resolve('../lib/summarize.cjs');
-    delete require.cache[summarizePath];
-    require.cache[summarizePath] = {
-      id: summarizePath,
-      filename: summarizePath,
-      loaded: true,
-      exports: {
-        summarize: async () => ({ summary: 'ok', model: 'claude-haiku-4-5' }),
-      },
-    };
-
-    const exchangesPath = require.resolve('../exchanges.cjs');
-    delete require.cache[exchangesPath];
+    stubSummarize(async () => ({ summary: 'ok', model: 'claude-haiku-4-5' }));
+
     const { recordExchange } = require('../exchanges.cjs');
-    const { encodeCwd } = require('../lib/encodeCwd.cjs');
 
-    const cwd = '/home/user/multiproject';
+    const cwd = mkTmpProject();
 
     await recordExchange({ sessionId: 's1', cwd, prompt: 'first', result: 'res1' });
     await recordExchange({ sessionId: 's2', cwd, prompt: 'second', result: 'res2' });
 
-    const encoded = encodeCwd(cwd);
-    const logPath = path.join(tmpHome, '.claude', 'knowledge-log', 'exchanges', `${encoded}.jsonl`);
-    const content = await fsp.readFile(logPath, 'utf8');
+    const content = await fsp.readFile(exchangesLogPath(cwd), 'utf8');
     const lines = content.trim().split('\n').filter(Boolean);
     assert.equal(lines.length, 2);
 

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

@@ -4,34 +4,31 @@
  * runs under node:test, not vitest) so this is picked up by
  * `npx vitest run` per this repo's test:unit convention.
  *
+ * PRD 1391: exchanges now write to <cwd>/session-manager-operations/
+ * prompt-sessions/exchanges.jsonl — each test uses a fresh tmp directory as
+ * its project `cwd`.
+ *
  * Run: timeout 120 npx vitest run src/main/__tests__/exchangesPromptId.test.cjs
  */
 
 'use strict';
 
-import { test, expect, beforeAll, afterAll, beforeEach } from 'vitest';
+import { test, expect, beforeEach } from 'vitest';
 const fs = require('node:fs');
 const fsp = require('node:fs/promises');
 const path = require('node:path');
 const os = require('node:os');
 
-let tmpHome;
-let origHome;
-
-beforeAll(() => {
-  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'exchanges-promptid-test-'));
-  origHome = process.env.HOME;
-  process.env.HOME = tmpHome;
-});
+function mkTmpProject() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'exchanges-promptid-test-'));
+}
 
-afterAll(async () => {
-  process.env.HOME = origHome;
-  await fsp.rm(tmpHome, { recursive: true, force: true });
-});
+function exchangesLogPath(cwd) {
+  return path.join(cwd, 'session-manager-operations', 'prompt-sessions', 'exchanges.jsonl');
+}
 
 beforeEach(() => {
-  // Stub summarize.cjs to avoid any network calls, and clear the modules
-  // that cache HOME-derived paths so each test sees the tmp HOME.
+  // Stub summarize.cjs to avoid any network calls.
   const summarizePath = require.resolve('../lib/summarize.cjs');
   delete require.cache[summarizePath];
   require.cache[summarizePath] = {
@@ -41,30 +38,24 @@ beforeEach(() => {
     exports: { summarize: async () => ({ summary: 'ok', model: 'claude-haiku-4-5' }) },
   };
   delete require.cache[require.resolve('../exchanges.cjs')];
-  delete require.cache[require.resolve('../config.cjs')];
-  delete require.cache[require.resolve('../lib/encodeCwd.cjs')];
 });
 
 test('recordExchange persists promptId when supplied', async () => {
   const { recordExchange } = require('../exchanges.cjs');
-  const { encodeCwd } = require('../lib/encodeCwd.cjs');
 
-  const cwd = '/home/user/promptid-project';
+  const cwd = mkTmpProject();
   await recordExchange({ sessionId: 's1', cwd, prompt: 'do X', result: 'done', promptId: 'ticket-abc-123' });
 
-  const logPath = path.join(tmpHome, '.claude', 'knowledge-log', 'exchanges', `${encodeCwd(cwd)}.jsonl`);
-  const record = JSON.parse((await fsp.readFile(logPath, 'utf8')).trim());
+  const record = JSON.parse((await fsp.readFile(exchangesLogPath(cwd), 'utf8')).trim());
   expect(record.promptId).toBe('ticket-abc-123');
 });
 
 test('recordExchange omits promptId when not supplied (no backfill/synthesis)', async () => {
   const { recordExchange } = require('../exchanges.cjs');
-  const { encodeCwd } = require('../lib/encodeCwd.cjs');
 
-  const cwd = '/home/user/no-promptid-project';
+  const cwd = mkTmpProject();
   await recordExchange({ sessionId: 's2', cwd, prompt: 'do Y', result: 'done' });
 
-  const logPath = path.join(tmpHome, '.claude', 'knowledge-log', 'exchanges', `${encodeCwd(cwd)}.jsonl`);
-  const record = JSON.parse((await fsp.readFile(logPath, 'utf8')).trim());
+  const record = JSON.parse((await fsp.readFile(exchangesLogPath(cwd), 'utf8')).trim());
   expect('promptId' in record).toBe(false);
 });

package/src/main/__tests__/files-reject-credentials.test.cjs

@@ -29,7 +29,7 @@ test('denies writing autostart persistence entries', () => {
 });
 
 test('allows ordinary files — including shell rc, which developers do edit', () => {
-  for (const p of [under('Projects', 'app', 'src', 'index.ts'), under('.bashrc'), under('.zshrc'), under('.config', 'session-manager', 'voice.json')]) {
+  for (const p of [under('Projects', 'app', 'src', 'index.ts'), under('.bashrc'), under('.zshrc'), under('.claude', 'session-manager', 'voice.json')]) {
     assert.doesNotThrow(() => rejectCredentials(p), `${p} should be allowed`);
   }
 });

package/src/main/__tests__/health-credentials.test.cjs

@@ -0,0 +1,81 @@
+/**
+ * health-credentials.test.cjs — the credential health component.
+ *
+ * An expired/absent Claude OAuth token silently voids the whole scheduler:
+ * headless `claude -p` jobs cannot authenticate, so the queue "runs" but
+ * nothing completes. On this machine the token expired 2026-04-04 with no
+ * refresh token, yet `npm run health` read GREEN — no component pointed the
+ * operator at `claude login`. evaluateCredentialHealth is the missing signal.
+ * Pure over an injected credState (the shape refreshIfNeeded returns), so no
+ * Keychain access here.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/health-credentials.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const { evaluateCredentialHealth } = require('../health.cjs');
+
+const NOW = Date.parse('2026-09-23T15:00:00.000Z');
+
+test('an expired token is not ok, names claude login, and reports how long ago it lapsed', () => {
+  const expiredAt = NOW - 90 * 60_000; // 90 min ago
+  const { component, issues } = evaluateCredentialHealth({
+    credState: { kind: 'auth', message: 'Credentials expired.', expiredAt },
+    now: NOW,
+  });
+  expect(component.ok).toBe(false);
+  expect(component.state).toBe('expired');
+  expect(component.expiredAt).toBe(expiredAt);
+  expect(component.message).toMatch(/claude login/);
+  expect(component.message).toMatch(/90m ago/);
+  expect(issues.length).toBe(1);
+  expect(issues[0]).toMatch(/cannot authenticate/i);
+});
+
+test('an auth failure with no expiredAt still fails and still names the fix', () => {
+  const { component, issues } = evaluateCredentialHealth({
+    credState: { kind: 'auth', message: 'refresh rejected: HTTP 401' },
+    now: NOW,
+  });
+  expect(component.ok).toBe(false);
+  expect(component.state).toBe('expired');
+  expect(component.message).toMatch(/claude login/);
+  expect(component.message).not.toMatch(/NaN/);
+  expect(issues.length).toBe(1);
+});
+
+test('unreadable/absent credentials (kind:config) fail with the login fix', () => {
+  const { component, issues } = evaluateCredentialHealth({
+    credState: { kind: 'config', message: 'credentials not found' },
+    now: NOW,
+  });
+  expect(component.ok).toBe(false);
+  expect(component.state).toBe('unreadable');
+  expect(component.message).toMatch(/claude login/);
+  expect(issues.length).toBe(1);
+});
+
+test('a fresh token is ok and raises no issue', () => {
+  const { component, issues } = evaluateCredentialHealth({ credState: { kind: 'ok' }, now: NOW });
+  expect(component.ok).toBe(true);
+  expect(component.state).toBe('valid');
+  expect(issues.length).toBe(0);
+});
+
+test('kind:unsupported (auto-refresh unavailable, token still valid) is ok — the token works, refresh just can not', () => {
+  const { component, issues } = evaluateCredentialHealth({ credState: { kind: 'unsupported' }, now: NOW });
+  expect(component.ok).toBe(true);
+  expect(component.state).toBe('valid-no-refresh');
+  expect(issues.length).toBe(0);
+});
+
+test('a missing/garbage credState never throws and never fails health (unknown, not a false alarm)', () => {
+  for (const bad of [undefined, null, 'nope', 42]) {
+    const { component, issues } = evaluateCredentialHealth({ credState: bad, now: NOW });
+    expect(component.ok).toBe(true);
+    expect(component.state).toBe('unknown');
+    expect(issues.length).toBe(0);
+  }
+});

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

@@ -92,6 +92,18 @@ test('no false positive: billing utilization at/above utilizationThreshold (when
   assert.strictEqual(result.reason, 'utilization-at-threshold');
 });
 
+test('utilization hold with reset days out is flagged longHold; within 5h is benign', () => {
+  const far = evaluateTickLiveness(baseQueue(), { ts: NOW - 30_000, utilization: 95, utilizationWindow: 'weekly_all', nextReset: new Date(NOW + 3 * 86_400_000).toISOString() }, NOW);
+  assert.strictEqual(far.stalled, false);
+  assert.strictEqual(far.longHold, true);
+  assert.strictEqual(far.window, 'weekly_all');
+  const unknown = evaluateTickLiveness(baseQueue(), { ts: NOW - 30_000, utilization: 95, nextReset: null }, NOW);
+  assert.strictEqual(unknown.longHold, true);
+  const near = evaluateTickLiveness(baseQueue(), { ts: NOW - 30_000, utilization: 95, utilizationWindow: 'five_hour', nextReset: new Date(NOW + 2 * 3_600_000).toISOString() }, NOW);
+  assert.strictEqual(near.stalled, false);
+  assert.strictEqual(near.longHold, undefined);
+});
+
 test('no false positive: no pending jobs at all', () => {
   const q = baseQueue({ jobs: [] });
   const result = evaluateTickLiveness(q, null, NOW);