claude-code-session-manager 0.64.0 → 0.66.0

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

@@ -0,0 +1,110 @@
+/**
+ * flatPrdTickSweep.test.cjs — the retired flat `scheduler/prds/` dir must be
+ * TRULY inert, not just documented as such.
+ *
+ * Prior to this PRD, `runPrdMigration()`'s consolidation of the flat dir into
+ * `prds-archived/` ran ONLY at Electron boot (src/main/scheduler.cjs). But
+ * `prdLocations.cjs`'s `resolvePrdsDirs()` unconditionally keeps scanning the
+ * flat dir as a live PRD source, and `reconcile()` runs on every tick — so a
+ * PRD hand-written into the flat dir *after* boot sat there live and WOULD
+ * get reconciled into a pending job and executed (observed 2026-08-07:
+ * 1021/1022 PRDs in social-signals-trader executed once their status was
+ * repaired), contradicting the develop skill's documented claim that
+ * anything landed there is "auto-consolidated ... WITHOUT being executed."
+ *
+ * The fix: `consolidateAllFlatPrds()` now also runs at the START of every
+ * `reconcile()` call itself (not just one caller like tickQueue's poll — every
+ * caller of reconcile gets the guarantee), BEFORE reconcile scans the flat
+ * dir. A freshly hand-written PRD has no queue row yet (reconcile hasn't
+ * seen it), so it is never in LIVE_JOB_STATUSES — this sweep archives it
+ * before reconcile ever gets a chance to turn it into a job. This test
+ * proves that invariant directly against `consolidateAllFlatPrds`: a file
+ * with no matching queue job is swept into `prds-archived/` on the very next
+ * call, which prdLocations.cjs's `resolvePrdsDirs()` never scans as a live
+ * source — so it can never be reconciled into a job afterward.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/flatPrdTickSweep.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 { consolidateAllFlatPrds } = require('../scheduler.cjs');
+const { resolvePrdWriteDir, resolvePrdsDirs } = require('../lib/prdLocations.cjs');
+
+const tmpDirs = [];
+afterEach(async () => {
+  while (tmpDirs.length) {
+    const d = tmpDirs.pop();
+    await fsp.rm(d, { recursive: true, force: true });
+  }
+});
+
+function newProjectRoot() {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-flat-tick-sweep-'));
+  tmpDirs.push(d);
+  return d;
+}
+
+test('a PRD hand-written into the retired flat dir after boot is swept before it could ever be reconciled', async () => {
+  const cwd = newProjectRoot();
+  const flatDir = resolvePrdWriteDir(cwd);
+  await fsp.mkdir(flatDir, { recursive: true });
+  const filename = '999-hand-written-bypass.md';
+  await fsp.writeFile(
+    path.join(flatDir, filename),
+    `---\ntitle: Hand-written bypass\ncwd: ${cwd}\nestimateMinutes: 10\n---\n\n# Goal\n\nSomething.\n`,
+    'utf8',
+  );
+  // No queue.json at all yet — this is exactly the state of a PRD dropped on
+  // disk moments ago, before any reconcile() pass has scanned it into a job.
+
+  await consolidateAllFlatPrds([cwd]);
+
+  // Swept out of the live flat dir...
+  expect(fs.existsSync(path.join(flatDir, filename))).toBe(false);
+  // ...and into prds-archived/, which resolvePrdsDirs() never returns as a
+  // scan source — so no future reconcile() pass can find it and queue it.
+  const archivedPath = path.join(path.dirname(flatDir), 'prds-archived', filename);
+  expect(fs.existsSync(archivedPath)).toBe(true);
+
+  const liveDirs = resolvePrdsDirs(Infinity, { projectsDir: path.join(cwd, '.nonexistent') });
+  expect(liveDirs.every((d) => !d.includes('prds-archived'))).toBe(true);
+});
+
+test('consolidateAllFlatPrds still protects a PRD that already has a live queue job (PRD 992 invariant preserved)', async () => {
+  const cwd = newProjectRoot();
+  const flatDir = resolvePrdWriteDir(cwd);
+  await fsp.mkdir(flatDir, { recursive: true });
+  const stateDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'state');
+  await fsp.mkdir(stateDir, { recursive: true });
+  await fsp.writeFile(
+    path.join(flatDir, '998-live.md'),
+    `---\ntitle: Live\ncwd: ${cwd}\nestimateMinutes: 10\n---\n\n# Goal\n`,
+    'utf8',
+  );
+  await fsp.writeFile(
+    path.join(stateDir, 'queue.json'),
+    JSON.stringify({ jobs: [{ slug: '998-live', status: 'running' }] }),
+    'utf8',
+  );
+
+  await consolidateAllFlatPrds([cwd]);
+
+  expect(fs.existsSync(path.join(flatDir, '998-live.md'))).toBe(true);
+});
+
+test('consolidateAllFlatPrds never throws when a project errors — one bad cwd does not block the sweep of the rest', async () => {
+  const good = newProjectRoot();
+  const flatDir = resolvePrdWriteDir(good);
+  await fsp.mkdir(flatDir, { recursive: true });
+  await fsp.writeFile(path.join(flatDir, '997-ok.md'), `---\ntitle: Ok\ncwd: ${good}\nestimateMinutes: 5\n---\n\n# Goal\n`, 'utf8');
+
+  await expect(consolidateAllFlatPrds([null, good])).resolves.toBeUndefined();
+
+  expect(fs.existsSync(path.join(flatDir, '997-ok.md'))).toBe(false);
+});

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

@@ -0,0 +1,68 @@
+/**
+ * prdAdminRouteParity.test.cjs — capability-parity gate for PRD 1024 ("lock
+ * the PRD entity behind the scheduler service boundary, step 1").
+ *
+ * Enumerates every PRD/job mutation the codebase can perform (the full set
+ * of `schedule:*` IPC channels that read/write a PRD file or a queue job,
+ * plus create-prd and cancel-job which have no IPC twin) and asserts each
+ * one has a corresponding admin HTTP route registered by scheduler.cjs's
+ * registerAdminRoutes, prdCreate.cjs's registerAdminRoute, or
+ * prdAdminRoutes.cjs's registerAdminRoute. A future PRD-lifecycle capability
+ * added only as an IPC handler (filesystem-only from the admin API's point
+ * of view) fails this test until an admin route is added for it too — that
+ * is the whole point: the admin API must never fall behind what's actually
+ * possible against a PRD/job.
+ *
+ * Route registration is captured via a fake `adminHttp` stub (just
+ * `registerRoute`) — no real HTTP server or Electron boot needed, matching
+ * how prdCreate.test.cjs already verifies wiring.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/prdAdminRouteParity.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const scheduler = require('../scheduler.cjs');
+const prdCreate = require('../lib/prdCreate.cjs');
+const prdAdminRoutes = require('../lib/prdAdminRoutes.cjs');
+
+// Every PRD-lifecycle capability the codebase can perform, mapped to the
+// admin HTTP route that must exist for it. `ipcChannel` is informational
+// (documents the renderer-facing twin, if any) — the assertion is only
+// against `adminRoute`.
+const REQUIRED_CAPABILITIES = [
+  { capability: 'create a PRD', ipcChannel: null, adminRoute: 'POST /admin/scheduler/create-prd' },
+  { capability: 'list PRDs (live + archived)', ipcChannel: 'schedule:list-prds', adminRoute: 'GET /admin/scheduler/prds' },
+  { capability: 'read one PRD (body + frontmatter)', ipcChannel: 'schedule:read-prd', adminRoute: 'GET /admin/scheduler/prd' },
+  { capability: 'edit a not-yet-running PRD', ipcChannel: 'schedule:write-prd', adminRoute: 'POST /admin/scheduler/update-prd' },
+  { capability: 'archive a PRD', ipcChannel: 'schedule:archive-prd', adminRoute: 'POST /admin/scheduler/archive-prd' },
+  { capability: 'retag a PRD (parallelGroup/estimateMinutes)', ipcChannel: 'schedule:retag-prd', adminRoute: 'POST /admin/scheduler/retag-prd' },
+  { capability: 'list scheduler jobs', ipcChannel: null, adminRoute: 'GET /admin/scheduler/jobs' },
+  { capability: 'reset a stuck job', ipcChannel: 'schedule:reset-job', adminRoute: 'POST /admin/scheduler/reset-job' },
+  { capability: 'cancel a not-yet-terminal job', ipcChannel: null, adminRoute: 'POST /admin/scheduler/cancel-job' },
+];
+
+function captureRegisteredRoutes() {
+  const registered = new Set();
+  const fakeAdminHttp = {
+    registerRoute(method, url) {
+      registered.add(`${method} ${url}`);
+    },
+  };
+  scheduler.registerAdminRoutes(fakeAdminHttp, scheduler.remote);
+  prdCreate.registerAdminRoute(fakeAdminHttp, scheduler.remote);
+  prdAdminRoutes.registerAdminRoute(fakeAdminHttp, scheduler.remote);
+  return registered;
+}
+
+test('every enumerated PRD/job mutation capability has a registered admin route', () => {
+  const registered = captureRegisteredRoutes();
+  const missing = REQUIRED_CAPABILITIES.filter((c) => !registered.has(c.adminRoute));
+  expect(missing).toEqual([]);
+});
+
+test.each(REQUIRED_CAPABILITIES)('capability "$capability" → $adminRoute is registered', ({ adminRoute }) => {
+  const registered = captureRegisteredRoutes();
+  expect(registered.has(adminRoute)).toBe(true);
+});

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