claude-code-session-manager 0.39.3 → 0.40.0

package/dist/index.html

@@ -7,10 +7,10 @@
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Newsreader:ital,opsz,wght@0,6..72,400;0,6..72,500;0,6..72,600;0,6..72,700;1,6..72,400&family=Geist:wght@300;400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
-    <script type="module" crossorigin src="./assets/index-BUuhV6vT.js"></script>
+    <script type="module" crossorigin src="./assets/index-oMNYp73N.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/monaco-editor-BW5C4Iv1.js">
     <link rel="stylesheet" crossorigin href="./assets/monaco-editor-BTnBOi8r.css">
-    <link rel="stylesheet" crossorigin href="./assets/index-DVlD8N1X.css">
+    <link rel="stylesheet" crossorigin href="./assets/index-CR-WdMgm.css">
   </head>
   <body class="bg-bg text-fg font-sans antialiased">
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-session-manager",
-  "version": "0.39.3",
+  "version": "0.40.0",
   "description": "Local cockpit for the Claude Code CLI — multi-tab terminal, full config surface, scheduler, voice dictation, and live observability.",
   "type": "module",
   "main": "src/main/index.cjs",

package/plugins/session-manager-dev/skills/develop/SKILL.md

@@ -77,7 +77,7 @@ can't load skills.
    do they actually share the same shape, or only look similar — confirm by reading, don't
    assume: a wrong assumption here means an inaccurate PRD, discovered only after the executor
    runs it), check existing tests for the area, and check whether a prior PRD already touched
-   this subsystem (`ls <cwd>/session-manager-operations/scheduler/prds/` for related slugs, in
+   this subsystem (`ls <cwd>/session-manager-operations/scheduler/epics/*/prds/` for related slugs, in
    the target repo) — duplicating or contradicting a still-queued PRD is a real failure mode,
    not a hypothetical one.
 
@@ -161,8 +161,9 @@ can't load skills.
    - **Evolving chain (3-5 PRDs).** Use this shape when the request is naturally a sequence of
      stages that build on each other rather than independent units — e.g. scaffold → core
      behavior → edge-case/interaction hardening → integration wiring → UI validation pass. Each
-     PRD in the chain: gets the **next sequential `NN`** (never the same `NN` as the PRD it
-     depends on — same-`NN` means "can run in parallel," which a chain link cannot), and its
+     PRD in the chain: gets its own unique `NN` (numbers are strictly unique per project —
+     PRD 832, user decision 2026-07-31) plus a `dependsOn: [<previous-link-slug>]`
+     frontmatter line expressing the chain edge explicitly, and its
      `# Implementation notes` states in one line what the *previous* link actually delivered
      (file paths/functions it added, referencing its real landed state — not the plan for it,
      since PRDs 1..k-1 may have adjusted scope during execution) and what this link is expected
@@ -184,11 +185,11 @@ can't load skills.
    (`mcp__session-manager-scheduler__scheduler_create_prd`) over hand-writing the file. Its input
    (`title`, `cwd`, `estimateMinutes`, `goal`, `acceptanceCriteria[]`, `implementationNotes`,
    `outOfScope[]`) maps directly onto the sections below — pass them straight through. It
-   allocates the parallel-group `NN` atomically (no read-then-write race against another
-   concurrent `/develop`/`/process-feedback` invocation), derives and collision-checks the slug,
-   and embeds the standards pointer for you. Set `parallelGroup` explicitly only when this PRD
-   must share an existing sibling's `NN` (a logically independent PRD that can run in parallel
-   with one already queued); omit it to get the next free `NN` atomically.
+   allocates a strictly-unique `NN` atomically (no read-then-write race against another
+   concurrent `/develop`/`/process-feedback` invocation, never reused across the project — PRD
+   832), derives and collision-checks the slug, and embeds the standards pointer for you.
+   `parallelGroup` is DEPRECATED and ignored — express ordering with the `dependsOn` input
+   (slugs that must complete first); independent PRDs simply omit it and may run in parallel.
 
    **Fallback — only when the tool errors with "app not running" / admin API unreachable**
    (the session-manager Electron app must be running for this MCP tool to work; if it isn't,
@@ -197,12 +198,12 @@ can't load skills.
    and collides). PRDs are stored per-project, so `NN` allocation for a given PRD only needs
    *that project's own* prds directory scanned — not every project's:
    ```bash
-   ls <cwd>/session-manager-operations/scheduler/prds/ | grep -oE '^[0-9]+' | sort -n | uniq | tail -5
+   ls <cwd>/session-manager-operations/scheduler/epics/*/prds/ <cwd>/session-manager-operations/scheduler/prds-archived/ 2>/dev/null | grep -oE '^[0-9]+' | sort -n | uniq | tail -5
    ```
    (`<cwd>` is the target repo's absolute path — the same one this PRD's `cwd` field will use.)
-   The last line is the current max within that project. Then: same `NN` as a logically
-   independent sibling that can run in parallel; **next free `NN` = max+1** when this PRD
-   hard-depends on prior work or is unrelated to every existing group. This manual path has a
+   The last line is the current max within that project. Then: **always next free `NN` =
+   max+1** — never reuse a sibling's number (unique-per-project rule, PRD 832); express
+   ordering with `dependsOn: [<slug>]` frontmatter instead. This manual path has a
    small, accepted race (two concurrent authors could compute the same "next free" `NN`) —
    cosmetic (two unrelated groups end up sharing a number) rather than destructive, and only
    reachable when the atomic tool path above isn't available. Record each cross-PRD dependency
@@ -218,23 +219,29 @@ can't load skills.
    system that runs `claude -p <prd-body> --dangerously-skip-permissions` jobs around 5-hour
    token-window resets, with auto-pause on rate-limit and auto-resume.
 
-   **Canonical location — non-negotiable.** PRDs MUST be written to, inside the target repo:
+   **Canonical location — non-negotiable.** Every PRD belongs to an **Epic** (the TAB → EPIC →
+   PRD domain model in the project CLAUDE.md). PRDs MUST be written to, inside the target repo:
    ```
-   <cwd>/session-manager-operations/scheduler/prds/<NN>-<kebab-slug>.md
+   <cwd>/session-manager-operations/scheduler/epics/<epic-id>/prds/<NN>-<kebab-slug>.md
    ```
-   **Anywhere else doesn't get scheduled.** If you write to `data/prds/`, `docs/prds/`, or the
-   old, now-retired global `prds/` dir under `~/.claude/session-manager/scheduled-plans/`,
-   the scheduler will not see it and the user loses their token-budget-managed execution. PRD
-   *source* files are per-project — each active project's own
-   `session-manager-operations/scheduler/prds/` directory, resolved at runtime from active
-   session cwds (`src/main/lib/prdLocations.cjs`) — but there is still exactly one **queue**
-   across all projects (`queue.json`/`history.jsonl`/`runs/` under
-   `~/.claude/session-manager/scheduled-plans/` remain global bookkeeping), because the 5-hour
-   token budget is global across all of the user's Claude work.
-
-   **Filename rules.** `NN` is the 2-digit zero-padded parallel group (picked per the `ls`
-   command above — same `NN` as an independent sibling, or next free `NN` = max+1 when this PRD
-   hard-depends on prior work). `<kebab-slug>` is a short, descriptive kebab-case identifier
+   Get `<epic-id>`'s prds/ directory by minting (or joining) an Epic first:
+   ```bash
+   node <session-manager-repo>/scripts/mint-epic.cjs <cwd> "<one-line goal for this work>" [feature|bug|discussion]
+   ```
+   The last stdout line is the exact directory to write into. Reuse-by-goal makes it idempotent —
+   all PRDs of one /develop ask share one Epic. (The MCP `scheduler_create_prd` tool does all of
+   this automatically; the mint step is only for the manual-write fallback.)
+
+   **Anywhere else doesn't get scheduled or gets retired.** `data/prds/`, `docs/prds/`, and the
+   old global `prds/` dir under `~/.claude/session-manager/scheduled-plans/` are invisible to
+   the scheduler; the legacy flat `session-manager-operations/scheduler/prds/` dir is RETIRED —
+   anything written there is auto-consolidated into `prds-archived/` at the next app boot
+   without being executed. PRD *source* files are per-project and per-Epic, resolved at runtime
+   via `src/main/lib/prdLocations.cjs`.
+
+   **Filename rules.** `NN` is the PRD's unique per-project number (always next free =
+   max+1 per the `ls` command above; ordering via `dependsOn` frontmatter, never via shared
+   numbers). `<kebab-slug>` is a short, descriptive kebab-case identifier
    (e.g. `voice-commands-send-cancel`, `ticker-velocity-mcp`), kept under 60 chars. Verify your
    chosen filename doesn't already exist before writing.
 

package/scripts/lib/watchdogHelpers.cjs

@@ -8,7 +8,9 @@ const os = require('node:os');
 const path = require('node:path');
 
 const { activeProjectCwds } = require('./activeSessions.cjs');
-const { resolvePrdWriteDir } = require('../../src/main/lib/prdLocations.cjs');
+const { resolvePrdWriteDir, listEpicPrdDirs } = require('../../src/main/lib/prdLocations.cjs');
+const { ensureEpic, appendPrdCreatedEvent } = require('../../src/main/lib/epicMint.cjs');
+const { projectQueuePath } = require('../../src/main/lib/queueStore.cjs');
 
 // Mirrors scheduler.cjs:215 (single source of truth there; kept in sync here).
 const DEFAULT_HEARTBEAT_PATH = path.join(
@@ -294,7 +296,7 @@ function hasOpenFeedback(cwd) {
  */
 function emitFeedbackPRD(cwd, {
   prdsDir,
-  queuePath = DEFAULT_QUEUE_PATH,
+  queuePath,
   skillPath,
   standardsPath,
   pluginCacheRoot = PLUGIN_CACHE_ROOT,
@@ -306,8 +308,18 @@ function emitFeedbackPRD(cwd, {
   // PRD dir so the sweep writer agrees with scheduler.cjs's reader (see
   // prdLocations.cjs — PRD chain 808→811 moved PRD sources out of the legacy
   // global dir into `<cwd>/session-manager-operations/scheduler/prds`).
+  let epicId = null;
   if (prdsDir === undefined) {
-    prdsDir = resolvePrdWriteDir(cwd);
+    // Every PRD belongs to an Epic (CLAUDE.md domain model). The sweep joins
+    // one standing "Inbound feedback" Epic per project (reuseByGoal) so
+    // recurring ticks chain into a single Epic rather than minting one each.
+    const epic = ensureEpic(cwd, {
+      goalText: 'Inbound feedback processing',
+      tag: 'discussion',
+      reuseByGoal: true,
+    });
+    epicId = epic.epicId;
+    prdsDir = epic.prdDir;
   }
   const skillPathExplicit = skillPath !== undefined;
   const standardsPathExplicit = standardsPath !== undefined;
@@ -319,11 +331,20 @@ function emitFeedbackPRD(cwd, {
   }
   const project = slugify(path.basename(cwd));
 
-  // De-dup: check queue.json for pending/running feedback job for this project.
-  let queueState = { jobs: [] };
-  try {
-    queueState = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
-  } catch { /* queue.json may not exist */ }
+  // De-dup: check the queue for a pending/running feedback job for this
+  // project. Federated state (2026-07-31): the project's own shard is the
+  // system of record; the legacy global path is still consulted as a fallback
+  // during transition. An explicit queuePath override (tests) wins verbatim.
+  const queuePaths = queuePath !== undefined
+    ? [queuePath]
+    : [projectQueuePath(cwd), DEFAULT_QUEUE_PATH];
+  const queueState = { jobs: [] };
+  for (const qp of queuePaths) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(qp, 'utf8'));
+      queueState.jobs.push(...(Array.isArray(parsed.jobs) ? parsed.jobs : []));
+    } catch { /* file may not exist */ }
+  }
 
   // project only contains [a-z0-9-] after slugify — no regex metachar escaping needed.
   const dupRe = new RegExp(`^\\d+-feedback-${project}$`);
@@ -341,18 +362,28 @@ function emitFeedbackPRD(cwd, {
   // watchdog tick emits a fresh NN-feedback-<project>.md, unbounded.
   const prdDupRe = new RegExp(`^\\d+-feedback-${project}\\.md$`);
   let maxNN = 0;
-  let prdFiles = [];
-  try {
-    prdFiles = fs.readdirSync(prdsDir);
-  } catch { /* prdsDir may not exist yet */ }
-  for (const f of prdFiles) {
-    if (prdDupRe.test(f)) {
-      return { emitted: false, reason: 'duplicate' };
-    }
-    const m = f.match(/^(\d+)-/);
-    if (m) {
-      const n = parseInt(m[1], 10);
-      if (n > maxNN) maxNN = n;
+  // NN numbering and the on-disk dedup are project-global, so scan every PRD
+  // location the project has: the write dir, the legacy flat dir, and every
+  // Epic's prds/ dir. (An explicit prdsDir override — tests — scans only it.)
+  const scanDirs = new Set([prdsDir]);
+  if (epicId !== null) {
+    try { scanDirs.add(resolvePrdWriteDir(cwd)); } catch { /* unusable cwd */ }
+    for (const d of listEpicPrdDirs(cwd)) scanDirs.add(d);
+  }
+  for (const dir of scanDirs) {
+    let prdFiles = [];
+    try {
+      prdFiles = fs.readdirSync(dir);
+    } catch { continue; /* dir may not exist yet */ }
+    for (const f of prdFiles) {
+      if (prdDupRe.test(f)) {
+        return { emitted: false, reason: 'duplicate' };
+      }
+      const m = f.match(/^(\d+)-/);
+      if (m) {
+        const n = parseInt(m[1], 10);
+        if (n > maxNN) maxNN = n;
+      }
     }
   }
   const nn = String(maxNN + 1).padStart(2, '0');
@@ -440,6 +471,11 @@ function emitFeedbackPRD(cwd, {
     fs.mkdirSync(prdsDir, { recursive: true });
     fs.writeFileSync(tmpPath, body + '\n', 'utf8');
     fs.renameSync(tmpPath, prdPath);
+    if (epicId !== null) {
+      // Trace the dispatch on the Epic's event chain (prompt → prd_created →
+      // ...) so the Epic conversation shows the PRD it spawned.
+      try { appendPrdCreatedEvent(cwd, epicId, slug, `Feedback sweep emitted ${slug}`); } catch { /* trace is best-effort */ }
+    }
   } catch (e) {
     try { fs.unlinkSync(tmpPath); } catch { /* best-effort cleanup */ }
     throw e;
@@ -622,7 +658,7 @@ function maybeRelaunchApp({
 function sweep({
   projectsDir,
   prdsDir,
-  queuePath = DEFAULT_QUEUE_PATH,
+  queuePath,
   skillPath,
   standardsPath,
 } = {}) {

package/src/main/__tests__/health-prd-migration.test.cjs

@@ -0,0 +1,37 @@
+/**
+ * health-prd-migration.test.cjs — stranded-PRD-migration health signal
+ * (behind two real 2026-07-31 incidents: a single stranded PRD causing an
+ * instant ENOENT job failure, and 223 stranded legacy PRDs + a missing
+ * history.jsonl resurrecting 189 completed jobs). Exercises
+ * evaluatePrdMigrationHealth() directly since it's pure — no need to spawn
+ * the full check() (which shells out to npm run typecheck) to cover this.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/health-prd-migration.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const { evaluatePrdMigrationHealth } = require('../health.cjs');
+
+const LEGACY_DIR = '/home/user/.claude/session-manager/scheduled-plans/prds';
+
+test('reports ok when nothing is stranded', () => {
+  const result = evaluatePrdMigrationHealth({ moved: 3, skipped: 0, unresolved: [] }, LEGACY_DIR);
+  expect(result.ok).toBe(true);
+  expect(result.strandedCount).toBe(0);
+  expect(result.legacyDir).toBe(LEGACY_DIR);
+  expect(result.unresolved).toBeUndefined();
+});
+
+test('reports RED with count and legacy dir path when files are stranded', () => {
+  const unresolved = [
+    { file: '01-stuck.md', reason: 'no cwd in frontmatter' },
+    { file: '02-stuck.md', reason: 'cwd does not exist on disk' },
+  ];
+  const result = evaluatePrdMigrationHealth({ moved: 0, skipped: 0, unresolved }, LEGACY_DIR);
+  expect(result.ok).toBe(false);
+  expect(result.strandedCount).toBe(2);
+  expect(result.legacyDir).toBe(LEGACY_DIR);
+  expect(result.unresolved).toEqual(unresolved);
+});

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

@@ -307,7 +307,7 @@ test('POST /admin/scheduler/create-prd rejects a title containing a newline (fro
   }
 });
 
-test('POST /admin/scheduler/create-prd with an explicit parallelGroup+slug that already exists on disk returns 409 and does not clobber the file', async () => {
+test('PRD 832: an explicit parallelGroup colliding with an existing file is ignored — a fresh unique NN is allocated and nothing is clobbered', async () => {
   const prdsDir = await mkTmpPrdsDir();
   const remote = makeFakeRemoteWithPrdsDir(prdsDir);
   const { admin, port, token } = await startWithRemote(remote);
@@ -317,17 +317,18 @@ test('POST /admin/scheduler/create-prd with an explicit parallelGroup+slug that
       method: 'POST', path: '/admin/scheduler/create-prd', token,
       body: validCreateBody({ slug: 'my-explicit-slug', parallelGroup: 777 }),
     });
-    expect(res.status).toBe(409);
-    expect(res.json.ok).toBe(false);
+    expect(res.status).toBe(200);
+    // Allocator scans past the existing 777 — unique per project, never reused.
+    expect(res.json.nn).toBe(778);
+    expect(res.json.filename).toBe('778-my-explicit-slug.md');
     const stillThere = await fsp.readFile(path.join(prdsDir, '777-my-explicit-slug.md'), 'utf8');
-    // existing PRD file must not be overwritten
     expect(stillThere).toBe('ORIGINAL CONTENT\n');
   } finally {
     await admin.stop();
   }
 });
 
-test('POST /admin/scheduler/create-prd honors an explicit slug + parallelGroup instead of deriving/allocating', async () => {
+test('PRD 832: explicit parallelGroup input is deprecated and ignored — NN always comes from the allocator', async () => {
   const prdsDir = await mkTmpPrdsDir();
   const remote = makeFakeRemoteWithPrdsDir(prdsDir);
   const { admin, port, token } = await startWithRemote(remote);
@@ -337,9 +338,9 @@ test('POST /admin/scheduler/create-prd honors an explicit slug + parallelGroup i
       body: validCreateBody({ slug: 'my-explicit-slug', parallelGroup: 777 }),
     });
     expect(res.status).toBe(200);
-    expect(res.json.nn).toBe(777);
-    expect(res.json.filename).toBe('777-my-explicit-slug.md');
-    expect(fs.existsSync(path.join(prdsDir, '777-my-explicit-slug.md'))).toBeTruthy();
+    expect(res.json.nn).toBe(1);
+    expect(res.json.filename).toBe('1-my-explicit-slug.md');
+    expect(fs.existsSync(path.join(prdsDir, '1-my-explicit-slug.md'))).toBeTruthy();
   } finally {
     await admin.stop();
   }
@@ -385,17 +386,55 @@ test('createPrd with a valid payload allocates a group, writes through remote.wr
   expect(written).toMatch(/# Goal/);
 });
 
-test('createPrd returns {ok:false, status:409} without clobbering an existing file at the same destination', async () => {
+test('createPrd returns {ok:false, status:409} without clobbering when the destination already exists', async () => {
   const prdsDir = await mkTmpPrdsDir();
+  // The existence guard survives PRD 832: whatever NN the allocator picks,
+  // a pre-existing file at that exact destination must 409, never clobber.
   const remote = makeFakeRemoteWithPrdsDir(prdsDir);
-  await fsp.writeFile(path.join(prdsDir, '777-my-explicit-slug.md'), 'ORIGINAL CONTENT\n');
+  const realRead = remote.readPrd.bind(remote);
+  remote.readPrd = async (slug) => (slug.endsWith('my-explicit-slug') ? { ok: true, text: 'ORIGINAL' } : realRead(slug));
+  const writes = [];
+  const realWrite = remote.writePrd.bind(remote);
+  remote.writePrd = async (...a) => { writes.push(a[0]); return realWrite(...a); };
 
-  const result = await createPrd(validCreateBody({ slug: 'my-explicit-slug', parallelGroup: 777 }), remote);
+  const result = await createPrd(validCreateBody({ slug: 'my-explicit-slug' }), remote);
 
   expect(result.ok).toBe(false);
   expect(result.status).toBe(409);
-  const stillThere = await fsp.readFile(path.join(prdsDir, '777-my-explicit-slug.md'), 'utf8');
-  expect(stillThere).toBe('ORIGINAL CONTENT\n');
+  expect(writes).toEqual([]);
+});
+
+// ──────────────────────────────────────────── PRD 825: Epic PRD dir write grant + `~` cwd normalization
+
+test('validateWrite allows writes under <root>/session-manager-operations/scheduler/epics/<id>/prds/', async () => {
+  const root = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-scheduler-epics-'));
+  config.addAllowedRoot(root);
+  const prdsDir = path.join(root, 'session-manager-operations', 'scheduler', 'epics', 'epic-abc123', 'prds');
+  await fsp.mkdir(prdsDir, { recursive: true });
+  const filePath = path.join(prdsDir, '1-do-thing.md');
+
+  await config.writeTextAtomic(filePath, 'PRD body\n');
+
+  expect(fs.existsSync(filePath)).toBeTruthy();
+  expect(await fsp.readFile(filePath, 'utf8')).toBe('PRD body\n');
+});
+
+test('createPrd normalizes a `~`-prefixed cwd via expandHome before calling remote', async () => {
+  const receivedCwds = [];
+  const remote = {
+    async allocateParallelGroup(cwd) { receivedCwds.push(cwd); return 42; },
+    async readPrd(slug, cwd) { receivedCwds.push(cwd); return { ok: false }; },
+    async writePrd(slug, body, cwd) { receivedCwds.push(cwd); return { ok: true, bytesWritten: body.length }; },
+  };
+
+  const result = await createPrd(validCreateBody({ cwd: '~' }), remote);
+
+  expect(result.ok).toBe(true);
+  expect(receivedCwds.length).toBeGreaterThan(0);
+  for (const cwd of receivedCwds) {
+    expect(cwd.startsWith('~')).toBe(false);
+    expect(cwd).toBe(os.homedir());
+  }
 });
 
 test('POST /admin/scheduler/create-prd with sourcePromptId writes it into the created PRD frontmatter', async () => {
@@ -405,10 +444,10 @@ test('POST /admin/scheduler/create-prd with sourcePromptId writes it into the cr
   try {
     const res = await request(port, {
       method: 'POST', path: '/admin/scheduler/create-prd', token,
-      body: validCreateBody({ slug: 'from-a-ticket', parallelGroup: 888, sourcePromptId: 'ticket-xyz-789' }),
+      body: validCreateBody({ slug: 'from-a-ticket', sourcePromptId: 'ticket-xyz-789' }),
     });
     expect(res.status).toBe(200);
-    const written = fs.readFileSync(path.join(prdsDir, '888-from-a-ticket.md'), 'utf8');
+    const written = fs.readFileSync(path.join(prdsDir, `${res.json.nn}-from-a-ticket.md`), 'utf8');
     expect(written).toMatch(/sourcePromptId: ticket-xyz-789/);
   } finally {
     await admin.stop();

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

@@ -0,0 +1,118 @@
+/**
+ * prdSourcePromptIdBackfill.test.cjs — PRD 830: a PRD file's location under
+ * `.../scheduler/epics/<epicId>/prds/<slug>.md` already IS its Epic
+ * membership, so ingest should stamp `sourcePromptId = <epicId>` whenever
+ * frontmatter doesn't supply one — instead of leaving it null forever.
+ *
+ * Covers:
+ *   - deriveEpicIdFromPrdPath: pure path-shape extraction (prdLocations.cjs)
+ *   - parsePrdRaw: dir-derived stamping + frontmatter-wins precedence
+ *   - reconcileSourcePromptId: pending-only backfill (scheduler.cjs)
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/prdSourcePromptIdBackfill.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+
+const { deriveEpicIdFromPrdPath, resolveEpicPrdWriteDir } = require('../lib/prdLocations.cjs');
+const { parsePrdRaw, _resetCache } = require('../scheduler/prdParser.cjs');
+const { reconcileSourcePromptId } = require('../scheduler.cjs');
+
+async function mkProjectCwd() {
+  return fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prd-backfill-'));
+}
+
+// ---------- deriveEpicIdFromPrdPath ----------
+
+test('deriveEpicIdFromPrdPath extracts the epic id from a well-formed epic PRD path', async () => {
+  const cwd = await mkProjectCwd();
+  const epicId = 'some-epic-abc123';
+  const dir = resolveEpicPrdWriteDir(cwd, epicId);
+  await fsp.mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, '900-example.md');
+  expect(deriveEpicIdFromPrdPath(filePath)).toBe(epicId);
+});
+
+test('deriveEpicIdFromPrdPath returns null for the retired flat prds/ layout', () => {
+  const filePath = '/home/user/Projects/foo/session-manager-operations/scheduler/prds/900-example.md';
+  expect(deriveEpicIdFromPrdPath(filePath)).toBe(null);
+});
+
+test('deriveEpicIdFromPrdPath returns null for an unrelated path', () => {
+  expect(deriveEpicIdFromPrdPath('/tmp/whatever/900-example.md')).toBe(null);
+  expect(deriveEpicIdFromPrdPath(null)).toBe(null);
+});
+
+// ---------- parsePrdRaw: dir-derived stamping + frontmatter-wins ----------
+
+test('parsePrdRaw derives sourcePromptId from the parent epic dir when frontmatter omits it', async () => {
+  _resetCache();
+  const cwd = await mkProjectCwd();
+  const epicId = 'derive-me-epic-def456';
+  const dir = resolveEpicPrdWriteDir(cwd, epicId);
+  await fsp.mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, '901-hand-authored.md');
+  await fsp.writeFile(filePath, [
+    '---',
+    'title: Hand-authored, no sourcePromptId',
+    `cwd: ${cwd}`,
+    '---',
+    '# Goal',
+    '',
+    'Do the thing.',
+    '',
+  ].join('\n'));
+
+  const parsed = await parsePrdRaw(filePath);
+  expect(parsed.sourcePromptId).toBe(epicId);
+});
+
+test('parsePrdRaw: explicit frontmatter sourcePromptId wins over the dir-derived epic id', async () => {
+  _resetCache();
+  const cwd = await mkProjectCwd();
+  const epicId = 'dir-epic-ghi789';
+  const dir = resolveEpicPrdWriteDir(cwd, epicId);
+  await fsp.mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, '902-explicit.md');
+  await fsp.writeFile(filePath, [
+    '---',
+    'title: Explicit sourcePromptId',
+    `cwd: ${cwd}`,
+    'sourcePromptId: ticket-explicit-999',
+    '---',
+    '# Goal',
+    '',
+    'Do the thing.',
+    '',
+  ].join('\n'));
+
+  const parsed = await parsePrdRaw(filePath);
+  expect(parsed.sourcePromptId).toBe('ticket-explicit-999');
+});
+
+// ---------- reconcileSourcePromptId: pending-only backfill ----------
+
+test('reconcileSourcePromptId backfills a pending job whose sourcePromptId is null', () => {
+  const job = { slug: 'x', status: 'pending', sourcePromptId: null };
+  expect(reconcileSourcePromptId(job, 'epic-abc')).toBe('epic-abc');
+});
+
+test('reconcileSourcePromptId leaves a running job untouched even if its sourcePromptId is null', () => {
+  const job = { slug: 'x', status: 'running', sourcePromptId: null };
+  expect(reconcileSourcePromptId(job, 'epic-abc')).toBe(null);
+});
+
+test('reconcileSourcePromptId leaves a completed job untouched even if its sourcePromptId is null', () => {
+  const job = { slug: 'x', status: 'completed', sourcePromptId: null };
+  expect(reconcileSourcePromptId(job, 'epic-abc')).toBe(null);
+});
+
+test('reconcileSourcePromptId keeps a pending job\'s existing value if the fresh parse yields null', () => {
+  const job = { slug: 'x', status: 'pending', sourcePromptId: 'already-set' };
+  expect(reconcileSourcePromptId(job, null)).toBe('already-set');
+});

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

@@ -146,11 +146,13 @@ test('readHistory respects limit and returns [] when file is absent', async () =
   const empty = await queueHistory.readHistory({ limit: 5 });
   expect(empty).toEqual([]);
 
-  const entries = Array.from({ length: 8 }, (_, i) => old({ slug: `s${i}`, runId: `r${i}`, finishedAt: new Date(NOW - i * 60_000).toISOString() }));
+  // Realistic append order: oldest finishedAt first (append-only file grows
+  // forward in time), so s7 is both last-appended and newest.
+  const entries = Array.from({ length: 8 }, (_, i) => old({ slug: `s${i}`, runId: `r${i}`, finishedAt: new Date(NOW - (7 - i) * 60_000).toISOString() }));
   await queueHistory.appendHistory(entries);
   const read = await queueHistory.readHistory({ limit: 3 });
   expect(read.length).toBe(3);
-  // newest-appended-first == last 3 entries reversed
+  // Federated readHistory (2026-07-31) orders by finishedAt newest-first.
   expect(read.map((j) => j.slug)).toEqual(['s7', 's6', 's5']);
 });
 
@@ -165,8 +167,11 @@ test('readHistory tail-reads correctly when the file is larger than one chunk',
   }));
   await queueHistory.appendHistory(bigEntries);
   const read = await queueHistory.readHistory({ limit: 5 });
-  // appended in ascending index order; readHistory reverses to newest-appended-first
-  expect(read.map((j) => j.slug)).toEqual(['bulk-1999', 'bulk-1998', 'bulk-1997', 'bulk-1996', 'bulk-1995']);
+  // The tail read only touches the file's end; whatever was read comes back
+  // ordered by finishedAt newest-first.
+  expect(read.length).toBe(5);
+  const t = (j) => Date.parse(j.finishedAt);
+  for (let i = 1; i < read.length; i++) expect(t(read[i - 1])).toBeGreaterThanOrEqual(t(read[i]));
 });
 
 // ---------- selectHistoryJobs merge (scheduler.cjs) ----------

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

@@ -140,3 +140,15 @@ test('autoArchiveCompleted: tolerates a missing/malformed state.jobs', async ()
   const result = await autoArchiveCompleted({}, { nowMs: NOW });
   expect(result.archived).toBe(0);
 });
+
+// ---------- archiving never strands a runnable queue job (scheduler PRD:
+// archived-prd-skip — job 822-epics-nav-rename fired ENOENT after its PRD
+// was archived out from under a still-queued job) ----------
+
+test('selectAutoArchivable never selects a slug whose job is still pending or running, so auto-archive can never leave a runnable job pointing at an archived PRD', () => {
+  const pending = old({ slug: '13-pending', status: 'pending', finishedAt: null });
+  const running = old({ slug: '14-running', status: 'running', finishedAt: null });
+  const completed = old({ slug: '15-done', status: 'completed' });
+  const slugs = selectAutoArchivable([pending, running, completed], { nowMs: NOW });
+  expect(slugs).toEqual(['15-done']);
+});