claude-code-session-manager 0.39.3 → 0.39.4

package/src/main/lib/epicMint.cjs

@@ -0,0 +1,144 @@
+/**
+ * epicMint.cjs — auto-mint an Epic (PromptSession) for a PRD dispatch.
+ *
+ * Domain rule (CLAUDE.md "Domain model"): every PRD belongs to an Epic; the
+ * hierarchy TAB → operations-root → EPIC → PRD is total. Dispatch paths that
+ * have no Epic in hand (feedback sweep, ad-hoc /develop, admin/MCP create)
+ * call ensureEpic() to create-or-join one instead of writing epicless PRDs.
+ *
+ * The Epic registry is the renderer's own store: the per-cwd
+ * `session-manager-operations/prompt-sessions/active-index.json`
+ * ({ sessions, events } — shape defined in state/promptSessions.ts). Writing
+ * the same file the renderer reads keeps a single source of truth: an
+ * auto-minted Epic shows up in the Epics nav like a hand-created one.
+ *
+ * Plain Node module (no Electron deps) so the external watchdog scripts can
+ * require it. Atomic writes: tmp + rename, same pattern as config.cjs.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { resolveEpicPrdWriteDir } = require('./prdLocations.cjs');
+
+function activeIndexPath(cwd) {
+  return path.join(cwd, 'session-manager-operations', 'prompt-sessions', 'active-index.json');
+}
+
+function readActiveIndex(cwd) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(activeIndexPath(cwd), 'utf8'));
+    return {
+      sessions: parsed && typeof parsed.sessions === 'object' && parsed.sessions ? parsed.sessions : {},
+      events: parsed && typeof parsed.events === 'object' && parsed.events ? parsed.events : {},
+    };
+  } catch {
+    return { sessions: {}, events: {} };
+  }
+}
+
+function writeActiveIndex(cwd, index) {
+  const file = activeIndexPath(cwd);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(index, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+function slugify(text) {
+  return String(text || 'epic')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48) || 'epic';
+}
+
+/**
+ * ensureEpic(cwd, { goalText, tag?, reuseByGoal? }) → { epicId, prdDir, created }
+ *
+ * Mints a new Epic — or, with `reuseByGoal`, joins the existing ACTIVE Epic
+ * whose goalText matches (used by the recurring feedback sweep so successive
+ * sweeps chain into one Epic instead of minting one per tick).
+ *
+ * The Epic's id doubles as its directory name under scheduler/epics/, so the
+ * PromptSession ↔ on-disk Epic mapping is 1:1 with no lookup table.
+ */
+function ensureEpic(cwd, { goalText, tag, reuseByGoal = false, epicId: explicitEpicId } = {}) {
+  if (!cwd || typeof cwd !== 'string') throw new Error('ensureEpic: cwd is required');
+  const index = readActiveIndex(cwd);
+
+  // A dispatch that already knows its Epic (sourcePromptId frontmatter from
+  // an Epic-conversation dispatch) joins it rather than minting a sibling.
+  if (explicitEpicId && index.sessions[explicitEpicId]) {
+    const prdDir = resolveEpicPrdWriteDir(cwd, explicitEpicId);
+    fs.mkdirSync(prdDir, { recursive: true });
+    return { epicId: explicitEpicId, prdDir, created: false };
+  }
+
+  if (reuseByGoal) {
+    for (const s of Object.values(index.sessions)) {
+      if (s && s.status === 'active' && s.goalText === goalText) {
+        const prdDir = resolveEpicPrdWriteDir(cwd, s.id);
+        fs.mkdirSync(prdDir, { recursive: true });
+        return { epicId: s.id, prdDir, created: false };
+      }
+    }
+  }
+
+  const epicId = `${slugify(goalText)}-${crypto.randomUUID().slice(0, 8)}`;
+  const now = new Date().toISOString();
+  const session = {
+    id: epicId,
+    cwd,
+    goalText: String(goalText || ''),
+    // Independently minted, never shared with a SessionTab — same invariant
+    // as renderer-created PromptSessions (state/promptSessions.ts).
+    claudeSessionId: crypto.randomUUID(),
+    status: 'active',
+    createdAt: now,
+    completedAt: null,
+    ...(tag ? { tag } : {}),
+  };
+  const firstEvent = {
+    id: crypto.randomUUID(),
+    promptSessionId: epicId,
+    kind: 'prompt',
+    causedByEventId: null,
+    at: now,
+    text: String(goalText || ''),
+  };
+  index.sessions[epicId] = session;
+  index.events[epicId] = [firstEvent];
+  writeActiveIndex(cwd, index);
+
+  const prdDir = resolveEpicPrdWriteDir(cwd, epicId);
+  fs.mkdirSync(prdDir, { recursive: true });
+  return { epicId, prdDir, created: true };
+}
+
+/**
+ * appendPrdCreatedEvent(cwd, epicId, prdSlug) — record a PRD dispatch on the
+ * Epic's event chain, FK-linked to the current tail (chain, not tree — the
+ * referential-integrity requirement from promptSessions.ts).
+ */
+function appendPrdCreatedEvent(cwd, epicId, prdSlug, text) {
+  const index = readActiveIndex(cwd);
+  if (!index.sessions[epicId]) return false;
+  const chain = Array.isArray(index.events[epicId]) ? index.events[epicId] : [];
+  const tail = chain.length ? chain[chain.length - 1] : null;
+  chain.push({
+    id: crypto.randomUUID(),
+    promptSessionId: epicId,
+    kind: 'prd_created',
+    causedByEventId: tail ? tail.id : null,
+    at: new Date().toISOString(),
+    prdSlug,
+    ...(text ? { text } : {}),
+  });
+  index.events[epicId] = chain;
+  writeActiveIndex(cwd, index);
+  return true;
+}
+
+module.exports = { ensureEpic, appendPrdCreatedEvent, activeIndexPath };

package/src/main/lib/prdLocations.cjs

@@ -20,6 +20,47 @@ const path = require('node:path');
 const { activeProjectCwds, allProjectCwds } = require('../../../scripts/lib/activeSessions.cjs');
 
 const PRD_SUBPATH = ['session-manager-operations', 'scheduler', 'prds'];
+const EPICS_SUBPATH = ['session-manager-operations', 'scheduler', 'epics'];
+
+/**
+ * resolveEpicsRoot(cwd) → `<cwd>/session-manager-operations/scheduler/epics`
+ * The per-project root under which every Epic keeps its own prds/ dir.
+ */
+function resolveEpicsRoot(cwd) {
+  if (!cwd || typeof cwd !== 'string') {
+    throw new Error('resolveEpicsRoot: cwd is required');
+  }
+  return path.join(cwd, ...EPICS_SUBPATH);
+}
+
+/**
+ * resolveEpicPrdWriteDir(cwd, epicId) →
+ *   `<cwd>/session-manager-operations/scheduler/epics/<epicId>/prds`
+ * The write destination for every NEW PRD. The flat legacy dir
+ * (resolvePrdWriteDir) remains read-only during the transition — new PRDs
+ * always belong to an Epic (auto-minted when the dispatch has none).
+ */
+function resolveEpicPrdWriteDir(cwd, epicId) {
+  if (!epicId || typeof epicId !== 'string' || epicId.includes('/') || epicId.includes('..')) {
+    throw new Error('resolveEpicPrdWriteDir: epicId must be a plain directory name');
+  }
+  return path.join(resolveEpicsRoot(cwd), epicId, 'prds');
+}
+
+/** Enumerate every existing `epics/<id>/prds` dir under one project cwd. */
+function listEpicPrdDirs(cwd) {
+  let root;
+  try { root = resolveEpicsRoot(cwd); } catch { return []; }
+  let entries;
+  try { entries = fs.readdirSync(root, { withFileTypes: true }); } catch { return []; }
+  const dirs = [];
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    const prdDir = path.join(root, ent.name, 'prds');
+    if (fs.existsSync(prdDir)) dirs.push(prdDir);
+  }
+  return dirs;
+}
 
 /**
  * resolvePrdWriteDir(cwd) → `<cwd>/session-manager-operations/scheduler/prds`
@@ -68,6 +109,9 @@ function resolvePrdsDirs(maxAgeMin, opts) {
     let dir;
     try { dir = resolvePrdWriteDir(cwd); } catch { continue; }
     if (fs.existsSync(dir)) add(dir);
+    // Epic-scoped dirs (the write layout for all new PRDs) are first-class
+    // scan sources alongside the legacy flat dir.
+    for (const epicDir of listEpicPrdDirs(cwd)) add(epicDir);
   }
 
   // Active projects are added unconditionally: a brand-new project has no
@@ -75,9 +119,18 @@ function resolvePrdsDirs(maxAgeMin, opts) {
   // find it. Scans over a non-existent dir are a harmless ENOENT no-op.
   for (const cwd of activeProjectCwds(maxAgeMin, opts)) {
     try { add(resolvePrdWriteDir(cwd)); } catch { /* unusable cwd */ }
+    for (const epicDir of listEpicPrdDirs(cwd)) add(epicDir);
   }
 
   return dirs;
 }
 
-module.exports = { resolvePrdWriteDir, resolvePrdsDirs, PRD_SUBPATH };
+module.exports = {
+  resolvePrdWriteDir,
+  resolvePrdsDirs,
+  resolveEpicsRoot,
+  resolveEpicPrdWriteDir,
+  listEpicPrdDirs,
+  PRD_SUBPATH,
+  EPICS_SUBPATH,
+};

package/src/main/lib/prdMigration.cjs

@@ -82,4 +82,50 @@ async function migratePrds(legacyPrdsDir) {
   return { moved, skipped, unresolved };
 }
 
-module.exports = { migratePrds };
+/**
+ * consolidateFlatPrds(cwd) — one-time, idempotent retirement of the legacy
+ * FLAT per-project PRD dir (`scheduler/prds/`) now that new PRDs are always
+ * epic-scoped (`scheduler/epics/<id>/prds/`, CLAUDE.md domain model).
+ *
+ * Every `.md` in the flat dir moves to the sibling `prds-archived/` for later
+ * special processing (per 2026-07-31 decision: "new PRDs only; consolidate
+ * existing into prds-archived"). Queue rows pointing at moved files are
+ * reaped by the existing archived-twin retirement (11ad3d8). Dotfiles
+ * (.max-allocated-group, .reserved-*) stay — NN allocation still uses them.
+ * Name collisions in prds-archived/ get a `-legacy-<n>` suffix, never an
+ * overwrite. Idempotent: an emptied flat dir is a no-op readdir.
+ *
+ * Returns { moved, failed: [{ file, reason }] }.
+ */
+async function consolidateFlatPrds(cwd) {
+  const flatDir = resolvePrdWriteDir(cwd);
+  const archiveDir = path.join(path.dirname(flatDir), 'prds-archived');
+  let entries;
+  try {
+    entries = await fsp.readdir(flatDir);
+  } catch {
+    return { moved: 0, failed: [] };
+  }
+
+  let moved = 0;
+  const failed = [];
+  for (const name of entries) {
+    if (!name.endsWith('.md') || name.startsWith('.')) continue;
+    const src = path.join(flatDir, name);
+    try {
+      await fsp.mkdir(archiveDir, { recursive: true });
+      let dst = path.join(archiveDir, name);
+      for (let n = 1; fs.existsSync(dst); n++) {
+        dst = path.join(archiveDir, `${name.slice(0, -3)}-legacy-${n}.md`);
+      }
+      await fsp.rename(src, dst);
+      moved++;
+    } catch (e) {
+      if (e?.code === 'ENOENT') continue; // raced with a concurrent mover
+      failed.push({ file: name, reason: e?.message ?? 'move failed' });
+    }
+  }
+  return { moved, failed };
+}
+
+module.exports = { migratePrds, consolidateFlatPrds };

package/src/main/lib/queueHistory.cjs

@@ -14,9 +14,32 @@ const os = require('os');
 const path = require('path');
 const fsp = require('fs').promises;
 const { HISTORY_RETENTION_MS } = require('./schedulerConfig.cjs');
+const { projectHistoryPath, stateCwds } = require('./queueStore.cjs');
 
+// Legacy global sidecar — READ-ONLY since 2026-07-31 (federated per-project
+// history under <cwd>/session-manager-operations/scheduler/state/history.jsonl,
+// resolved via queueStore.cjs). Old rows stay readable from here; new appends
+// go to the owning project's shard (entries without a cwd still land here so
+// nothing is ever dropped).
 const HISTORY_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'scheduled-plans', 'history.jsonl');
 
+/** Every history file currently in play: each project's shard + the legacy global. */
+function historyPaths() {
+  const paths = [];
+  for (const cwd of stateCwds()) {
+    try { paths.push(projectHistoryPath(cwd)); } catch { /* unusable cwd */ }
+  }
+  paths.push(HISTORY_PATH);
+  return paths;
+}
+
+function historyPathFor(entry) {
+  if (entry && entry.cwd) {
+    try { return projectHistoryPath(entry.cwd); } catch { /* fall through */ }
+  }
+  return HISTORY_PATH;
+}
+
 function isFixPlanSlug(slug) {
   return /^\d+-fix-/.test(slug);
 }
@@ -76,32 +99,45 @@ async function appendHistory(entries) {
   const list = Array.isArray(entries) ? entries.filter(Boolean) : [];
   if (list.length === 0) return { appended: 0 };
 
-  let existingText = '';
-  try {
-    existingText = await fsp.readFile(HISTORY_PATH, 'utf8');
-  } catch (e) {
-    if (e.code !== 'ENOENT') throw e;
+  // Federated: each entry appends to its own project's shard (fallback: the
+  // legacy global file for cwd-less rows). Dedupe stays per target file.
+  const byPath = new Map();
+  for (const e of list) {
+    const target = historyPathFor(e);
+    if (!byPath.has(target)) byPath.set(target, []);
+    byPath.get(target).push(e);
   }
 
-  const existingKeys = new Set();
-  if (existingText) {
-    for (const line of existingText.split('\n')) {
-      if (!line.trim()) continue;
-      try {
-        existingKeys.add(jobKey(JSON.parse(line)));
-      } catch {
-        // corrupt/partial line — ignore for dedupe purposes
+  let appended = 0;
+  for (const [target, group] of byPath) {
+    let existingText = '';
+    try {
+      existingText = await fsp.readFile(target, 'utf8');
+    } catch (e) {
+      if (e.code !== 'ENOENT') throw e;
+    }
+
+    const existingKeys = new Set();
+    if (existingText) {
+      for (const line of existingText.split('\n')) {
+        if (!line.trim()) continue;
+        try {
+          existingKeys.add(jobKey(JSON.parse(line)));
+        } catch {
+          // corrupt/partial line — ignore for dedupe purposes
+        }
       }
     }
-  }
 
-  const fresh = list.filter((e) => !existingKeys.has(jobKey(e)));
-  if (fresh.length === 0) return { appended: 0 };
+    const fresh = group.filter((e) => !existingKeys.has(jobKey(e)));
+    if (fresh.length === 0) continue;
 
-  await fsp.mkdir(path.dirname(HISTORY_PATH), { recursive: true });
-  const text = fresh.map((e) => JSON.stringify(e)).join('\n') + '\n';
-  await fsp.appendFile(HISTORY_PATH, text, 'utf8');
-  return { appended: fresh.length };
+    await fsp.mkdir(path.dirname(target), { recursive: true });
+    const text = fresh.map((e) => JSON.stringify(e)).join('\n') + '\n';
+    await fsp.appendFile(target, text, 'utf8');
+    appended += fresh.length;
+  }
+  return { appended };
 }
 
 /**
@@ -112,10 +148,22 @@ async function appendHistory(entries) {
  */
 async function readHistory({ limit } = {}) {
   const cap = Math.max(1, Math.min(500, Number.isFinite(limit) ? Math.floor(limit) : 50));
+  // Federated: newest `cap` from EACH file, merged newest-first by finishedAt
+  // (fallback startedAt), then capped. Per-file tail reads keep this cheap.
+  const chunks = await Promise.all(historyPaths().map((p2) => readHistoryFile(p2, cap)));
+  const ts = (e) => Date.parse(e?.finishedAt ?? e?.startedAt ?? '') || 0;
+  // Each chunk is already newest-first; keep that order as the tiebreak so
+  // timestamp-less rows don't get shuffled by the cross-file sort.
+  const tagged = chunks.flatMap((chunk) => chunk.map((e, idx) => ({ e, ts: ts(e), idx })));
+  tagged.sort((a, b) => (b.ts - a.ts) || (a.idx - b.idx));
+  return tagged.slice(0, cap).map((t) => t.e);
+}
 
+/** Tail-read one history file: newest `cap` parsed rows, newest-first. */
+async function readHistoryFile(target, cap) {
   let fh;
   try {
-    fh = await fsp.open(HISTORY_PATH, 'r');
+    fh = await fsp.open(target, 'r');
   } catch (e) {
     if (e.code === 'ENOENT') return [];
     throw e;
@@ -162,7 +210,7 @@ async function readHistory({ limit } = {}) {
 // mtime-gated cache, same convention as scheduler/prdParser.cjs's dirCache —
 // repeated reconcile() calls between appends hit the cache instead of
 // re-reading/re-parsing a JSONL file that only grows over time.
-let historyCacheMtime = -1;
+let historyCacheKey = null;
 let historyCacheMap = null;
 
 /**
@@ -176,22 +224,22 @@ let historyCacheMap = null;
  * from "this is a genuinely brand-new PRD nobody has ever queued."
  */
 async function historyTerminalBySlug() {
-  let mtime;
-  try {
-    mtime = (await fsp.stat(HISTORY_PATH)).mtimeMs;
-  } catch {
-    mtime = -1;
-  }
-  if (mtime === historyCacheMtime && historyCacheMap) return historyCacheMap;
+  const paths = historyPaths();
+  const mtimes = await Promise.all(paths.map(async (p2) => {
+    try { return (await fsp.stat(p2)).mtimeMs; } catch { return -1; }
+  }));
+  const cacheKey = paths.map((p2, i) => `${p2}:${mtimes[i]}`).join('|');
+  if (cacheKey === historyCacheKey && historyCacheMap) return historyCacheMap;
 
   const map = new Map();
-  let text = '';
-  try {
-    text = await fsp.readFile(HISTORY_PATH, 'utf8');
-  } catch (e) {
-    if (e.code !== 'ENOENT') throw e;
-  }
-  if (text) {
+  for (const p2 of paths) {
+    let text = '';
+    try {
+      text = await fsp.readFile(p2, 'utf8');
+    } catch (e) {
+      if (e.code !== 'ENOENT') throw e;
+    }
+    if (!text) continue;
     for (const line of text.split('\n')) {
       if (!line.trim()) continue;
       try {
@@ -202,7 +250,7 @@ async function historyTerminalBySlug() {
       }
     }
   }
-  historyCacheMtime = mtime;
+  historyCacheKey = cacheKey;
   historyCacheMap = map;
   return map;
 }