claude-code-session-manager 0.65.0 → 0.67.0

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/);
+});

package/src/main/__tests__/scheduler-reconcile-invalid-repair.test.cjs

@@ -0,0 +1,203 @@
+/**
+ * scheduler-reconcile-invalid-repair.test.cjs — end-to-end reproduction of
+ * the 2026-08-07 1021/1022 incident: a queue.json row with `"status":
+ * "queued"` (a value outside ScheduleJobStatus) sat unpicked for 4+ hours.
+ *
+ * queueStore.shapeJobs (scheduleJobSchema.cjs, landed by a prior PRD)
+ * already quarantines such a row into `invalidJobs` on read rather than
+ * passing it through — but reconcile() itself was still add-only (`if
+ * (seen.has(slug)) continue`), so a quarantined row was never repaired, only
+ * silently absent from state.jobs with no log of what its bad status had
+ * been.
+ *
+ * This test exercises the real quarantine path (queueStore.shapeJobs on the
+ * raw incident JSON) against a real on-disk PRD, runs the real reconcile(),
+ * and asserts: computeStallSummary flags the PRE-repair state as stalled,
+ * reconcile() repairs the row to 'pending', logs the repair at warn level,
+ * and audits it.
+ *
+ * HOME-isolated (mirrors scheduler-prd-missing-skip.test.cjs): stub HOME to
+ * a mkdtemp dir before requiring scheduler.cjs/queueStore.cjs, and register
+ * the fixture project as "active" via a fake ~/.claude/projects transcript —
+ * reconcile's PRD/history discovery (prdLocations.cjs, queueHistory.cjs)
+ * only scans cwds it can find that way.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-reconcile-invalid-repair.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll, afterEach, vi } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let originalHome;
+let scheduler;
+let queueStore;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-reconcile-repair-home-'));
+  process.env.HOME = tmpHome;
+
+  scheduler = require('../scheduler.cjs');
+  queueStore = require('../lib/queueStore.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 });
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+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 prdsDir = path.join(opsRoot, 'scheduler', 'prds');
+  const stateDir = path.join(opsRoot, 'scheduler', 'state');
+  fs.mkdirSync(prdsDir, { recursive: true });
+  fs.mkdirSync(stateDir, { recursive: true });
+  return { cwd, prdsDir, stateDir };
+}
+
+test('reconcile() repairs a queue row with an invalid status back to pending, logs, and audits it', async () => {
+  const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-reconcile-repair-proj-');
+  try {
+    // Real on-disk PRD (its file location is the reconcile source of truth).
+    fs.writeFileSync(
+      path.join(prdsDir, '1021-fix-the-thing.md'),
+      '---\ntitle: Fix the thing\ncwd: ' + cwd + '\nestimateMinutes: 15\n---\n\n# Goal\nFix it.\n',
+      'utf8',
+    );
+
+    // The exact incident shape: a row whose status is 'queued', outside
+    // ScheduleJobStatus entirely.
+    const badRow = {
+      slug: '1021-fix-the-thing',
+      title: 'Fix the thing',
+      cwd,
+      status: 'queued',
+      runId: null,
+      startedAt: null,
+      finishedAt: null,
+      exitCode: null,
+      error: null,
+    };
+    const queuePath = path.join(stateDir, 'queue.json');
+    fs.writeFileSync(queuePath, JSON.stringify({ jobs: [badRow] }, null, 2), 'utf8');
+
+    // Exercise the REAL quarantine gate (same one queueStore.readMerged runs
+    // at boot/every IPC read) rather than hand-building invalidJobs.
+    const { jobs, invalid } = queueStore.shapeJobs(fs.readFileSync(queuePath, 'utf8'), queuePath);
+    expect(jobs.length).toBe(0); // the bad row never reaches state.jobs
+    expect(invalid.length).toBe(1);
+    expect(invalid[0].slug).toBe(badRow.slug);
+    expect(invalid[0].row.status).toBe('queued');
+
+    const state = { jobs, invalidJobs: invalid, paused: null };
+
+    // Stall detector must flag the PRE-repair state: the queue holds a
+    // (quarantined) job but nothing is running or pending and it isn't
+    // paused — this is exactly the condition that was silent for 4+ hours.
+    const preRepairStall = scheduler.computeStallSummary(state);
+    expect(preRepairStall.stalled).toBe(true);
+    expect(preRepairStall.total).toBe(1);
+    expect(preRepairStall.running).toBe(0);
+    expect(preRepairStall.pending).toBe(0);
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    // scheduler.cjs destructures `appendAuditEvent` out of auditLog.cjs at
+    // require time, so spying on the module's export property after the
+    // fact wouldn't intercept scheduler.cjs's already-bound reference —
+    // assert against the real (tmpHome-isolated) audit log file instead.
+    const { AUDIT_LOG_PATH } = require('../lib/auditLog.cjs');
+    expect(AUDIT_LOG_PATH.startsWith(tmpHome)).toBe(true);
+
+    queueStore.bustCwdCache();
+    await scheduler.reconcile(state);
+
+    const repaired = state.jobs.find((j) => j.slug === badRow.slug);
+    expect(repaired).toBeDefined();
+    expect(repaired.status).toBe('pending');
+
+    const warnedRepair = warnSpy.mock.calls.some((args) =>
+      String(args[0]).includes('repaired invalid queue row') && String(args[0]).includes(badRow.slug),
+    );
+    expect(warnedRepair).toBe(true);
+
+    const auditLines = fs.readFileSync(AUDIT_LOG_PATH, 'utf8').trim().split('\n').filter(Boolean).map((l) => JSON.parse(l));
+    const auditedRepair = auditLines.some(
+      (rec) => rec.kind === 'scheduler_row_repaired' && rec.slug === badRow.slug && rec.oldStatus === 'queued',
+    );
+    expect(auditedRepair).toBe(true);
+
+    // Post-repair, the same condition must no longer read as stalled.
+    const postRepairStall = scheduler.computeStallSummary(state);
+    expect(postRepairStall.stalled).toBe(false);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('reconcile() does not resurrect an invalid row whose slug already has a terminal history record', async () => {
+  const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-reconcile-repair-done-');
+  try {
+    fs.writeFileSync(
+      path.join(prdsDir, '1022-already-done.md'),
+      '---\ntitle: Already done\ncwd: ' + cwd + '\nestimateMinutes: 15\n---\n\n# Goal\nDone.\n',
+      'utf8',
+    );
+
+    const badRow = {
+      slug: '1022-already-done',
+      title: 'Already done',
+      cwd,
+      status: 'queued',
+      runId: 'run-xyz',
+      startedAt: new Date().toISOString(),
+      finishedAt: null,
+      exitCode: null,
+      error: null,
+    };
+    const queuePath = path.join(stateDir, 'queue.json');
+    fs.writeFileSync(queuePath, JSON.stringify({ jobs: [badRow] }, null, 2), 'utf8');
+
+    const { jobs, invalid } = queueStore.shapeJobs(fs.readFileSync(queuePath, 'utf8'), queuePath);
+    expect(invalid.length).toBe(1);
+
+    const state = { jobs, invalidJobs: invalid, paused: null };
+
+    // A terminal record already exists for this slug — reconcile must never
+    // repair the corrupted row back into a runnable 'pending' state on top
+    // of already-shipped work.
+    fs.writeFileSync(
+      path.join(stateDir, 'history.jsonl'),
+      JSON.stringify({ slug: badRow.slug, status: 'completed', finishedAt: new Date().toISOString(), runId: 'run-xyz' }) + '\n',
+      'utf8',
+    );
+
+    queueStore.bustCwdCache();
+    await scheduler.reconcile(state);
+
+    expect(state.jobs.find((j) => j.slug === badRow.slug)).toBeUndefined();
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});

package/src/main/__tests__/scheduler-reconcile-quarantine.test.cjs

@@ -0,0 +1,196 @@
+/**
+ * scheduler-reconcile-quarantine.test.cjs — PRD-authoring-lockdown provenance
+ * gate: reconcile() must never turn a discovered PRD with no `createdVia`
+ * frontmatter into a runnable 'pending' queue row. It quarantines it instead
+ * (a distinct, non-runnable status), logs a warning naming the file, and
+ * audits the event — then, once the file is stamped (the Scheduler tab's
+ * "adopt PRD" action / scheduler_update_prd, both routed through
+ * remote.updatePrd), promotes the row to 'pending' on the very next pass.
+ *
+ * Mirrors scheduler-reconcile-invalid-repair.test.cjs's HOME-isolation setup.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-reconcile-quarantine.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll, afterEach, vi } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let originalHome;
+let scheduler;
+let queueStore;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-reconcile-quarantine-home-'));
+  process.env.HOME = tmpHome;
+
+  scheduler = require('../scheduler.cjs');
+  queueStore = require('../lib/queueStore.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 });
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+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');
+  // Epic-scoped, not the retired flat dir: a flat PRD with no live queue row
+  // gets swept into prds-archived/ by reconcile()'s own consolidation pass
+  // (see consolidateAllFlatPrds) BEFORE it's ever scanned as a discoverable
+  // PRD — exactly the scenario every test below needs to observe, so the
+  // flat layout would race the very thing under test.
+  const prdsDir = path.join(opsRoot, 'scheduler', 'epics', 'test-epic-1', 'prds');
+  const stateDir = path.join(opsRoot, 'scheduler', 'state');
+  fs.mkdirSync(prdsDir, { recursive: true });
+  fs.mkdirSync(stateDir, { recursive: true });
+  return { cwd, prdsDir, stateDir };
+}
+
+test('reconcile() quarantines a newly-discovered PRD with no createdVia provenance', async () => {
+  const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-quarantine-new-');
+  try {
+    fs.writeFileSync(
+      path.join(prdsDir, '9001-hand-written.md'),
+      `---\ntitle: Hand-written PRD\ncwd: ${cwd}\nestimateMinutes: 15\n---\n\n# Goal\nDo the thing.\n`,
+      'utf8',
+    );
+    fs.writeFileSync(path.join(stateDir, 'queue.json'), JSON.stringify({ jobs: [] }, null, 2), 'utf8');
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const { AUDIT_LOG_PATH } = require('../lib/auditLog.cjs');
+
+    queueStore.bustCwdCache();
+    const state = { jobs: [], invalidJobs: [], paused: null };
+    await scheduler.reconcile(state);
+
+    const row = state.jobs.find((j) => j.slug === '9001-hand-written');
+    expect(row).toBeDefined();
+    expect(row.status).toBe('quarantined');
+
+    const warned = warnSpy.mock.calls.some((args) =>
+      String(args[0]).includes('quarantining unstamped PRD') && String(args[0]).includes('9001-hand-written'),
+    );
+    expect(warned).toBe(true);
+
+    const auditLines = fs.readFileSync(AUDIT_LOG_PATH, 'utf8').trim().split('\n').filter(Boolean).map((l) => JSON.parse(l));
+    expect(auditLines.some((rec) => rec.kind === 'prd_quarantined' && rec.slug === '9001-hand-written')).toBe(true);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('reconcile() queues a newly-discovered PRD stamped with createdVia as pending, not quarantined', async () => {
+  const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-quarantine-stamped-');
+  try {
+    fs.writeFileSync(
+      path.join(prdsDir, '9002-api-written.md'),
+      `---\ntitle: API-written PRD\ncwd: ${cwd}\nestimateMinutes: 15\ncreatedVia: scheduler-api\nissuedAt: 2026-08-07T00:00:00.000Z\n---\n\n# Goal\nDo the thing.\n`,
+      'utf8',
+    );
+    fs.writeFileSync(path.join(stateDir, 'queue.json'), JSON.stringify({ jobs: [] }, null, 2), 'utf8');
+
+    queueStore.bustCwdCache();
+    const state = { jobs: [], invalidJobs: [], paused: null };
+    await scheduler.reconcile(state);
+
+    const row = state.jobs.find((j) => j.slug === '9002-api-written');
+    expect(row).toBeDefined();
+    expect(row.status).toBe('pending');
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('reconcile() exempts a fix-plan PRD (NN-fix-*) from quarantine even with no createdVia', async () => {
+  const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-quarantine-fixplan-');
+  try {
+    fs.writeFileSync(
+      path.join(prdsDir, '9003-fix-something.md'),
+      `---\ntitle: Fix something\ncwd: ${cwd}\nestimateMinutes: 15\n---\n\n# Goal\nHeal it.\n`,
+      'utf8',
+    );
+    fs.writeFileSync(path.join(stateDir, 'queue.json'), JSON.stringify({ jobs: [] }, null, 2), 'utf8');
+
+    queueStore.bustCwdCache();
+    const state = { jobs: [], invalidJobs: [], paused: null };
+    await scheduler.reconcile(state);
+
+    const row = state.jobs.find((j) => j.slug === '9003-fix-something');
+    expect(row).toBeDefined();
+    expect(row.status).toBe('pending');
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('reconcile() adopts a quarantined row to pending once its PRD file is stamped', async () => {
+  const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-quarantine-adopt-');
+  try {
+    const prdPath = path.join(prdsDir, '9004-adopt-me.md');
+    fs.writeFileSync(
+      prdPath,
+      `---\ntitle: Adopt me\ncwd: ${cwd}\nestimateMinutes: 15\n---\n\n# Goal\nAdopt.\n`,
+      'utf8',
+    );
+    const quarantinedRow = {
+      slug: '9004-adopt-me',
+      title: 'Adopt me',
+      cwd,
+      status: 'quarantined',
+      runId: null,
+      startedAt: null,
+      finishedAt: null,
+      exitCode: null,
+      error: null,
+    };
+    fs.writeFileSync(path.join(stateDir, 'queue.json'), JSON.stringify({ jobs: [quarantinedRow] }, null, 2), 'utf8');
+
+    // Simulate the adopt action: stamp the file via the same update-prd
+    // logic the IPC handler/admin route call (parsePrdFile/serializePrdFile
+    // round-trip), rather than hand-writing raw text, to exercise the real
+    // round-trip path this feature depends on.
+    const { parsePrdFile, serializePrdFile } = require('../lib/prdFrontmatter.cjs');
+    const raw = fs.readFileSync(prdPath, 'utf8');
+    const { frontmatter: fm, body } = parsePrdFile(raw);
+    fm.createdVia = 'legacy-adopted';
+    fm.issuedAt = '2026-08-07T01:00:00.000Z';
+    fs.writeFileSync(prdPath, serializePrdFile(fm, body), 'utf8');
+
+    const { AUDIT_LOG_PATH } = require('../lib/auditLog.cjs');
+    queueStore.bustCwdCache();
+    const state = { jobs: [quarantinedRow], invalidJobs: [], paused: null };
+    await scheduler.reconcile(state);
+
+    const row = state.jobs.find((j) => j.slug === '9004-adopt-me');
+    expect(row).toBeDefined();
+    expect(row.status).toBe('pending');
+
+    const auditLines = fs.readFileSync(AUDIT_LOG_PATH, 'utf8').trim().split('\n').filter(Boolean).map((l) => JSON.parse(l));
+    expect(auditLines.some((rec) => rec.kind === 'scheduler_prd_adopted' && rec.slug === '9004-adopt-me')).toBe(true);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});