claude-code-session-manager 0.86.0 → 0.88.0

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

@@ -18,13 +18,18 @@ const opsErrorLog = require('../lib/opsErrorLog.cjs');
 const tmpDirs = [];
 let originalHome;
 let originalSmTelemetrySpool;
+let originalWorktreeRoot;
 
 afterEach(async () => {
   if (originalHome !== undefined) process.env.HOME = originalHome;
   if (originalSmTelemetrySpool === undefined) delete process.env.SM_TELEMETRY_SPOOL; else process.env.SM_TELEMETRY_SPOOL = originalSmTelemetrySpool;
+  if (originalWorktreeRoot !== undefined) {
+    if (originalWorktreeRoot === null) delete process.env.SM_WORKTREE_ROOT; else process.env.SM_WORKTREE_ROOT = originalWorktreeRoot;
+    originalWorktreeRoot = undefined;
+  }
   const telemetryPath = require.resolve('../lib/telemetryClient.cjs');
   delete require.cache[telemetryPath];
-  const activeSessionsPath = require.resolve('../../../scripts/lib/activeSessions.cjs');
+  const activeSessionsPath = require.resolve('../lib/activeSessions.cjs');
   delete require.cache[activeSessionsPath];
   while (tmpDirs.length) {
     const d = tmpDirs.pop();
@@ -85,12 +90,23 @@ test('level "warn" routes to telemetryClient.logLine, default "error" routes to
 // ─── ephemeral cwd: local refused, telemetry still fires ─────────────────
 
 test('an ephemeral cwd yields zero local lines but one telemetry record, with a normalized projectHash', () => {
+  // Why this test depends on the process tmpdir: ephemeral classification
+  // (cwdClassify.classifyCwd, via ephemeralCwd.isEphemeralCwd) is an exact match
+  // on os.tmpdir() plus a prefix match on the managed job/epic worktree roots,
+  // and those roots are <SM_WORKTREE_ROOT || os.tmpdir()>/session-manager-*-worktrees
+  // (schedulerPaths.worktreeRoot). The sandbox globalSetup mkdtemp's that base under
+  // the tmpdir it saw at startup, so a relocated TMPDIR / prior env mutation changes
+  // where KIND_CONFIG.epic.root points. Pin SM_WORKTREE_ROOT to a fixture dir this
+  // test owns and derive the cwd from KIND_CONFIG, so expected and actual roots
+  // resolve through the same code path regardless of TMPDIR.
+  originalWorktreeRoot = process.env.SM_WORKTREE_ROOT === undefined ? null : process.env.SM_WORKTREE_ROOT;
+  process.env.SM_WORKTREE_ROOT = mkTmpProject();
   const { KIND_CONFIG } = require('../lib/gitWorktree.cjs');
   const worktreeCwd = path.join(KIND_CONFIG.epic.root, 'fakehash', 'fake-epic-id');
   const realRoot = '/home/bilko/Projects/real-project';
 
-  const activeSessionsPath = require.resolve('../../../scripts/lib/activeSessions.cjs');
-  const original = require('../../../scripts/lib/activeSessions.cjs');
+  const activeSessionsPath = require.resolve('../lib/activeSessions.cjs');
+  const original = require('../lib/activeSessions.cjs');
   require.cache[activeSessionsPath] = {
     id: activeSessionsPath,
     filename: activeSessionsPath,
@@ -103,7 +119,9 @@ test('an ephemeral cwd yields zero local lines but one telemetry record, with a
 
   opsErrorLog.appendError({ cwd: worktreeCwd, scope: 'chatRunner', message: 'worktree err' });
 
-  expect(fs.existsSync(opsErrorLog.todayFile(worktreeCwd))).toBe(false);
+  // resolveProjectRoot now consumes cwdClassify (not the stubbed projectRootOf):
+  // an ephemeral worktree cwd is refused outright, so no local path is even built.
+  expect(() => opsErrorLog.todayFile(worktreeCwd)).toThrow(/ephemeral/);
   expect(reportErrorCalls).toHaveLength(1);
   expect(reportErrorCalls[0].context.cwd).toBe(realRoot);
   expect(reportErrorCalls[0].context.cwd).not.toBe(worktreeCwd);
@@ -139,6 +157,12 @@ test('a realistic error with an absolute path and a prompt-like string never rea
     message: `run failed while processing "${promptLike}" at ${absPath}`,
   });
 
+  // The telemetry write is fire-and-forget async; poll (bounded) for the queue
+  // file instead of a fixed sleep, which raced under load.
+  const deadline = Date.now() + 5000;
+  while (!fs.existsSync(client.queuePath()) && Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 25));
+  }
   await new Promise((r) => setTimeout(r, 50));
 
   const raw = await fsp.readFile(client.queuePath(), 'utf8');

package/src/main/__tests__/pollLoop-dispatch-on-failure.test.cjs

@@ -16,6 +16,16 @@
  * whether that pass ends in an actual job launch (see classifyQueueStarvation's
  * header for why this must be distinct from `lastRunAt`).
  *
+ * Usage-meter circuit PRD update: pollLoop no longer fires blind at a hard-
+ * coded cachedUtilization=0 on failure — it falls back to
+ * usageCircuit.degradedBudget(), which carries forward the last known-good
+ * BINDING window's utilization (or conservatively assumes 100/no-headroom
+ * when there's no known-good reading yet at all). So each test below first
+ * drives ONE successful ('ok') poll — with the queue still empty, so it
+ * can't itself cause a dispatch — to seed that known-good low-utilization
+ * reading, THEN seeds the pending job and drives the failure. This proves
+ * dispatch proceeds under the CARRIED-FORWARD degraded budget, not a blind 0.
+ *
  * No existing test in this repo mocks a module import (see
  * pty-epic-worktree-spawn-cwd.test.cjs's header) — this monkey-patches
  * usage.cjs's cached module object directly instead, same pattern.
@@ -73,10 +83,24 @@ function mkProject() {
   return { cwd, slug };
 }
 
+// dependsOn deliberately references a slug that can never resolve (no such
+// row, no history/archive entry) so pickNextBatch's dep gate holds this job
+// forever instead of ever handing it to spawnJob. tickQueue() still reaches
+// the picker and stamps lastDispatchAttemptAt (that stamp is unconditional —
+// see lastDispatchAttemptAt's own header comment), which is the only thing
+// these tests assert on. Without this, the picker actually dispatches the
+// job: spawnJob() is fire-and-forget (scheduler.cjs's own comment: "spawnJob
+// is fire-and-forget; it calls tickQueue() on completion") and its real
+// child-process exit handler later calls mutate() independently of the
+// tickTail chain flushPendingTick() drains — round-tripping whatever
+// lastDispatchAttemptAt was in memory at ITS read time. Reproduced outside
+// vitest: that stray write landed ~2s after this suite's own reset-to-null,
+// clobbering the NEXT test's "still null" assertion with the previous test's
+// stamp. A held (never-dispatched) job has no such background continuation.
 async function seedOnePendingJob() {
   const { cwd, slug } = mkProject();
   await scheduler.writeQueue({
-    jobs: [{ slug, title: 'x', cwd, status: 'pending', dependsOn: [] }],
+    jobs: [{ slug, title: 'x', cwd, status: 'pending', dependsOn: ['unresolvable-dep-never-completes'] }],
     config: {},
     paused: null,
   });
@@ -96,11 +120,23 @@ async function flushPendingTick() {
   await scheduler.tickQueue();
 }
 
-test('pollLoop still attempts a dispatch after a transient billing failure', async () => {
+test('pollLoop still attempts a dispatch after a transient billing failure, using the degraded budget (not utilization 0)', async () => {
+  // Seed a known-good low-utilization reading via an 'ok' poll first.
+  process.env.SM_E2E = '1';
+  process.env.SM_MOCK_BILLING_KIND = 'ok';
+  await scheduler.pollLoop();
+  // A prior test's leftover project (a REAL, still-registered project cwd —
+  // readQueue() merges every such cwd) can still hold its own permanently-
+  // pending job, so this seed poll's own maybeLaunchWhenAvailable may itself
+  // spawn a fire-and-forget tick; drain it before resetting/reseeding so
+  // that stray tick's async mutate() can't land AFTER (and clobber) the
+  // reset below.
+  await flushPendingTick();
+  await scheduler.writeQueue({ jobs: [], config: {}, paused: null });
+
   await seedOnePendingJob();
   expect(await lastDispatchAttemptAt()).toBeNull();
 
-  process.env.SM_E2E = '1';
   process.env.SM_MOCK_BILLING_KIND = 'transient';
   await scheduler.pollLoop();
   await flushPendingTick();
@@ -108,10 +144,18 @@ test('pollLoop still attempts a dispatch after a transient billing failure', asy
   expect(await lastDispatchAttemptAt()).not.toBeNull();
 });
 
-test('pollLoop still attempts a dispatch after the billing poll throws', async () => {
+test('pollLoop still attempts a dispatch after the billing poll throws, using the degraded budget (not utilization 0)', async () => {
+  process.env.SM_E2E = '1';
+  process.env.SM_MOCK_BILLING_KIND = 'ok';
+  await scheduler.pollLoop(); // seed a known-good low-utilization reading
+  await flushPendingTick();
+  await scheduler.writeQueue({ jobs: [], config: {}, paused: null });
+
   await seedOnePendingJob();
   expect(await lastDispatchAttemptAt()).toBeNull();
 
+  delete process.env.SM_E2E;
+  delete process.env.SM_MOCK_BILLING_KIND;
   billing.fetchUsage = async () => { throw new Error('simulated IPC transport failure'); };
   await scheduler.pollLoop();
   await flushPendingTick();

package/src/main/__tests__/prd-group-allocator.test.cjs

@@ -8,12 +8,12 @@
  * so a collision silently merges two unrelated projects' PRDs into one
  * group.
  *
- * Run: timeout 120 node --test src/main/__tests__/prd-group-allocator.test.cjs
+ * Run: timeout 300 npx vitest run src/main/__tests__/prd-group-allocator.test.cjs
  */
 
 'use strict';
 
-const { test } = require('node:test');
+import { test } from 'vitest';
 const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const fsp = require('node:fs/promises');

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

@@ -40,6 +40,8 @@ const REQUIRED_CAPABILITIES = [
   { 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: 'pause new dispatch (user-initiated)', ipcChannel: 'schedule:pause', adminRoute: 'POST /admin/scheduler/pause' },
+  { capability: 'resume a paused scheduler', ipcChannel: 'schedule:resume', adminRoute: 'POST /admin/scheduler/resume' },
   { capability: 'cancel a not-yet-terminal job', ipcChannel: null, adminRoute: 'POST /admin/scheduler/cancel-job' },
 ];
 

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

@@ -499,6 +499,12 @@ test('POST /admin/scheduler/reset-job with cwd resets the SAME-slug job belongin
   bustCwdCache();
   const slug = uniqueSlug('collision-slug');
   const epicId = 'epic-reset-collision';
+  // Both projects' rows need a real PRD source — a 'needs_review' row whose
+  // PRD is invisible to reconcile()'s onDisk scan is silently dropped (never
+  // backfilled to history.jsonl the way a completed/failed/skipped orphan
+  // is), which would make jobA vanish for a reason unrelated to what this
+  // test actually verifies (cwd-scoped job lookup).
+  await writePrdFixture({ cwd: cwdA, epicId, slug });
   await writePrdFixture({ cwd: cwdB, epicId, slug });
   await scheduler.writeQueue({
     jobs: [
@@ -518,8 +524,14 @@ test('POST /admin/scheduler/reset-job with cwd resets the SAME-slug job belongin
     expect(res.json).toEqual({ ok: true, slug, status: 'pending' });
 
     const state = await scheduler.remote.listJobs();
-    const jobA = state.find((j) => j.cwd === cwdA);
-    const jobB = state.find((j) => j.cwd === cwdB);
+    // Filter by slug too, not just cwd: cwdA is a shared fixture directory
+    // reused by many tests in this file, each of which leaves its own
+    // never-archived PRD file behind (only the queue row is cleared in
+    // `finally`) — reconcile()'s fresh-discovery pass can quarantine one of
+    // those leftovers as a NEW row under this same cwd on any later pass, so
+    // `cwd` alone no longer uniquely identifies this test's own job.
+    const jobA = state.find((j) => j.cwd === cwdA && j.slug === slug);
+    const jobB = state.find((j) => j.cwd === cwdB && j.slug === slug);
     expect(jobA.status).toBe('needs_review'); // untouched
     expect(jobB.status).toBe('pending'); // the one actually targeted
   } finally {

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

@@ -0,0 +1,39 @@
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { seedAuthoringGuide } = require('../lib/prdAuthoringSeed.cjs');
+
+const write = async (abs, text) => fs.writeFileSync(abs, text, 'utf8');
+
+describe('seedAuthoringGuide', () => {
+  let dir, src, dest;
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'prd-seed-'));
+    src = path.join(dir, 'src.md');
+    dest = path.join(dir, 'dest.md');
+    fs.writeFileSync(src, '<!-- PRD_AUTHORING.md v3 -->\nnew body\n');
+  });
+  afterEach(() => fs.rmSync(dir, { recursive: true, force: true }));
+
+  it('seeds an absent destination', async () => {
+    expect(await seedAuthoringGuide({ src, dest, write })).toBe(true);
+    expect(fs.readFileSync(dest, 'utf8')).toContain('new body');
+  });
+  it('overwrites a stale stamp', async () => {
+    fs.writeFileSync(dest, '<!-- PRD_AUTHORING.md v2 -->\nold\n');
+    expect(await seedAuthoringGuide({ src, dest, write })).toBe(true);
+    expect(fs.readFileSync(dest, 'utf8')).toContain('v3');
+  });
+  it('leaves a matching stamp untouched', async () => {
+    const same = '<!-- PRD_AUTHORING.md v3 -->\nlocal edit\n';
+    fs.writeFileSync(dest, same);
+    expect(await seedAuthoringGuide({ src, dest, write })).toBe(false);
+    expect(fs.readFileSync(dest, 'utf8')).toBe(same);
+  });
+  it('overwrites a destination with no stamp', async () => {
+    fs.writeFileSync(dest, '# no stamp\n');
+    expect(await seedAuthoringGuide({ src, dest, write })).toBe(true);
+    expect(fs.readFileSync(dest, 'utf8')).toContain('v3');
+  });
+});

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

@@ -0,0 +1,201 @@
+/**
+ * prdCreateDisposition.test.cjs — scheduler wave-disposition PRD:
+ * createPrd()'s authoring-time disposition gate. A PRD landing as a wave
+ * ROOT (no dependsOn of its own) in an Epic that already has incomplete
+ * PRDs must record an explicit 'append'/'new-head' choice — required for an
+ * interactive caller, defaulted (and logged) for a non-interactive one.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/prdCreateDisposition.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach, afterEach } from 'vitest';
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const config = require('../config.cjs');
+const prdParser = require('../scheduler/prdParser.cjs');
+const { parsePrdFile } = require('../lib/prdFrontmatter.cjs');
+const { createPrd } = require('../lib/prdCreate.cjs');
+
+async function mkTmpPrdsDir() {
+  const root = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-disposition-create-prd-'));
+  config.addAllowedRoot(root);
+  const prdsDir = path.join(root, '.claude', 'prds');
+  await fsp.mkdir(prdsDir, { recursive: true });
+  return prdsDir;
+}
+
+/** Minimal fake `remote` — same shape as prdCreate.test.cjs's
+ *  makeFakeRemoteWithPrdsDir, but listPrds also reports sourcePromptId/
+ *  dependsOn (read back from each seeded file's real frontmatter) and
+ *  status (from the test-supplied statusBySlug map) — the fields
+ *  createPrd()'s disposition gate actually reads. */
+function makeFakeRemote(prdsDir, statusBySlug = {}) {
+  return {
+    async allocateParallelGroup() {
+      return prdParser.allocateParallelGroup(prdsDir);
+    },
+    async readPrd(slug) {
+      try {
+        const text = await fsp.readFile(path.join(prdsDir, `${slug}.md`), 'utf8');
+        return { ok: true, text };
+      } catch (e) {
+        return { ok: false, error: e?.message };
+      }
+    },
+    async writePrd(slug, body) {
+      try {
+        const filePath = path.join(prdsDir, `${slug}.md`);
+        await config.writeTextAtomic(filePath, body, { writer: 'scheduler' });
+        return { ok: true };
+      } catch (e) {
+        return { ok: false, error: e?.message };
+      }
+    },
+    async listPrds() {
+      const entries = await fsp.readdir(prdsDir);
+      const prds = [];
+      for (const f of entries) {
+        if (!f.endsWith('.md')) continue;
+        const slug = f.slice(0, -3);
+        const raw = await fsp.readFile(path.join(prdsDir, f), 'utf8');
+        const { frontmatter } = parsePrdFile(raw);
+        prds.push({
+          slug,
+          sourcePromptId: frontmatter.sourcePromptId ?? null,
+          dependsOn: frontmatter.dependsOn ?? null,
+          status: statusBySlug[slug] ?? null,
+        });
+      }
+      return { prds, total: prds.length, limit: prds.length, offset: 0, hasMore: false };
+    },
+  };
+}
+
+/** Seeds a fixture PRD file directly (bypassing createPrd) at an explicit,
+ *  already-NN-prefixed slug, so tests can assert dependsOn against a known
+ *  name instead of a freshly-allocated one. */
+async function seedPrd(prdsDir, slug, { sourcePromptId, dependsOn } = {}) {
+  const lines = ['---', 'title: seed', `sourcePromptId: ${sourcePromptId}`];
+  if (dependsOn && dependsOn.length) lines.push(`dependsOn: [${dependsOn.join(', ')}]`);
+  lines.push('---', '# Goal', '', 'seed body', '');
+  await fsp.writeFile(path.join(prdsDir, `${slug}.md`), lines.join('\n'));
+}
+
+function validBody(overrides = {}) {
+  return {
+    title: 'Wave 2 root',
+    cwd: os.homedir(),
+    estimateMinutes: 10,
+    goal: 'Do the follow-on work.',
+    acceptanceCriteria: ['a'],
+    implementationNotes: 'n',
+    ...overrides,
+  };
+}
+
+// This suite's own process may itself be running as a scheduled job (this
+// file's disposition gate keys directly off SM_SCHEDULER_JOB_SLUG — see
+// createPrd()) — never assume it's unset going in; each test controls it
+// explicitly.
+const originalJobSlug = process.env.SM_SCHEDULER_JOB_SLUG;
+beforeEach(() => {
+  delete process.env.SM_SCHEDULER_JOB_SLUG;
+});
+afterEach(() => {
+  if (originalJobSlug === undefined) delete process.env.SM_SCHEDULER_JOB_SLUG;
+  else process.env.SM_SCHEDULER_JOB_SLUG = originalJobSlug;
+});
+
+test('refuses to write, without a disposition, a new root joining an Epic that already has an incomplete PRD', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  await seedPrd(prdsDir, '1-wave1-tail', { sourcePromptId: 'epic-1' });
+  const remote = makeFakeRemote(prdsDir, { '1-wave1-tail': 'pending' });
+
+  const result = await createPrd(validBody({ sourcePromptId: 'epic-1' }), remote);
+
+  expect(result.ok).toBe(false);
+  expect(result.status).toBe(400);
+  expect(result.error).toMatch(/disposition/i);
+});
+
+test('disposition: append attaches the new root behind the Epic\'s current terminal PRD', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  await seedPrd(prdsDir, '1-wave1-tail', { sourcePromptId: 'epic-1' });
+  const remote = makeFakeRemote(prdsDir, { '1-wave1-tail': 'pending' });
+
+  const result = await createPrd(validBody({ sourcePromptId: 'epic-1', disposition: 'append' }), remote);
+
+  expect(result.ok).toBe(true);
+  const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+  expect(written).toMatch(/^dependsOn: \[1-wave1-tail\]$/m);
+  expect(written).toMatch(/^disposition: append$/m);
+});
+
+test('disposition: new-head leaves the new root independent (no dependsOn)', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  await seedPrd(prdsDir, '1-wave1-tail', { sourcePromptId: 'epic-1' });
+  const remote = makeFakeRemote(prdsDir, { '1-wave1-tail': 'pending' });
+
+  const result = await createPrd(validBody({ sourcePromptId: 'epic-1', disposition: 'new-head' }), remote);
+
+  expect(result.ok).toBe(true);
+  const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+  expect(written).not.toContain('dependsOn');
+  expect(written).toMatch(/^disposition: new-head$/m);
+});
+
+test('a non-interactive caller (SM_SCHEDULER_JOB_SLUG set) with no disposition defaults to append, logged as a default', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  await seedPrd(prdsDir, '1-wave1-tail', { sourcePromptId: 'epic-1' });
+  const remote = makeFakeRemote(prdsDir, { '1-wave1-tail': 'pending' });
+  process.env.SM_SCHEDULER_JOB_SLUG = 'some-running-job';
+
+  const result = await createPrd(validBody({ sourcePromptId: 'epic-1' }), remote);
+
+  expect(result.ok).toBe(true);
+  const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+  expect(written).toMatch(/^dependsOn: \[1-wave1-tail\]$/m);
+  expect(written).toMatch(/^disposition: append$/m);
+});
+
+test('no disposition required for the first PRD in a brand-new Epic', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  const remote = makeFakeRemote(prdsDir);
+
+  const result = await createPrd(validBody({ sourcePromptId: 'epic-empty' }), remote);
+
+  expect(result.ok).toBe(true);
+  const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+  expect(written).not.toContain('disposition');
+});
+
+test('no disposition required when every existing PRD in the Epic is already completed', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  await seedPrd(prdsDir, '1-wave1-tail', { sourcePromptId: 'epic-done' });
+  const remote = makeFakeRemote(prdsDir, { '1-wave1-tail': 'completed' });
+
+  const result = await createPrd(validBody({ sourcePromptId: 'epic-done' }), remote);
+
+  expect(result.ok).toBe(true);
+  const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+  expect(written).not.toContain('disposition');
+});
+
+test('an explicit dependsOn bypasses the disposition gate entirely', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  await seedPrd(prdsDir, '1-wave1-tail', { sourcePromptId: 'epic-1' });
+  const remote = makeFakeRemote(prdsDir, { '1-wave1-tail': 'pending' });
+
+  const result = await createPrd(
+    validBody({ sourcePromptId: 'epic-1', dependsOn: ['1-wave1-tail'] }),
+    remote,
+  );
+
+  expect(result.ok).toBe(true);
+  const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+  expect(written).toMatch(/^dependsOn: \[1-wave1-tail\]$/m);
+  expect(written).not.toContain('disposition');
+});

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

@@ -0,0 +1,125 @@
+/**
+ * prdFrontmatterDisposition.test.cjs — scheduler wave-disposition PRD:
+ * `disposition` ('append' | 'new-head') is a recognized, patchable PRD
+ * frontmatter key, same pattern as `dependsOn` in
+ * prdFrontmatterDependsOn.test.cjs. It records the authoring-time decision
+ * for a wave's root PRD: does it extend the Epic's existing dependsOn chain
+ * (append) or start an independent, parallel-eligible chain (new-head)?
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/prdFrontmatterDisposition.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+
+const { parsePrdFile, serializePrdFile, RECOGNIZED_KEYS } = require('../lib/prdFrontmatter.cjs');
+
+test('disposition is a recognized key', () => {
+  expect(RECOGNIZED_KEYS.has('disposition')).toBe(true);
+});
+
+test('parsePrdFile parses disposition: append and round-trips it byte-identically when unedited', () => {
+  const raw = [
+    '---',
+    'title: A second wave',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 20',
+    'dependsOn: [widget-base]',
+    'disposition: append',
+    '---',
+    '# Goal',
+    '',
+    'Extend the chain.',
+    '',
+  ].join('\n');
+
+  const { frontmatter, body } = parsePrdFile(raw);
+  expect(frontmatter.disposition).toBe('append');
+  expect(serializePrdFile(frontmatter, body)).toBe(raw);
+});
+
+test('parsePrdFile parses disposition: new-head', () => {
+  const raw = [
+    '---',
+    'title: A parallel wave',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 20',
+    'disposition: new-head',
+    '---',
+    'body',
+    '',
+  ].join('\n');
+
+  const { frontmatter } = parsePrdFile(raw);
+  expect(frontmatter.disposition).toBe('new-head');
+});
+
+test('parsePrdFile leaves disposition unset for an unrecognized value rather than throwing', () => {
+  const raw = [
+    '---',
+    'title: A hand-edited PRD',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 20',
+    'disposition: sideways',
+    '---',
+    'body',
+    '',
+  ].join('\n');
+
+  const { frontmatter } = parsePrdFile(raw);
+  expect(frontmatter.disposition).toBeUndefined();
+});
+
+test('parsePrdFile leaves disposition undefined when omitted — a PRD authored before this field existed round-trips unaffected', () => {
+  const raw = [
+    '---',
+    'title: An older PRD',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 10',
+    '---',
+    '# Goal',
+    '',
+    'Do the thing.',
+    '',
+  ].join('\n');
+
+  const { frontmatter, body } = parsePrdFile(raw);
+  expect(frontmatter.disposition).toBeUndefined();
+  expect(serializePrdFile(frontmatter, body)).toBe(raw);
+});
+
+test('serializePrdFile emits a newly-set disposition onto a frontmatter object that lacked one', () => {
+  const raw = [
+    '---',
+    'title: Legacy PRD',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 5',
+    '---',
+    'body',
+    '',
+  ].join('\n');
+
+  const { frontmatter, body } = parsePrdFile(raw);
+  const updated = serializePrdFile({ ...frontmatter, disposition: 'new-head' }, body);
+  expect(updated).toContain('disposition: new-head');
+});
+
+test('serializePrdFile patches an existing disposition (promoting append to new-head)', () => {
+  const raw = [
+    '---',
+    'title: A second wave',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 20',
+    'dependsOn: [widget-base]',
+    'disposition: append',
+    '---',
+    'body',
+    '',
+  ].join('\n');
+
+  const { frontmatter, body } = parsePrdFile(raw);
+  const updated = serializePrdFile({ ...frontmatter, dependsOn: [], disposition: 'new-head' }, body);
+  expect(updated).toContain('disposition: new-head');
+  expect(updated).not.toContain('dependsOn');
+});