claude-code-session-manager 0.53.0 → 0.55.0

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

@@ -12,7 +12,7 @@ const fs = require('node:fs');
 const fsp = require('node:fs/promises');
 const os = require('node:os');
 const path = require('node:path');
-const { listPersonas, openProjects, parseTools } = require('../agentLibrary.cjs');
+const { listPersonas, openProjects, parseTools, savePersona, deletePersona, removeOverride } = require('../agentLibrary.cjs');
 
 const tmpDirs = [];
 afterEach(async () => {
@@ -33,6 +33,15 @@ async function mkTmp(prefix) {
 // home directory config.cjs's validatePath would otherwise enforce.
 const identityValidatePath = (p) => p;
 
+// savePersona/deletePersona/removeOverride take an injectable writeTextAtomic
+// too, since the real config.cjs one enforces its own home-dir validatePath
+// regardless of what's injected for the `validatePath` param here.
+async function fakeWriteTextAtomic(abs, text) {
+  await fsp.mkdir(path.dirname(abs), { recursive: true });
+  await fsp.writeFile(abs, text, 'utf8');
+  return { ok: true, mtimeMs: Date.now() };
+}
+
 test('parseTools splits + trims a comma-separated tools frontmatter value', () => {
   expect(parseTools('Read, Grep, Glob, Bash')).toEqual(['Read', 'Grep', 'Glob', 'Bash']);
   expect(parseTools('')).toEqual([]);
@@ -74,6 +83,7 @@ test('listPersonas parses frontmatter and reports overridingProjects for open ta
       'name: builder',
       'description: Watch git history and drive the next publish.',
       'tools: Read, Grep, Glob, Bash',
+      'tags: feature, bug',
       '---',
       '',
       'You are the Builder agent.',
@@ -103,6 +113,8 @@ test('listPersonas parses frontmatter and reports overridingProjects for open ta
 
   const byName = Object.fromEntries(personas.map((p) => [p.name, p]));
   expect(byName.builder.description).toBe('Watch git history and drive the next publish.');
+  expect(byName.builder.tags).toEqual(['feature', 'bug']);
+  expect(byName.debugger.tags).toEqual([]);
   expect(byName.builder.tools).toEqual(['Read', 'Grep', 'Glob', 'Bash']);
   expect(byName.builder.body).toContain('You are the Builder agent.');
   expect(byName.builder.overridingProjects).toEqual([path.basename(projectWithOverlay)]);
@@ -131,3 +143,73 @@ test('listPersonas skips a project cwd that validatePath rejects, rather than th
   expect(personas).toHaveLength(1);
   expect(personas[0].overridingProjects).toEqual([]);
 });
+
+test('savePersona writes frontmatter + body, and rejects a non-slug name', async () => {
+  const globalDir = await mkTmp('sm-agent-library-save-');
+  await savePersona({
+    name: 'my-agent',
+    description: 'Does a thing.',
+    tools: ['Read', 'Grep'],
+    model: 'opus',
+    color: 'blue',
+    tags: ['feature', 'bug'],
+    body: 'You are my-agent.',
+    globalDir,
+    validatePath: identityValidatePath,
+    writeTextAtomic: fakeWriteTextAtomic,
+  });
+  const text = await fsp.readFile(path.join(globalDir, 'my-agent.md'), 'utf8');
+  expect(text).toContain('name: my-agent');
+  expect(text).toContain('description: Does a thing.');
+  expect(text).toContain('tools: Read, Grep');
+  expect(text).toContain('model: opus');
+  expect(text).toContain('color: blue');
+  expect(text).toContain('tags: feature, bug');
+  expect(text).toContain('You are my-agent.');
+
+  await expect(
+    savePersona({ name: 'Not Valid', body: '', globalDir, validatePath: identityValidatePath, writeTextAtomic: fakeWriteTextAtomic }),
+  ).rejects.toThrow(/lowercase, hyphenated/);
+});
+
+test('savePersona with originalName renames — writes the new file and removes the old one', async () => {
+  const globalDir = await mkTmp('sm-agent-library-rename-');
+  await fsp.writeFile(path.join(globalDir, 'old-name.md'), '---\nname: old-name\n---\nBody.\n');
+  await savePersona({
+    name: 'new-name',
+    originalName: 'old-name',
+    description: '',
+    tools: [],
+    model: 'inherit',
+    color: '',
+    body: 'Body.',
+    globalDir,
+    validatePath: identityValidatePath,
+    writeTextAtomic: fakeWriteTextAtomic,
+  });
+  expect(fs.existsSync(path.join(globalDir, 'new-name.md'))).toBe(true);
+  expect(fs.existsSync(path.join(globalDir, 'old-name.md'))).toBe(false);
+});
+
+test('deletePersona removes the file, and is a no-op when it is already gone', async () => {
+  const globalDir = await mkTmp('sm-agent-library-delete-');
+  await fsp.writeFile(path.join(globalDir, 'gone-soon.md'), '---\nname: gone-soon\n---\nBody.\n');
+  await deletePersona({ name: 'gone-soon', globalDir, validatePath: identityValidatePath });
+  expect(fs.existsSync(path.join(globalDir, 'gone-soon.md'))).toBe(false);
+  await expect(deletePersona({ name: 'gone-soon', globalDir, validatePath: identityValidatePath })).resolves.toEqual({ ok: true });
+});
+
+test('removeOverride deletes a project overlay resolved by project name, and rejects an unknown project', async () => {
+  const project = await mkTmp('sm-agent-library-override-');
+  await fsp.mkdir(path.join(project, '.claude', 'agents'), { recursive: true });
+  const overlayPath = path.join(project, '.claude', 'agents', 'builder.md');
+  await fsp.writeFile(overlayPath, 'overlay\n');
+  const loadSessions = async () => ({ tabs: [{ cwd: project }] });
+
+  await removeOverride({ name: 'builder', projectName: path.basename(project), loadSessions, validatePath: identityValidatePath });
+  expect(fs.existsSync(overlayPath)).toBe(false);
+
+  await expect(
+    removeOverride({ name: 'builder', projectName: 'not-open', loadSessions, validatePath: identityValidatePath }),
+  ).rejects.toThrow(/project not open/);
+});

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

@@ -66,7 +66,7 @@ test('removeEpic deletes a minted Epic from both sessions and events maps', asyn
   const minted = await ensureEpic(cwd, { goalText: 'to be rolled back' });
   expect(readActiveIndex(cwd).sessions[minted.epicId]).toBeDefined();
 
-  const removed = removeEpic(cwd, minted.epicId);
+  const removed = await removeEpic(cwd, minted.epicId);
 
   expect(removed).toBe(true);
   const index = readActiveIndex(cwd);
@@ -78,7 +78,7 @@ test('removeEpic is a no-op (returns false) for an unknown epicId', async () =>
   const cwd = await mkCwd();
   await ensureEpic(cwd, { goalText: 'unrelated epic' });
 
-  const removed = removeEpic(cwd, 'nonexistent-epic-id');
+  const removed = await removeEpic(cwd, 'nonexistent-epic-id');
 
   expect(removed).toBe(false);
   expect(Object.keys(readActiveIndex(cwd).sessions)).toHaveLength(1);
@@ -105,7 +105,7 @@ for (const pollutedKey of ['__proto__', 'constructor', 'toString', 'hasOwnProper
 
 test('removeEpic refuses to report success for the prototype-chain key "__proto__"', async () => {
   const cwd = await mkCwd();
-  const removed = removeEpic(cwd, '__proto__');
+  const removed = await removeEpic(cwd, '__proto__');
   expect(removed).toBe(false);
 });
 

package/src/main/agentLibrary.cjs

@@ -31,6 +31,101 @@ function parseTools(raw) {
   return raw.split(',').map((t) => t.trim()).filter(Boolean);
 }
 
+/** Filename-safe persona name: lowercase, hyphenated, matches the `.md` files on disk. */
+const PERSONA_NAME_RE = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Serializes a persona's frontmatter + body back to `.md` file text.
+ * `tags` is a Claude-Code-agnostic extension of the frontmatter (Claude Code
+ * itself never reads it) — the Epic intent tags (tagLibrary.ts's TAG_LIBRARY)
+ * this persona is associated with, so Agent Library and Tag Library can each
+ * assign/remove the relationship from either side. Stored the same
+ * comma-list way as `tools` for one parser to cover both.
+ */
+function serializePersona({ name, description, tools, model, color, tags, body }) {
+  const lines = ['---', `name: ${name}`];
+  if (description) lines.push(`description: ${description}`);
+  if (tools && tools.length) lines.push(`tools: ${tools.join(', ')}`);
+  if (model && model !== 'inherit') lines.push(`model: ${model}`);
+  if (color) lines.push(`color: ${color}`);
+  if (tags && tags.length) lines.push(`tags: ${tags.join(', ')}`);
+  lines.push('---', '');
+  return lines.join('\n') + (body || '').trim() + '\n';
+}
+
+/**
+ * Writes a global persona `.md` file — `~/.claude/agents/<name>.md`. Pass
+ * `originalName` when renaming an existing persona so the old file is
+ * removed once the new one is written (no-op if names match).
+ */
+async function savePersona({
+  name,
+  originalName,
+  description,
+  tools,
+  model,
+  color,
+  tags,
+  body,
+  globalDir = path.join(os.homedir(), '.claude', 'agents'),
+  validatePath = configMgr.validatePath,
+  writeTextAtomic = configMgr.writeTextAtomic,
+} = {}) {
+  if (!PERSONA_NAME_RE.test(name || '')) {
+    throw new Error('agent name must be lowercase, hyphenated (e.g. "my-agent")');
+  }
+  const target = validatePath(path.join(globalDir, `${name}.md`));
+  const text = serializePersona({ name, description, tools, model, color, tags, body });
+  await writeTextAtomic(target, text);
+  if (originalName && originalName !== name) {
+    const oldReal = validatePath(path.join(globalDir, `${originalName}.md`));
+    try {
+      await fsp.unlink(oldReal);
+    } catch (e) {
+      if (e.code !== 'ENOENT') throw e;
+    }
+  }
+  return { ok: true, path: target };
+}
+
+/** Deletes a global persona `.md` file. Idempotent — missing file is not an error. */
+async function deletePersona({
+  name,
+  globalDir = path.join(os.homedir(), '.claude', 'agents'),
+  validatePath = configMgr.validatePath,
+} = {}) {
+  const target = validatePath(path.join(globalDir, `${name}.md`));
+  try {
+    await fsp.unlink(target);
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  return { ok: true };
+}
+
+/**
+ * Drops a project's local override (`<cwd>/.claude/agents/<name>.md`) so the
+ * global definition applies there again. `projectName` is resolved against
+ * currently-open tabs (same source `listPersonas` uses for overridingProjects).
+ */
+async function removeOverride({
+  name,
+  projectName,
+  loadSessions = sessionsStore.load,
+  validatePath = configMgr.validatePath,
+} = {}) {
+  const projects = await openProjects({ loadSessions });
+  const project = projects.find((p) => p.name === projectName);
+  if (!project) throw new Error(`project not open: ${projectName}`);
+  const target = validatePath(path.join(project.cwd, '.claude', 'agents', `${name}.md`));
+  try {
+    await fsp.unlink(target);
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  return { ok: true };
+}
+
 /**
  * Currently-open project tabs, deduped by cwd, as `{ cwd, name }` — `name`
  * is the last path segment (matches the `projectNameFromCwd` convention used
@@ -103,6 +198,9 @@ async function listPersonas({
       name: fm.name || fallbackName,
       description: fm.description || null,
       tools: parseTools(fm.tools),
+      model: fm.model || null,
+      color: fm.color || null,
+      tags: parseTools(fm.tags),
       path: real,
       body: body.trim(),
       overridingProjects,
@@ -112,4 +210,12 @@ async function listPersonas({
   return personas;
 }
 
-module.exports = { listPersonas, openProjects, parseTools };
+module.exports = {
+  listPersonas,
+  openProjects,
+  parseTools,
+  savePersona,
+  deletePersona,
+  removeOverride,
+  PERSONA_NAME_RE,
+};

package/src/main/index.cjs

@@ -31,6 +31,7 @@ const prdCreate = require('./lib/prdCreate.cjs');
 const { appendAuditEvent } = require('./lib/auditLog.cjs');
 const chatRunner = require('./chatRunner.cjs');
 const promptSessionEvents = require('./promptSessionEvents.cjs');
+const activeIndexMerge = require('./lib/activeIndexMerge.cjs');
 const agentLibrary = require('./agentLibrary.cjs');
 const { resolveBuildTarget } = require('./lib/buildTarget.cjs');
 const adminHttp = createAdminHttp();
@@ -453,6 +454,13 @@ ipcMain.handle('mcp:status', () => probeMcpStatus());
 // personas plus, per currently-open project tab, whether that project
 // overlays the same agent name at `<cwd>/.claude/agents/<name>.md`. Read-only.
 ipcMain.handle('agents:list-personas', () => agentLibrary.listPersonas());
+// Agent Library CRUD — global personas only (`~/.claude/agents/*.md`); a
+// project's local overlay can only be removed here (removeOverride), never
+// created, since Agent Library is a Home-face, machine-wide surface with no
+// per-tab cwd context of its own.
+ipcMain.handle('agents:save-persona', (_e, payload) => agentLibrary.savePersona(payload));
+ipcMain.handle('agents:delete-persona', (_e, payload) => agentLibrary.deletePersona(payload));
+ipcMain.handle('agents:remove-override', (_e, payload) => agentLibrary.removeOverride(payload));
 
 ipcMain.handle('app:engage-rules-path', () => process.env.SESSION_MANAGER_ENGAGE_RULES || null);
 
@@ -789,6 +797,7 @@ registerHistoryAggregatorHandlers();
 registerHistoryDashboardHandlers();
 pluginInstall.registerPluginInstallHandlers();
 memoryTool.registerMemoryHandlers();
+activeIndexMerge.registerActiveIndexMergeHandlers();
 registerMemoryAggregateIpc();
 registerProjectBriefIpc();
 registerProjectPagesIpc();

package/src/main/ipcSchemas.cjs

@@ -214,6 +214,39 @@ const configWatch = z.array(z.string().min(1).max(4096));
 
 const configParseImports = z.object({ path: z.string().min(1).max(4096) });
 
+// ──────────────────────────────────────────── PromptSessions (Epics) active-index merge
+// lib/activeIndexMerge.cjs's read-merge-write, invoked over IPC by the
+// renderer's persistActiveIndex (state/promptSessions.ts) instead of that
+// module doing its own config:read-json/config:write-json round trip. Payload
+// carries only the CALLING renderer's in-memory contribution for this cwd —
+// disk is main's truth, merged inside the same withPathLock epicMint.cjs uses.
+//
+// Epic ids are keys here (Electron's structured-clone IPC transport, unlike
+// JSON.parse, can produce an own-enumerable "__proto__" key on a cloned
+// object) — the regex excludes the prototype-pollution trio so a malformed/
+// hostile payload fails validation before it ever reaches activeIndexMerge.cjs
+// (which additionally uses null-prototype merge targets as defense in depth).
+// Real epic ids are `${slugify(goalText)}-${uuid8}` (epicMint.cjs) — max 64
+// mirrors slugify's 48-char cap plus the "-" + 8 hex chars suffix, rounded up.
+const PROMPT_SESSION_ID_RE = /^(?!__proto__$|constructor$|prototype$)[A-Za-z0-9_-]{1,64}$/;
+const promptSessionsMergeActiveIndex = z.object({
+  cwd: z.string().min(1).max(4096),
+  sessions: z.record(z.string().regex(PROMPT_SESSION_ID_RE), z.unknown()).refine(
+    (v) => Object.keys(v).length <= 2000,
+    { message: 'too many sessions in one merge payload' },
+  ),
+  events: z.record(z.string().regex(PROMPT_SESSION_ID_RE), z.array(z.unknown()).max(5000)).refine(
+    (v) => Object.keys(v).length <= 2000,
+    { message: 'too many event chains in one merge payload' },
+  ),
+  removedIds: z.array(z.string().regex(PROMPT_SESSION_ID_RE)).max(500).optional(),
+  // Always the literal 'epics' on the wire — the handler ignores this value
+  // and hardcodes the writer id itself (single-writer law,
+  // lib/opsOwnership.cjs); requiring the literal here just means a
+  // forged/malformed payload fails validation before it reaches the merge.
+  source: z.literal('epics'),
+});
+
 // ──────────────────────────────────────────── Sessions
 const sessionsPayload = z.object({
   tabs: z.array(z.object({
@@ -908,6 +941,7 @@ module.exports = {
     projectBriefUpdate,
     promptSessionTranscriptAppend,
     promptSessionTranscriptRead,
+    promptSessionsMergeActiveIndex,
     auditLogAppend,
     agentMemoryList,
     agentMemoryGet,

package/src/main/lib/activeIndexMerge.cjs

@@ -0,0 +1,168 @@
+'use strict';
+
+/**
+ * activeIndexMerge.cjs — main-process read-merge-write for a cwd's
+ * prompt-sessions/active-index.json, invoked over IPC by the renderer's
+ * persistActiveIndex (state/promptSessions.ts). Moved here from the renderer
+ * (which used to read-merge-write itself over config:read-json/
+ * config:write-json, commit 3d12e19) to close two holes a purely-renderer
+ * merge can't:
+ *
+ *  1. Resurrection: a second window that still holds an archived/deleted
+ *     Epic as 'active'/'proposed' in its stale in-memory snapshot would
+ *     write that row right back on its next persist — "memory wins on id
+ *     collision" doesn't know the row was deliberately removed elsewhere.
+ *     Fixed with a removal tombstone (index.tombstones, id -> removedAt
+ *     ISO): an id present there is dropped from every future merge's memory
+ *     contribution, not just from the write that performed the removal.
+ *  2. TOCTOU: a renderer's own read (config:read-json) and write
+ *     (config:write-json), round-tripped over IPC with no lock in between,
+ *     left a gap where a main-process mint (epicMint.cjs's ensureEpic,
+ *     itself serialized through its own withPathLock) could land and then
+ *     be silently dropped by the renderer's subsequent write. Running the
+ *     merge inside the SAME withPathLock instance epicMint.cjs already
+ *     serializes ensureEpic/appendPrdCreatedEvent through closes the gap:
+ *     every read-modify-write of this file, from either caller, is now one
+ *     lock (epicMint.cjs exports withPathLock; requiring it here shares the
+ *     same module-level Map via Node's require cache, not a second one).
+ *
+ * Tombstones are never auto-cleared: resumeArchived() (state/promptSessions.ts)
+ * always mints a BRAND NEW Epic id + claudeSessionId — it never reuses the
+ * archived id — so a tombstoned id is never legitimately reborn under the
+ * current domain model. If that ever changes, this module would need an
+ * explicit "un-tombstone" path; today one would be dead code.
+ */
+
+const { activeIndexPath, withPathLock } = require('./epicMint.cjs');
+const config = require('../config.cjs');
+
+function hasOwn(obj, key) {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+// Mirrors state/promptSessions.ts's compareEventsChainAware exactly. Kept as
+// a separate copy (not a shared module) since one side runs in the renderer
+// and the other in Node — small and stable enough that duplicating it here
+// is cheaper than wiring a cross-boundary shared module for one function.
+function compareEventsChainAware(a, b) {
+  const ta = Date.parse(a.at);
+  const tb = Date.parse(b.at);
+  const aValid = !Number.isNaN(ta);
+  const bValid = !Number.isNaN(tb);
+  if (aValid && bValid && ta !== tb) return ta - tb;
+  if (b.causedByEventId === a.id) return -1;
+  if (a.causedByEventId === b.id) return 1;
+  if (aValid && bValid) return 0;
+  if (aValid) return -1;
+  if (bValid) return 1;
+  return 0;
+}
+
+/**
+ * mergeActiveIndex(cwd, { sessions, events, removedIds }) → Promise<{ sessions, events }>
+ *
+ * `sessions`/`events` are the CALLING renderer's own in-memory contribution
+ * for this cwd only (already filtered to 'active'/'proposed' sessions by
+ * persistActiveIndex) — never a full merged file; disk remains the source of
+ * truth this function reads and reconciles against. Returns the merged
+ * { sessions, events } actually written.
+ */
+async function mergeActiveIndex(cwd, { sessions: rawMemorySessions = {}, events: rawMemoryEvents = {}, removedIds = [] } = {}) {
+  if (!cwd || typeof cwd !== 'string') throw new Error('mergeActiveIndex: cwd is required');
+  const filePath = activeIndexPath(cwd);
+  // Null-prototype copies of the CALLER'S OWN payload too: an Epic id equal
+  // to "__proto__" is a plain string key from the caller's perspective, but
+  // `rawMemoryEvents[id]` on a plain object literal resolves through the
+  // prototype chain to Object.prototype itself (not undefined) rather than
+  // hitting the `?? []` fallback below — same hazard as the disk-side merge
+  // targets, just on the read side instead of the write side.
+  const memorySessions = Object.assign(Object.create(null), rawMemorySessions);
+  const memoryEvents = Object.assign(Object.create(null), rawMemoryEvents);
+  return withPathLock(filePath, async () => {
+    // Null-prototype targets: `sessions`/`events` are keyed by Epic id, which
+    // for an IPC payload delivered via Electron's structured-clone (not
+    // JSON.parse) could legitimately carry an own-enumerable "__proto__" key.
+    // A plain-object target's bracket assignment (`obj[id] = x`) with
+    // id === "__proto__" invokes Object.prototype's accessor and re-links the
+    // object's own prototype instead of storing a normal entry — the same
+    // hazard epicMint.cjs's hasOwn() helper guards reads against (see its
+    // comment ~epicMint.cjs:61). A null-prototype target has no such accessor,
+    // so "__proto__"/"constructor"/etc. behave as ordinary keys.
+    let diskSessions = Object.create(null);
+    let diskEvents = Object.create(null);
+    let tombstones = Object.create(null);
+    const result = await config.readJson(filePath);
+    if (result.exists && result.data) {
+      const disk = result.data;
+      if (disk.sessions && typeof disk.sessions === 'object') Object.assign(diskSessions, disk.sessions);
+      if (disk.events && typeof disk.events === 'object') Object.assign(diskEvents, disk.events);
+      if (disk.tombstones && typeof disk.tombstones === 'object') Object.assign(tombstones, disk.tombstones);
+    } else if (result.error || result.parseError) {
+      // Genuine unreadable/corrupt disk index (fs error, or valid file that
+      // failed JSON.parse) rather than "file legitimately doesn't exist yet".
+      // config.readJson never throws (it reports failure via exists/error/
+      // parseError, not exceptions), so this branch — not a try/catch — is
+      // the only way to detect it. Falling back to this caller's own memory
+      // contribution is still the best-effort choice (matches the old
+      // renderer merge's contract), but silently doing so would recreate the
+      // exact "unlogged data loss" incident this module exists to close —
+      // any on-disk tombstones/other-window sessions get dropped, so log it.
+      console.warn(
+        `[activeIndexMerge] disk index unreadable for ${filePath} (error=${result.error ?? 'none'}, `
+        + `parseError=${result.parseError ?? 'none'}) — falling back to this caller's in-memory contribution alone`,
+      );
+    }
+
+    const now = new Date().toISOString();
+    for (const id of removedIds) tombstones[id] = now;
+
+    const mergedSessions = Object.assign(Object.create(null), diskSessions);
+    for (const [id, session] of Object.entries(memorySessions)) {
+      // Resurrection guard: a caller whose in-memory snapshot still thinks a
+      // tombstoned id is open (it hasn't hydrated the removal yet) must not
+      // write it back into the merged file.
+      if (hasOwn(tombstones, id)) continue;
+      mergedSessions[id] = session;
+    }
+    for (const id of removedIds) delete mergedSessions[id];
+
+    // Events are a per-id UNION (same contract the renderer's own merge used
+    // — PRD 855): a scheduler job appends events to disk under its narrow
+    // delegation, so memory-wins-wholesale would silently drop any event
+    // that landed since this caller's last hydrate. Memory order wins for
+    // events both sides know; disk-only events are appended and re-sorted
+    // chain-aware.
+    const mergedEvents = Object.create(null);
+    for (const id of Object.keys(mergedSessions)) {
+      const memEvts = memoryEvents[id] ?? [];
+      const diskEvts = diskEvents[id] ?? [];
+      if (memEvts.length === 0) {
+        mergedEvents[id] = diskEvts;
+        continue;
+      }
+      const memIds = new Set(memEvts.map((e) => e.id));
+      const missing = diskEvts.filter((e) => !memIds.has(e.id));
+      mergedEvents[id] = missing.length > 0 ? [...memEvts, ...missing].sort(compareEventsChainAware) : memEvts;
+    }
+
+    const index = { sessions: mergedSessions, events: mergedEvents, tombstones };
+    // Single-writer law: prompt-sessions/ is owned by 'epics'
+    // (lib/opsOwnership.cjs) — hardcoded here, never taken from the IPC
+    // payload, so a compromised/forged renderer call can't claim a
+    // different writer id.
+    await config.writeJson(filePath, index, { writer: 'epics' });
+    return { sessions: mergedSessions, events: mergedEvents };
+  });
+}
+
+function registerActiveIndexMergeHandlers() {
+  const { ipcMain } = require('electron');
+  const { schemas: s, validated: v } = require('../ipcSchemas.cjs');
+  ipcMain.handle(
+    'promptSessions:merge-active-index',
+    v(s.promptSessionsMergeActiveIndex, ({ cwd, sessions, events, removedIds }) =>
+      mergeActiveIndex(cwd, { sessions, events, removedIds: removedIds || [] })),
+  );
+}
+
+module.exports = { mergeActiveIndex, registerActiveIndexMergeHandlers };

package/src/main/lib/epicMint.cjs

@@ -34,9 +34,16 @@ function readActiveIndex(cwd) {
     return {
       sessions: parsed && typeof parsed.sessions === 'object' && parsed.sessions ? parsed.sessions : {},
       events: parsed && typeof parsed.events === 'object' && parsed.events ? parsed.events : {},
+      // Passed through untouched — this module never consults tombstones (it
+      // doesn't resurrect completed/deleted Epics on its own), but every
+      // caller here does read-modify-write on the object this returns, so
+      // dropping the field would silently erase the removal tombstones
+      // lib/activeIndexMerge.cjs's mergeActiveIndex records the next time any
+      // of ensureEpic/appendPrdCreatedEvent/removeEpic writes this file.
+      tombstones: parsed && typeof parsed.tombstones === 'object' && parsed.tombstones ? parsed.tombstones : {},
     };
   } catch {
-    return { sessions: {}, events: {} };
+    return { sessions: {}, events: {}, tombstones: {} };
   }
 }
 
@@ -374,12 +381,28 @@ function appendPrdCreatedEvent(cwd, epicId, prdSlug, text) {
  */
 function removeEpic(cwd, epicId) {
   if (!cwd || !epicId) return false;
-  const index = readActiveIndex(cwd);
-  if (!hasOwn(index.sessions, epicId)) return false;
-  delete index.sessions[epicId];
-  delete index.events[epicId];
-  writeActiveIndex(cwd, index);
-  return true;
+  return withPathLock(activeIndexPath(cwd), () => {
+    const index = readActiveIndex(cwd);
+    if (!hasOwn(index.sessions, epicId)) return false;
+    delete index.sessions[epicId];
+    delete index.events[epicId];
+    writeActiveIndex(cwd, index);
+    return true;
+  });
 }
 
-module.exports = { ensureEpic, appendPrdCreatedEvent, removeEpic, activeIndexPath, readActiveIndex, findJoinableEpic, tokenize };
+module.exports = {
+  ensureEpic,
+  appendPrdCreatedEvent,
+  removeEpic,
+  activeIndexPath,
+  readActiveIndex,
+  findJoinableEpic,
+  tokenize,
+  // Exported so lib/activeIndexMerge.cjs's renderer-facing merge IPC handler
+  // serializes through the SAME lock instance as ensureEpic/
+  // appendPrdCreatedEvent (module-level Map, shared via Node's require
+  // cache) — one lock per active-index.json path across both callers, not
+  // two independent lock maps that could still interleave.
+  withPathLock,
+};

package/src/main/promptSessionEvents.cjs

@@ -13,10 +13,13 @@
  */
 
 const config = require('./config.cjs');
-
-function promptSessionActiveIndexPath(cwd) {
-  return `${String(cwd).replace(/\/+$/, '')}/session-manager-operations/prompt-sessions/active-index.json`;
-}
+// activeIndexPath/withPathLock come from epicMint.cjs so this module's
+// read-modify-write of active-index.json (appendResponseEventIfKnown, below)
+// serializes through the EXACT SAME lock instance as ensureEpic/
+// appendPrdCreatedEvent and lib/activeIndexMerge.cjs's mergeActiveIndex — one
+// lock across all three writers of this file, not three independent maps
+// that could still interleave a stale read-modify-write past each other.
+const { activeIndexPath: promptSessionActiveIndexPath, withPathLock } = require('./lib/epicMint.cjs');
 
 // IPC channel broadcast whenever an event is appended to a PromptSession's
 // chain from the main process (currently only the scheduler's response-event
@@ -40,26 +43,6 @@ function mintEventId() {
   return `pevt-${Date.now().toString(36)}-${seq}`;
 }
 
-// Serializes read-modify-write cycles per active-index.json path so two
-// PRDs finishing back-to-back for sessions in the same cwd chain onto the
-// tail in issue order instead of racing two independent read-then-write
-// round trips (mirrors promptSessions.ts's own pendingWritesByPath).
-const pendingWritesByPath = new Map();
-
-function withPathLock(path, task) {
-  const prior = pendingWritesByPath.get(path) || Promise.resolve();
-  const settle = () => task();
-  const run = prior.then(settle, settle);
-  pendingWritesByPath.set(
-    path,
-    run.then(
-      () => undefined,
-      () => undefined,
-    ),
-  );
-  return run;
-}
-
 /**
  * If `sourcePromptId` resolves to a known, still-active PromptSession under
  * `cwd`'s active-index.json, appends a 'response' event chained to that