claude-code-session-manager 0.65.0 → 0.66.0

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

@@ -0,0 +1,311 @@
+/**
+ * prdAdminRoutes.test.cjs — unit tests for PRD 1024's admin HTTP routes
+ * (list/get/update/archive/cancel/retag) and the scheduler.cjs `remote`
+ * methods they delegate to. Exercises real HTTP round-trips against a real
+ * (temp-HOME) filesystem, matching prdCreate.test.cjs's pattern for the
+ * create-prd route.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/prdAdminRoutes.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll, beforeEach } from 'vitest';
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const http = require('node:http');
+
+let tmpHome;
+let originalHome;
+let scheduler;
+let prdAdminRoutes;
+let config;
+let createAdminHttp;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-admin-prd-routes-'));
+  process.env.HOME = tmpHome;
+
+  // Load AFTER HOME is stubbed — scheduler.cjs/config.cjs snapshot
+  // os.homedir() into module-level constants at load time, not lazily.
+  scheduler = require('../scheduler.cjs');
+  prdAdminRoutes = require('../lib/prdAdminRoutes.cjs');
+  config = require('../config.cjs');
+  ({ createAdminHttp } = require('../lib/localAdminHttp.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})`);
+  }
+
+  // allProjectCwds()/activeProjectCwds() (queueStore.cjs's stateCwds, and
+  // prdLocations.cjs's resolvePrdsDirs) discover project cwds by scanning
+  // ~/.claude/projects/*/*.jsonl for a `cwd` field — fake one project
+  // transcript pointing at the real on-disk fixture cwd this file uses,
+  // same pattern as scheduler-verify-prd-path.test.cjs.
+  const projDir = path.join(tmpHome, '.claude', 'projects', 'fake-project-slug');
+  fs.mkdirSync(projDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(projDir, 'session.jsonl'),
+    `${JSON.stringify({ cwd: path.join(tmpHome, 'fake-project-cwd') })}\n`,
+    'utf8',
+  );
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+function projectCwd() {
+  const cwd = path.join(tmpHome, 'fake-project-cwd');
+  fs.mkdirSync(cwd, { recursive: true });
+  config.addAllowedRoot(cwd);
+  return cwd;
+}
+
+function uniqueSlug(prefix) {
+  return `${prefix}-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+}
+
+async function writePrdFixture({ cwd, epicId, slug, extra = '' }) {
+  const prdsDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'epics', epicId, 'prds');
+  await fsp.mkdir(prdsDir, { recursive: true });
+  const filePath = path.join(prdsDir, `${slug}.md`);
+  const body = `---\ntitle: fixture title\ncwd: ${cwd}\nestimateMinutes: 10\n${extra}---\n\n# Goal\n\ndo the thing\n`;
+  await fsp.writeFile(filePath, body, 'utf8');
+  return filePath;
+}
+
+function request(port, { method = 'GET', path: reqPath, token, body }) {
+  return new Promise((resolve, reject) => {
+    const headers = {};
+    if (token !== undefined) headers.Authorization = `Bearer ${token}`;
+    let payload;
+    if (body !== undefined) {
+      payload = JSON.stringify(body);
+      headers['Content-Type'] = 'application/json';
+      headers['Content-Length'] = Buffer.byteLength(payload);
+    }
+    const req = http.request({ hostname: '127.0.0.1', port, method, path: reqPath, headers }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const text = Buffer.concat(chunks).toString('utf8');
+        let json = null;
+        try { json = JSON.parse(text); } catch { /* leave null */ }
+        resolve({ status: res.statusCode, json, text });
+      });
+    });
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+async function startAdmin() {
+  const prevE2e = process.env.SM_E2E;
+  process.env.SM_E2E = '1';
+  const admin = createAdminHttp();
+  prdAdminRoutes.registerAdminRoute(admin, scheduler.remote);
+  const { port, token } = await admin.start();
+  if (prevE2e === undefined) delete process.env.SM_E2E; else process.env.SM_E2E = prevE2e;
+  return { admin, port, token };
+}
+
+test('GET /admin/scheduler/prds without token returns 401', async () => {
+  const { admin, port } = await startAdmin();
+  try {
+    const res = await request(port, { path: '/admin/scheduler/prds' });
+    expect(res.status).toBe(401);
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('GET /admin/scheduler/prds lists a live PRD with status null (no queue row yet), filterable by cwd', async () => {
+  const cwd = projectCwd();
+  const epicId = 'epic-list';
+  const slug = uniqueSlug('list-prds');
+  await writePrdFixture({ cwd, epicId, slug });
+
+  const { admin, port, token } = await startAdmin();
+  try {
+    const res = await request(port, { path: `/admin/scheduler/prds?cwd=${encodeURIComponent(cwd)}`, token });
+    expect(res.status).toBe(200);
+    expect(res.json.ok).toBe(true);
+    const entry = res.json.prds.find((p) => p.slug === slug);
+    expect(entry).toBeTruthy();
+    expect(entry.status).toBe(null);
+    expect(entry.epicId).toBe(epicId);
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('GET /admin/scheduler/prd?slug=&cwd= returns parsed frontmatter + body', async () => {
+  const cwd = projectCwd();
+  const epicId = 'epic-get';
+  const slug = uniqueSlug('get-prd');
+  await writePrdFixture({ cwd, epicId, slug });
+
+  const { admin, port, token } = await startAdmin();
+  try {
+    const res = await request(port, { path: `/admin/scheduler/prd?slug=${slug}&cwd=${encodeURIComponent(cwd)}`, token });
+    expect(res.status).toBe(200);
+    expect(res.json.ok).toBe(true);
+    expect(res.json.frontmatter.title).toBe('fixture title');
+    expect(res.json.body).toMatch(/do the thing/);
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('GET /admin/scheduler/prd for a nonexistent slug returns 404', async () => {
+  const cwd = projectCwd();
+  const { admin, port, token } = await startAdmin();
+  try {
+    const res = await request(port, { path: `/admin/scheduler/prd?slug=${uniqueSlug('nope')}&cwd=${encodeURIComponent(cwd)}`, token });
+    expect(res.status).toBe(404);
+    expect(res.json.ok).toBe(false);
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('POST /admin/scheduler/update-prd edits a not-yet-queued PRD and preserves unrecognized frontmatter keys', async () => {
+  const cwd = projectCwd();
+  const epicId = 'epic-update';
+  const slug = uniqueSlug('update-prd');
+  await writePrdFixture({ cwd, epicId, slug, extra: 'dependsOn: [some-other-slug]\n' });
+
+  const { admin, port, token } = await startAdmin();
+  try {
+    const res = await request(port, {
+      method: 'POST', path: '/admin/scheduler/update-prd', token,
+      body: { slug, cwd, frontmatter: { title: 'edited title', estimateMinutes: 25 } },
+    });
+    expect(res.status).toBe(200);
+    expect(res.json.ok).toBe(true);
+
+    const raw = await fsp.readFile(path.join(cwd, 'session-manager-operations', 'scheduler', 'epics', epicId, 'prds', `${slug}.md`), 'utf8');
+    expect(raw).toMatch(/title: edited title/);
+    expect(raw).toMatch(/estimateMinutes: 25/);
+    // Unrecognized key round-trips verbatim.
+    expect(raw).toMatch(/dependsOn: \[some-other-slug\]/);
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('POST /admin/scheduler/update-prd refuses a slug whose job is running, naming the current status', async () => {
+  const cwd = projectCwd();
+  const epicId = 'epic-update-running';
+  const slug = uniqueSlug('update-prd-running');
+  await writePrdFixture({ cwd, epicId, slug });
+
+  await scheduler.writeQueue({
+    jobs: [{ slug, title: 'x', cwd, status: 'running', runtime: {} }],
+    config: {},
+    paused: null,
+  });
+
+  const { admin, port, token } = await startAdmin();
+  try {
+    const res = await request(port, {
+      method: 'POST', path: '/admin/scheduler/update-prd', token,
+      body: { slug, cwd, frontmatter: { title: 'should not land' } },
+    });
+    expect(res.status).toBe(409);
+    expect(res.json.ok).toBe(false);
+    expect(res.json.error).toMatch(/running/);
+  } finally {
+    await admin.stop();
+    await scheduler.writeQueue({ jobs: [], config: {}, paused: null });
+  }
+});
+
+test('POST /admin/scheduler/cancel-job cancels a pending job (no cancelled status exists — lands as failed)', async () => {
+  const cwd = projectCwd();
+  const slug = uniqueSlug('cancel-pending');
+  await scheduler.writeQueue({
+    jobs: [{ slug, title: 'x', cwd, status: 'pending' }],
+    config: {},
+    paused: null,
+  });
+
+  const { admin, port, token } = await startAdmin();
+  try {
+    const res = await request(port, { method: 'POST', path: '/admin/scheduler/cancel-job', token, body: { slug } });
+    expect(res.status).toBe(200);
+    expect(res.json.ok).toBe(true);
+    expect(res.json.status).toBe('failed');
+    expect(res.json.wasRunning).toBe(false);
+  } finally {
+    await admin.stop();
+    await scheduler.writeQueue({ jobs: [], config: {}, paused: null });
+  }
+});
+
+test('POST /admin/scheduler/cancel-job refuses an already-terminal job', async () => {
+  const cwd = projectCwd();
+  const slug = uniqueSlug('cancel-terminal');
+  await scheduler.writeQueue({
+    jobs: [{ slug, title: 'x', cwd, status: 'completed' }],
+    config: {},
+    paused: null,
+  });
+
+  const { admin, port, token } = await startAdmin();
+  try {
+    const res = await request(port, { method: 'POST', path: '/admin/scheduler/cancel-job', token, body: { slug } });
+    expect(res.status).toBe(409);
+    expect(res.json.ok).toBe(false);
+    expect(res.json.error).toMatch(/terminal/);
+  } finally {
+    await admin.stop();
+    await scheduler.writeQueue({ jobs: [], config: {}, paused: null });
+  }
+});
+
+test('POST /admin/scheduler/archive-prd moves a PRD to prds-archived/', async () => {
+  const cwd = projectCwd();
+  const epicId = 'epic-archive';
+  const slug = uniqueSlug('archive-prd');
+  const filePath = await writePrdFixture({ cwd, epicId, slug });
+
+  const { admin, port, token } = await startAdmin();
+  try {
+    const res = await request(port, { method: 'POST', path: '/admin/scheduler/archive-prd', token, body: { slugs: [slug] } });
+    expect(res.status).toBe(200);
+    expect(res.json.ok).toBe(true);
+    expect(res.json.archived).toBe(1);
+    expect(fs.existsSync(filePath)).toBe(false);
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('POST /admin/scheduler/retag-prd rewrites estimateMinutes frontmatter', async () => {
+  const cwd = projectCwd();
+  const epicId = 'epic-retag';
+  const slug = uniqueSlug('retag-prd');
+  const filePath = await writePrdFixture({ cwd, epicId, slug });
+
+  const { admin, port, token } = await startAdmin();
+  try {
+    const res = await request(port, {
+      method: 'POST', path: '/admin/scheduler/retag-prd', token,
+      body: { items: [{ slug, estimateMinutes: 42 }] },
+    });
+    expect(res.status).toBe(200);
+    expect(res.json.ok).toBe(true);
+    expect(res.json.retagged).toBe(1);
+    const raw = await fsp.readFile(filePath, 'utf8');
+    expect(raw).toMatch(/estimateMinutes: 42/);
+  } finally {
+    await admin.stop();
+  }
+});

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

@@ -221,7 +221,7 @@ test('POST /admin/scheduler/create-prd without token returns 401', async () => {
   }
 });
 
-test('POST /admin/scheduler/create-prd with a valid payload writes a file with frontmatter + standards appended, returns {nn, filename, status}', async () => {
+test('POST /admin/scheduler/create-prd with a valid payload writes a file with frontmatter + standards appended, returns {nn, filename, enqueued:false}', async () => {
   const prdsDir = await mkTmpPrdsDir();
   const remote = makeFakeRemoteWithPrdsDir(prdsDir);
   const { admin, port, token } = await startWithRemote(remote);
@@ -230,7 +230,12 @@ test('POST /admin/scheduler/create-prd with a valid payload writes a file with f
       method: 'POST', path: '/admin/scheduler/create-prd', token, body: validCreateBody(),
     });
     expect(res.status).toBe(200);
-    expect(res.json.status).toBe('queued');
+    // Never a 'status' field, and never the literal 'queued' — this route
+    // only writes the PRD file; the queue row is derived by the next
+    // reconcile() pass, not created here. See prdCreate.cjs's createPrd.
+    expect(res.json.status).toBeUndefined();
+    expect(res.json.enqueued).toBe(false);
+    expect(typeof res.json.note).toBe('string');
     expect(typeof res.json.nn).toBe('number');
     expect(res.json.filename).toMatch(/^\d+-add-widget-frobnication\.md$/);
 

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

@@ -250,6 +250,23 @@ test('consolidateFlatPrds archives a file with no job at all', async () => {
   expect(fs.existsSync(path.join(opsRoot(root), 'prds-archived', '701-orphan.md'))).toBe(true);
 });
 
+// PRD 1024: an UNRECOGNIZED/invalid status (the exact 2026-08-07 1021/1022
+// incident shape) must protect the file, not archive it — reconcile() is
+// what repairs such a row back to 'pending', and this consolidation must
+// never race that repair by moving the row's only source out from under it.
+for (const invalidStatus of ['queued', 'cancelled', 'bogus-status', '']) {
+  test(`consolidateFlatPrds does NOT archive a file whose job has the unrecognized status "${invalidStatus}"`, async () => {
+    const root = newRoot();
+    const flat = await makeFlatProject(root, ['950-invalid-status.md']);
+    await writeQueue(root, [{ slug: '950-invalid-status', status: invalidStatus }]);
+
+    const r = await consolidateFlatPrds(root);
+
+    expect(r.moved).toBe(0);
+    expect(fs.existsSync(path.join(flat, '950-invalid-status.md'))).toBe(true);
+  });
+}
+
 test('consolidateFlatPrds mixed dir: only the live one survives', async () => {
   const root = newRoot();
   const flat = await makeFlatProject(root, ['800-live.md', '801-done.md', '802-none.md']);

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

@@ -0,0 +1,91 @@
+/**
+ * prdMigrationLegacyAdopt.test.cjs — legacyAdoptExistingPrds() (PRD-authoring-
+ * lockdown rollout migration): every PRD .md already on disk when the
+ * provenance gate ships must be stamped `createdVia: legacy-adopted` before
+ * reconcile() ever runs its quarantine check against it, so the rollout
+ * itself never quarantines pre-existing work.
+ *
+ * HOME-isolated (mirrors scheduler-reconcile-quarantine.test.cjs): stamping
+ * relies on resolvePrdsDirs(), which discovers projects via
+ * ~/.claude/projects transcripts.
+ *
+ * Run: timeout 60 npx vitest run src/main/__tests__/prdMigrationLegacyAdopt.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 legacyAdoptExistingPrds;
+let parsePrdFile;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-legacy-adopt-home-'));
+  process.env.HOME = tmpHome;
+  ({ legacyAdoptExistingPrds } = require('../lib/prdMigration.cjs'));
+  ({ parsePrdFile } = require('../lib/prdFrontmatter.cjs'));
+});
+
+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 prdsDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'prds');
+  fs.mkdirSync(prdsDir, { recursive: true });
+  return { cwd, prdsDir };
+}
+
+test('stamps a pre-existing unstamped PRD as createdVia: legacy-adopted', async () => {
+  const { cwd, prdsDir } = makeFixtureProject('sm-legacy-adopt-proj-');
+  try {
+    const prdPath = path.join(prdsDir, '01-old.md');
+    fs.writeFileSync(prdPath, `---\ntitle: Old PRD\ncwd: ${cwd}\nestimateMinutes: 15\n---\n\n# Goal\nOld work.\n`, 'utf8');
+
+    const result = await legacyAdoptExistingPrds();
+    expect(result.stamped).toBeGreaterThanOrEqual(1);
+    expect(result.failed).toEqual([]);
+
+    const { frontmatter } = parsePrdFile(fs.readFileSync(prdPath, 'utf8'));
+    expect(frontmatter.createdVia).toBe('legacy-adopted');
+    expect(typeof frontmatter.issuedAt).toBe('string');
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('is idempotent — never overwrites an already-stamped PRD', async () => {
+  const { cwd, prdsDir } = makeFixtureProject('sm-legacy-adopt-idempotent-');
+  try {
+    const prdPath = path.join(prdsDir, '02-already-stamped.md');
+    fs.writeFileSync(
+      prdPath,
+      `---\ntitle: Already stamped\ncwd: ${cwd}\nestimateMinutes: 15\ncreatedVia: scheduler-api\nissuedAt: 2026-08-01T00:00:00.000Z\n---\n\n# Goal\nDone.\n`,
+      'utf8',
+    );
+
+    await legacyAdoptExistingPrds();
+
+    const { frontmatter } = parsePrdFile(fs.readFileSync(prdPath, 'utf8'));
+    expect(frontmatter.createdVia).toBe('scheduler-api'); // unchanged
+    expect(frontmatter.issuedAt).toBe('2026-08-01T00:00:00.000Z'); // unchanged
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});

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