claude-code-session-manager 0.39.3 → 0.40.0

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, readActiveIndex };

package/src/main/lib/instanceLock.cjs

@@ -0,0 +1,100 @@
+/**
+ * instanceLock.cjs — machine-wide scheduler-ownership lock (PRD 834).
+ *
+ * Electron's app.requestSingleInstanceLock() is keyed by userData path, so an
+ * instance launched with a different identity bypasses it entirely — live
+ * incident 2026-07-31: a Playwright `_electron.launch(src/main/index.cjs)`
+ * runs as the "Electron" default app (userData ~/.config/Electron), won its
+ * own Electron lock, ran full scheduler boot reconciliation against the same
+ * per-project queue state as the production instance, SIGTERM'd the
+ * production instance's live job as an "orphan", and overwrote
+ * admin-api.json. Dev/e2e launches skip the Electron lock on purpose, with
+ * the same effect.
+ *
+ * This lock is identity-independent: a pid file at a FIXED path under
+ * ~/.claude/session-manager/. Exactly one process — whichever wins the
+ * atomic 'wx' create — owns scheduler mutation (boot reconciliation, queue
+ * ticking, feedback sweep, supervisor, heartbeat) and the admin API. Every
+ * other instance runs scheduler-passive: UI reads still work (IPC read
+ * handlers register unconditionally), but nothing that mutates queue state
+ * or kills processes runs.
+ *
+ * Deliberately plain sync fs (no config.cjs writeJson): this runs before
+ * app.whenReady and must not await; the file is tiny and single-writer.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// Env override is for unit tests only (isolates the lock from the real
+// ~/.claude of the machine running the suite).
+function lockPath() {
+  return process.env.SM_SCHEDULER_LOCK_PATH
+    || path.join(os.homedir(), '.claude', 'session-manager', 'scheduler-owner.lock');
+}
+
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // EPERM = alive but not ours; ESRCH = dead.
+    return e && e.code === 'EPERM';
+  }
+}
+
+function readLock() {
+  try {
+    const raw = fs.readFileSync(lockPath(), 'utf8');
+    const parsed = JSON.parse(raw);
+    return Number.isInteger(parsed?.pid) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeLockExclusive() {
+  const body = JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() });
+  fs.mkdirSync(path.dirname(lockPath()), { recursive: true });
+  // 'wx' = atomic create-or-fail — two racing instances cannot both win.
+  fs.writeFileSync(lockPath(), body, { flag: 'wx', mode: 0o600 });
+}
+
+/**
+ * Try to become the machine's scheduler owner.
+ * Returns { owner: true } or { owner: false, holderPid } — never throws.
+ */
+function acquireSchedulerOwnership() {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const existing = readLock();
+    if (existing && existing.pid !== process.pid && pidAlive(existing.pid)) {
+      return { owner: false, holderPid: existing.pid };
+    }
+    // Missing, unreadable, our own, or stale (holder pid dead) — take it.
+    try {
+      if (existing || fs.existsSync(lockPath())) fs.unlinkSync(lockPath());
+    } catch { /* raced with another breaker — retry loop below settles it */ }
+    try {
+      writeLockExclusive();
+      return { owner: true };
+    } catch {
+      // Lost the create race — loop once more to report the winner's pid.
+    }
+  }
+  const winner = readLock();
+  return { owner: false, holderPid: winner?.pid };
+}
+
+/** Best-effort release on clean shutdown; stale-pid detection covers crashes. */
+function releaseSchedulerOwnership() {
+  try {
+    const existing = readLock();
+    if (existing && existing.pid === process.pid) fs.unlinkSync(lockPath());
+  } catch { /* nothing to release */ }
+}
+
+module.exports = { acquireSchedulerOwnership, releaseSchedulerOwnership, pidAlive, lockPath };

package/src/main/lib/prdCreate.cjs

@@ -48,7 +48,7 @@ function deriveSlugFromTitle(title) {
 function buildPrdBody(input) {
   const {
     title, cwd, estimateMinutes, goal, acceptanceCriteria,
-    implementationNotes, outOfScope, sourcePromptId, sourceTabId, tag,
+    implementationNotes, outOfScope, sourcePromptId, sourceTabId, tag, dependsOn,
   } = input;
 
   // No `parallelGroup` frontmatter key by convention (SKILL.md) — the NN-
@@ -64,6 +64,8 @@ function buildPrdBody(input) {
   // Optional, additive: the user-selected Feature/Bug tag (PRD 774) carried
   // through from the originating PromptTicket — deterministic, never LLM-classified.
   if (tag) fmLines.push(`tag: ${tag}`);
+  // Explicit ordering (PRD 832): replaces the retired shared-NN convention.
+  if (dependsOn && dependsOn.length) fmLines.push(`dependsOn: [${dependsOn.join(', ')}]`);
   fmLines.push('---', '');
 
   const acLines = acceptanceCriteria.map((line) => `- [ ] ${line}`).join('\n');
@@ -108,21 +110,32 @@ async function createPrd(input, remote) {
   // through config.cjs's validatePath (allowedRoots = home dir) —
   // same boundary every other fs-touching IPC handler uses — never a
   // bespoke check here.
+  // Normalize a `~`-prefixed cwd BEFORE it reaches allocateParallelGroup/
+  // readPrd/writePrd — those pass cwd through to safeSlugPathIn-adjacent path
+  // joins that treat it as a literal path segment, so an unexpanded `~/...`
+  // fails downstream as a bare "invalid slug" instead of a clear cwd error.
+  const cwd = expandHome(input.cwd);
   try {
-    config.validatePath(expandHome(input.cwd));
+    config.validatePath(cwd);
   } catch (e) {
     return { ok: false, status: 400, error: `cwd rejected: ${e?.message ?? 'outside allowed roots'}` };
   }
+  input = { ...input, cwd };
 
   const slug = input.slug || deriveSlugFromTitle(input.title);
   if (!slug || !PRD_CREATE_SLUG_RE.test(slug)) {
     return { ok: false, status: 400, error: 'could not derive a valid kebab-case slug from title; supply "slug" explicitly' };
   }
 
-  // NN allocation is delegated to allocateParallelGroup() (PRD 548) via
-  // the injected remote — never re-derived here — unless the caller
-  // opted into an existing group explicitly.
-  const nn = input.parallelGroup ?? await remote.allocateParallelGroup(input.cwd);
+  // NN allocation is delegated to allocateParallelGroup() (PRD 548) via the
+  // injected remote — never re-derived here. `parallelGroup` input is
+  // DEPRECATED (PRD 832, user decision 2026-07-31): numbers are strictly
+  // unique per project; ordering is expressed via `dependsOn` frontmatter,
+  // never by sharing a number. An explicit parallelGroup is ignored.
+  if (input.parallelGroup != null) {
+    console.warn(`[prdCreate] parallelGroup input is deprecated and ignored (got ${input.parallelGroup}) — numbers are unique per project; use dependsOn for ordering`);
+  }
+  const nn = await remote.allocateParallelGroup(input.cwd);
   const filenameSlug = `${nn}-${slug}`;
 
   // An explicit `parallelGroup` bypasses allocateParallelGroup()'s

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,46 @@ 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 };
+/**
+ * deriveEpicIdFromPrdPath(filePath) → epicId | null
+ *
+ * A PRD's file location already IS its Epic membership (epic id == parent
+ * dir name, 1:1 by design). Given an absolute PRD file path, walk back up
+ * `EPICS_SUBPATH.length` segments from the epics root implied by the path's
+ * own `.../prds/<slug>.md` shape and confirm it round-trips through
+ * `resolveEpicsRoot` — i.e. the path really is
+ * `<projectCwd>/session-manager-operations/scheduler/epics/<epicId>/prds/<slug>.md`,
+ * not some other `prds/` dir (e.g. the retired flat layout). Returns null for
+ * any path that doesn't match this shape.
+ */
+function deriveEpicIdFromPrdPath(filePath) {
+  if (!filePath || typeof filePath !== 'string') return null;
+  const prdsDir = path.dirname(filePath);
+  if (path.basename(prdsDir) !== 'prds') return null;
+  const epicDir = path.dirname(prdsDir);
+  const epicId = path.basename(epicDir);
+  if (!epicId || epicId === '.' || epicId === path.sep) return null;
+  let projectCwd = path.dirname(epicDir); // epicsRoot (.../scheduler/epics)
+  for (let i = 0; i < EPICS_SUBPATH.length; i++) projectCwd = path.dirname(projectCwd);
+  let epicsRoot;
+  try { epicsRoot = resolveEpicsRoot(projectCwd); } catch { return null; }
+  if (path.join(epicsRoot, epicId, 'prds') !== prdsDir) return null;
+  return epicId;
+}
+
+module.exports = {
+  resolvePrdWriteDir,
+  resolvePrdsDirs,
+  resolveEpicsRoot,
+  resolveEpicPrdWriteDir,
+  listEpicPrdDirs,
+  deriveEpicIdFromPrdPath,
+  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;
 }