claude-code-session-manager 0.52.0 → 0.54.0

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({
@@ -493,6 +526,25 @@ const promptSessionTranscriptRead = z.object({
   limit: z.number().int().positive().max(10_000).optional(),
 }).strict();
 
+// ──────────────────────────────────────────── Audit log (renderer Epic
+// lifecycle trace, PRD 940). Kind allowlist is enforced HERE, main-side — the
+// renderer cannot write arbitrary kinds through this channel, only the six
+// Epic lifecycle transitions it emits from promptSessions.ts.
+const AUDIT_LOG_KIND = z.enum([
+  'epic_create',
+  'epic_approve',
+  'epic_complete',
+  'epic_delete',
+  'epic_resume',
+  'epic_duplicate',
+]);
+const auditLogAppend = z.object({
+  kind: AUDIT_LOG_KIND,
+  cwd: z.string().min(1).max(4096),
+  epicId: z.string().min(1).max(256),
+  source: z.string().min(1).max(256),
+}).strict();
+
 // ──────────────────────────────────────────── Per-subagent memory
 // Distinct from the workspace-scoped Memory tool: agentMemory is keyed by
 // subagent name (the .md filename in ~/.claude/agents/, e.g. "code-reviewer"),
@@ -889,6 +941,8 @@ module.exports = {
     projectBriefUpdate,
     promptSessionTranscriptAppend,
     promptSessionTranscriptRead,
+    promptSessionsMergeActiveIndex,
+    auditLogAppend,
     agentMemoryList,
     agentMemoryGet,
     agentMemorySet,

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: {} };
   }
 }
 
@@ -182,9 +189,13 @@ function withPathLock(lockPath, task) {
  *
  * `status` defaults to 'proposed' — a fail-safe default so any caller that
  * forgets to pass it files an Epic that waits for human approval rather than
- * one that starts running immediately. Pass 'active' explicitly only for the
- * one legitimate immediate-start path (the New Epic UI's own proposed→active
- * transition, `promptSessions.ts`'s `approveProposed`).
+ * one that starts running immediately. Every Epic is BORN 'proposed' — the
+ * mint branch below ignores/rejects any other requested status; it is
+ * fail-closed, mirroring opsOwnership.cjs's assertOpsWrite. Activation
+ * ('proposed' → 'active') happens exactly once, entirely in the renderer
+ * store's `approveProposed` (`state/promptSessions.ts`) — that code path
+ * never calls ensureEpic(). Joining an already-'active' Epic (this function's
+ * join branches, above the mint branch) remains legal and unchanged.
  *
  * `mintIfMissing` defaults to true for the small set of callers that are
  * themselves the human-intent gate (propose-epic, the RCA hook, the feedback
@@ -223,6 +234,12 @@ function ensureEpic(cwd, { goalText, tag, reuseByGoal = false, epicId: explicitE
         return { epicId: explicitEpicId, prdDir, created: false };
       }
       console.warn(`[epicMint] ensureEpic: explicit epicId ${explicitEpicId} exists but is not open (status=${preferred?.status ?? 'unknown'}) — refusing to join, falling through`);
+      appendAuditEvent('epic_mint_refused', {
+        cwd,
+        epicId: explicitEpicId,
+        status,
+        reason: `explicit epicId exists but is not open (status=${preferred?.status ?? 'unknown'}) — refusing to join, falling through to mint`,
+      });
     }
 
     if (reuseByGoal) {
@@ -251,11 +268,11 @@ function ensureEpic(cwd, { goalText, tag, reuseByGoal = false, epicId: explicitE
     }
 
     if (!mintIfMissing) {
-      throw new Error(
-        `ensureEpic: no existing Epic found (epicId=${explicitEpicId ?? 'none'}) and mintIfMissing is false — `
-        + 'a new Epic can only be created by explicit human intent (New Epic UI, or /propose-epic + Approve & start), '
-        + 'never implicitly by a PRD-authoring path',
-      );
+      const reason = 'no existing Epic found and mintIfMissing is false — a new Epic can only be created by '
+        + 'explicit human intent (New Epic UI, or /propose-epic + Approve & start), never implicitly by a '
+        + 'PRD-authoring path';
+      appendAuditEvent('epic_mint_refused', { cwd, epicId: explicitEpicId ?? null, status, reason });
+      throw new Error(`ensureEpic: ${reason} (epicId=${explicitEpicId ?? 'none'})`);
     }
 
     if (!forceNewEpic) {
@@ -267,6 +284,20 @@ function ensureEpic(cwd, { goalText, tag, reuseByGoal = false, epicId: explicitE
       }
     }
 
+    // BORN-PROPOSED LAW (fail-closed, mirrors opsOwnership.cjs's
+    // assertOpsWrite): a mint always writes 'proposed', regardless of what
+    // status the caller requested. A caller explicitly asking to mint
+    // 'active' is refused outright rather than silently downgraded — that
+    // shape (mint + already-active) should never occur, so it is treated as
+    // a bug in the caller, not a normal fallback path.
+    if (status !== 'proposed') {
+      const reason = `ensureEpic: refusing to mint a new Epic with status '${status}' — every Epic is born `
+        + "'proposed' (CLAUDE.md domain model); activation happens only via the renderer store's "
+        + 'approveProposed, never through ensureEpic()';
+      appendAuditEvent('epic_mint_refused', { cwd, epicId: explicitEpicId ?? null, status, reason });
+      throw new Error(reason);
+    }
+
     const epicId = `${slugify(goalText)}-${crypto.randomUUID().slice(0, 8)}`;
     const now = new Date().toISOString();
     const session = {
@@ -350,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

package/src/main/scheduler.cjs

@@ -565,22 +565,33 @@ async function archivedTwinExists(job) {
 }
 
 /**
- * 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.
+ * Build the non-failure result + run meta for a queued job whose PRD source
+ * is gone. Shared by both PRD-read failure exits in executeJob so the
+ * stale-skip logic isn't duplicated. Two reasons, both exitCode: 0 (no RCA
+ * feedback item, since neither is a real work failure):
+ *   - 'prd-archived': the source was archived — archivedTwinExists found it
+ *     under a prds-archived/ dir. The work already shipped.
+ *   - 'prd-missing': the source is gone everywhere (ENOENT on every
+ *     candidate dir, no archived twin either) — most commonly a PRD that
+ *     existed at enqueue time and was deleted before dispatch (e.g. a test
+ *     fixture that leaked into the live queue and was cleaned up by its own
+ *     `finally` block). Retire the row rather than fail it.
  */
-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`;
+function prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, reason = 'prd-archived') {
+  const msg = reason === 'prd-missing'
+    ? 'PRD source no longer exists on disk — retiring stale queue entry'
+    : (() => {
+        const archivedTwin = archivedPrdPathForJob(job);
+        return `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',
+    slug: job.slug, cwd, sessionId, exitCode: 0, skipped: reason,
     note: msg, startedAt, finishedAt, durationMs: 0,
   });
-  return { exitCode: 0, durationMs: 0, skipped: 'prd-archived', note: msg, sessionId };
+  return { exitCode: 0, durationMs: 0, skipped: reason, note: msg, sessionId };
 }
 
 /**
@@ -2032,16 +2043,34 @@ async function executeJob(job, runDir, defaultCwd, onPid) {
         prompt = parsed.body + FINISH_PROTOCOL;
         prdPath = fallbackPath;
       } catch (e2) {
+        // Found the dir a moment ago but the read still failed. Case A: the
+        // source has since been archived — stale-skip as usual. Case B: it
+        // was deleted out from under us in the window between findPrdDir and
+        // parsePrd (ENOENT) with no archived twin — also a stale row, not a
+        // real failure. Anything else (malformed/unreadable PRD) is a real
+        // failure and keeps exitCode: -1.
         if (await archivedTwinExists(job)) {
-          return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath);
+          return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, 'prd-archived');
+        }
+        if (e2 && e2.code === 'ENOENT') {
+          return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, 'prd-missing');
         }
         safeLog(`[scheduler] failed to read PRD: ${e2?.message}\n`);
         closeFd();
         return { exitCode: -1, durationMs: 0, error: e2?.message };
       }
     } else {
+      // No candidate dir has the slug at all. Case A: it was archived —
+      // stale-skip. Case B: the read error is ENOENT (the common case: a
+      // source that existed at enqueue time and is gone by dispatch, e.g. a
+      // leaked test fixture) with no archived twin — retire as stale rather
+      // than a hard failure. Anything else (a real read/parse error) still
+      // fails the job.
       if (await archivedTwinExists(job)) {
-        return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath);
+        return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, 'prd-archived');
+      }
+      if (e && e.code === 'ENOENT') {
+        return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, 'prd-missing');
       }
       safeLog(`[scheduler] failed to read PRD: ${e?.message}\n`);
       closeFd();
@@ -4480,4 +4509,4 @@ function registerAdminRoutes(adminHttp, remoteObj = remote) {
   });
 }
 
-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, registerAdminRoutes, notifyOriginatingTab, isNotifiableTerminalStatus, extractResultTextFromLog, candidatePrdsDirs, candidateArchivedPrdsDirs, resolveArchivedPrdStatus, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, runPrdMigration, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, 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, registerAdminRoutes, notifyOriginatingTab, isNotifiableTerminalStatus, extractResultTextFromLog, candidatePrdsDirs, candidateArchivedPrdsDirs, resolveArchivedPrdStatus, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, runPrdMigration, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields, executeJob, prdArchivedSkipResult };

package/src/preload/api.d.ts

@@ -1556,6 +1556,15 @@ export interface SessionManagerAPI {
     /** Read back an Epic's full-text turns (optionally capped to the last `limit`). Skips corrupt lines rather than throwing. */
     read: (cwd: string, epicId: string, limit?: number) => Promise<{ turns: PromptSessionTranscriptTurn[] }>;
   };
+  auditLog: {
+    /** Append one Epic-lifecycle audit event to ~/.claude/session-manager/audit-log.jsonl.
+     *  Kind allowlist is enforced main-side (ipcSchemas.cjs) — this channel is
+     *  append-only, no read/list IPC exists. */
+    append: (
+      kind: 'epic_create' | 'epic_approve' | 'epic_complete' | 'epic_delete' | 'epic_resume' | 'epic_duplicate',
+      fields: { cwd: string; epicId: string; source: string },
+    ) => Promise<{ ok: boolean }>;
+  };
   agentMemory: {
     /** List all memory entries for one subagent. Sorted newest first. */
     list: (agentId: string) => Promise<AgentMemoryListResult>;
@@ -1644,9 +1653,28 @@ export interface SessionManagerAPI {
      *  from notifyOriginatingTab) — lets an already-hydrated Epic pick it up
      *  live instead of waiting for a restart. */
     onEventAppended: (handler: (e: PromptSessionEventAppendedPayload) => void) => () => void;
+    /** Main-side read-merge-write of a cwd's active-index.json
+     *  (lib/activeIndexMerge.cjs) — persistActiveIndex sends only its own
+     *  in-memory contribution for the cwd; disk stays main's truth, merged
+     *  inside the same lock epicMint.cjs's ensureEpic serializes through. */
+    mergeActiveIndex: (payload: PromptSessionsMergeActiveIndexPayload) => Promise<PromptSessionsMergeActiveIndexResult>;
   };
 }
 
+// ─────────────────────────────────── PromptSessions active-index merge
+export interface PromptSessionsMergeActiveIndexPayload {
+  cwd: string;
+  sessions: Record<string, unknown>;
+  events: Record<string, unknown[]>;
+  removedIds?: string[];
+  source: 'epics';
+}
+
+export interface PromptSessionsMergeActiveIndexResult {
+  sessions: Record<string, unknown>;
+  events: Record<string, unknown[]>;
+}
+
 // ─────────────────────────────────── PromptSession event-appended broadcast
 
 export interface PromptSessionEventAppendedPayload {

package/src/preload/index.cjs

@@ -339,6 +339,9 @@ contextBridge.exposeInMainWorld('api', {
     read: (cwd, epicId, limit) =>
       ipcRenderer.invoke('promptSessionTranscript:read', { cwd, epicId, ...(limit ? { limit } : {}) }),
   },
+  auditLog: {
+    append: (kind, fields) => ipcRenderer.invoke('auditLog:append', { kind, ...fields }),
+  },
   agentMemory: {
     list: (agentId) => ipcRenderer.invoke('agent-memory:list', { agentId }),
     get: (agentId, entryId) => ipcRenderer.invoke('agent-memory:get', { agentId, entryId }),
@@ -468,5 +471,10 @@ contextBridge.exposeInMainWorld('api', {
       ipcRenderer.on('promptSession:event-appended', listener);
       return () => ipcRenderer.removeListener('promptSession:event-appended', listener);
     },
+    /** Main-side read-merge-write of a cwd's active-index.json
+     *  (lib/activeIndexMerge.cjs) — replaces persistActiveIndex's old
+     *  renderer-side read-merge-write. Payload carries only this renderer's
+     *  own in-memory contribution for the cwd; disk stays main's truth. */
+    mergeActiveIndex: (payload) => ipcRenderer.invoke('promptSessions:merge-active-index', payload),
   },
 });