claude-code-session-manager 0.39.3 → 0.40.0

package/src/main/scheduler.cjs

@@ -85,8 +85,31 @@ const queueOps = require('./queueOps.cjs');
 // match ROOT/QUEUE_PATH below since both resolve the same ~/.claude/session-manager
 // home-dir layout.
 const { sweep: sweepFeedback } = require('../../scripts/lib/watchdogHelpers.cjs');
-const { resolvePrdsDirs, resolvePrdWriteDir } = require('./lib/prdLocations.cjs');
-const { migratePrds } = require('./lib/prdMigration.cjs');
+const { resolvePrdsDirs, resolvePrdWriteDir, listEpicPrdDirs } = require('./lib/prdLocations.cjs');
+const { ensureEpic, appendPrdCreatedEvent, readActiveIndex } = require('./lib/epicMint.cjs');
+
+// ---------- origin session resolution (PRD 832) ----------
+// An Epic IS a tagged claude session — job rows carry the originating
+// claudeSessionId alongside sourcePromptId so every PRD stays traceable to
+// the session that spawned it. active-index.json is tiny; a short TTL cache
+// keeps reconcile (every 60s, N jobs) at one read per project per pass.
+const originIndexCache = new Map(); // cwd -> { at, sessions }
+const ORIGIN_CACHE_TTL_MS = 30_000;
+function resolveOriginSessionId(cwd, epicId) {
+  if (!cwd || !epicId) return null;
+  let entry = originIndexCache.get(cwd);
+  if (!entry || Date.now() - entry.at > ORIGIN_CACHE_TTL_MS) {
+    entry = { at: Date.now(), sessions: readActiveIndex(cwd).sessions };
+    originIndexCache.set(cwd, entry);
+  }
+  const session = entry.sessions[epicId];
+  return session && typeof session.claudeSessionId === 'string' ? session.claudeSessionId : null;
+}
+const sessionSlots = require('./lib/sessionSlots.cjs');
+const queueStore = require('./lib/queueStore.cjs');
+const { splitFrontmatter } = require('./lib/prdFrontmatter.cjs');
+const { migratePrds, consolidateFlatPrds } = require('./lib/prdMigration.cjs');
+const { allProjectCwds } = require('../../scripts/lib/activeSessions.cjs');
 
 // Captured once at module load so every run's meta sidecar can record how
 // stale the running process is relative to on-disk source (incident: PRD
@@ -469,6 +492,44 @@ function prdPathForJob(job) {
   return path.join(prdDirForCwd(job && job.cwd), `${job && job.slug}.md`);
 }
 
+/** Absolute path to the sibling `prds-archived/<slug>.md` twin of a job's PRD. */
+function archivedPrdPathForJob(job) {
+  return path.join(prdDirForCwd(job && job.cwd), '..', 'prds-archived', `${job && job.slug}.md`);
+}
+
+/**
+ * True if a job's PRD has already been archived (sibling `prds-archived/<slug>.md`
+ * exists). A queue entry whose PRD moved there is stale — the work already shipped
+ * — not a genuine missing-PRD failure.
+ */
+async function archivedTwinExists(job) {
+  try {
+    await fsp.access(archivedPrdPathForJob(job));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build the non-failure result + run meta for a job whose PRD has already
+ * been archived (work shipped, queue entry is stale). Shared by both
+ * PRD-read failure exits in executeJob so the stale-skip logic isn't
+ * duplicated.
+ */
+function prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath) {
+  const archivedTwin = archivedPrdPathForJob(job);
+  const msg = `PRD already archived (${archivedTwin}) — work shipped; retiring stale queue entry`;
+  safeLog(`[scheduler] ${msg}\n`);
+  closeFd();
+  const finishedAt = Date.now();
+  config.writeJsonSync(metaPath, {
+    slug: job.slug, cwd, sessionId, exitCode: 0, skipped: 'prd-archived',
+    note: msg, startedAt, finishedAt, durationMs: 0,
+  });
+  return { exitCode: 0, durationMs: 0, skipped: 'prd-archived', note: msg, sessionId };
+}
+
 /**
  * Search every candidate PRD dir for `<slug>.md` (legacy dir first, then
  * each active project's dir). Returns the containing dir, or null if the
@@ -538,6 +599,34 @@ async function archiveCompletedPrd(slug, cwd) {
   }
 }
 
+/**
+ * Mark any still-runnable (pending/running) queue job for the given slugs as
+ * completed. Called after a PRD's .md is manually archived (queueOps.cjs's
+ * `schedule:archive-prd`) so a stale queue entry can never survive to fire
+ * against a PRD that no longer exists in the live prds/ dir — the same
+ * ENOENT-avoidance archivedTwinExists provides in executeJob, applied at the
+ * archiving source instead of at fire-time. auto-archived slugs never need
+ * this (selectAutoArchivable in queueOps.cjs only selects already-completed
+ * jobs), so this is exercised only by the manual archive path.
+ */
+async function retireCompletedSlugs(slugs) {
+  const list = Array.isArray(slugs) ? slugs.filter(Boolean) : [];
+  if (list.length === 0) return;
+  const slugSet = new Set(list);
+  await mutate((s) => {
+    for (const j of s.jobs) {
+      if (!j || !slugSet.has(j.slug)) continue;
+      if (j.status !== 'pending' && j.status !== 'running') continue;
+      j.status = 'completed';
+      j.finishedAt = new Date().toISOString();
+      j.exitCode = 0;
+      j.error = null;
+      delete j.runtime;
+    }
+  });
+  await broadcast({ flush: true });
+}
+
 // Bundled authoring guide seeded into the scheduler dir so the session-manager-dev
 // plugin's /develop and /prd skills — which reference this stable `~`-absolute
 // path — work on any user's machine, not just the author's.
@@ -570,7 +659,7 @@ async function runPrdMigration() {
     result = await migratePrds(PRDS_DIR);
   } catch (e) {
     logs.writeLine({ level: 'error', scope: 'scheduler', message: 'PRD migration failed', meta: { error: e?.message } });
-    return;
+    return null;
   }
   console.log(`[scheduler] PRD migration: moved ${result.moved}, skipped ${result.skipped}`);
   if (result.unresolved.length > 0) {
@@ -584,6 +673,30 @@ async function runPrdMigration() {
       console.warn(`[scheduler] PRD migration: left ${u.file} in legacy dir (${u.reason})`);
     }
   }
+
+  // Phase 2 (2026-07-31 domain-model decision): the flat per-project
+  // `scheduler/prds/` dir is retired — new PRDs are epic-scoped, and anything
+  // still sitting flat consolidates into `prds-archived/` for later special
+  // processing. Queue rows for moved files are reaped by the archived-twin
+  // retirement. Idempotent per project; failures are logged, never fatal.
+  for (const cwd of allProjectCwds()) {
+    try {
+      const c = await consolidateFlatPrds(cwd);
+      if (c.moved > 0) {
+        console.log(`[scheduler] flat-PRD consolidation: archived ${c.moved} file(s) in ${cwd}`);
+      }
+      for (const f of c.failed) {
+        logs.writeLine({
+          level: 'warn', scope: 'scheduler',
+          message: `flat-PRD consolidation: could not archive ${f.file}`,
+          meta: { cwd, reason: f.reason },
+        });
+      }
+    } catch (e) {
+      logs.writeLine({ level: 'warn', scope: 'scheduler', message: 'flat-PRD consolidation failed', meta: { cwd, error: e?.message } });
+    }
+  }
+  return result;
 }
 
 // Matches only numbered timestamp backups (queue.json.bak-<epoch>), not the
@@ -698,74 +811,62 @@ function appendHeartbeat(entry) {
 // So: a MISSING file is a legitimately empty queue (first boot). A file that
 // exists but won't read or parse is `unreadable` — a poison state that must
 // never reach reconcile() or writeQueue(). Callers get the flag, not a lie.
-const EMPTY_QUEUE = () => ({
-  config: { ...DEFAULT_CONFIG }, jobs: [], scheduledFor: null, lastRunAt: null, paused: null,
-});
-
-function shapeQueue(raw) {
-  const data = JSON.parse(raw);
-  return {
-    config: { ...DEFAULT_CONFIG, ...(data.config || {}) },
-    jobs: Array.isArray(data.jobs) ? data.jobs : [],
-    scheduledFor: data.scheduledFor ?? null,
-    lastRunAt: data.lastRunAt ?? null,
-    paused: data.paused ?? null,
-  };
-}
+// (The single-file EMPTY_QUEUE/shapeQueue readers were retired with the
+// global queue.json — queueStore.cjs's merged readers own the shape now.)
 
-// Quarantine a corrupt queue.json alongside itself (once per process — the
-// first copy is the one that matters; later ticks would just overwrite it
-// with the same bytes) so a human can diff it against the .bak-* snapshots.
+// Quarantine a corrupt shard alongside itself (once per process — the first
+// copy is the one that matters; later ticks would just overwrite it with the
+// same bytes) so a human can diff it against the .bak-* snapshots.
 let quarantined = false;
-function unreadableQueue(e) {
-  const state = EMPTY_QUEUE();
-  state.unreadable = e?.message ?? 'queue.json read failed';
-  if (!quarantined) {
+function flagUnreadable(state) {
+  if (!state.unreadable) return state;
+  if (!quarantined && state.unreadablePath) {
     quarantined = true;
     try {
-      fs.copyFileSync(QUEUE_PATH, `${QUEUE_PATH}.corrupt-${Date.now()}`);
+      fs.copyFileSync(state.unreadablePath, `${state.unreadablePath}.corrupt-${Date.now()}`);
     } catch { /* best-effort: the read already failed, the copy may too */ }
   }
-  console.error(`[scheduler] queue.json unreadable — refusing to treat as empty: ${state.unreadable}`);
+  console.error(`[scheduler] queue state unreadable — refusing to treat as empty: ${state.unreadable}`);
   logs.writeLine({
     level: 'error', scope: 'scheduler',
-    message: 'queue.json unreadable — scheduling halted until it reads clean',
-    meta: { path: QUEUE_PATH, error: state.unreadable },
+    message: 'queue state unreadable — scheduling halted until it reads clean',
+    meta: { path: state.unreadablePath, error: state.unreadable },
   });
   return state;
 }
 
+// Storage is FEDERATED (lib/queueStore.cjs, 2026-07-31): per-project job
+// shards under `<cwd>/session-manager-operations/scheduler/state/queue.json`
+// plus one machine-runtime file (config/paused/lastRunAt). Reads merge every
+// shard into the single state object all downstream logic already expects;
+// writes split it back. The old global scheduled-plans/queue.json is retired
+// (split at boot by queueStore.migrateLegacyGlobalQueue).
+
 // Sync queue read — passed to the supervisor module (which calls it from
 // supervisorTick / applyAction with no await) and the heartbeat interval.
 // IPC handlers and mutate() use readQueue (async) below.
 function readQueueSync() {
-  try {
-    return shapeQueue(fs.readFileSync(QUEUE_PATH, 'utf8'));
-  } catch (e) {
-    if (e?.code === 'ENOENT') return EMPTY_QUEUE();
-    return unreadableQueue(e);
-  }
+  const s = queueStore.readMergedSync();
+  s.config = { ...DEFAULT_CONFIG, ...(s.config || {}) };
+  return flagUnreadable(s);
 }
 
 // Async queue read — used on all IPC hot paths. Reading queue.json sync was
-// blocking the main thread inside ipcMain.handle callbacks; awaiting fsp.readFile
-// hands control back to the renderer while the kernel paginates the file.
+// blocking the main thread inside ipcMain.handle callbacks; awaiting the
+// shard reads hands control back to the renderer between files.
 async function readQueue() {
-  try {
-    return shapeQueue(await fsp.readFile(QUEUE_PATH, 'utf8'));
-  } catch (e) {
-    if (e?.code === 'ENOENT') return EMPTY_QUEUE();
-    return unreadableQueue(e);
-  }
+  const s = await queueStore.readMerged();
+  s.config = { ...DEFAULT_CONFIG, ...(s.config || {}) };
+  return flagUnreadable(s);
 }
 
 async function writeQueue(state) {
   // Last line of defence: never persist a state derived from a failed read.
   if (state && state.unreadable) {
-    throw new Error(`refusing to write queue.json from an unreadable read (${state.unreadable})`);
+    throw new Error(`refusing to write queue state from an unreadable read (${state.unreadable})`);
   }
   ensureDirs();
-  await config.writeJson(QUEUE_PATH, state);
+  await queueStore.writeSplit(state, state.config?.defaultCwd ?? DEFAULT_PROJECT_CWD);
 }
 
 // ---------- serialized mutation queue ----------
@@ -828,7 +929,23 @@ async function listPrdFiles() {
 async function allocateParallelGroup(cwd) {
   const dir = prdDirForCwd(cwd);
   await fsp.mkdir(dir, { recursive: true });
-  return prdParser.allocateParallelGroup(dir);
+  // PRD 832: numbers are unique across the WHOLE project, not just the
+  // allocator's bookkeeping dir — scan every Epic prds/ dir plus the
+  // archive so a number used anywhere (even by a hand-authored or archived
+  // PRD) is never reissued. The reservation markers + high-water sidecar
+  // stay in `dir`; the cross-dir max only raises the floor.
+  const targetCwd = cwd || DEFAULT_PROJECT_CWD;
+  const extraDirs = [
+    ...listEpicPrdDirs(targetCwd),
+    path.join(prdDirForCwd(targetCwd), '..', 'prds-archived'),
+  ];
+  let extraFloor = 0;
+  for (const d of extraDirs) {
+    try {
+      extraFloor = Math.max(extraFloor, await prdParser.maxParallelGroupInUse(d));
+    } catch { /* missing dir — nothing allocated there */ }
+  }
+  return prdParser.allocateParallelGroup(dir, { extraFloor });
 }
 
 /**
@@ -908,6 +1025,20 @@ function validatePromptForSpawn(body, srcLabel) {
 
 // ---------- queue reconciliation ----------
 
+/**
+ * sourcePromptId backfill (PRD 830) is pending-only: a pending row always
+ * takes the freshly-parsed value (explicit frontmatter, or the dir-derived
+ * epic id parsePrd falls back to when frontmatter has none) since it hasn't
+ * started executing yet. A running/completed row's sourcePromptId is left
+ * exactly as it was minted at dispatch time — reconcile must not rewrite
+ * linkage on work already in flight or finished.
+ */
+function reconcileSourcePromptId(job, parsedSourcePromptId) {
+  return job.status === 'pending'
+    ? (parsedSourcePromptId ?? job.sourcePromptId ?? null)
+    : job.sourcePromptId;
+}
+
 /**
  * Walk prds/, ensure every .md has a queue entry. Drop entries whose .md
  * is gone. Refresh title/cwd/parallelGroup from disk every reconcile so
@@ -950,6 +1081,16 @@ async function reconcile(state) {
       // or mid-move. "I can't see it" is not "the user deleted it", so the
       // row survives — worst case it re-resolves on the next pass.
       if (job.status === 'pending' || job.status === 'running') {
+        // Exception: a PENDING row whose PRD has an archived twin was
+        // retired on purpose (work landed by other means — e.g. implemented
+        // inline — and the source .md moved to prds-archived/). Keeping it
+        // would show a phantom "scheduled" job forever; firing it would just
+        // hit executeJob's archived-twin skip anyway. Running rows are left
+        // alone — the reaper owns their lifecycle.
+        if (job.status === 'pending' && (await archivedTwinExists(job))) {
+          console.log(`[scheduler] reconcile: retiring pending job ${job.slug} — PRD already archived (work landed elsewhere)`);
+          continue;
+        }
         seen.add(job.slug);
         next.push({ ...job });
         console.warn(`[scheduler] reconcile: keeping ${job.status} job ${job.slug} — PRD source not visible in any candidate dir`);
@@ -963,8 +1104,11 @@ async function reconcile(state) {
       cwd: p.cwd,
       parallelGroup: p.parallelGroup,
       estimateMinutes: p.estimateMinutes,
-      sourcePromptId: p.sourcePromptId,
+      sourcePromptId: reconcileSourcePromptId(job, p.sourcePromptId),
       sourceTabId: p.sourceTabId,
+      dependsOn: p.dependsOn,
+      originSessionId: job.originSessionId
+        ?? resolveOriginSessionId(p.cwd, reconcileSourcePromptId(job, p.sourcePromptId)),
       bodyPreview: p.body.split('\n').slice(0, 6).join('\n'),
     });
   }
@@ -1023,6 +1167,8 @@ async function reconcile(state) {
       estimateMinutes: p.estimateMinutes,
       sourcePromptId: p.sourcePromptId,
       sourceTabId: p.sourceTabId,
+      dependsOn: p.dependsOn,
+      originSessionId: resolveOriginSessionId(p.cwd, p.sourcePromptId),
       bodyPreview: p.body.split('\n').slice(0, 6).join('\n'),
       status: 'pending',
       runId: null,
@@ -1219,7 +1365,7 @@ function buildScheduleStatePayload(state, { withPaths = false } = {}) {
     },
   };
   if (withPaths) {
-    payload.paths = { root: ROOT, prds: PRDS_DIR, runs: RUNS_DIR, queue: QUEUE_PATH };
+    payload.paths = { root: ROOT, prds: PRDS_DIR, runs: RUNS_DIR, queue: queueStore.MACHINE_STATE_PATH };
   }
   return payload;
 }
@@ -1713,11 +1859,17 @@ async function executeJob(job, runDir, defaultCwd, onPid) {
         prompt = parsed.body + FINISH_PROTOCOL;
         prdPath = fallbackPath;
       } catch (e2) {
+        if (await archivedTwinExists(job)) {
+          return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath);
+        }
         safeLog(`[scheduler] failed to read PRD: ${e2?.message}\n`);
         closeFd();
         return { exitCode: -1, durationMs: 0, error: e2?.message };
       }
     } else {
+      if (await archivedTwinExists(job)) {
+        return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath);
+      }
       safeLog(`[scheduler] failed to read PRD: ${e?.message}\n`);
       closeFd();
       return { exitCode: -1, durationMs: 0, error: e?.message };
@@ -2252,6 +2404,14 @@ async function spawnInvestigation(failedJob, runDir) {
 }
 
 async function spawnJob(job, runId, runDir, defaultCwd) {
+  // Session-Manager owns the machine-wide `claude -p` pool (sessionSlots.cjs)
+  // — the scheduler REQUESTS capacity, it doesn't own a private cap. A miss
+  // leaves the job pending; the next tick retries when a slot frees up.
+  const slotToken = sessionSlots.acquire(`scheduler:${job.slug}`);
+  if (!slotToken) {
+    console.log(`[scheduler] no session slot free for ${job.slug} — deferring (${JSON.stringify(sessionSlots.snapshot().holders.map((h) => h.owner))})`);
+    return;
+  }
   runningSet.add(job.slug);
   try {
     await mutate((s) => {
@@ -2286,6 +2446,25 @@ async function spawnJob(job, runId, runDir, defaultCwd) {
       await setPaused('rate_limit', resetIso);
     }
 
+    // Stale queue entry: the PRD already shipped and was archived before this
+    // run fired (see archivedTwinExists in executeJob). Treat it as a plain
+    // completion — no verify pass, no commit guard, no RCA feedback — since
+    // there is no real transcript/commit to check.
+    if (res.skipped === 'prd-archived') {
+      await mutate((s) => {
+        const idx = s.jobs.findIndex((x) => x.slug === job.slug);
+        if (idx >= 0) {
+          s.jobs[idx].status = 'completed';
+          s.jobs[idx].finishedAt = new Date().toISOString();
+          s.jobs[idx].exitCode = 0;
+          s.jobs[idx].error = null;
+          delete s.jobs[idx].runtime;
+        }
+      });
+      await broadcast({ flush: true });
+      return;
+    }
+
     // Post-run verification: for exit=0 runs, scan the transcript and check
     // dependency prerequisites before stamping 'completed'. This catches the
     // false-positive class where an agent exits cleanly while leaving failures
@@ -2665,6 +2844,8 @@ async function spawnJob(job, runId, runDir, defaultCwd) {
     console.error('[scheduler] spawnJob error', job.slug, e);
   } finally {
     runningSet.delete(job.slug);
+    // Slot release notifies subscribed pumps (chat lane) machine-wide.
+    sessionSlots.release(slotToken);
     // Each job completion is a signal to advance the queue.
     tickQueue().catch(() => {});
   }
@@ -2722,7 +2903,18 @@ function tickQueue() {
     // job is never started into the host's own headroom (that path OOM-kills
     // Electron and SIGHUPs every pty — 2026-06-16 incident).
     const jobBudgetMb = availableForJobs(availableMb, RESERVED_HOST_MB);
-    const allowed = memoryLimitedBatchSize(jobBudgetMb, MIN_FREE_MB_PER_JOB, runningSet.size, batch.length);
+    // Session-Manager's machine-wide slot pool is the outer bound: chat runs
+    // and scheduler jobs share it, so a busy chat lane shrinks this batch.
+    const slotAllowed = sessionSlots.available();
+    if (slotAllowed === 0) {
+      const snap = sessionSlots.snapshot();
+      console.log(`[scheduler] slot gate: 0 of ${snap.total} session slots free (${snap.holders.map((h) => h.owner).join(', ')}) — deferring ${batch.length} job(s)`);
+      return { fired: false, reason: 'slots-exhausted', deferredCount: batch.length, holders: snap.holders };
+    }
+    const allowed = Math.min(
+      slotAllowed,
+      memoryLimitedBatchSize(jobBudgetMb, MIN_FREE_MB_PER_JOB, runningSet.size, batch.length),
+    );
     if (allowed === 0) {
       const threshold = RESERVED_HOST_MB + MIN_FREE_MB_PER_JOB * (runningSet.size + 1);
       console.log(`[scheduler] memory gate: available=${availableMb} MB < threshold=${threshold} MB (host reserve ${RESERVED_HOST_MB} + ${MIN_FREE_MB_PER_JOB}/job × ${runningSet.size + 1}) — deferring ${batch.length} job(s)`);
@@ -2775,6 +2967,8 @@ function forceTickOutcome(result) {
       return { ok: true, kind: 'warn', message: 'Batch cancelled — try again' };
     case 'memory-deferred':
       return { ok: true, kind: 'warn', message: `Deferred ${result.deferredCount} job(s) — low memory (${result.availableMb} MB available, need ${result.threshold} MB)` };
+    case 'slots-exhausted':
+      return { ok: true, kind: 'warn', message: `Deferred ${result.deferredCount} job(s) — all session slots in use (${(result.holders ?? []).map((h) => h.owner).join(', ')})` };
     case 'held': {
       const detail = String(result.detail ?? '').replace(/^\[scheduler\]\s*[\w-]+\s*(?:\[[^\]]*\])?:\s*/, '');
       return { ok: true, kind: 'warn', message: detail || 'Batch held' };
@@ -3367,6 +3561,11 @@ function registerScheduleHandlers() {
     return buildScheduleStatePayload(state, { withPaths: true });
   });
 
+  // Session-Manager-wide claude -p slot pool (lib/sessionSlots.cjs) —
+  // read-only diagnostic surface for the Home widget and the global
+  // configuration tab.
+  ipcMain.handle('schedule:session-slots', () => sessionSlots.snapshot());
+
   ipcMain.handle('schedule:health', async () => {
     const state = await readQueue();
     const runningJobs = [];
@@ -3623,6 +3822,19 @@ function registerScheduleHandlers() {
 
 async function init() {
   ensureDirs();
+  // A slot freed anywhere (e.g. a chat run settled) may unblock a deferred
+  // batch — advance the queue without waiting for the next 60s poll.
+  sessionSlots.subscribe(() => { tickQueue().catch(() => {}); });
+  // Retire the global queue.json: split its rows into per-project shards
+  // BEFORE the first read below, so boot reconciliation sees the shards.
+  try {
+    const m = await queueStore.migrateLegacyGlobalQueue(DEFAULT_PROJECT_CWD);
+    if (m.migrated) {
+      console.log(`[scheduler] legacy global queue retired: ${m.moved} row(s) split across ${m.projects} project shard(s)`);
+    }
+  } catch (e) {
+    console.error('[scheduler] legacy queue split failed', e?.message);
+  }
   await runPrdMigration();
   sweepQueueBackups().catch((e) => console.warn('[scheduler] backup sweep failed', e?.message));
 
@@ -3822,7 +4034,19 @@ const remote = {
   // nothing for findPrdDir to search for); the renderer's slug-only IPC
   // path (editing an already-queued PRD) omits it and relies on findPrdDir.
   async readPrd(slug, cwd) {
-    const dir = cwd ? prdDirForCwd(cwd) : await findPrdDir(slug);
+    let dir;
+    if (cwd) {
+      // The slug may live in the legacy flat dir or any Epic's prds/ under
+      // this project; probe local dirs, defaulting to the flat dir (callers
+      // use a miss there as the "doesn't exist yet" signal on create).
+      const localDirs = [prdDirForCwd(cwd), ...listEpicPrdDirs(cwd)];
+      dir = localDirs.find((d) => {
+        const p = safeSlugPathIn(d, slug);
+        return p && fs.existsSync(p);
+      }) ?? prdDirForCwd(cwd);
+    } else {
+      dir = await findPrdDir(slug);
+    }
     if (!dir) return { ok: false, error: 'invalid slug' };
     const filePath = safeSlugPathIn(dir, slug);
     if (!filePath) return { ok: false, error: 'invalid slug' };
@@ -3864,15 +4088,65 @@ const remote = {
   // doesn't exist yet, so findPrdDir would return nothing to write into).
   async writePrd(slug, body, cwd) {
     let dir;
+    let epicTrace = null;
+    let epicCreated = false;
+    let epicId = null;
     if (cwd) {
-      dir = prdDirForCwd(cwd);
+      // Edit-in-place if this slug already lives anywhere under this project
+      // (legacy flat dir or any Epic's prds/); otherwise this is a CREATE,
+      // and every new PRD belongs to an Epic (CLAUDE.md domain model) — mint
+      // one from the body's frontmatter title/tag.
+      const localDirs = [prdDirForCwd(cwd), ...listEpicPrdDirs(cwd)];
+      for (const d of localDirs) {
+        const candidate = safeSlugPathIn(d, slug);
+        if (candidate && fs.existsSync(candidate)) { dir = d; break; }
+      }
+      if (!dir) {
+        try {
+          const { fm } = splitFrontmatter(body);
+          const epic = ensureEpic(cwd, {
+            goalText: fm.title || slug,
+            tag: fm.tag,
+            // An Epic-conversation dispatch already has its Epic — join it.
+            epicId: fm.sourcePromptId,
+          });
+          dir = epic.prdDir;
+          epicTrace = epic.epicId;
+          epicCreated = epic.created === true;
+          epicId = epic.epicId;
+        } catch (e) {
+          // Epic mint must never block a PRD write — fall back to the
+          // legacy flat dir and log loudly.
+          console.error(`[scheduler] ensureEpic failed for ${slug}: ${e?.message}`);
+          dir = prdDirForCwd(cwd);
+        }
+      }
       await fsp.mkdir(dir, { recursive: true });
     } else {
       dir = (await findPrdDir(slug)) ?? PRDS_DIR;
       if (dir === PRDS_DIR) ensureDirs();
     }
+
+    // PRD 825: if this call minted a brand-new Epic (ensureEpic's `created`)
+    // and the write below never lands, don't strand an empty Epic dir —
+    // best-effort remove `<epic>/prds` then `<epic>` itself, only when empty.
+    const cleanupEmptyMintedEpic = async () => {
+      if (!epicCreated || !epicId) return;
+      try {
+        const entries = await fsp.readdir(dir);
+        if (entries.length > 0) return;
+        await fsp.rmdir(dir);
+        const epicRootDir = path.dirname(dir);
+        const epicRootEntries = await fsp.readdir(epicRootDir);
+        if (epicRootEntries.length === 0) await fsp.rmdir(epicRootDir);
+      } catch { /* best-effort only */ }
+    };
+
     const resolved = safeSlugPathIn(dir, slug);
-    if (!resolved) return { ok: false, error: 'invalid slug' };
+    if (!resolved) {
+      await cleanupEmptyMintedEpic();
+      return { ok: false, error: 'invalid slug' };
+    }
     try {
       // Symlink defense, matching readPrd/readLog: safeSlugPathIn is lexical
       // and does NOT resolve symlinks, so a rogue job could plant a PRDs-dir
@@ -3882,16 +4156,23 @@ const remote = {
       // symlink.
       const realParent = await fsp.realpath(path.dirname(resolved));
       if (realParent !== dir && !realParent.startsWith(dir + path.sep)) {
+        await cleanupEmptyMintedEpic();
         return { ok: false, error: 'invalid slug' };
       }
       const existing = await fsp.lstat(resolved).catch(() => null);
       if (existing && existing.isSymbolicLink()) {
+        await cleanupEmptyMintedEpic();
         return { ok: false, error: 'invalid slug' };
       }
       await config.writeTextAtomic(resolved, body);
       const stat = await fsp.stat(resolved);
+      if (epicTrace) {
+        // Best-effort: record the dispatch on the minted Epic's event chain.
+        try { appendPrdCreatedEvent(cwd, epicTrace, slug); } catch { /* trace only */ }
+      }
       return { ok: true, bytesWritten: stat.size };
     } catch (e) {
+      await cleanupEmptyMintedEpic();
       return { ok: false, error: e?.message ?? 'write failed' };
     }
   },
@@ -3986,4 +4267,4 @@ function registerAdminRoutes(adminHttp, remoteObj = remote) {
   });
 }
 
-module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, writeQueue, reconcile, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, committedInWindow, computeCommittedDuringRun, classifySigtermWithCommit, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, commitGuardVerdict, TRANSIENT_RETRY_CAP, buildScheduleStatePayload, partitionBootOrphans, applyOrphanOutcome, BOOT_ORPHAN_KILL_GRACE_MS, feedbackSweepDue, FEEDBACK_SWEEP_TICK_INTERVAL, sweepFeedback, registerAdminRoutes, notifyOriginatingTab, isNotifiableTerminalStatus, candidatePrdsDirs, prdDirForCwd, prdPathForJob, findPrdDir, runPrdMigration, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields };
+module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, writeQueue, reconcile, reconcileSourcePromptId, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, committedInWindow, computeCommittedDuringRun, classifySigtermWithCommit, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, commitGuardVerdict, TRANSIENT_RETRY_CAP, buildScheduleStatePayload, partitionBootOrphans, applyOrphanOutcome, BOOT_ORPHAN_KILL_GRACE_MS, feedbackSweepDue, FEEDBACK_SWEEP_TICK_INTERVAL, sweepFeedback, registerAdminRoutes, notifyOriginatingTab, isNotifiableTerminalStatus, candidatePrdsDirs, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, runPrdMigration, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields };

package/src/main/templates/PRD_AUTHORING.md

@@ -392,17 +392,21 @@ the user may or may not have open.
 
 ### Fallback: writing the PRD file directly
 
-When the app is not running, write `<NN>-<slug>.md` by hand into the target repo's own
-`<cwd>/session-manager-operations/scheduler/prds/` following the frontmatter rules in §6 and the
+When the app is not running, first mint (or join) an Epic — `node <session-manager-repo>/scripts/mint-epic.cjs <cwd> "<goal>" [feature|bug|discussion]`; its last stdout line is the prds dir — then write `<NN>-<slug>.md` by hand into that
+`<cwd>/session-manager-operations/scheduler/epics/<epic-id>/prds/` dir (the flat `scheduler/prds/` is RETIRED and auto-archived unexecuted at boot), add `sourcePromptId: <epic-id>` to the frontmatter so the job keeps its Epic linkage, following the frontmatter rules in §6 and the
 body conventions the rest of this guide describes (`# Goal`, `# Acceptance criteria`,
 `# Implementation notes`, `## Engineering standards` inlined verbatim — see `/develop`'s output
 for the exact shape). **Trade-off:** this path has no atomic `NN` allocation. The tool's
 `allocateParallelGroup()` (PRD 548) exists specifically to close a race where two writers pick
 the same `NN` at once; a hand-written file bypasses that reservation entirely, so if another
 writer (a human, `/develop`, or another automation) picks the same `NN` around the same time, one
-file silently shadows or is shadowed by the other's parallel-group slot. Pick an `NN` by scanning
-the existing prds directory for the current max and incrementing, and treat a collision as
-possible, not merely theoretical.
+file silently shadows or is shadowed by the other's number. Pick an `NN` by scanning ALL of the
+project's prds dirs (`scheduler/epics/*/prds/` and `prds-archived/`) for the current max and
+incrementing, and treat a collision as possible, not merely theoretical. NN is strictly unique
+per project (PRD 832) — NEVER reuse an existing number to signal "runs in parallel"; that
+convention is retired. Express ordering with `dependsOn: [<slug>, ...]` frontmatter (the job is
+eligible once every listed slug's queue row is completed); independent PRDs omit it and the
+scheduler may run them concurrently.
 
 ### Ownership boundary