claude-code-session-manager 0.64.0 → 0.66.0

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

@@ -0,0 +1,109 @@
+/**
+ * reconcileFlatPrdSweep.test.cjs — end-to-end proof that `reconcile()` itself
+ * (not just `consolidateAllFlatPrds()` in isolation) never turns a
+ * hand-written flat-dir PRD into a queue job, regardless of which of
+ * reconcile's several callers (tickQueue's poll, job completion, the
+ * schedule:state/schedule:rescan IPC handlers, rescheduleTimer) triggered
+ * the pass.
+ *
+ * A code-review pass on this PRD flagged that gating only `tickQueue()` left
+ * every OTHER caller of `reconcile()` free to still turn a freshly
+ * hand-written flat-dir PRD into a `pending` job — the fix moved the sweep
+ * inside `reconcile()` itself instead. This test exercises the real
+ * `reconcile()` (not a stand-in) against a real on-disk flat-dir PRD with no
+ * pre-existing queue row (exactly the state of a file dropped there moments
+ * ago) and asserts it never appears in `state.jobs` afterward.
+ *
+ * HOME-isolated (mirrors scheduler-reconcile-invalid-repair.test.cjs): stub
+ * HOME to a mkdtemp dir before requiring scheduler.cjs, and register the
+ * fixture project as "active" via a fake ~/.claude/projects transcript —
+ * reconcile's PRD discovery (prdLocations.cjs) only scans cwds it can find
+ * that way.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/reconcileFlatPrdSweep.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let originalHome;
+let scheduler;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-reconcile-flatsweep-home-'));
+  process.env.HOME = tmpHome;
+
+  scheduler = require('../scheduler.cjs');
+
+  if (!scheduler.PRDS_DIR.startsWith(tmpHome)) {
+    throw new Error(`refusing to run: PRDS_DIR (${scheduler.PRDS_DIR}) is not under the temp HOME (${tmpHome})`);
+  }
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+function registerActiveProject(cwd) {
+  const projectsDir = path.join(tmpHome, '.claude', 'projects');
+  const slugDir = path.join(projectsDir, `fake-project-slug-${path.basename(cwd)}`);
+  fs.mkdirSync(slugDir, { recursive: true });
+  fs.writeFileSync(path.join(slugDir, 'transcript.jsonl'), JSON.stringify({ cwd }) + '\n');
+}
+
+function makeFixtureProject(prefix) {
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  registerActiveProject(cwd);
+  const opsRoot = path.join(cwd, 'session-manager-operations');
+  const flatPrdsDir = path.join(opsRoot, 'scheduler', 'prds');
+  const stateDir = path.join(opsRoot, 'scheduler', 'state');
+  fs.mkdirSync(flatPrdsDir, { recursive: true });
+  fs.mkdirSync(stateDir, { recursive: true });
+  return { cwd, flatPrdsDir, stateDir, archiveDir: path.join(opsRoot, 'scheduler', 'prds-archived') };
+}
+
+test('reconcile() never turns a hand-written flat-dir PRD into a job, no matter which caller triggers it', async () => {
+  const { cwd, flatPrdsDir, archiveDir } = makeFixtureProject('sm-reconcile-flatsweep-proj-');
+  const filename = '1500-hand-written-bypass.md';
+  fs.writeFileSync(
+    path.join(flatPrdsDir, filename),
+    `---\ntitle: Hand-written bypass\ncwd: ${cwd}\nestimateMinutes: 10\n---\n\n# Goal\n\nSomething.\n`,
+    'utf8',
+  );
+  // No queue.json at all — the exact state of a PRD dropped on disk moments
+  // ago, before any prior reconcile() pass has scanned it into a job.
+
+  const state = { jobs: [], invalidJobs: [], paused: null };
+  await scheduler.reconcile(state);
+
+  const found = state.jobs.find((j) => j.slug === '1500-hand-written-bypass');
+  expect(found).toBeUndefined();
+  expect(fs.existsSync(path.join(flatPrdsDir, filename))).toBe(false);
+  expect(fs.existsSync(path.join(archiveDir, filename))).toBe(true);
+});
+
+test('reconcile() still onboards a PRD written to the canonical Epic-scoped dir (the sweep only touches the flat dir)', async () => {
+  const { cwd } = makeFixtureProject('sm-reconcile-flatsweep-epic-proj-');
+  const epicId = 'epic-abc';
+  const epicPrdsDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'epics', epicId, 'prds');
+  fs.mkdirSync(epicPrdsDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(epicPrdsDir, '1501-canonical.md'),
+    `---\ntitle: Canonical\ncwd: ${cwd}\nestimateMinutes: 10\nsourcePromptId: ${epicId}\ncreatedVia: scheduler-api\nissuedAt: 2026-08-07T00:00:00.000Z\n---\n\n# Goal\n\nSomething.\n`,
+    'utf8',
+  );
+
+  const state = { jobs: [], invalidJobs: [], paused: null };
+  await scheduler.reconcile(state);
+
+  const found = state.jobs.find((j) => j.slug === '1501-canonical');
+  expect(found).toBeDefined();
+  expect(found.status).toBe('pending');
+});

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

@@ -0,0 +1,127 @@
+/**
+ * scheduleJobSchema.test.cjs — unit tests for the canonical ScheduleJob zod
+ * schema, its assertValidScheduleJob fail-closed helper, and queueStore.cjs's
+ * shapeJobs on-read quarantine gate.
+ *
+ * Reproduces the 2026-08-07 incident: PRDs 1021/1022 (social-signals-trader)
+ * sat unscheduled for 4+ hours because their queue.json rows carried
+ * `"status": "queued"` — a value absent from ScheduleJobStatus — which every
+ * picker silently skipped since none of them treat an unrecognized status as
+ * an error.
+ *
+ * Run: timeout 300 npx vitest run src/main/__tests__/scheduleJobSchema.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach, afterEach, vi } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const {
+  ScheduleJobSchema,
+  JOB_STATUSES,
+  assertValidScheduleJob,
+} = require('../lib/scheduleJobSchema.cjs');
+const { shapeJobs } = require('../lib/queueStore.cjs');
+
+function validJob(overrides = {}) {
+  return {
+    slug: '1021-social-signals',
+    title: 'Wire up social signals trader',
+    cwd: '/home/bilko/Projects/social-signals-trader',
+    parallelGroup: 1021,
+    estimateMinutes: 30,
+    bodyPreview: 'Do the thing.',
+    status: 'pending',
+    runId: null,
+    startedAt: null,
+    finishedAt: null,
+    exitCode: null,
+    error: null,
+    ...overrides,
+  };
+}
+
+test('JOB_STATUSES matches ScheduleJobStatus', () => {
+  expect(JOB_STATUSES).toEqual(['pending', 'running', 'investigating', 'completed', 'failed', 'needs_review', 'quarantined']);
+});
+
+test('a valid full job record parses', () => {
+  const full = validJob({
+    sessionId: 'c1b2a3d4-0000-0000-0000-000000000000',
+    runtime: { pid: 123, runId: 'run-1', startedAt: '2026-08-07T00:00:00.000Z' },
+    verifierVerdict: 'halt',
+    dependsOn: ['1020-prereq'],
+    originSessionId: 'orig-session',
+    sourceTabId: 'tab-1',
+    sourcePromptId: 'prompt-1',
+    epicId: 'epic-1',
+  });
+  expect(() => assertValidScheduleJob(full)).not.toThrow();
+  expect(ScheduleJobSchema.safeParse(full).success).toBe(true);
+});
+
+test('a job with an invalid status value fails', () => {
+  const badStatus = validJob({ status: 'queued' });
+  expect(() => assertValidScheduleJob(badStatus)).toThrow(/status/);
+});
+
+test('a job missing a required field fails', () => {
+  const { slug, ...missingSlug } = validJob();
+  expect(() => assertValidScheduleJob(missingSlug)).toThrow(/slug/);
+});
+
+// ---------- shapeJobs (the on-read quarantine gate) ----------
+
+let tmpFile;
+let errorSpy;
+
+beforeEach(() => {
+  tmpFile = path.join(
+    os.tmpdir(),
+    `scheduleJobSchema-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`
+  );
+  errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  try { fs.unlinkSync(tmpFile); } catch { /* ok if absent */ }
+  errorSpy.mockRestore();
+});
+
+test('a row with status "queued" (the 1021/1022 incident) is quarantined, logged, and absent from jobs', () => {
+  fs.writeFileSync(tmpFile, JSON.stringify({
+    jobs: [
+      validJob({ slug: '1021-social-signals', status: 'queued' }),
+      validJob({ slug: '1022-social-signals', status: 'queued' }),
+      validJob({ slug: '1023-healthy', status: 'pending' }),
+    ],
+  }));
+
+  const raw = fs.readFileSync(tmpFile, 'utf8');
+  const { jobs, invalid } = shapeJobs(raw, tmpFile);
+
+  expect(jobs.map((j) => j.slug)).toEqual(['1023-healthy']);
+  expect(invalid.map((i) => i.slug)).toEqual(['1021-social-signals', '1022-social-signals']);
+  expect(invalid[0].issues).toMatch(/status/);
+  expect(invalid[0].file).toBe(tmpFile);
+
+  expect(errorSpy).toHaveBeenCalledTimes(2);
+  const firstCallArgs = errorSpy.mock.calls[0][0];
+  expect(firstCallArgs).toContain(tmpFile);
+  expect(firstCallArgs).toContain('1021-social-signals');
+  expect(firstCallArgs).toMatch(/status/);
+});
+
+test('a fully valid row round-trips through shapeJobs unchanged', () => {
+  const job = validJob({ slug: '1023-healthy' });
+  fs.writeFileSync(tmpFile, JSON.stringify({ jobs: [job] }));
+
+  const raw = fs.readFileSync(tmpFile, 'utf8');
+  const { jobs, invalid } = shapeJobs(raw, tmpFile);
+
+  expect(invalid).toEqual([]);
+  expect(jobs).toEqual([job]);
+  expect(errorSpy).not.toHaveBeenCalled();
+});

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

@@ -0,0 +1,65 @@
+/**
+ * scheduleJobStatusDrift.test.cjs — guards the mirrored copies of
+ * JOB_STATUSES (src/main/lib/scheduleJobSchema.cjs) against silent drift.
+ *
+ * The renderer cannot require a .cjs module directly, and src/preload/api.d.ts
+ * is types-only (erased at build time, nothing to import at test runtime), so
+ * each consumer keeps its own hand-written mirror of the status enum:
+ *   - src/preload/api.d.ts's `ScheduleJobStatus` union
+ *   - src/renderer/components/ui/StatusBadge.tsx's `JobStatus` union
+ *   - src/renderer/components/SchedulePanel.tsx's `FilterStatus` union
+ *     (which also carries the UI-only 'all' meta-value)
+ *
+ * This test reads each file's source text and extracts its status list by
+ * regex, then diffs it against JOB_STATUSES — the single source of truth.
+ * A file whose union drifts (a status added/removed/renamed in one place but
+ * not the others) fails this test instead of silently mis-filtering jobs,
+ * which is exactly how the 2026-08-07 'queued' incident went undetected.
+ *
+ * Run: timeout 300 npx vitest run src/main/__tests__/scheduleJobStatusDrift.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const fs = require('node:fs');
+const path = require('node:path');
+const { JOB_STATUSES } = require('../lib/scheduleJobSchema.cjs');
+
+const ROOT = path.join(__dirname, '..', '..', '..');
+
+function readSource(relPath) {
+  return fs.readFileSync(path.join(ROOT, relPath), 'utf8');
+}
+
+function extractQuotedList(source, anchorRegex) {
+  const match = source.match(anchorRegex);
+  if (!match) throw new Error(`extractQuotedList: anchor not found — ${anchorRegex}`);
+  return [...match[1].matchAll(/'([a-z_]+)'/g)].map((m) => m[1]);
+}
+
+test('JOB_STATUSES is the expected canonical list', () => {
+  expect(JOB_STATUSES).toEqual(['pending', 'running', 'investigating', 'completed', 'failed', 'needs_review', 'quarantined']);
+});
+
+function sorted(list) {
+  return [...list].sort();
+}
+
+test('src/preload/api.d.ts ScheduleJobStatus matches JOB_STATUSES', () => {
+  const source = readSource('src/preload/api.d.ts');
+  const values = extractQuotedList(source, /export type ScheduleJobStatus = ([^;]+);/);
+  expect(sorted(values)).toEqual(sorted(JOB_STATUSES));
+});
+
+test('src/renderer/components/ui/StatusBadge.tsx JobStatus matches JOB_STATUSES', () => {
+  const source = readSource('src/renderer/components/ui/StatusBadge.tsx');
+  const values = extractQuotedList(source, /export type JobStatus = ([^\n]+)/);
+  expect(sorted(values)).toEqual(sorted(JOB_STATUSES));
+});
+
+test('src/renderer/components/SchedulePanel.tsx FilterStatus matches JOB_STATUSES plus "all"', () => {
+  const source = readSource('src/renderer/components/SchedulePanel.tsx');
+  const values = extractQuotedList(source, /type FilterStatus = ([^\n]+)/);
+  expect(sorted(values)).toEqual(sorted(['all', ...JOB_STATUSES]));
+});

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

@@ -0,0 +1,152 @@
+/**
+ * scheduleJobTransitions.test.cjs — unit tests for transitionJob(), the sole
+ * chokepoint for a ScheduleJob's `status` field (scheduleJobTransitions.cjs).
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduleJobTransitions.test.cjs
+ */
+'use strict';
+
+import { test, expect } from 'vitest';
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+const {
+  transitionJob,
+  LEGAL_TRANSITIONS,
+  STATUS_HISTORY_CAP,
+  getRefusedTransitionCount,
+  _resetRefusedTransitionCountForTests,
+} = require('../lib/scheduleJobTransitions.cjs');
+const auditLog = require('../lib/auditLog.cjs');
+
+function uniqueSlug(label) {
+  return `test-${label}-${crypto.randomUUID().slice(0, 8)}`;
+}
+
+function readAuditRecordsForSlug(slug) {
+  if (!fs.existsSync(auditLog.AUDIT_LOG_PATH)) return [];
+  return fs.readFileSync(auditLog.AUDIT_LOG_PATH, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      try { return JSON.parse(line); } catch { return null; }
+    })
+    .filter((record) => record && record.slug === slug);
+}
+
+test('a legal transition mutates the job, records statusHistory, and audits', () => {
+  const slug = uniqueSlug('legal');
+  const job = { slug, cwd: '/tmp/proj', status: 'pending' };
+
+  const ok = transitionJob(job, 'running', { reason: 'dispatched', source: 'test' });
+
+  expect(ok).toBe(true);
+  expect(job.status).toBe('running');
+  expect(job.statusHistory).toHaveLength(1);
+  expect(job.statusHistory[0]).toMatchObject({ from: 'pending', to: 'running', reason: 'dispatched', source: 'test' });
+  expect(typeof job.statusHistory[0].at).toBe('string');
+
+  const records = readAuditRecordsForSlug(slug);
+  expect(records).toHaveLength(1);
+  expect(records[0]).toMatchObject({ kind: 'job_transition', slug, from: 'pending', to: 'running', reason: 'dispatched', source: 'test', cwd: '/tmp/proj' });
+});
+
+test('an illegal transition refuses: job untouched, error logged, counter incremented, audit written', () => {
+  const slug = uniqueSlug('illegal');
+  const job = { slug, cwd: '/tmp/proj', status: 'pending' };
+  const before = getRefusedTransitionCount();
+
+  const ok = transitionJob(job, 'needs_review', { reason: 'bogus', source: 'test' });
+
+  expect(ok).toBe(false);
+  expect(job.status).toBe('pending'); // untouched
+  expect(job.statusHistory).toBeUndefined(); // never mutated
+  expect(getRefusedTransitionCount()).toBe(before + 1);
+
+  const records = readAuditRecordsForSlug(slug);
+  expect(records).toHaveLength(1);
+  expect(records[0]).toMatchObject({ kind: 'job_transition_refused', slug, from: 'pending', to: 'needs_review' });
+});
+
+test('an identity transition (status unchanged) is accepted as a no-op with no history entry', () => {
+  const slug = uniqueSlug('identity');
+  const job = { slug, cwd: '/tmp/proj', status: 'running' };
+
+  const ok = transitionJob(job, 'running', { reason: 'no-op', source: 'test' });
+
+  expect(ok).toBe(true);
+  expect(job.status).toBe('running');
+  expect(job.statusHistory).toBeUndefined();
+  expect(readAuditRecordsForSlug(slug)).toHaveLength(0);
+});
+
+test('statusHistory caps at STATUS_HISTORY_CAP entries, dropping the oldest first', () => {
+  const slug = uniqueSlug('cap');
+  const job = { slug, cwd: '/tmp/proj', status: 'pending' };
+
+  // pending -> running -> pending -> running -> ... alternate legally more
+  // than the cap, to exercise eviction.
+  const cycles = STATUS_HISTORY_CAP + 5;
+  for (let i = 0; i < cycles; i++) {
+    const to = job.status === 'pending' ? 'running' : 'pending';
+    expect(transitionJob(job, to, { reason: `cycle ${i}`, source: 'test' })).toBe(true);
+  }
+
+  expect(job.statusHistory).toHaveLength(STATUS_HISTORY_CAP);
+  // Oldest entries (early cycles) were dropped — the earliest surviving
+  // entry's reason should be from a late cycle, not "cycle 0".
+  expect(job.statusHistory[0].reason).not.toBe('cycle 0');
+  expect(job.statusHistory[job.statusHistory.length - 1].reason).toBe(`cycle ${cycles - 1}`);
+});
+
+test('LEGAL_TRANSITIONS covers every real scheduler.cjs edge', () => {
+  // Spot-check the edges scheduler.cjs actually exercises, so a future prune
+  // of this table can't silently break a real call site without a test
+  // failure here pointing at it.
+  const mustBeLegal = [
+    ['pending', 'running'],
+    ['pending', 'completed'],
+    ['pending', 'failed'],
+    ['running', 'completed'],
+    ['running', 'failed'],
+    ['running', 'needs_review'],
+    ['running', 'pending'],
+    ['investigating', 'failed'],
+    ['investigating', 'needs_review'],
+    ['investigating', 'pending'],
+    ['failed', 'investigating'],
+    ['failed', 'pending'],
+    ['failed', 'completed'],
+    ['needs_review', 'investigating'],
+    ['needs_review', 'pending'],
+    ['needs_review', 'completed'],
+    ['completed', 'pending'],
+  ];
+  for (const [from, to] of mustBeLegal) {
+    expect(LEGAL_TRANSITIONS[from]).toContain(to);
+  }
+});
+
+test('a genuinely nonsensical edge (completed -> running) is illegal', () => {
+  expect(LEGAL_TRANSITIONS.completed).not.toContain('running');
+  const slug = uniqueSlug('nonsense');
+  const job = { slug, cwd: '/tmp/proj', status: 'completed' };
+  expect(transitionJob(job, 'running', { reason: 'nope', source: 'test' })).toBe(false);
+  expect(job.status).toBe('completed');
+});
+
+test('transitionJob never throws on a missing/malformed job', () => {
+  expect(transitionJob(null, 'running', {})).toBe(false);
+  expect(transitionJob(undefined, 'running', {})).toBe(false);
+  // status undefined -> 'running' is not a legal edge from any known state —
+  // refused, not a crash.
+  expect(transitionJob({}, 'running', {})).toBe(false);
+});
+
+test('_resetRefusedTransitionCountForTests resets the counter', () => {
+  const slug = uniqueSlug('reset-counter');
+  const job = { slug, status: 'completed' };
+  transitionJob(job, 'running', {});
+  expect(getRefusedTransitionCount()).toBeGreaterThan(0);
+  _resetRefusedTransitionCountForTests();
+  expect(getRefusedTransitionCount()).toBe(0);
+});

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

@@ -0,0 +1,59 @@
+/**
+ * scheduleJobTransitionsGrep.test.cjs — asserts scheduleJobTransitions.cjs's
+ * transitionJob() is the ONLY place a ScheduleJob's `status` field is
+ * assigned, per the PRD that introduced it (job-lifecycle chokepoint,
+ * mirroring epicMint.cjs's ownership of the Epic's status transition).
+ *
+ * A bare `job.status = '...'` reintroduces the exact failure class this
+ * module exists to close: no legality check, no statusHistory trail, no
+ * audit record — the 1021/1022 stall (2026-08-07) was undiagnosable from
+ * the app because status changes left no trace beyond a heartbeat count.
+ *
+ * Deliberately a plain grep, not an AST walk — this repo's other structural
+ * guards (check-unstable-selectors.cjs, check-conditional-hooks.cjs) use the
+ * same grep-based approach for the same reason: fast, dependency-free, and
+ * precise enough for a single well-known pattern.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduleJobTransitionsGrep.test.cjs
+ */
+'use strict';
+
+import { test, expect } from 'vitest';
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SCHEDULER_PATH = path.join(__dirname, '..', 'scheduler.cjs');
+
+// Lines explicitly exempt: `entry.status = ...` inside listPrdsInternal
+// assigns a freshly-synthesized PRD-listing row's display field, never a
+// persisted ScheduleJob's status (no queue.json mutation, no
+// statusHistory/audit trail applies). Each must carry the justifying
+// comment referencing this test, so the exemption can't silently drift.
+const ALLOWLISTED_PATTERN = /^\s*entry\.status = /;
+
+test('no bare `.status = ` assignment on a job object outside scheduleJobTransitions.cjs', () => {
+  const lines = fs.readFileSync(SCHEDULER_PATH, 'utf8').split('\n');
+  const offenders = [];
+  lines.forEach((line, i) => {
+    if (!/\.status = /.test(line)) return;
+    if (ALLOWLISTED_PATTERN.test(line)) return;
+    offenders.push(`scheduler.cjs:${i + 1}: ${line.trim()}`);
+  });
+  expect(offenders).toEqual([]);
+});
+
+test('scheduler.cjs references transitionJob (the chokepoint is actually wired up)', () => {
+  const content = fs.readFileSync(SCHEDULER_PATH, 'utf8');
+  expect(content).toMatch(/require\(['"]\.\/lib\/scheduleJobTransitions\.cjs['"]\)/);
+  // At least as many call sites as the PRD's own enumerated list — guards
+  // against someone reverting individual sites back to bare assignment
+  // without reintroducing the literal `.status = ` grep hit (e.g. swapping
+  // in a different mutation helper that itself bypasses transitionJob).
+  const callSites = content.match(/transitionJob\(/g) || [];
+  expect(callSites.length).toBeGreaterThanOrEqual(17);
+});
+
+test('the allowlisted entry.status lines carry their justifying comment', () => {
+  const content = fs.readFileSync(SCHEDULER_PATH, 'utf8');
+  expect(content).toMatch(/exempt from the\s*\n\s*\/\/ transitionJob-only rule enforced by scheduleJobTransitionsGrep\.test\.cjs/);
+});