claude-code-session-manager 0.85.0 → 0.87.0

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

@@ -0,0 +1,162 @@
+/**
+ * needsReviewLedger.test.cjs — unit tests for src/main/lib/needsReviewLedger.cjs's
+ * pure ladder-rung classification, line builders, and rollup reduction.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/needsReviewLedger.test.cjs
+ */
+'use strict';
+
+import { test, expect } from 'vitest';
+const {
+  LADDER_RUNGS,
+  classifyLadderRung,
+  buildNeedsReviewEntryLine,
+  buildNeedsReviewResolutionLine,
+  reduceNeedsReviewLedger,
+} = require('../lib/needsReviewLedger.cjs');
+
+// ---------- classifyLadderRung ----------
+
+test('classifyLadderRung maps every known automated source to its named rung', () => {
+  expect(classifyLadderRung({ source: 'scheduler:mechanicalRecovery' })).toBe('mechanical-recovery');
+  expect(classifyLadderRung({ source: 'spawnJob:dispatch', reason: 'dispatched for resume-recovery' })).toBe('resume-recovery');
+  expect(classifyLadderRung({ source: 'spawnInvestigation:start' })).toBe('auto-fix');
+  expect(classifyLadderRung({ source: 'spawnJob:auto-promote' })).toBe('auto-fix');
+  expect(classifyLadderRung({ source: 'reverifyNeedsReview:auto-promote' })).toBe('auto-fix');
+  expect(classifyLadderRung({ source: 'reverifyNeedsReview:heal' })).toBe('reverify');
+  expect(classifyLadderRung({ source: 'needsReviewAutoResolve' })).toBe('reverify');
+});
+
+test('classifyLadderRung: ordinary spawnJob:dispatch (no resume-recovery reason) is NOT resume-recovery', () => {
+  // 'spawnJob:dispatch' is shared with the everyday pending->running dispatch
+  // — only the resume-recovery REASON text distinguishes the two.
+  expect(classifyLadderRung({ source: 'spawnJob:dispatch', reason: 'dispatched for execution' })).toBe('manual-reset');
+});
+
+test('classifyLadderRung: unrecognized/explicit-reset sources default to manual-reset', () => {
+  expect(classifyLadderRung({ source: 'ipc:schedule:reset-job' })).toBe('manual-reset');
+  expect(classifyLadderRung({ source: 'remote:resetJob' })).toBe('manual-reset');
+  expect(classifyLadderRung({ source: 'clear-queue' })).toBe('manual-reset');
+  expect(classifyLadderRung({})).toBe('manual-reset');
+});
+
+test('LADDER_RUNGS names exactly the 6 documented rungs', () => {
+  expect(LADDER_RUNGS).toEqual(['mechanical-recovery', 'resume-recovery', 'quarantine', 'auto-fix', 'reverify', 'manual-reset']);
+});
+
+// ---------- buildNeedsReviewEntryLine / buildNeedsReviewResolutionLine ----------
+
+test('buildNeedsReviewEntryLine: park reason prefers verifierVerdict, then heldReason, then error', () => {
+  const entry = { to: 'needs_review', source: 'spawnJob:finalize', at: '2026-09-13T00:00:00.000Z' };
+  expect(buildNeedsReviewEntryLine({ slug: 's1', verifierVerdict: 'uncommitted_changes', heldReason: 'held', error: 'err' }, entry).reason).toBe('uncommitted_changes');
+  expect(buildNeedsReviewEntryLine({ slug: 's1', heldReason: 'held', error: 'err' }, entry).reason).toBe('held');
+  expect(buildNeedsReviewEntryLine({ slug: 's1', error: 'err' }, entry).reason).toBe('err');
+  expect(buildNeedsReviewEntryLine({ slug: 's1' }, entry).reason).toBeNull();
+});
+
+test('buildNeedsReviewEntryLine: carries slug/cwd/epicId/runId/at/source verbatim', () => {
+  const job = { slug: '42-x', cwd: '/proj', epicId: 'epic-1', runId: 'run-9' };
+  const entry = { to: 'needs_review', source: 'spawnJob:finalize', at: '2026-09-13T00:00:00.000Z' };
+  const line = buildNeedsReviewEntryLine(job, entry);
+  expect(line).toEqual({
+    kind: 'needs_review_entry',
+    slug: '42-x',
+    cwd: '/proj',
+    epicId: 'epic-1',
+    runId: 'run-9',
+    at: '2026-09-13T00:00:00.000Z',
+    reason: null,
+    source: 'spawnJob:finalize',
+  });
+});
+
+test('buildNeedsReviewResolutionLine: references the EPISODE runId, not job.runId, and computes dwellMs', () => {
+  const job = { slug: '42-x', cwd: '/proj', epicId: 'epic-1', runId: 'run-LATER' };
+  const entry = { to: 'completed', source: 'reverifyNeedsReview:heal', at: '2026-09-13T00:10:00.000Z' };
+  const episode = { runId: 'run-ORIGINAL', enteredAt: '2026-09-13T00:00:00.000Z' };
+  const line = buildNeedsReviewResolutionLine(job, entry, episode);
+  expect(line.runId).toBe('run-ORIGINAL');
+  expect(line.resolvedTo).toBe('completed');
+  expect(line.ladderRung).toBe('reverify');
+  expect(line.dwellMs).toBe(10 * 60_000);
+});
+
+test('buildNeedsReviewResolutionLine: dwellMs is null when the episode has no enteredAt (defensive — should not happen in practice)', () => {
+  const job = { slug: '42-x', runId: 'run-1' };
+  const entry = { to: 'failed', source: 'ipc:schedule:reset-job', at: '2026-09-13T00:00:00.000Z' };
+  const line = buildNeedsReviewResolutionLine(job, entry, { runId: 'run-1', enteredAt: null });
+  expect(line.dwellMs).toBeNull();
+});
+
+// ---------- reduceNeedsReviewLedger ----------
+
+function entryLine({ slug, runId, at, reason = 'uncommitted_changes', source = 'spawnJob:finalize' }) {
+  return { kind: 'needs_review_entry', slug, cwd: null, epicId: null, runId, at, reason, source };
+}
+function resolutionLine({ slug, runId, at, resolvedTo = 'completed', ladderRung = 'reverify', source = 'reverifyNeedsReview:heal', dwellMs = 1000 }) {
+  return { kind: 'needs_review_resolution', slug, cwd: null, epicId: null, runId, at, resolvedTo, ladderRung, source, dwellMs };
+}
+
+test('reduceNeedsReviewLedger: entry-only (unresolved) episode counts toward byReason and unresolvedCount, not byLadderRung', () => {
+  const lines = [entryLine({ slug: 'a', runId: 'r1', at: '2026-09-13T00:00:00.000Z', reason: 'silent_no_op' })];
+  const rollup = reduceNeedsReviewLedger(lines);
+  expect(rollup.byReason).toEqual({ silent_no_op: 1 });
+  expect(rollup.byLadderRung).toEqual({});
+  expect(rollup.unresolvedCount).toBe(1);
+  expect(rollup.dwellMsP50).toBeNull();
+  expect(rollup.dwellMsP90).toBeNull();
+});
+
+test('reduceNeedsReviewLedger: entry+resolution pair resolves and contributes dwell', () => {
+  const lines = [
+    entryLine({ slug: 'a', runId: 'r1', at: '2026-09-13T00:00:00.000Z' }),
+    resolutionLine({ slug: 'a', runId: 'r1', at: '2026-09-13T00:00:05.000Z', dwellMs: 5000, ladderRung: 'mechanical-recovery' }),
+  ];
+  const rollup = reduceNeedsReviewLedger(lines);
+  expect(rollup.unresolvedCount).toBe(0);
+  expect(rollup.byLadderRung).toEqual({ 'mechanical-recovery': 1 });
+  expect(rollup.dwellMsP50).toBe(5000);
+  expect(rollup.dwellMsP90).toBe(5000);
+});
+
+test('reduceNeedsReviewLedger: repeated entries for the same slug (different runIds) count as independent episodes', () => {
+  const lines = [
+    entryLine({ slug: 'a', runId: 'r1', at: '2026-09-13T00:00:00.000Z', reason: 'uncommitted_changes' }),
+    resolutionLine({ slug: 'a', runId: 'r1', at: '2026-09-13T00:00:10.000Z', dwellMs: 10_000, ladderRung: 'manual-reset' }),
+    entryLine({ slug: 'a', runId: 'r2', at: '2026-09-13T01:00:00.000Z', reason: 'uncommitted_changes' }),
+    // r2 never resolves.
+  ];
+  const rollup = reduceNeedsReviewLedger(lines);
+  expect(rollup.byReason).toEqual({ uncommitted_changes: 2 });
+  expect(rollup.unresolvedCount).toBe(1);
+  expect(rollup.byLadderRung).toEqual({ 'manual-reset': 1 });
+  expect(rollup.dwellMsP50).toBe(10_000);
+});
+
+test('reduceNeedsReviewLedger: p50/p90 over several resolved episodes', () => {
+  const dwells = [1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10_000];
+  const lines = dwells.flatMap((d, i) => [
+    entryLine({ slug: `s${i}`, runId: `r${i}`, at: '2026-09-13T00:00:00.000Z' }),
+    resolutionLine({ slug: `s${i}`, runId: `r${i}`, at: '2026-09-13T00:00:00.000Z', dwellMs: d }),
+  ]);
+  const rollup = reduceNeedsReviewLedger(lines);
+  expect(rollup.dwellMsP50).toBe(5000);
+  expect(rollup.dwellMsP90).toBe(9000);
+});
+
+test('reduceNeedsReviewLedger: ignores unrelated (terminal) rows mixed into the same lines array', () => {
+  const lines = [
+    { kind: 'terminal', slug: 'a', status: 'completed', runId: 'r1' },
+    { slug: 'b', status: 'failed', runId: 'r2' }, // legacy row, no kind at all
+    entryLine({ slug: 'c', runId: 'r3', at: '2026-09-13T00:00:00.000Z' }),
+  ];
+  const rollup = reduceNeedsReviewLedger(lines);
+  expect(rollup.unresolvedCount).toBe(1);
+  expect(Object.keys(rollup.byReason)).toEqual(['uncommitted_changes']);
+});
+
+test('reduceNeedsReviewLedger: empty/non-array input returns a zeroed rollup, never throws', () => {
+  expect(reduceNeedsReviewLedger([])).toEqual({ byReason: {}, byLadderRung: {}, unresolvedCount: 0, dwellMsP50: null, dwellMsP90: null });
+  expect(reduceNeedsReviewLedger(null)).toEqual({ byReason: {}, byLadderRung: {}, unresolvedCount: 0, dwellMsP50: null, dwellMsP90: null });
+  expect(reduceNeedsReviewLedger(undefined)).toEqual({ byReason: {}, byLadderRung: {}, unresolvedCount: 0, dwellMsP50: null, dwellMsP90: null });
+});

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

@@ -24,7 +24,7 @@ afterEach(async () => {
   if (originalSmTelemetrySpool === undefined) delete process.env.SM_TELEMETRY_SPOOL; else process.env.SM_TELEMETRY_SPOOL = originalSmTelemetrySpool;
   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();
@@ -89,8 +89,8 @@ test('an ephemeral cwd yields zero local lines but one telemetry record, with a
   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,

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

@@ -73,10 +73,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,
   });

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

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

@@ -7,12 +7,17 @@
 
 'use strict';
 
-import { test, expect, afterEach } from 'vitest';
+import { test, expect, afterEach, vi } from 'vitest';
 const fs = require('node:fs');
 const fsp = require('node:fs/promises');
 const os = require('node:os');
 const path = require('node:path');
-const { resolvePrdWriteDir, resolvePrdsDirs } = require('../lib/prdLocations.cjs');
+const {
+  resolvePrdWriteDir,
+  resolvePrdsDirs,
+  resolveEpicPrdWriteDir,
+  listEpicPrdDirs,
+} = require('../lib/prdLocations.cjs');
 
 const tmpDirs = [];
 afterEach(async () => {
@@ -95,3 +100,96 @@ test('resolvePrdsDirs returns [] when no project has a recent transcript', () =>
   const dirs = resolvePrdsDirs(90, { projectsDir: '/nonexistent-projects-dir' });
   expect(dirs).toEqual([]);
 });
+
+test('listEpicPrdDirs memoizes on the Epics-root mtime: no readdir on a repeat call, but a freshly minted Epic prds dir is picked up on the very next call', async () => {
+  const cwd = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-memo-cwd-'));
+  tmpDirs.push(cwd);
+  fs.mkdirSync(resolveEpicPrdWriteDir(cwd, 'epic-1'), { recursive: true });
+
+  const first = listEpicPrdDirs(cwd);
+  expect(first).toEqual([resolveEpicPrdWriteDir(cwd, 'epic-1')]);
+
+  const readdirSpy = vi.spyOn(fs, 'readdirSync');
+  try {
+    // Nothing under the Epics root changed — the cached result comes back
+    // without a fresh readdir of the Epics root.
+    const second = listEpicPrdDirs(cwd);
+    expect(second).toEqual(first);
+    expect(readdirSpy).not.toHaveBeenCalled();
+  } finally {
+    readdirSpy.mockRestore();
+  }
+
+  // A brand-new Epic's prds/ dir is a NEW entry under the Epics root, which
+  // bumps the root's own mtime — no TTL wait required to see it.
+  fs.mkdirSync(resolveEpicPrdWriteDir(cwd, 'epic-2'), { recursive: true });
+  const third = listEpicPrdDirs(cwd);
+  expect(third).toEqual(
+    expect.arrayContaining([resolveEpicPrdWriteDir(cwd, 'epic-1'), resolveEpicPrdWriteDir(cwd, 'epic-2')]),
+  );
+});
+
+test('listEpicPrdDirs: an unreadable Epics root does not write a poisoned entry that survives the dir becoming readable', async () => {
+  const cwd = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-unreadable-cwd-'));
+  tmpDirs.push(cwd);
+
+  // No Epics root at all yet.
+  expect(listEpicPrdDirs(cwd)).toEqual([]);
+
+  // The root now exists, with a real Epic prds dir inside it.
+  fs.mkdirSync(resolveEpicPrdWriteDir(cwd, 'epic-1'), { recursive: true });
+  expect(listEpicPrdDirs(cwd)).toEqual([resolveEpicPrdWriteDir(cwd, 'epic-1')]);
+});
+
+test('resolvePrdsDirs EDGE (non-negotiable): a new epics/<id>/prds dir created after a prior call is visible on the VERY NEXT call, no TTL wait', async () => {
+  const projectsDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-freshness-projects-'));
+  tmpDirs.push(projectsDir);
+  const projectCwd = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-freshness-cwd-'));
+  tmpDirs.push(projectCwd);
+
+  const projDir = path.join(projectsDir, 'freshness-project');
+  fs.mkdirSync(projDir, { recursive: true });
+  fs.writeFileSync(path.join(projDir, 'session1.jsonl'), `${JSON.stringify({ cwd: projectCwd })}\n`);
+
+  const before = resolvePrdsDirs(90, { projectsDir });
+  const newEpicPrdDir = resolveEpicPrdWriteDir(projectCwd, 'freshly-minted-epic');
+  expect(before).not.toContain(newEpicPrdDir);
+
+  fs.mkdirSync(newEpicPrdDir, { recursive: true });
+
+  const after = resolvePrdsDirs(90, { projectsDir });
+  expect(after).toContain(newEpicPrdDir);
+});
+
+test('resolvePrdsDirs: calls with an explicit { projectsDir } opts are keyed separately per projectsDir and never share a stale cache entry', async () => {
+  const projectsDirA = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-keyed-a-'));
+  tmpDirs.push(projectsDirA);
+  const projectsDirB = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-keyed-b-'));
+  tmpDirs.push(projectsDirB);
+  const cwdA = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-keyed-cwd-a-'));
+  tmpDirs.push(cwdA);
+  const cwdB = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-keyed-cwd-b-'));
+  tmpDirs.push(cwdB);
+
+  const projDirA = path.join(projectsDirA, 'proj-a');
+  fs.mkdirSync(projDirA, { recursive: true });
+  fs.writeFileSync(path.join(projDirA, 'session1.jsonl'), `${JSON.stringify({ cwd: cwdA })}\n`);
+  fs.mkdirSync(resolvePrdWriteDir(cwdA), { recursive: true });
+
+  const projDirB = path.join(projectsDirB, 'proj-b');
+  fs.mkdirSync(projDirB, { recursive: true });
+  fs.writeFileSync(path.join(projDirB, 'session1.jsonl'), `${JSON.stringify({ cwd: cwdB })}\n`);
+  fs.mkdirSync(resolvePrdWriteDir(cwdB), { recursive: true });
+
+  const dirsA = resolvePrdsDirs(90, { projectsDir: projectsDirA });
+  const dirsB = resolvePrdsDirs(90, { projectsDir: projectsDirB });
+
+  expect(dirsA).toContain(resolvePrdWriteDir(cwdA));
+  expect(dirsA).not.toContain(resolvePrdWriteDir(cwdB));
+  expect(dirsB).toContain(resolvePrdWriteDir(cwdB));
+  expect(dirsB).not.toContain(resolvePrdWriteDir(cwdA));
+
+  // Re-querying A after B was resolved must still reflect A's own state, not
+  // B's — proof the two opts objects never shared one cache key.
+  expect(resolvePrdsDirs(90, { projectsDir: projectsDirA })).toEqual(dirsA);
+});